From 8a141b7fe50ad0b1d1948f44d1a2b0f101ced57f Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 24 Sep 2026 07:58:09 +0200 Subject: [PATCH] Establish phased research program with evidence and validation gates Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9 --- README.md | 11 +- TREE.md | 128 +++++++++--------- research/README.md | 9 ++ research/plan/OpenQuestions.md | 16 +++ research/plan/ResearchProgram.md | 80 +++++------ research/plan/ResearchProtocol.md | 66 +++++++++ research/plan/ValidationCases.md | 48 +++++++ templates/ArchitectureWalkthrough.md | 42 ++++++ templates/SourceReview.md | 34 +++++ .../FEP-WP-0002-seed-language-validation.md | 21 ++- workplans/FEP-WP-0003-contrasting-schools.md | 48 +++++++ workplans/FEP-WP-0004-reference-surface.md | 48 +++++++ 12 files changed, 438 insertions(+), 113 deletions(-) create mode 100644 research/plan/ResearchProtocol.md create mode 100644 research/plan/ValidationCases.md create mode 100644 templates/ArchitectureWalkthrough.md create mode 100644 templates/SourceReview.md create mode 100644 workplans/FEP-WP-0003-contrasting-schools.md create mode 100644 workplans/FEP-WP-0004-reference-surface.md diff --git a/README.md b/README.md index 795148d..e84e1b2 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,15 @@ Software patterns must describe when they become harmful, misleading, expensive ## Status -This repository begins as a research-backed v0.1 scaffold. The first research case is Ryan Carniato's +This repository begins as a v0.1 research scaffold with evidence collection still pending. The first research case is Ryan Carniato's "The Grand Unifying Architecture of Frontend", used as a starting point for decomposing modern frontend architectures into deeper responsibilities and forces. + + +## Research entry point + +Start with the [research program](research/plan/ResearchProgram.md), its +[protocol](research/plan/ResearchProtocol.md) and [validation cases](research/plan/ValidationCases.md). +The first cycle is ready in [FEP-WP-0002](workplans/FEP-WP-0002-seed-language-validation.md): +resolve the metadata contract, review contrasting sources and test a connected seed +corpus. Later phases broaden coverage and evaluate retrieval against real systems. diff --git a/TREE.md b/TREE.md index 0553097..3744a65 100644 --- a/TREE.md +++ b/TREE.md @@ -1,69 +1,65 @@ -# Repository Tree +# Repository file inventory + +Tracked project documents and research scaffold, updated 2026-09-24. ```text -frontend-patterns/ -├── architectures/ -│ ├── DocumentWeb.md -│ ├── Islands.md -│ ├── LocalFirst.md -│ ├── Microfrontends.md -│ ├── README.md -│ ├── ServerComponents.md -│ └── SPA.md -├── canon/ -│ ├── Forces.md -│ ├── FrontendPatternLanguage.md -│ ├── PatternSchema.md -│ ├── Relations.md -│ ├── Responsibilities.md -│ └── Scales.md -├── patterns/ -│ ├── address/ -│ │ └── README.md -│ ├── affordance/ -│ │ └── README.md -│ ├── authority/ -│ │ └── README.md -│ ├── composition/ -│ │ └── README.md -│ ├── execution/ -│ │ └── README.md -│ ├── mutation/ -│ │ └── README.md -│ ├── projection/ -│ │ └── README.md -│ ├── quality/ -│ │ └── README.md -│ ├── synchronization/ -│ │ └── README.md -│ └── README.md -├── research/ -│ ├── cases/ -│ │ └── CarniatoGrandUnifyingArchitecture.md -│ ├── catalog/ -│ │ ├── PatternCandidateCatalog.md -│ │ └── SourceCatalog.md -│ ├── compendium/ -│ │ └── FrontendArchitectureCompendium.md -│ ├── concepts/ -│ │ ├── GenerativeSequence.md -│ │ └── ResponsibilityModel.md -│ ├── plan/ -│ │ ├── OpenQuestions.md -│ │ └── ResearchProgram.md -│ └── README.md -├── sequences/ -│ ├── CollaborativeApplication.md -│ ├── ContentSite.md -│ ├── GeneralWebApplication.md -│ ├── LocalFirstApplication.md -│ ├── README.md -│ └── TransactionalApplication.md -├── technologies/ -│ └── README.md -├── templates/ -│ ├── Pattern.md -│ └── TechnologyMapping.md -├── INTENT.md -└── README.md +.custodian-brief.md +.gitignore +.repo-classification.yaml +AGENTS.md +INTENT.md +README.md +REVIEW.md +SCOPE.md +TREE.md +WORK-RECORDS.md +architectures/DocumentWeb.md +architectures/Islands.md +architectures/LocalFirst.md +architectures/Microfrontends.md +architectures/README.md +architectures/SPA.md +architectures/ServerComponents.md +canon/Forces.md +canon/FrontendPatternLanguage.md +canon/PatternSchema.md +canon/Relations.md +canon/Responsibilities.md +canon/Scales.md +patterns/README.md +patterns/address/README.md +patterns/affordance/README.md +patterns/authority/README.md +patterns/composition/README.md +patterns/execution/README.md +patterns/mutation/README.md +patterns/projection/README.md +patterns/quality/README.md +patterns/synchronization/README.md +research/README.md +research/cases/CarniatoGrandUnifyingArchitecture.md +research/catalog/PatternCandidateCatalog.md +research/catalog/SourceCatalog.md +research/compendium/FrontendArchitectureCompendium.md +research/concepts/GenerativeSequence.md +research/concepts/ResponsibilityModel.md +research/plan/OpenQuestions.md +research/plan/ResearchProgram.md +research/plan/ResearchProtocol.md +research/plan/ValidationCases.md +sequences/CollaborativeApplication.md +sequences/ContentSite.md +sequences/GeneralWebApplication.md +sequences/LocalFirstApplication.md +sequences/README.md +sequences/TransactionalApplication.md +technologies/README.md +templates/ArchitectureWalkthrough.md +templates/Pattern.md +templates/SourceReview.md +templates/TechnologyMapping.md +workplans/FEP-WP-0001-statehub-bootstrap.md +workplans/FEP-WP-0002-seed-language-validation.md +workplans/FEP-WP-0003-contrasting-schools.md +workplans/FEP-WP-0004-reference-surface.md ``` diff --git a/research/README.md b/research/README.md index bff4f74..9024878 100644 --- a/research/README.md +++ b/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. diff --git a/research/plan/OpenQuestions.md b/research/plan/OpenQuestions.md index 452eb25..c7e0a70 100644 --- a/research/plan/OpenQuestions.md +++ b/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 | diff --git a/research/plan/ResearchProgram.md b/research/plan/ResearchProgram.md index 45565e8..8a270db 100644 --- a/research/plan/ResearchProgram.md +++ b/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 diff --git a/research/plan/ResearchProtocol.md b/research/plan/ResearchProtocol.md new file mode 100644 index 0000000..c6a05b5 --- /dev/null +++ b/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. diff --git a/research/plan/ValidationCases.md b/research/plan/ValidationCases.md new file mode 100644 index 0000000..60c7ea6 --- /dev/null +++ b/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. diff --git a/templates/ArchitectureWalkthrough.md b/templates/ArchitectureWalkthrough.md new file mode 100644 index 0000000..e159514 --- /dev/null +++ b/templates/ArchitectureWalkthrough.md @@ -0,0 +1,42 @@ +# Architecture walkthrough — + +Status: planned | drafted | reviewed +Case and corpus revision: +Author / reviewer / date: +Synthetic brief or observed repository (URL and revision): + +## Fixed brief and assumptions + +Include authority, latency, offline, concurrency, accessibility, security, privacy, +performance and recovery constraints. Mark unspecified requirements explicitly. + +## Baseline narrative without the pattern catalog + +Describe a plausible architecture and its trade-offs for comparison. + +## Decisions + +| Order | Context and forces | Pattern references | Alternatives and rejection reasons | Resulting context | Evidence | +| --- | --- | --- | --- | --- | --- | + +## Change one constraint + +State the change and trace its impact through the decisions and pattern relations. + +## Failure and recovery + +Describe stale reads, rejected mutations, interruption and partial failure as applicable. + +## Review + +| Criterion | Pass / revise / unknown | Evidence and reason | +| --- | --- | --- | +| Traceability | | | +| Coherence of configuration | | | +| Decision usefulness beyond baseline | | | +| Quality constraints | | | +| Changed-constraint branch | | | + +## Gaps and follow-up + +Record missing patterns, invalid relations, ordering failures and work record links. diff --git a/templates/SourceReview.md b/templates/SourceReview.md new file mode 100644 index 0000000..ff79bfa --- /dev/null +++ b/templates/SourceReview.md @@ -0,0 +1,34 @@ +# Source review — + +Status: queued | extracted | reviewed +Reviewer and review date: +Research question / hypothesis: +Potential disconfirming evidence: + +## Source identity + +- Author / publisher: +- Title: +- URL or bibliographic locator: +- Publication date / version: +- Access date: +- Primary or secondary source; independence from other sources: + +## Claims + +| Label | Source claim (paraphrase) | Section/page/revision | Assumptions | Our interpretation | +| --- | --- | --- | --- | --- | +| C01 | | | | | + +## Candidate patterns and forces + +Link candidates and explain competing forces, recurrence and resulting contexts. + +## Counterevidence and limits + +Separate observed counterexamples from hypothetical ones. Record inaccessible evidence. + +## Conclusion and next action + +Support, revise, reject or defer the hypothesis; explain why. Link the question +ledger, candidate/source catalogs and any follow-up work record. diff --git a/workplans/FEP-WP-0002-seed-language-validation.md b/workplans/FEP-WP-0002-seed-language-validation.md index dc7b9a5..535fb50 100644 --- a/workplans/FEP-WP-0002-seed-language-validation.md +++ b/workplans/FEP-WP-0002-seed-language-validation.md @@ -4,17 +4,23 @@ type: workplan title: "Validate the seed frontend pattern language" domain: infotech repo: frontend-patterns -status: proposed +status: ready owner: codex topic_slug: canon created: "2026-09-23" -updated: "2026-09-23" +updated: "2026-09-24" state_hub_workstream_id: "3350b7f2-375a-54e8-8f7c-3bf7c7c3af71" --- # Validate the seed frontend pattern language -Follow-up from `REVIEW.md` and FEP-WP-0001. This records future research. +First executable cycle of `research/plan/ResearchProgram.md`, following `REVIEW.md` +and FEP-WP-0001. Readiness review on 2026-09-24: scaffold is present, source and +walkthrough templates exist, VC-01/VC-02 are defined, and deliverables below are +bounded. No research execution or evidence gate is claimed complete. + +T01 and source extraction in T02 can proceed independently. T03 requires both. +Use `research/plan/ResearchProtocol.md`; track Q01–Q04 in the question ledger. ## Reconcile the metadata contract @@ -55,3 +61,12 @@ Author a small connected pattern set and exercise it in server-authoritative and local-first scenarios. Show forces, alternatives, ordering rationale, resulting contexts and failure modes. Record gaps, then define the minimum metadata validator and graph export needed by these examples. + + +## Phase acceptance + +Produce 6–10 connected draft patterns, complete VC-01 and VC-02, and write +`research/reviews/M1-SeedReview.md` with evidence for each M1 criterion. Include +rejected or merged candidates and any source-access limitations. Retain hypothesis +maturity where evidence is incomplete. Handoff broader investigations to FEP-WP-0003; +metadata tooling and empirical evaluation are tracked in FEP-WP-0004. diff --git a/workplans/FEP-WP-0003-contrasting-schools.md b/workplans/FEP-WP-0003-contrasting-schools.md new file mode 100644 index 0000000..1d75c94 --- /dev/null +++ b/workplans/FEP-WP-0003-contrasting-schools.md @@ -0,0 +1,48 @@ +--- +id: FEP-WP-0003 +type: workplan +title: "Challenge the language across architectural schools" +domain: infotech +repo: frontend-patterns +status: proposed +owner: codex +topic_slug: canon +created: "2026-09-24" +updated: "2026-09-24" +--- + +# Challenge the language across architectural schools + +Part of `research/plan/ResearchProgram.md`. Phase prerequisite: FEP-WP-0002's evidence +gate. This is planned follow-up, not an active background execution request. +Individual task descriptions identify any work that can start earlier. + +## Compare the six research streams + +```task +id: FEP-WP-0003-T01 +status: todo +priority: high +``` + +Build a source coverage matrix for streams A–F in ResearchProgram.md. Complete a primary-source review for each stream, including disagreements and independent known uses. Q05 and Q06 guide the comparison; source counts alone do not establish coverage. + +## Complete contrasting architecture walkthroughs + +```task +id: FEP-WP-0003-T02 +status: todo +priority: high +``` + +After the M1 review, complete VC-03 through VC-06 using the walkthrough template. Mark coverage of VC-07 through VC-10 with evidence and gaps. Revise sequences and architecture decompositions where constraints break the current model. + +## Review pattern and ontology changes + +```task +id: FEP-WP-0003-T03 +status: todo +priority: medium +``` + +Record retain/merge/split/reject decisions, revised relations, quality constraints and counterexamples. Write research/reviews/M2-CoverageReview.md against the M2 gate; hand unresolved questions into live work records before closing. diff --git a/workplans/FEP-WP-0004-reference-surface.md b/workplans/FEP-WP-0004-reference-surface.md new file mode 100644 index 0000000..c5d7642 --- /dev/null +++ b/workplans/FEP-WP-0004-reference-surface.md @@ -0,0 +1,48 @@ +--- +id: FEP-WP-0004 +type: workplan +title: "Evaluate retrieval and real repository applicability" +domain: infotech +repo: frontend-patterns +status: proposed +owner: codex +topic_slug: canon +created: "2026-09-24" +updated: "2026-09-24" +--- + +# Evaluate retrieval and real repository applicability + +Part of `research/plan/ResearchProgram.md`. Phase prerequisite: FEP-WP-0003's evidence +gate. This is planned follow-up, not an active background execution request. +Individual task descriptions identify any work that can start earlier. + +## Validate metadata and export the graph + +```task +id: FEP-WP-0004-T01 +status: todo +priority: high +``` + +After the schema and seed examples pass M1, implement the smallest validator/exporter needed to check unique IDs, allowed values, relation targets and evidence references. Add meaningful invalid and valid fixtures; preserve prose and source provenance. + +## Evaluate held-out retrieval cases + +```task +id: FEP-WP-0004-T02 +status: todo +priority: medium +``` + +After M2, freeze a corpus revision and evaluate at least six unseen prompts following ValidationCases.md. Record expected alternatives, abstentions, unsupported claims and missed constraints; compare with manual navigation. Address Q07. + +## Test against real repository revisions + +```task +id: FEP-WP-0004-T03 +status: todo +priority: medium +``` + +Study at least two contrasting accessible repositories at recorded revisions. Separate observed implementation from inferred intent. Write research/reviews/M3-EmpiricalReview.md, publish limitations, and hand remaining findings into live work records.