frontend-patterns/docs/ReuseAndImprovementLoop.md

# Reuse that improves the language

Operating design: 2026-09-27. Owner: frontend-patterns. Implementation:
[FEP-WP-0008](../workplans/FEP-WP-0008-use-driven-improvement.md).
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:

```mermaid
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](../START.md) and [reference/0.1](../reference/0.1/README.md). 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](../templates/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](https://www.w3.org/TR/prov-primer/). JSON/YAML
receipts suffice here; no RDF infrastructure is proposed or required.