Research baseline and source-of-truth map
Research baseline and source-of-truth map
Section titled “Research baseline and source-of-truth map”This appendix captures the research baseline used to build the planning-meta corpus.
Source classification model
Section titled “Source classification model”- Normative source: defines policy or contract that other planning docs should not contradict.
- Operational source: describes practical workflow and execution state.
- Explanatory source: clarifies architecture intent and boundaries.
- Analytical source: provides checklists or critique support.
Classified sources
Section titled “Classified sources”| Source | Classification | Confidence | Notes |
|---|---|---|---|
docs/src/architecture/internal-web-ir-implementation-blueprint.md | operational + partial normative | Medium | comprehensive, but mixes historical and active sections |
docs/src/adr/012-internal-web-ir-strategy.md | normative architecture intent | High | accepted ADR with clear target boundaries |
docs/src/explanation/expl-architecture.md | explanatory | High | conceptual pipeline and module map |
docs/src/explanation/expl-compiler-lowering.md | explanatory | High | lowering-phase narrative and current-vs-target bridge |
docs/agents/governance.md | normative quality/governance constraints | High | TOESTUB and quality review constraints |
docs/src/architecture/doc-to-code-acceptance-checklist.md | analytical + acceptance checklist | High | concrete merge-time checklist controls |
Baseline goals extracted
Section titled “Baseline goals extracted”- Build a full-stack Vox strategy centered on internal structural representation.
- Preserve current islands compatibility while reducing internal complexity.
- Improve semantic ownership clarity across AST/HIR/Web IR/emit layers.
- Define anti-foot-gun planning controls.
- Make planning explicit enough for agent execution with low ambiguity.
Risks discovered during research
Section titled “Risks discovered during research”- Normative and historical content co-located in large planning artifacts.
- Drift risk in ownership language and gate interpretation.
- Deferral metadata inconsistent across artifacts.
- Truncation pressure in large plans without explicit weighted detail policy.
External assumption validation (web + repo)
Section titled “External assumption validation (web + repo)”| Assumption | Status | Confidence | Source links | Notes |
|---|---|---|---|---|
| React ecosystem interop remains high-value for Vox web strategy | Supported | High | React Compiler 1.0 stable, React Compiler docs | Aligns with ADR strategy to keep React/TanStack target while reducing internal complexity. |
| Strict nullability modeling reduces undefined-behavior risk | Supported | High | TypeScript strictNullChecks | Supports explicit Required/Optional/Defaulted planning posture for WebIR boundaries. |
| Island architecture remains compatible with attribute-anchored hydration contracts | Supported | Medium | Astro islands architecture | Confirms selective-hydration compatibility model; does not prescribe Vox wire format details. |
| Transform/codegen separation improves maintainability in compiler systems | Supported | Medium | SWC architecture | Supports planning preference for structured IR + thin printers. |
Validation caveats:
- External references support directionality, not one-to-one implementation requirements.
- Repo code-path truth remains the final authority for current-state claims.
Why this appendix exists
Section titled “Why this appendix exists”This file provides traceability for the planning corpus. It reduces “why did we choose this structure?” churn during future rewrites.