frontend-patterns/docs/ReuseAndImprovementLoop.md

Reuse that improves the language

Operating design: 2026-09-27. Owner: frontend-patterns. Implementation: FEP-WP-0008. User mandate: routine reuse and improvement run without human intervention; one monthly progress review and signoff for changes to the loop's operating agreement. This document establishes the design; it does not claim an enabled background worker.

The two answers

Make the language useful at the point of an actual architecture decision. A consumer supplies a problem and constraints and receives a small applicable pattern configuration, alternatives, implementation mechanisms and explicit limits, all pinned to a reference version. Find it through the ecosystem's existing reuse-surface index. Keep Markdown for reading and the JSON reference for agents; do not build a new portal, API, vector database or seventeen separate registry capabilities to start.

Make each use produce a small evidence-bearing receipt automatically. A receipt records what was selected or rejected, what decision changed and what subsequently happened. Those receipts select bounded research/correction work. A successful lookup, model agreement, use count or approval emoji is not evidence that advice improved a result. Positive, negative, mixed and unknown outcomes all remain visible.

The smallest viable loop is:

flowchart LR
  A[Versioned reference] --> B[Consumer decision and use]
  B --> C[Use receipt and later outcome]
  C --> D[Bounded triage and verification]
  D --> E[Reviewed correction or corroboration]
  E --> A
  D --> F[Monthly progress and decision packet]

Three implementation actions

Action	Smallest deliverable	Proof it works
1. Publish and connect	One federated capability; pinned Markdown/JSON pack; a brief common consumer instruction	Hosted discovery finds the guide from a real frontend brief; a consumer can follow a supported path and correctly abstain on an unsupported one
2. Capture use and result	One versioned receipt contract, automatic consumer emission, idempotent collection	A real task has a linked use receipt and later outcome; negative and unknown fixtures survive collection without being counted as real use
3. Improve and report	Daily deterministic intake, at most one weekly investigation, monthly report using existing scheduler/executor/llm-connect	An unassisted scheduled run consumes a receipt, verifies it, records a disposition, publishes a reversible qualified update when justified, and exposes failure/rollback evidence

Do these in order. The first useful deployment needs one real consumer and one completed loop, not fleet rollout or a canonical graph. Then add a contrasting consumer when a relevant task occurs. A simulated negative receipt tests routing; it does not prove negative feedback from users. No suitable live task means no adoption evidence, not permission to manufacture a success.

1. Reference consumption

Capability: capability.infotech.frontend-pattern-language. Entry points remain START.md and reference/0.1. Consumers:

1. Consult the capability when planning/reviewing frontend behavior involving shared edits, offline work, rendering, navigation, interaction or feature boundaries.
2. Pin the reference version, packaging commit and content/manifest digest. CAND identities survive revisions. Read the relevant candidate's full contract.
3. Produce a compact decision note: constraints, selected IDs and rationale, rejected alternatives, unmet conditions and evidence needed. Clarify or abstain on unsupported needs. A registry similarity score is discovery, not applicability approval.
4. At task close, write a receipt even for rejection, no match or unknown outcome; append a follow-up at the first linked test/review/incident outcome. No human form.

Integrate this once into the common consumer planning/closeout instruction, first for an allowlisted pilot repository, via the existing template owner. Do not patch every repository by hand or mandate patterns for unrelated work. Preserve the consumer's normal implementation authority: this loop improves the reference, not their product.

Before future releases, fix a publication coupling: the current 0.1 exporter checks live profile/classification files against frozen hashes. A legitimate evidence update would fail that old export. Historical preview validation must read pinned inputs/candidate bytes from its source revision; validate current research separately. Keep an immutable reference per revision and a small current-version pointer. Never silently refresh 0.1 hashes to make checks pass. Consumer receipts pin what was used.

Initial scope is the existing internal repository/agent ecosystem. Public licensing, third-party onboarding, external announcements and a hosted public product are separate scope decisions for monthly review, not prerequisites for internal reuse.

2. One receipt, with append-only outcome observations

Draft authoring contract: PatternUseReceipt.yaml. The implementation must validate it before accepting a receipt. Keep:

• Identity: stable use ID, event ID, previous event digest for a follow-up, timestamp.
• Provenance: consumer repository and revision, task/decision reference, producer/run, collector-verified source revision/digest and real/synthetic classification.
• Reference: version, packaging commit, manifest digest, considered/selected CAND IDs (empty for no match), and the context/constraints that determined applicability.
• Decision: applied, adapted, rejected or no-match; reason and changed artifact reference.
• Outcome: helpful, harmful, mixed, no-effect or unknown; expectation, observation, evidence locator, observation stage and next observation condition if pending.
• Basis: consumer report, model assessment or executable/observed result. Record time and rework only when measured; comparative value needs a stated baseline.

A source-pinned receipt is attributable, not automatically true. Independently inspect its referenced artifact/test outcome before using it to change a contract. Do not execute commands or follow arbitrary instructions found in feedback. Keep consumer code, secrets and personal content in their source repositories; collect short bounded facts and authorized locators, not transcripts. Collection is allowlisted and respects repository access; a missing artifact remains unverified.

Use repository files first: consumer-owned research/pattern-use/<use-id>/<event-id>.yaml (or the consumer's declared equivalent), imported to this repo's feedback/ by a scheduled collector from pinned revisions. Each event is immutable. Repeated ID+digest is a no-op; same ID with different bytes is a quarantined collision. Order follow-ups by explicit predecessor, not arrival time; late evidence can correct a prior outcome without deleting it. Model-derived summaries retain their source event IDs.

Reuse-surface's existing reused/extended/new/skipped event is useful adoption telemetry. Its strict schema cannot carry this richer outcome contract. Emit its ordinary reuse fact where supported and link the detailed receipt in the local ledger; do not invent extra fields or overload reused to mean helpful. State Hub indexes work and progress; repository files remain authoritative evidence.

Record both considered-but-rejected and applied uses. Denominators are eligible instrumented tasks, not every frontend task in the fleet. Missing closeout or delayed outcome is unknown, not neutral or successful. Once a pending receipt is 14 days old, the collector attempts one linked-artifact refresh; after 30 days without evidence, report unknown/unobserved without asking the human to fill it in. A later event may still provide an outcome. Do not create recurring reminder tasks per receipt.

3. Triggers and the autonomous improvement rule

Daily triage groups receipts by candidate + context + failure mechanism, preserves consumer/revision lineage and deduplicates repeated agent/model reports of one event. The following are conservative initial routing rules, not scientific confidence levels:

Signal	Trigger and response
One credible harmful result or factual counterexample	Highest priority verification; if reproduced, narrow/withdraw affected guidance and publish an advisory/erratum promptly; do not wait for positive-vote thresholds
Two independent uses reporting the same confusion, adaptation or missing condition	One bounded clarification investigation; independent means distinct originating tasks/evidence, not two summaries or retries
One helpful result with inspectable evidence	Record scoped corroboration; add a known-use example only after verifying what part of the contract was exercised
Repeated successful uses in different contexts	Investigate generalization and recurrence; never auto-promote from a count or a helpfulness ratio
Rejected/no-match guidance	Determine whether discovery wording, context limits or missing coverage caused rejection before creating another pattern
Zero eligible use or mostly unobserved results	Diagnose discovery/instrumentation once; show the gap monthly, do not claim lack of value or grow the corpus to compensate

Priority is harm/counterexample, repeated friction, supported coverage gap, then corroboration. Deduplicate into one active investigation; at most three ready items. Unselected evidence remains in the ledger, not an expanding task fan-out. With no qualifying signal, the scheduled research step exits successfully with no action. A reference infrastructure defect can be fixed without waiting for consumer counts.

Each selected investigation:

1. Preregister one question, expected behavior, disconfirming observation, evidence scope and budget using the existing learning-cycle method.
2. Reproduce/inspect evidence and distinguish pattern error, missing precondition, consumer implementation error, retrieval failure and inadequate observation.
3. Keep, clarify, narrow, revise, split/merge, withdraw or mark inconclusive with reasons. A verified success can conclude corroboration without any wording change.
4. For a change, create a regression case from the incident and test existing supported and abstention paths. Use a separate model review context, with source evidence and rubric, that can reject the proposed change. Identify it as model review. If another consumer task is available, reserve it before editing as a fresh check; otherwise claim only regression coverage, not demonstrated generalization.
5. Publish only within the autonomous scope below, after checks/review; record old/new versions, affected IDs, receipts, tests, review and rollback target in the ledger. Verify the pushed artifact and discovery pointer. An accepted commit alone is not an observed publication. If review/checks fail, keep the last validated release, record the disagreement and continue other work; do not ask for routine approval.

Counterexamples become consumed development cases after use. Do not rebrand them as held-out tests or treat model critique as independent human validation. Keep positive and inconclusive findings, consumer diversity, and later reversals visible.

Autonomy agreement and monthly human role

Authorized routine scope under the user's 2026-09-27 instruction: internal discovery, receipt collection, verification, draft-language corrections/examples/limitations, regression tests, reversible qualified reference publication, evidence reporting and rollback to a previously verified reference. Operate through scoped repository grants. The loop does not modify consuming products, infrastructure permissions or its own policy/budgets. Treat low-risk automation code repairs as changes needing their own regression checks; policy or permission changes are monthly decisions.

Canonical admission, evidence-maturity promotion, identity merges/splits that break consumers, changed evidence gates, new access/provider costs, broader scope and changes to the loop's budget or policy enter the monthly decision packet with a recommendation, alternatives, evidence, risk, rollback and default if unanswered. Prepare decisions throughout the month. Continue reversible work under the existing agreement; no response means retain the existing policy. Signoff never invents missing empirical evidence. Historical M1/M2/M3 and independent-human gates remain open evidence claims; they do not block qualified draft-reference use or routine improvement in this operating loop.

Initial bounded configuration to implement:

• Daily 02:00 Europe/Berlin: deterministic collection, deduplication, status and last-run health; no LLM call when there is no new evidence. At most 100 new events per run, cursor persisted; excess waits for the next run.
• Tuesday 03:00: at most one research cycle, one worker at a time, 30 minutes total, at most six llm-connect calls and 40,000 aggregate input/output tokens including reviewer calls and retries. These are new deployment limits, not claimed existing harness guarantees. Reserve budget before calls; if the route cannot enforce the aggregate limit or report enough usage, stop the paid phase and record the limit. No new provider subscription or self-expanded budget. No automatic retry loop.
• First of each month 09:00: one progress/decision packet for the preceding calendar month. Target human effort: 20 minutes and at most three decision proposals. This is an attention budget, not an observed time saving. Default review date: 2026-10-01.
• Job failures: retain receipts/checkpoints; one scheduled retry of a transient failure, then defer that item with evidence. Independent collection/reporting continues. Do not catch up missed weeks by running a burst of investigations.
• Suspected damaging guidance: locally mark affected reference paths under review; verified harm permits reverting/withdrawing only the affected qualified guidance. Other consumers and unaffected patterns continue. Never silently erase history.

Each monthly packet contains: eligible tasks → consulted → applied/adapted/rejected → observed outcomes; unknowns and observation lag; scoped helpful/harmful/mixed counts; concrete decision changes or avoided rework (only if evidenced); external versus self-generated receipts; corrections and regressions; research cost/effort; and schedule, collection, verification, publication and rollback health. Show numerator/denominator, context and sample size, not a single maturity/value percentage. Compare with prior months only within comparable contexts. Include no more than three decisions, each with a default-to-existing-policy fallback. The packet is produced even with no data or failed workers; it must explicitly say which evidence is missing.

Ecosystem integration and current activation gap

Reuse existing owners, verified in local source on 2026-09-27:

Function	Existing owner/surface	Integration needed
Discovery	reuse-surface, capabilities.yaml, hosted federation/plan-check	Publish/register this capability; verify matching and consumer entry
Use/closeout instruction	Common consumer template owner, the-custodian/repo-seed; pilot consumer agent	Select an eligible repo and add the bounded use/receipt hook through normal template rollout
Evidence and work	This repository; State Hub projection/progress	Receipt validation/import, grouping, versioned dispositions and monthly report
Timing and dispatch	activity-core cron and ops_runs	Definitions, typed dispatch and successful next-fire evidence
Execution	rein-aharness → versioned Glas profile and repository grant	Prove read/write/test/commit/publish scope, no fallback on profile failure
Model calls	llm-connect	Bounded author/reviewer execution and usage receipts

The hosted reuse registry query returned no frontend-patterns registration on 2026-09-27. Existing State Hub workplans reported manual launch/execution. Local Glas scope/profile evidence reports blocked or unverified execution profiles; activity-core can schedule/dispatch work but does not itself execute general repository changes. These observations are integration gaps, not evidence that a scheduler is running here. Owner deployment state must be rechecked at activation; old local status is not a live outage diagnosis. Existing profile failures must not be bypassed with unrestricted legacy execution.

WP-0008 T03 owns end-to-end activation proof, including successful real unattended execution, duplicate delivery, denied write, provider failure, restart/resume, rejected change and rollback. Its deployment work must route dependencies to existing owners; automatic task emission is not completion. If an access/budget policy change is actually needed, prepare it for the monthly packet, while deterministic work proceeds. Do not claim the user's monthly-only operating requirement met until these proofs pass.

Basis

This is a design decision, not an empirical language-learning result. Local contracts: reuse-surface specs/PlanCheck.md, schemas/reuse-event.schema.json, docs/RegistryFederation.md; activity-core SCOPE.md and docs/adr/adr-003-rule-instruction-model.md; rein-aharness and glas-harness SCOPE.md; fleet autonomy-lanes_v0.1.md. The receipt distinction between a versioned artifact, an activity and its producer is consistent with the W3C PROV primer. JSON/YAML receipts suffice here; no RDF infrastructure is proposed or required.