@sabaiway/agent-workflow-engine 3.2.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.0.0 — the scenario floor, and five answers the canon now states at its own points of use (AD-117)
+
+Slice 4 wrote the layer's first real specs and came back with six questions the canon had left for
+the next reader to rediscover. Five are answered here, IN `references/specs.md`, each at the point
+where it is needed — and four of the five answers are a refusal to add a mechanism.
+
+> ### ⚠ BREAKING — a spec written to the 3.3.0 canon can be invalid under this one
+>
+> `## Scenarios` gains a floor: at least one scenario line, with no empty-marker escape. A document
+> the 3.3.0 canon and its reader both accepted now refuses as `scenarios-empty`. Same class as
+> **3.0.0**, where deleting a vocabulary from the canon was already called MAJOR. The remedy is one
+> line per scenario — `- S<N> <name> :: unbound` while no test pins it.
+
+- **(1) No empty-marker escape on `## Scenarios`.** `*(empty)*` written there refuses as
+  `scenario-line`; `unbound` already covers a scenario no test pins yet. An empty exclusion list is a
+  claim, an empty scenario list is an absence. The refusal table gains the matching `scenarios-empty`
+  row, in the reader's own order.
+- **(2) A binding marker is an ORDINARY source line.** It counts toward the source-size practice like
+  any other line, and a pinning file already at its cap raises its recorded ratchet to host one. No
+  carve-out: the size judge counts bytes and must not learn spec vocabulary.
+- **(3) There is NO sidecar binding form.** Retroactive coverage of a PUBLISHED package rides a
+  release train, because the marker moves that package's subtree — a cost the family already pays
+  deliberately, against a second place a binding could live.
+- **(4) No `root` op verb.** The store root is the navigator, never an op target; it is judged as the
+  listing parent of its declared child. The canon says so where containment is defined.
+- **(5) The promoting event of a RETROACTIVE draft is PLAN APPROVAL.** `live` lands in the SAME slice
+  that authors the draft, once every scenario is bound — otherwise a slice whose whole deliverable IS
+  the specs has no later landing row, and the store's first contracts stay permanently provisional by
+  the canon's own wording.
+- `test/specs-canon.test.mjs` pins all five as prose assertions at their point of use, absorbs the
+  new rule in the rules-table deep-equal, and gains two refuse fixtures — the empty section and the
+  empty marker — each yielding exactly its one rule. The arm was red-proofed against the unchanged
+  canon.
+
+
+## 3.3.0 — the feature-spec canon: `references/specs.md`, the `Spec-first` lens bullet, specs as plan rows (AD-112)
+
+- **`references/specs.md`** (NEW) — the canon of the feature-spec layer in the family's own
+  vocabulary: where specs live and how the navigator counts them; the FROZEN schema (kinds,
+  statuses and their forward-only transitions, the caps and the numeric fan-out / promotion
+  thresholds, the slug pattern, the scenario-binding grammar, the module-root grammar, the
+  Out-of-scope rule, the advisory unbound warning); the shape per kind; the 33-row refusal table
+  the deployed reader enforces; lifecycle, per-scenario binding and atomic plan approval; the
+  complete feature-vs-page precedence table; spec-driven feature-sliced architecture with ONE
+  dependency rule and an honestly stated review-level enforcement altitude; spec vs ADR; the
+  retroactive onboarding path; the scale budget. `test/specs-canon.test.mjs` pins this file against
+  the reader's `SPEC_SCHEMA` — no second source of the numbers — reads the repo-only fixture corpus
+  (81 files: every accept case clean, every refuse case exactly its one rule) and reads the two
+  rendered templates clean.
+- **`references/agent-rules-lens.md`** gains ONE bullet, `Spec-first`: a plan names its governing
+  spec(s) — zero, one or many, one per touched slice — each one's Out of scope bounds that slice
+  (no global union; a conflict is a spec revision BEFORE approval); a new feature's draft spec
+  exists AT plan review, a contract change rides the plan as a proposed revision, and the revision
+  lands with the code; page-only coverage governs as an adoption shim. The outgoing body is appended
+  to the append-only prior store, so every unmodified deployment converges on the next kit touch.
+- **`references/planning.md`** — Goal and boundary names the governing spec(s); a contract change
+  is a ledger row present at review (`create` = draft spec, `modify` = revision; the landing row
+  moves `draft -> live`, a removal row `live -> retired`). **`references/procedures.md`** —
+  plan-authoring step 2 names the governing spec(s) and writes the `create` / `modify` spec rows so
+  they exist at review; plan-execution step 3 lands the approved draft or revision WITH the code.
+- `provides` stays `["plan"]`; the payload pins (tarball, installer) name the new file.
+
 ## 3.2.0 — the state table comes BEFORE the guard: enumerate by proof, never by exclusion (AD-111)
 
 The canon already said a repeat finding in one subarea routes to SUBTRACTION rather than a fourth

package/README.md

@@ -42,6 +42,12 @@ the canonical methodology reference on disk:
 - [`references/planning.md`](references/planning.md) — the **plan canon**: the capped plan shape
   (Goal and boundary · Module ledger · Verification), the subtraction rubric, the plan-file
   lifecycle, the `queue.md` series index, and the mandatory final **Phase: Cleanup**.
+- [`references/specs.md`](references/specs.md) — the **feature-spec canon**: the durable
+  per-feature contract layer under `docs/ai/specs/` (Contract · Scenarios · Out of scope · Module),
+  the frozen schema (kinds, statuses, forward-only transitions, the numeric fan-out and promotion
+  thresholds, the scenario-binding grammar, the refusal table), governing specs cited per plan, the
+  feature-vs-page precedence table, spec-driven feature-sliced architecture, and the retroactive
+  onboarding path. The deployed reader `scripts/spec-schema.mjs` (memory) is pinned against it.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
   methodology fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
   pointer, kept under the entry point's line cap).

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-engine
-description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
+description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the feature-spec canon (the durable per-feature contract layer with its frozen schema and Out-of-scope discipline), the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '3.2.0'
+  version: '4.0.0'
 ---
 
 # agent-workflow-engine
@@ -22,6 +22,13 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
   (Goal and boundary · Module ledger · Verification — literal headings), the subtraction rubric for
   review, the plan-file lifecycle (`docs/plans/*.md`, gitignored, never committed), the `queue.md`
   series index and the mandatory final **Phase: Cleanup**.
+- [`references/specs.md`](references/specs.md) — the **feature-spec canon**: the durable per-feature
+  contract layer under `docs/ai/specs/` (Contract · Scenarios · Out of scope · Module), the frozen
+  schema (kinds, statuses, forward-only transitions, the numeric fan-out and promotion thresholds,
+  the scenario-binding grammar, the refusal table the deployed reader enforces), governing specs
+  cited per plan, the feature-vs-page precedence table, spec-driven feature-sliced architecture,
+  and the retroactive onboarding path. The memory substrate's deployed reader
+  `scripts/spec-schema.mjs` is pinned against this canon by the engine's own test.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded** fragment the
   composition root injects into a deployed project's `AGENTS.md`, between the
   `<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/agent-rules-lens-priors.md

@@ -176,3 +176,21 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 - **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).
+
+<!-- prior: 2026-08-23 (AD-112) — before the spec-first bullet (the spec layer) -->
+### 2.x. Planning, review & process-fidelity invariants
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
+- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
+- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
+- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
+- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **State table BEFORE the guard — enumerate by PROOF, never by exclusion.** The subtraction rule above fires on a repeat finding, which is a LATE signal: by then the review has paid for each miss. The EARLY signal is structural — a decision whose input has **several independent state dimensions** (is it tracked? do the bytes still match the source? does the neighbouring file exist?). Write the table first, admit the write with **ONE conjunction of proven facts**, and funnel every other cell into a single refusal; the table is then the table-driven test. An exclusion list (`if (bad1) return; if (bad2) return;`) fails **OPEN** on the first state nobody enumerated — and "unreadable" is a state, distinct from "absent". A reviewer cannot save you here: it judges the patch in front of it and can only name the NEXT missing state, one round at a time.
+- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
+- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
+- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
+- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).

package/references/agent-rules-lens.md

@@ -3,6 +3,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **Spec-first.** A plan names its GOVERNING spec(s) — zero, one or many, one per touched spec-covered slice (the feature spec under `docs/ai/specs/`; page-only coverage governs as an ADOPTION SHIM, with Out of scope + Revision stated inline in the plan). Each cited spec's Out of scope bounds that slice's work and the plan's non-goals restate it per slice — no global union; a cross-spec conflict is resolved by a spec revision BEFORE approval, never by silent precedence. A NEW feature's draft spec exists AT plan review (a `create` row); a change to a governed contract rides the plan as its proposed revision (a `modify` row); approval confirms plan and contract atomically, and the revision lands with the code. Scenario bindings are per scenario: a new scenario is `unbound` until its test lands in the same plan, and a status never regresses for an extension.
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.

package/references/planning.md

@@ -24,7 +24,8 @@ A plan that does not fit is not under-described. Either the TASK is too big —
 independently verifiable boundaries, never by document size — or it is a SWEEP (below).
 
 - **Goal and boundary** (10 lines) — the observable outcome, what behaviour is preserved, explicit
-  non-goals.
+  non-goals, and the GOVERNING spec(s) ([`specs.md`](specs.md)): zero, one or many — one per touched
+  spec-covered slice — each cited spec's Out of scope restated as a non-goal for that slice.
 - **Module ledger** (60 lines) — the single list of paths, and the plan's execution order.
 - **Verification** (20 lines) — the acceptance check, plus one command that validates the whole ledger.
 - **Phase: Cleanup** and **Next steps** (human-actionable only) share the 10 reserved lines.
@@ -41,6 +42,11 @@ One row per path, ≤200 bytes per row, six fields:
 only anchor on a path above it or on existing code. There is no separate step/phase numbering — the
 only phases are session boundaries in a multi-session plan, and Cleanup.
 
+**A contract change is a row, present at review.** A NEW feature's draft spec is a `create` row
+(`docs/ai/specs/<slug>.md`) and a proposed REVISION of a governed contract is a `modify` row — both
+written WITH the plan, so approval confirms the plan and every cited draft or revision atomically; the
+landing row moves the spec `draft -> live`, a removal row `live -> retired`.
+
 A `create` row's responsibility names the **exported surface** the module must provide — the names
 other rows import. That surface does not exist in the checkout yet, so it cannot be derived from it;
 this is the one interface contract a plan owes its executor.

package/references/procedures.md

@@ -33,7 +33,10 @@ Slots: review
 
 1. **Research** — the exact files, contracts and constraints touched.
 2. **Draft** — write to the shape [`planning.md`](planning.md) fixes; its *Module ledger* decides
-   the layout and every budget before any file exists — a size gate is only the backstop.
+   the layout and every budget before any file exists — a size gate is only the backstop. Name the
+   governing spec(s) in *Goal and boundary* ([`specs.md`](specs.md)); a new feature's draft spec is
+   a `create` row and a revision of a governed contract a `modify` row, both written here so they
+   exist AT review.
 3. **Self-review** — apply *What gets cut*; fold by code (read and cite the `file:line`); update
    `queue.md` for a series.
 4. **review {recipe}** — Solo (self-review only) / Reviewed (one backend) / Council (both; you
@@ -67,7 +70,8 @@ Each ledger row is one logical commit.
    readiness (`--override <slot>=<recipe>` per run).
 2. **If `execute` resolved to Delegated, dispatch execution FIRST** — the backend returns a diff
    (codex-exec) *before* you integrate; otherwise implement directly.
-3. **Implement / integrate** — your own edits or the reviewed delegated diff.
+3. **Implement / integrate** — your own edits or the reviewed delegated diff; a spec row lands its
+   approved draft or revision WITH the code ([`specs.md`](specs.md)).
 4. **Self-review** — the change against its [`planning.md`](planning.md) ledger row and the plan's
    Verification, under the project's reuse and clean-code rules; fold by code (cite the
    `file:line`); **characterize-first**: pin uncovered code's behaviour in a green test before

package/references/specs.md

@@ -0,0 +1,202 @@
+# Feature Specs
+
+The durable per-feature CONTRACT layer of `docs/ai/`: what a feature accepts and returns, which
+scenarios pin it, and — the core value — what is OUT of scope. A plan is the ephemeral delta; a spec
+is the living, name-addressed WHAT; an ADR is the immutable, numbered WHY. Specs are not numbered.
+
+The layer is a continuation of the family's own practice, not a methodology import: the existing
+plan-approval checkpoint confirms a contract, the existing `maxLines` caps bound every file, the
+existing `[[AD-NNN]]` convention links the why, and hidden mode covers the store with no new
+machinery. **No new blocking checkpoints**: statuses are lifecycle markers, never approval gates.
+
+## Where specs live
+
+- `docs/ai/specs/`, inside the memory substrate, hierarchical by domain and feature slice, built for
+  thousands of specs. The store root `docs/ai/specs/index.md` links up to `technical_specification.md`
+  (the top spec stays the system root).
+- Every folder's `index.md` lists ONLY its immediate children; there is no global per-spec index.
+  The always-loaded navigator `docs/ai/index.md` carries ONE counted `specs/` row (specs / parts /
+  indexes) generated from the store, so adding or removing a valid spec changes the navigator and the
+  freshness gate sees it. A file the reader refuses keeps its own visible navigator row — never
+  swallowed by the aggregate.
+- "Well-formed" has ONE definition: the deployed reader `scripts/spec-schema.mjs`
+  (`readSpecDocument(text, rel)`), read through by the navigator collapse and by the structural
+  checker alike. It is pure text — it imports nothing, opens no file, and models no markdown code
+  (a fence line refuses; a spec carries no code sample, so no line is ever ambiguous).
+
+## The frozen schema
+
+These values are frozen; the reader's `SPEC_SCHEMA` carries them and the canon test pins this file
+against it.
+
+- **Frontmatter**: the substrate six keys — `type: spec`, `lastUpdated`, `scope`, `staleAfter`,
+  `owner`, `maxLines` — plus `kind`; the key set is CLOSED (an unknown or repeated key refuses).
+  `status` and an integer `revision >= 1` ride ONLY on
+  `kind: spec` (the contract root owns them); a `part` or an `index` carrying either REFUSES.
+- **kind** — `index` | `spec` | `part` (the entity discriminant: an `index.md` with `kind: spec` is a
+  promoted contract root, with `kind: index` a domain navigator).
+- **status** — `draft` | `live` | `retired`. Transitions run forward only: draft -> live (the
+  landing row of the approved plan) and live -> retired (the removal row), never backwards.
+  `revision` increments by one per live contract change.
+- **Caps and thresholds** — `maxLines: 80` on an index, `maxLines: 150` on a spec or a part. Fan-out:
+  an index lists at most 30 immediate children; beyond that it subdivides along feature-slice /
+  subdomain boundaries, never into arbitrary buckets. Promotion: a spec over its own `maxLines: 150`
+  becomes `<slug>/index.md` (`kind: spec`) plus `part` files beside it — recursive, no depth limit.
+- **slug** — the file stem of a flat spec, the folder name of a promoted root or a domain index:
+  `^[a-z0-9]+(-[a-z0-9]+)*$`. Every path segment under the store is a slug.
+- **Scenario line** — `- S<N> <name> :: <repo-relative test path> :: spec:<slug>/S<N>` or
+  `- S<N> <name> :: unbound`; N runs contiguously from 1; the marker equals the line's own id.
+- **`## Scenarios`** — at least one scenario line; `*(empty)*` is NOT an escape here (it refuses as
+  `scenario-line`), because an `unbound` line already covers a scenario no test pins yet. A contract
+  that pins nothing is the one shape the layer exists to refuse.
+- **`## Module`** — bullets of repo-relative paths: ONE `dir/` root OR a literal file list. `..`,
+  an absolute path, a backslash, a glob, and a dir + file mix each REFUSE. A retired spec may carry
+  `*(empty)*`.
+- **`## Out of scope`** — at least one non-blank bullet, or exactly `*(empty)*` when the emptiness is a decision.
+- An `unbound` scenario on a `live` spec is an advisory warning, never a refusal.
+
+## Shape per kind
+
+- **`index`** — frontmatter: the six keys + `kind: index` (+ `maxLines: 80`). Headings: `# <title>`,
+  `## Children` — each immediate child exactly once as `- [name](./<child>.md)` or
+  `- [name](./<child>/index.md)`, at most 30. No `status`, no `revision`, no `## Scenarios`,
+  `## Out of scope`, `## Module` or `## Parts`. The store root additionally carries, before its
+  first section, exactly the line `> Up: [technical_specification.md](../technical_specification.md)`.
+- **`spec`** — frontmatter: the six keys + `kind: spec` + `status` + `revision` (+ `maxLines: 150`).
+  File: `<slug>.md` (flat) or `<slug>/index.md` (promoted). Headings in order: `# Spec: <title>`,
+  `## Contract`, `## Scenarios`, `## Out of scope`, `## Module`, optional `## Parts` (promoted roots
+  only: each part exactly once as `- [name](./<part>.md)`), optional `## Links` (`[[AD-NNN]]`, page
+  citations).
+- **`part`** — frontmatter: the six keys + `kind: part` (+ `maxLines: 150`). File: `<name>.md` beside
+  a promoted root. Heading: `# Part: <title>`. No `status`, `revision`, `## Scenarios`,
+  `## Out of scope`, `## Module` or `## Parts` — the root owns them.
+
+## Refusals
+
+The reader names exactly one rule per defect. The repo-only fixture corpus carries at least one
+refuse case per rule and an accept case per kind; a refuse fixture yields exactly its rule.
+
+| Rule | Refuses |
+|------|---------|
+| `frontmatter` | no YAML frontmatter |
+| `frontmatter-key` | an unknown key, a repeated key, or a line that is not `key: value` (the key set is closed; this ends the read) |
+| `substrate-key` | one of the six substrate keys is missing |
+| `type` | `type` is not `spec` |
+| `kind` | `kind` missing or outside `index`, `spec`, `part` |
+| `maxlines` | `maxLines` differs from the kind's frozen cap |
+| `status` | a spec's `status` missing or outside `draft`, `live`, `retired` |
+| `revision` | a spec's `revision` missing or not an integer >= 1 |
+| `root-owns` | a part or an index carrying `status` or `revision` |
+| `slug` | a path segment outside the slug pattern |
+| `kind-path` | an index not named `index.md`, a part named `index.md` or placed at the store root, a contract root at the store root |
+| `root-uplink` | the store root without the exact up-link line before its first section |
+| `title` | the first heading is not the kind's title form, or a section opens before it |
+| `section-missing` | a required section absent |
+| `section-order` | the required and optional sections out of order |
+| `section-forbidden` | a section the kind never carries |
+| `fence` | a code fence line — a spec document carries no code sample; the reader models no markdown code |
+| `children-link` | a `## Children` line that is not a child link to a slug |
+| `children-duplicate` | a child listed twice |
+| `fan-out` | more than 30 children |
+| `scenario-line` | a `## Scenarios` line outside the scenario grammar |
+| `scenario-number` | scenario ids not contiguous from 1 |
+| `scenario-marker` | a marker whose slug or id differs from its own line |
+| `scenario-path` | a binding's test path that is not a repo-relative file |
+| `scenarios-empty` | a `## Scenarios` section carrying no scenario line |
+| `out-of-scope` | no non-blank bullet and not exactly `*(empty)*` |
+| `module-line` | a `## Module` line that is not a `- <path>` bullet |
+| `module-empty` | no module path and not exactly `*(empty)*` (a retired spec may carry the marker instead of a path) |
+| `module-traversal` | a module path with `..` |
+| `module-absolute` | an absolute module path |
+| `module-backslash` | a module path with a backslash |
+| `module-glob` | a module path with a wildcard |
+| `module-mix` | neither ONE `dir/` root nor a literal file list |
+| `parts` | `## Parts` on a flat spec, a malformed part link, or a part listed twice |
+
+## Lifecycle, binding and approval
+
+- **One entity.** A spec is the durable contract; the ephemeral plan is the delta vehicle; the spec
+  revision lands with the code. There is no change-spec entity.
+- **Governing specs are plural.** A plan cites ZERO (nothing spec-covered touched — legal during
+  adoption), ONE or MANY governing specs — one per touched spec-covered slice; a shared-module change
+  cites the specs of every slice whose contract it can alter.
+- **Out of scope composes PER GOVERNING SLICE — there is no global union.** Each cited spec's
+  exclusions bound only the work inside that slice, and the plan's non-goals restate them per slice.
+  A cross-spec conflict is resolved by a spec REVISION BEFORE plan approval — never by silent
+  precedence or review-time improvisation.
+- **Every contract change is reviewable at plan review.** A NEW feature's draft spec is authored WITH
+  the plan and exists AT review (a `create` ledger row); a plan that ALTERS a governed contract
+  carries the proposed revision at review the same way (a `modify` row). Approval confirms the plan
+  and every cited draft or revision atomically; the rows then land them. A contract is never
+  "confirmed" before it is visible.
+- **Test-as-spec binding is per scenario.** Every scenario names the test that pins it; a NEW
+  scenario on a live spec is individually `unbound` until its test lands within the same plan — the
+  spec's status never regresses for an extension. The binding is literal and language-agnostic: the
+  marker `spec:<slug>/S<N>` must occur exactly once in the named file. The honest claim is an
+  advisory structural pin; runnability and greenness stay the test suite's own gate. A marker is an
+  ORDINARY source line — it counts toward the source-size practice like any other, and a pinning file
+  already at its cap raises the recorded ratchet to host one. There is NO sidecar binding form:
+  retroactive coverage of a PUBLISHED package rides a release train, because the marker moves that
+  package's subtree.
+- **Containment** is lexical AND realpath on every path-bearing field (bindings, child links, module
+  roots). The reader judges the lexical half; realpath and symlink escapes are the structural
+  checker's duty (`spec-check`, a later slice), together with marker existence and uniqueness, link
+  resolution and the global invariants (slug uniqueness, module-root overlap, tree acyclicity) that
+  only a full-tree sweep can prove. The store ROOT is never an op target and needs no `root` verb: it
+  is the navigator, judged as the listing parent of its declared child.
+
+## Precedence — feature spec and page spec
+
+| Feature spec | Page spec | Governs |
+|--------------|-----------|---------|
+| present | present | the feature spec; `pages/<page>.md` is a subordinate view-layer document cited from it |
+| absent | present | the page spec, as an ADOPTION SHIM — the citing plan states Out of scope + Revision inline |
+| present | absent | the feature spec |
+
+`PAGE_TEMPLATE.md` is not upgraded for this; the durable fix is authoring the feature spec through
+the retroactive path below.
+
+## Spec and code
+
+- **A discoverable bijection.** The spec path mirrors the feature-slice path; a slug is IDENTICAL to
+  the slice or module name for NEW and deliberately refactored slices. A LEGACY module keeps its
+  existing name — the spec's declared module root IS the mapping, no rename ride-alongs; folder
+  promotion keeps the slug. A module root is a DIRECTORY or a DECLARED FILE SET, so a file-based
+  boundary binds without an architectural refactor.
+- **Spec drives modular, feature-sliced architecture.** Code is organized by feature slice, not by
+  technical layer; a spec's drill-down mirrors the slice's module boundaries; the pure rule / IO
+  shell split is the default module anatomy, composing with the source-size practice (a module you
+  can hold whole is the unit of review).
+- **ONE dependency rule: the dependency graph is explicit and acyclic.** A slice depends on `shared`
+  and on another slice's PUBLIC contract only when that edge is DECLARED in its spec; an undeclared
+  cross-slice reach-in is refused at review.
+- **Enforcement altitude, stated honestly.** This series the dependency and reach-in rules are
+  REVIEW-level canon defaults for NEW and deliberately refactored slices — no machine enforcement
+  (declared-edge fields, cycle checks, reach-in detection) ships; a legacy layered project is not
+  rendered nonconforming and adopts per feature through the retroactive path.
+
+## Spec and ADR
+
+Complementary, never competing: an ADR is the immutable, numbered, chronological WHY; a spec is the
+living, name-addressed WHAT. A spec cites its shaping ADRs in `## Links` via `[[AD-NNN]]`; an ADR
+that changes a contract triggers a spec revision.
+
+## Retroactive coverage
+
+The onboarding path for an existing feature: read the code, author a `draft` spec from it (the
+contract it actually keeps, the scenarios its tests already pin, the Out of scope its boundaries
+imply), then human review promotes it to `live` through a plan. The promoting event of a retroactive
+draft is PLAN APPROVAL — `live` lands in the SAME slice that authors the draft, once every scenario
+is bound; a slice whose whole deliverable is the specs needs no later plan to leave them provisional.
+Used to dogfood the family's own subsystems; a legacy module binds through a declared file set, never
+a refactor ride-along.
+
+## Scale
+
+The navigator walk is O(all docs) per pre-commit; the spec store joins it. The budget is a numeric
+release gate: 1500 ms for both hook runs over a valid 1000-spec, 30-per-folder tree (the median of
+three trials), measured by the repo's scale probe before every release of the checker — exceeding it
+is fixed inside the walk (cheaper per-file work, early exits), never queued. The structural checker
+is O(changed) by construction: it takes explicit spec paths, and `--all` is the explicit full sweep;
+a git-derived "changed" lane is refused, because hidden mode ignores `docs/ai/**` and git would see
+no spec at all.