Establish phased research program with evidence and validation gates

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9

research/README.md

@@ -16,3 +16,12 @@ Additional directories:
 Research material may be provisional.
 
 Promotion into the canon should happen only after the concept has been reconciled with competing models and tested against multiple frontend architectures.
+
+
+## Start a research session
+
+1. Read [ResearchProgram](plan/ResearchProgram.md) for phases and current work records.
+2. Follow [ResearchProtocol](plan/ResearchProtocol.md) for evidence and promotion.
+3. Select a question from [OpenQuestions](plan/OpenQuestions.md) and a bounded task.
+4. Use [ValidationCases](plan/ValidationCases.md) and the templates in `templates/`.
+5. Update catalogs and question outcomes, then commit and sync the workplan status.

research/plan/OpenQuestions.md

@@ -26,3 +26,19 @@
 - What makes a frontend pattern "established"?
 - Should known uses be manually curated or automatically mined?
 - How should contradictory source claims be represented?
+
+
+## Investigation ledger
+
+All entries are open. Update status and evidence links as research proceeds;
+retaining a hypothesis requires evidence just as rejecting one does.
+
+| Question | Working hypothesis | Disconfirmation exercise | Owner workplan |
+| --- | --- | --- | --- |
+| Q01 Responsibility coverage | Nine responsibilities explain the seed cases | Record any important decision that cannot be mapped without distortion | FEP-WP-0002 |
+| Q02 Independence | Authority and projection can vary independently | Compare server-authoritative and local-first decisions; identify forced coupling | FEP-WP-0002 |
+| Q03 Pattern recurrence | Candidates describe reusable configurations | Seek independent uses and a counterexample; reject product-specific restatements | FEP-WP-0002 |
+| Q04 Generativity | Resulting contexts make later decisions easier | Compare walkthrough with a plain narrative and change one constraint | FEP-WP-0002 |
+| Q05 Sequence ordering | The general sequence works with explicit branches | Test offline, collaboration and quality requirements that force earlier decisions | FEP-WP-0003 |
+| Q06 Scale and boundaries | Composition and deployment are distinct dimensions | Analyze independently owned features that deploy together, and the reverse | FEP-WP-0003 |
+| Q07 Retrieval | Metadata improves relevant, justified recommendations | Held-out prompts including ambiguity, incompatibility and abstention | FEP-WP-0004 |

research/plan/ResearchProgram.md

@@ -1,5 +1,11 @@
 # Frontend Patterns Research Program
 
+Status: planned · Program established: 2026-09-24
+
+Start with [Research Protocol](ResearchProtocol.md), then the
+[validation cases](ValidationCases.md). Source families and pattern names below
+are a research agenda, not completed evidence.
+
 ## 1. Objective
 
 Develop a coherent Alexander-style pattern language for frontend architecture and design that is useful to both human practitioners and software agents.
@@ -316,56 +322,44 @@ The infospace should eventually support prompts such as:
 
 This requires graph-friendly metadata and stable identifiers.
 
-## 10. Initial milestones
+## 10. Execution and review gates
 
-### M0 — Scaffold
+The phases are ordered by evidence dependencies, not calendar deadlines. A failed
+review gate returns to the relevant research question; it does not force promotion.
+Workplan files own execution status. This table defines intended outcomes.
 
-- repository structure,
-- intent,
-- responsibility model,
-- force vocabulary,
-- relation vocabulary,
-- pattern schema,
-- research method.
+| Phase | Work record | Deliverable and exit criterion |
+| --- | --- | --- |
+| M0 — Scaffold | FEP-WP-0001, finished | Intent, repository structure and State Hub integration exist. |
+| M1 — Seed investigation | [FEP-WP-0002](../../workplans/FEP-WP-0002-seed-language-validation.md), ready | Reconciled schema; first source case and local-first contrast; 6–10 connected draft patterns; two completed case walkthroughs with evidence and counterexamples. |
+| M2 — Broaden and challenge | [FEP-WP-0003](../../workplans/FEP-WP-0003-contrasting-schools.md), proposed | Evidence from all six streams; coverage matrix for all ten application types; revise, merge or reject candidates; complete at least four further contrasting cases. |
+| M3 — Retrieval and empirical use | [FEP-WP-0004](../../workplans/FEP-WP-0004-reference-surface.md), proposed | Validated metadata and graph export; held-out retrieval cases; at least two real repository studies tied to revisions; publish limitations. |
 
-### M1 — Seed corpus
+M1 does not require a large catalog. Six to ten patterns is a working scope cap,
+not a maturity score. Expand toward the original 20–30 candidate ambition only
+when additional patterns explain decisions the seed corpus cannot express.
 
-- source catalog,
-- Carniato case analysis,
-- historical GUI architecture review,
-- local-first review,
-- rendering architecture review.
+### First research cycle
 
-### M2 — First canonical language
+1. T01 of FEP-WP-0002 resolves the metadata contradictions in `REVIEW.md` with
+   worked examples. Source extraction can begin while that contract is explored.
+2. T02 completes the Carniato case and an independently sourced local-first case.
+   Use the source-review template and record claims before normalizing vocabulary.
+3. T03 selects a connected subset around authority, addressability, projection,
+   local interaction, mutation and reconciliation. Walk through VC-01 and VC-02.
+4. Review the evidence and question ledger. Record rejected patterns, missing
+   responsibilities and ordering failures as carefully as supporting examples.
+5. Write an M1 review under `research/reviews/` with pass/revise/defer for each
+   criterion and links to artifacts. Hand unresolved work into the next workplan.
 
-- 20–30 candidate patterns,
-- reviewed force vocabulary,
-- relation graph,
-- first architecture decompositions.
+### Working rhythm and ownership
 
-### M3 — Generative sequences
-
-- general web application,
-- content site,
-- transactional application,
-- collaborative application,
-- local-first application.
-
-### M4 — Agentic reference surface
-
-- normalized metadata,
-- stable identifiers,
-- pattern graph export,
-- query examples,
-- retrieval/evaluation fixtures.
-
-### M5 — Empirical refinement
-
-- test language against real repositories,
-- collect pattern co-occurrence,
-- identify missing forces,
-- identify misleading or redundant patterns,
-- revise maturity levels.
+The executing repository agent owns artifact updates and State Hub synchronization;
+`owner: codex` does not imply a scheduled or autonomous background run. Each research
+session takes one bounded question or case, records evidence, updates the question
+ledger and task status, and commits and syncs the result. Review at every phase gate
+and whenever contradictory evidence changes the ontology. Review roles are explicit
+in the resulting review document; a self-review must be identified as such.
 
 ## 11. Open research questions
 

research/plan/ResearchProtocol.md

@@ -0,0 +1,66 @@
+# Research protocol
+
+Status: working method · 2026-09-24
+
+## Research unit
+
+A unit is a question, an evidence set and a recorded conclusion. Before reading,
+state the question, current hypothesis, assumptions and what would contradict it.
+Use [SourceReview](../../templates/SourceReview.md) for extraction and
+[ArchitectureWalkthrough](../../templates/ArchitectureWalkthrough.md) for application.
+
+## Evidence handling
+
+1. Prefer original publications, standards, research papers, official documentation
+   and identifiable implementations. Secondary surveys help discovery; trace their
+   substantive claims to primary evidence where possible.
+2. Record author/publisher, title, exact URL or bibliographic locator, publication
+   date/version and access date. Mark unavailable information as unknown.
+3. In each source review, assign local claim labels (C01, C02, …). Cite claims by
+   file path plus label. Separate source statements, our interpretations and tests.
+4. Cite sections, pages or repository revisions. Paraphrase accurately; keep any
+   quotations short and attributed. A source being listed is not evidence of review.
+5. Record conflicts and negative cases. Multiple sources repeating the same origin
+   are not independent confirmation. An unavailable source stays pending.
+6. Update `research/catalog/SourceCatalog.md` with the review path and state:
+   queued, extracted or reviewed. These are research workflow labels, not pattern
+   evidence maturity. Do not invent publication details to fill a template.
+
+## Pattern synthesis
+
+Extract problem, context, competing forces, recurring configuration, dynamics,
+resulting context, consequences and failure modes before assigning a pattern name.
+Compare candidates against existing ones: retain, merge, split, reject or defer,
+with reasons in `research/catalog/PatternCandidateCatalog.md`.
+
+A draft promoted into `patterns/` must satisfy the schema agreed in FEP-WP-0002,
+include at least two competing forces, evidence locators, a justified relation to
+another pattern, a failure case and an explicit maturity. Cite two contrasting
+applications where available; otherwise retain hypothesis status and state the gap.
+A framework feature alone does not establish recurrence. A directory named `canon`
+does not confer evidence maturity on its contents.
+
+## Generativity test
+
+Hold the application brief fixed. Record each architectural decision, forces,
+applicable alternatives, chosen patterns and resulting context. Then vary one
+constraint (for example offline operation or independent deployment) and explain
+which decisions change. Compare with a plain architecture narrative written without
+the pattern catalog. If the language adds only renamed labels, revise it.
+
+Record quality constraints at the start and throughout the walkthrough: accessibility,
+security, privacy, recovery and performance must influence earlier decisions too.
+The existing sequence's late quality step is a hypothesis to challenge.
+
+## Review and stopping rules
+
+For every gate, record reviewer, date, artifacts, checks, counterevidence and outcome
+(pass, revise or defer) in `research/reviews/`. A review passes only if references
+are traceable, examples resolve their metadata references, and another reader can
+follow the reasoning. Distinguish synthetic scenarios from observed systems.
+
+Stop broad source collection when the bounded question has sufficient evidence to
+support or reject the current hypothesis; record remaining uncertainty. Do not
+stretch source claims to meet a pattern-count target. Preserve superseded conclusions
+through Git history and link the replacement. Reopen a conclusion when new evidence
+invalidates a stated assumption.

research/plan/ValidationCases.md

@@ -0,0 +1,48 @@
+# Validation cases
+
+Status: planned synthetic briefs · No walkthroughs completed
+
+These briefs are inputs for reasoning tests, not claims about real systems. Keep
+inputs fixed when comparing approaches. Record all additional assumptions.
+
+| Case | Fixed starting constraints | Key challenge | Phase |
+| --- | --- | --- | --- |
+| VC-01 Transactional administration | Shared records; server validates writes; concurrent edits; deep links; keyboard operation; failed requests recoverable | Distinguish drafts, optimistic feedback, committed state and stale observations | M1 |
+| VC-02 Offline field notes | Create and edit without connectivity; restart without losing work; later multi-device sync; conflicting edits possible | Local authority, persistence, identity and explicit reconciliation | M1 |
+| VC-03 Content publication | Mostly read-only; shareable URLs; useful content before scripts; slow network | Avoid unnecessary client execution; preserve accessible navigation | M2 |
+| VC-04 Collaborative editor | Concurrent editing; presence; reconnect; undo; access changes | Distinguish durable document changes, ephemeral presence and authorization | M2 |
+| VC-05 Real-time dashboard | Frequent updates; disconnects; stale indicators; bounded client compute | Communication lifetime, freshness and overload | M2 |
+| VC-06 Microfrontend estate | Independent teams/releases; shared navigation; partial outages | Separate ownership, composition and deployment boundaries | M2 |
+| VC-07 Storefront | Crawlable catalog; price changes; cart; authoritative checkout | Cacheability versus transaction correctness | M2 coverage |
+| VC-08 SaaS workspace | Dense interaction; multiple views; shared data; long sessions | Derived state, component boundaries and interaction continuity | M2 coverage |
+| VC-09 Local-first personal tool | Private local data; optional sync; backup and restore | Separate local ownership from replication and recovery | M2 coverage |
+| VC-10 Mobile web application | Intermittent network; constrained memory; interrupted sessions | Persistence, startup cost and recoverability | M2 coverage |
+
+M2 completes VC-03 through VC-06 and explicitly marks VC-07 through VC-10 covered,
+partially covered or unresolved with evidence. Coverage is not a completed walkthrough.
+M3 selects real repositories with accessible source/history and records exact revisions.
+Do not treat synthetic results as empirical confirmation.
+
+## Required result for each completed case
+
+Use [ArchitectureWalkthrough](../../templates/ArchitectureWalkthrough.md). Include:
+
+- constraints and assumptions, including cross-cutting quality requirements;
+- ordered decisions with pattern references, alternatives and rationale;
+- at least one branch caused by a changed constraint;
+- failure/recovery behavior and unresolved forces;
+- evidence links and distinction between observation and inference;
+- comparison with an architecture narrative without the pattern language.
+
+Assess traceability, coherence, decision usefulness, quality coverage and handling
+of the changed constraint as pass/revise/unknown, with reasons. Do not combine
+these into an unsupported numerical confidence score.
+
+## Held-out retrieval evaluation (M3)
+
+Freeze a corpus revision before preparing at least six new prompts derived from
+unseen variants. Include incompatible constraints, an underspecified brief and an
+out-of-scope problem. Record expected acceptable patterns, prohibited claims and
+when to ask for context or abstain. Compare retrieval with manual navigation;
+report unsupported recommendations, missed constraints and unresolved references.
+Keep development examples separate from the held-out set.