Ratified decision
FULL PRODUCT / ARCHITECTURE SPECIFICATION
complete target-state behavior and seams
+ complete human HTML
+ cross-links / diagrams / Decisions
+ explicit Increment Realization boundaries
↓
INCREMENTAL IMPLEMENTATION
I0 → I1 → I2 → … → I9
↓
DOGFOOD / LEARN / EXPLICITLY AMEND
This replaces the earlier interpretation that later domains could remain mostly unspecified until their implementation increment.
What “full specification” means
Before Increment 0 implementation materially begins, the specification system describes the complete intended target state across architecture, domains, workflows, UI/pages and machine-readable contracts.
| Area | Required target-state content |
|---|---|
| Architecture | Topology, module boundaries, persistence authority, transactions, durable execution, trust, configuration, providers/adapters, execution, CI/release/deployment boundaries. |
| Domains | Primitives, identity, ownership, relationships, lifecycle, invariants, authorization, persistence, failure/recovery, provider mappings. |
| Workflows | Entry/exit, state transitions, actors/authority, failure/retry, evidence, handoffs and cross-domain effects. |
| UI/pages | Information architecture, journeys, data truth, actions, complete material states, responsiveness, accessibility, URL truth and linked contracts. |
| Contracts/schemas | Ownership, compatibility boundary, versioning/migration and adapter/provider mapping. |
What may remain implementation-local
Private algorithms, SQL index tuning, provider-version request plumbing, measured concurrency constants, profiling-driven performance tuning and other details may remain later implementation decisions when they can change behind an already-defined seam without changing product behavior or architecture.
Required structure in every canonical spec
Target State Invariants From Day 1 Increment Realization Current Implementation State Deferred Realization Temporary Dogfood Behavior Decisions / ADRs
Early implementation is a compatible subset of the final model, never a separate temporary model.
Increment boundaries remain binding
| Increment | Operational scope |
|---|---|
| I0 | Foundation / self-hosting substrate |
| I1 | Project → Plan → Task → FactoryRun → AgentRun → ChangeSet → Review → Merge |
| I2 | Real Planning |
| I3 | Generic autonomy / Decisions / Approvals |
| I4 | Full Factory observability UX |
| I5 | CI control plane |
| I6 | Release / Environment / Deployment / CD |
| I7 | Cluster product surface |
| I8 | Self-healing operations |
| I9 | External / enterprise productization + formal reliability/SLO machinery |
See the Increment Realization Matrix for capability-level boundaries.
Human HTML authority
<spec>.md canonical diff/agent source <spec>.html complete human-readable presentation
The HTML contains the complete contract, diagrams, stable links, increment mapping, Decision/ADR links and mockups where applicable. INDEX.html remains the human root.
UI and high-fidelity design
Full page behavior and product information architecture are specified now. The shared shell/navigation/design language must be coherent before the first user-facing implementation. Exact high-fidelity states are approved before the increment that implements them, including materially different failure, waiting, permission and responsive states.
Anti-drift rule
implementation discovers a conflict → open/supersede Decision → impact analysis → amend target spec → amend increment matrix if timing changes → update mockups if affected → implement
Code never silently becomes the new design authority.
Full-specification completion gate
Before Increment 0 implementation materially begins: full architecture/domain/workflow/UI target specs exist, all active specs have HTML companions, INDEX.html links them, increment mapping is explicit, Decisions/ADRs are linked, and Increment 0/1 operational boundaries are unambiguous.
Immediate next work
1. Complete the full spec inventory. 2. Write all target-state specs. 3. Generate linked HTML + diagrams. 4. Complete/cross-check the Increment Realization Matrix. 5. Run contradiction / missing-seam / traceability review. 6. Produce Increment-0/1 high-fi against the full baseline. 7. Consolidated spec + high-fi review. 8. Begin Increment 0.