Establish ecosystem reuse and monthly-supervised improvement loop

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0e241-8285-7a63-8c0c-51c9cb824dc3

docs/ReuseAndImprovementLoop.md

@@ -0,0 +1,255 @@
+# 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.