frontend-patterns/research/evolution/README.md

Learning and language evolution

Start with the generated evolution report. The language is an ongoing learning system; a completed investigation is a bounded result, not a claim that the language is finished. Maturity can rise or fall when evidence changes. Even canonical means reviewed for reference use, not permanently true.

Records and ownership

• profiles.json holds current, manually reviewed evidence profiles. CAND-* identifiers are stable research identities, not admitted FEP-* pattern identities. Preserve identity across renames. For a merge, retain the retired candidate with deprecated metadata and superseded_by; explain the decision in the ledger. Promotion and relations still require the PatternSchema review gates.
• ledger.json records consequential outcomes, independent confirmation, rejection/merge and inconclusive investigation. Its initial ten entries are a selected retrospective account, not a complete historical census. Historical effort is unknown. Never rewrite an old conclusion to hide its failure; append a correction with supersedes. Git preserves corrections to recording errors.
• context.json records walkthrough state, usefulness results and live work records. These are curated assessments, not automatically inferred findings.
• baseline-2026-09-26 freezes all three assessments and the source commit for the 17 candidate hashes. The assessment itself is new metadata, versioned by the commit adding the snapshot, not claimed to exist at that older source revision. Later snapshots never overwrite earlier ones.

A profile explains a decision and records documentary, static-code and runtime support separately. Each evidence item identifies a family, scope and local review. Related packages/examples, multiple files and repeated fixture runs do not establish independence. Family labels are provenance groupings, not an independence score. independent_full_contract_uses: null means unassessed, not zero known mechanisms. A numeric value requires an explicit review locating independent full-contract uses.

Review provenance distinguishes author/model, independent model and human review. The baseline is an author-model metadata assessment; no independent human review is implied. assessed_at does not reset last_substantive_review_date: the latter is unknown until the evidence review's date and scope have been reconciled. Open limits include counterexamples and contexts still untested. Supersession is explicit. Current profiles require substantive_review_ref and substantive_review_scope for a known substantive date. The reconciliation records original evidence-review dates; a synthesis or metadata refresh does not renew them. Historical snapshots retain their original schema-v1 assessments.

Closing a bounded cycle

1. Before execution, copy LearningCycle into a dated research plan. State one question, belief, disconfirming observation, stream, protocol, comparison group, intended decision and effort budget. Include the evidence needed to distinguish revision from simple corroboration.
2. Execute and retain failures and negative controls. Live inference uses llm-connect. Record active research minutes and execution minutes separately; do not infer effort from token count or elapsed calendar time. Allocate overlapping activity once. Record the clock/method and missing portions in the cycle plan. Tokens and cost are optional receipt-backed telemetry, not substitutes for effort.
3. Close one ledger entry per bounded question, including inconclusive work. Add a protocol reference for prospective cycles. One question can count at most one consequential outcome even if it revises several files. Repeat trials belong under that entry; a genuinely new question needs its own preregistered cycle. Choose revision, corroboration, rejection, merge or inconclusive, with rationale.
4. Update affected profiles and their candidate hashes after reviewing the actual changes; update case/usefulness status only when supporting review changes. Regenerate and check the report. Commit candidate edits before taking a snapshot.
5. At a review boundary, run python3 scripts/research_evolution.py snapshot --name cycle-YYYY-MM-DD-short-name, commit the snapshot and sync the workplan. Reopen decisions when contradictions, new contexts, dependency changes or failed use undermine their scope. Never promote automatically from metric thresholds.

Commands: make evolution-report, make evolution-check, make evolution-test. The check rejects stale candidate hashes, missing references, inventory drift, invalid provenance, unknown identities, corrupted baseline candidate hashes and stale generated output. It does not validate source truth, external URLs, semantic independence or full-contract scope. Snapshot creation pins committed candidate content and refuses to overwrite a file.

Measuring viability without a composite score

Dimension	Observation to collect	Current limit
Applicability	Reviewed decisions and failure contexts across the ten validation cases	Four synthetic/provisional walkthroughs; six planned
Trustworthiness	Scoped evidence, independent full-contract uses, unresolved contradictions, provenance and review age	Independent recurrence unassessed; dated evidence-review provenance reconciled
Usefulness	Constraint misses, unsupported recommendations, decision quality and time against equivalent prose	Frozen small model-reviewed pilot; human gate open
Coherence	Ambiguous selections, redundant candidates and unjustified relations found/resolved in reviews	No measured baseline; reconciliation/copy overlap remains open
Maintainability	Reference checks, overdue review obligations, remaining gaps and effort per revision	Local links/hash checks automated; age/backlog estimates not yet measured
Learning efficiency	Consequential changes per recorded research hour, alongside corroboration and inconclusive outcomes	Retrospective effort unknown; no trend yet

Usefulness evaluations retain stable development anchors for regression and add fresh generalization tasks. Register tasks, criteria and equivalent-information conditions before execution; preserve negative results and reviewer provenance. Do not tune on the frozen pilot and relabel it held-out. The six consumed pilot briefs cannot demonstrate fresh generalization. Keep time, decision quality and unsupported claims separate; equal aggregate scores do not establish equivalence.

Assessing diminishing returns

Fast initial learning followed by slower change is a hypothesis, not an assumed trajectory. Compare prospective cycles only within the same stream, evidence tier, question granularity, effort accounting and evaluation protocol. A comparison-group name refers to that declared contract. Split the group when the contract changes; do not pool unrelated research just to obtain a trend.

The report shows per-cycle consequential outcomes per recorded active research hour for prospective groups. Unknown or zero time yields an unknown rate. Corroboration is shown separately: no revision can be valuable confirmation, and inconclusive work may reveal a faulty method. Execution time, tokens and cost remain separate ledger fields; the active-effort rate is not a total-cost productivity claim.

After at least three comparable cycles, review the sequence qualitatively: did new sources change decisions or limits, did uncertainty shrink, and do fresh cases still fail? Three is a review trigger, not statistical proof of a plateau. Record any conclusion and its window/protocol in a new review. Do not infer a slope from this baseline or the selected retrospective entries. Prefer more independent validation when beliefs stabilize; broaden when new contexts expose missing decisions; repair structure when ambiguity prevents use. Low novelty alone is not a stopping rule.

Keep both the unchanged candidate cohort and additions/removals visible when comparing snapshots. A growing inventory must not hide weakening evidence for old claims. Learning continues after milestones; finite workplans carry the next bounded question and explicit residuals.