frontend-patterns/research/evolution/README.md

# Learning and language evolution

Start with the generated [evolution report](EvolutionReport.md). 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](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](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](context.json) records walkthrough state, usefulness results and live
  work records. These are curated assessments, not automatically inferred findings.
- [baseline-2026-09-26](snapshots/baseline-2026-09-26.json) 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.

## Closing a bounded cycle

1. Before execution, copy [LearningCycle](../../templates/LearningCycle.md) 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 and substantive-review ages unassessed |
| 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.