From 78e8ee5297332b1fa19ad11b7e3c0ef02c4d8452 Mon Sep 17 00:00:00 2001
From: Mateus Andrade <133387879+protonspy@users.noreply.github.com>
Date: Tue, 7 Jul 2026 05:30:49 -0300
Subject: [PATCH 1/2] feat(plan): plan mode, decision records, and the glossary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Land the plan layer above specs and the two knowledge contracts that ride on it.

Plan mode (substrate): docs/plans/<slug>/ decomposes an initiative into feats,
each becoming exactly one spec. Adds the plan grammar (parse/validate), the
approval hash gate, the sequencer, deterministic briefs, the autonomous runner
and its sandbox, the /prd + quick-prd authoring skills, plan/feat graph nodes,
and the web read model.

Decision records (docs/adr/): a decision passing the triple gate — hard to
reverse, surprising without context, a real trade-off — becomes an ADR at
docs/adr/NNNN-<slug>.md. Feats cite it as adr:<slug>, a third ref token beside
stack: and [[wiki]]. `csdd plan validate` reports broken/ambiguous/malformed and
cites-superseded citations plus docs/adr well-formedness; `csdd plan brief`
inlines cited records in full with the open-decision forbidden line; the graph
emits adr nodes with cites/superseded_by edges and a broken/orphan-decision lint.
The prd skill grills gate-positive decisions one at a time (recording each ADR
inline), sweeps assumptions at Present, and funnels run deviations through
supersession; quick-prd carries the light gate. Dogfood: ADRs 0001-0003.

The glossary (docs/glossary.md): one canonical term per domain concept with an
_Avoid_ synonym list. A shared internal/glossary package parses, normalizes, and
whole-token matches identifiers. `csdd plan validate` reports an avoided term in a
feat/plan slug; `csdd graph analyze` / `csdd wiki lint` catch spec dirs and wiki
page names; the graph emits term nodes and references edges (orphan-term lint).
The glossary skill (challenge/sharpen/stress-test/record, the tombstone rule) and
/glossary command own the discipline; prd/quick-prd/wiki gain invocation hooks.
Dogfood: docs/glossary.md.
---
 docs/adr/0001-decision-records-storage.md     |    3 +
 docs/adr/0002-two-tier-interview.md           |    3 +
 docs/adr/0003-glossary-deferred.md            |    3 +
 docs/glossary.md                              |   52 +
 docs/plans/PLAN-decision-records.md           |  472 +++++++
 docs/plans/PLAN-glossary.md                   |  419 +++++++
 docs/plans/PLAN-knowledge-base.md             | 1093 +++++++++++++++++
 docs/plans/PLAN-plan-mode.md                  |  667 ++++++++++
 internal/cli/cli.go                           |    6 +
 internal/cli/glossary_cli_test.go             |  128 ++
 internal/cli/plan.go                          |  543 ++++++++
 internal/cli/plan_adr_test.go                 |  129 ++
 internal/cli/plan_bridge_cli_test.go          |  151 +++
 internal/cli/plan_cli_test.go                 |  130 ++
 internal/cli/plan_e2e_test.go                 |  168 +++
 internal/cli/plan_skill_test.go               |   45 +
 internal/cli/sandbox.go                       |  110 ++
 internal/cli/sandbox_cli_test.go              |   58 +
 internal/cli/spec.go                          |    7 +-
 internal/glossary/glossary.go                 |  266 ++++
 internal/glossary/glossary_test.go            |  136 ++
 internal/graph/analyze.go                     |  170 ++-
 internal/graph/extract.go                     |    3 +
 internal/graph/extract_adr.go                 |  131 ++
 internal/graph/extract_adr_test.go            |  114 ++
 internal/graph/extract_glossary.go            |  102 ++
 internal/graph/extract_glossary_test.go       |  129 ++
 internal/graph/extract_plan.go                |  281 +++++
 internal/graph/extract_plan_test.go           |  135 ++
 internal/graph/extract_spec.go                |   15 +-
 internal/graph/incremental.go                 |    2 +
 internal/graph/model.go                       |   13 +-
 internal/paths/paths.go                       |   19 +
 internal/plan/adr.go                          |  267 ++++
 internal/plan/adr_test.go                     |  259 ++++
 internal/plan/approve.go                      |   51 +
 internal/plan/brief.go                        |  247 ++++
 internal/plan/brief_test.go                   |  108 ++
 internal/plan/load.go                         |  115 ++
 internal/plan/model.go                        |  140 +++
 internal/plan/parse.go                        |  258 ++++
 internal/plan/parse_test.go                   |  250 ++++
 internal/plan/planjson.go                     |   42 +
 internal/plan/runner.go                       |  437 +++++++
 internal/plan/runner_exec.go                  |  210 ++++
 internal/plan/runner_test.go                  |  296 +++++
 internal/plan/sandbox.go                      |  269 ++++
 internal/plan/sandbox_test.go                 |  150 +++
 internal/plan/seq.go                          |  260 ++++
 internal/plan/seq_test.go                     |  157 +++
 internal/plan/status.go                       |  192 +++
 internal/plan/status_test.go                  |  179 +++
 internal/plan/validate.go                     |  436 +++++++
 internal/plan/validate_test.go                |  201 +++
 .../templates/commands/csdd-plan-run.md.tmpl  |   23 +
 .../commands/csdd-plan-status.md.tmpl         |   13 +
 .../commands/csdd-plan-validate.md.tmpl       |   11 +
 .../templates/commands/glossary.md.tmpl       |   22 +
 .../templater/templates/commands/prd.md.tmpl  |   29 +
 .../templater/templates/plan/plan.md.tmpl     |   64 +
 .../templates/root/knowledge-section.md.tmpl  |   40 +
 .../templates/sandbox/Dockerfile.tmpl         |   36 +
 .../sandbox/allowed-domains.txt.tmpl          |   36 +
 .../templates/sandbox/devcontainer.json.tmpl  |   25 +
 .../templates/sandbox/init-firewall.sh.tmpl   |   62 +
 .../templates/skills/glossary/SKILL.md.tmpl   |  109 ++
 .../templates/skills/prd/SKILL.md.tmpl        |  177 +++
 .../templates/skills/quick-prd/SKILL.md.tmpl  |   25 +
 .../templates/skills/wiki/SKILL.md.tmpl       |    3 +
 internal/web/frontend/src/App.tsx             |    6 +-
 internal/web/frontend/src/api.ts              |   12 +-
 .../web/frontend/src/components/PlansView.tsx |  181 +++
 internal/web/frontend/src/styles.css          |   49 +
 internal/web/frontend/src/types.ts            |   42 +
 internal/web/handlers.go                      |   16 +
 internal/web/plans.go                         |  142 +++
 internal/web/plans_test.go                    |  105 ++
 77 files changed, 11441 insertions(+), 14 deletions(-)
 create mode 100644 docs/adr/0001-decision-records-storage.md
 create mode 100644 docs/adr/0002-two-tier-interview.md
 create mode 100644 docs/adr/0003-glossary-deferred.md
 create mode 100644 docs/glossary.md
 create mode 100644 docs/plans/PLAN-decision-records.md
 create mode 100644 docs/plans/PLAN-glossary.md
 create mode 100644 docs/plans/PLAN-knowledge-base.md
 create mode 100644 docs/plans/PLAN-plan-mode.md
 create mode 100644 internal/cli/glossary_cli_test.go
 create mode 100644 internal/cli/plan.go
 create mode 100644 internal/cli/plan_adr_test.go
 create mode 100644 internal/cli/plan_bridge_cli_test.go
 create mode 100644 internal/cli/plan_cli_test.go
 create mode 100644 internal/cli/plan_e2e_test.go
 create mode 100644 internal/cli/plan_skill_test.go
 create mode 100644 internal/cli/sandbox.go
 create mode 100644 internal/cli/sandbox_cli_test.go
 create mode 100644 internal/glossary/glossary.go
 create mode 100644 internal/glossary/glossary_test.go
 create mode 100644 internal/graph/extract_adr.go
 create mode 100644 internal/graph/extract_adr_test.go
 create mode 100644 internal/graph/extract_glossary.go
 create mode 100644 internal/graph/extract_glossary_test.go
 create mode 100644 internal/graph/extract_plan.go
 create mode 100644 internal/graph/extract_plan_test.go
 create mode 100644 internal/plan/adr.go
 create mode 100644 internal/plan/adr_test.go
 create mode 100644 internal/plan/approve.go
 create mode 100644 internal/plan/brief.go
 create mode 100644 internal/plan/brief_test.go
 create mode 100644 internal/plan/load.go
 create mode 100644 internal/plan/model.go
 create mode 100644 internal/plan/parse.go
 create mode 100644 internal/plan/parse_test.go
 create mode 100644 internal/plan/planjson.go
 create mode 100644 internal/plan/runner.go
 create mode 100644 internal/plan/runner_exec.go
 create mode 100644 internal/plan/runner_test.go
 create mode 100644 internal/plan/sandbox.go
 create mode 100644 internal/plan/sandbox_test.go
 create mode 100644 internal/plan/seq.go
 create mode 100644 internal/plan/seq_test.go
 create mode 100644 internal/plan/status.go
 create mode 100644 internal/plan/status_test.go
 create mode 100644 internal/plan/validate.go
 create mode 100644 internal/plan/validate_test.go
 create mode 100644 internal/templater/templates/commands/csdd-plan-run.md.tmpl
 create mode 100644 internal/templater/templates/commands/csdd-plan-status.md.tmpl
 create mode 100644 internal/templater/templates/commands/csdd-plan-validate.md.tmpl
 create mode 100644 internal/templater/templates/commands/glossary.md.tmpl
 create mode 100644 internal/templater/templates/commands/prd.md.tmpl
 create mode 100644 internal/templater/templates/plan/plan.md.tmpl
 create mode 100644 internal/templater/templates/sandbox/Dockerfile.tmpl
 create mode 100644 internal/templater/templates/sandbox/allowed-domains.txt.tmpl
 create mode 100644 internal/templater/templates/sandbox/devcontainer.json.tmpl
 create mode 100644 internal/templater/templates/sandbox/init-firewall.sh.tmpl
 create mode 100644 internal/templater/templates/skills/glossary/SKILL.md.tmpl
 create mode 100644 internal/templater/templates/skills/prd/SKILL.md.tmpl
 create mode 100644 internal/web/frontend/src/components/PlansView.tsx
 create mode 100644 internal/web/plans.go
 create mode 100644 internal/web/plans_test.go

diff --git a/docs/adr/0001-decision-records-storage.md b/docs/adr/0001-decision-records-storage.md
new file mode 100644
index 0000000..3bd9438
--- /dev/null
+++ b/docs/adr/0001-decision-records-storage.md
@@ -0,0 +1,3 @@
+# Store decision records under docs/adr/ with an adr:<slug> citation token
+
+**Context.** Every load-bearing decision except technology had three destinations, all of which rot: "Context and vision" prose the parser ignores, `[ASSUMPTION]` markers nothing forces resolving, or nowhere at all — so the *why* never travelled with the *what* into specs and runner sessions. **Decision.** Decision records live in project-scoped `docs/adr/NNNN-<slug>.md` (append-only, one flat sequence, like `docs/stack.md`), and feats cite them with a third ref token, `adr:<slug>`, tokenized and linted beside `stack:` and `[[wiki]]`. **Why.** Reusing the proven stack-ref machinery (tokenize → validate → inline into the brief) makes hand-written ADRs first-class before any skill ships, and a lintable citation is what a plain `NNNN-slug.md` file alone lacks; the rejected alternatives — a wiki page (prose, not a contract) and a plan-scoped record (invisible to sibling plans) — both recreate the drift this feature removes.
diff --git a/docs/adr/0002-two-tier-interview.md b/docs/adr/0002-two-tier-interview.md
new file mode 100644
index 0000000..ee93dcb
--- /dev/null
+++ b/docs/adr/0002-two-tier-interview.md
@@ -0,0 +1,3 @@
+# Draft interviews in two tiers — batch scope facts, grill decisions
+
+**Context.** The prd skill's Draft used one batched multiple-choice interview ("1B, 2A, 3C") optimized for speed, which bundles load-bearing decisions in with scope facts so they pass undiscussed; pure one-at-a-time grilling (the studied grilling skill) is the opposite failure — it makes cheap scope facts as expensive as real decisions. **Decision.** Draft runs two tiers: the existing batched lettered multiple-choice for scope facts, then a sequential Decision grill (one decision per exchange, recommendation first, dependency order, ADR written inline) for every candidate that passes the triple gate. **Why.** csdd's batch already beats grilling for facts and grilling already beats batch for decisions, so splitting on the triple gate takes the strength of each; the grill applies only to the 2–5 gate-positive decisions a typical initiative carries, bounding the interview cost that killed pure grilling.
diff --git a/docs/adr/0003-glossary-deferred.md b/docs/adr/0003-glossary-deferred.md
new file mode 100644
index 0000000..59cfab6
--- /dev/null
+++ b/docs/adr/0003-glossary-deferred.md
@@ -0,0 +1,3 @@
+# Defer the glossary / ubiquitous language to its own phase
+
+**Context.** domain-modeling bundles a `CONTEXT.md` glossary (ubiquitous language, canonical entity aliases) with its ADR discipline, and it was tempting to ship both under the decision-records feature. **Decision.** The glossary is deferred to its own phase (`docs/plans/PLAN-glossary.md`) rather than folded into decision-records. **Why.** The glossary's real value is the canonical/alias entity table feeding the knowledge-base graph extractor, so it must be designed *with* the graph — a different seam than the plan-grammar/validate/brief seams this feature touches; conflating the two would widen this feature's blast radius for no shared machinery. This is the explicit "no" — the deferral is a decision, not an omission — and PLAN-glossary is the phase that resolves it.
diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 0000000..85532c6
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,52 @@
+# Glossary — csdd's ubiquitous language
+
+This is the project's **ubiquitous-language contract**: one canonical term per
+domain concept, defined as what it **is**, with an `_Avoid_` list of the synonyms
+it bans. Identifiers (feat slugs, spec directories, wiki page names) are minted
+from canonical terms; `csdd plan validate`, `csdd graph analyze`, and
+`csdd wiki lint` report an avoided term used as a whole token. Prose outside the
+`## Language` section is ignored by the parser.
+
+## Language
+
+### Planning
+
+**Plan**: The structured document above specs (`docs/plans/<slug>/`) that
+decomposes an initiative into feats; each feat becomes exactly one spec.
+_Avoid_: prd, epic
+
+**Feat**: One row of a plan's Feats table — a spec-sized chunk of work with an
+explicit objective, dependencies, and refs; it becomes exactly one spec.
+_Avoid_: feature, story, ticket
+
+**Spec**: The per-feature contract under `specs/<name>/` (requirements, design,
+tasks) that a feat is realized as.
+_Avoid_: specification-doc
+
+**Seed**: A pre-authored artifact under a plan's `seeds/<feat>/` that hands the
+eventual spec a head start.
+
+**Brief**: The deterministic context pack `csdd plan brief` assembles for one run
+step — the feat, its refs, decisions, and the step contract.
+
+### Contracts
+
+**Quality Gate**: A `- <label>: <command>` line in a plan's Quality Gates section;
+the runner executes every gate after each implementation step.
+
+**Stack Row**: One Decided-table row of `docs/stack.md` — a one-line technology
+contract a feat cites as `stack:<name>`.
+
+**ADR**: A decision record under `docs/adr/NNNN-<slug>.md` capturing a
+gate-positive decision (hard to reverse, surprising, a real trade-off); a feat
+cites it as `adr:<slug>`.
+_Avoid_: decision-doc
+
+### Knowledge base
+
+**Steering**: The project-memory documents under `.claude/steering/` (product,
+tech, structure) that source facts for the authoring flows.
+
+**Wiki Page**: One concept page under `docs/wiki/pages/<slug>.md`, derived from a
+raw source and cross-linked with `[[wikilinks]]`.
+_Avoid_: article
diff --git a/docs/plans/PLAN-decision-records.md b/docs/plans/PLAN-decision-records.md
new file mode 100644
index 0000000..5688a1d
--- /dev/null
+++ b/docs/plans/PLAN-decision-records.md
@@ -0,0 +1,472 @@
+# Master Plan — Decision Records (`docs/adr/` + the PRD decision grill)
+
+> **Audience:** the LLM agent (and humans) implementing this feature end-to-end.
+> **Status:** draft for review — revision 1 (2026-07-07). Not yet approved.
+> **Companions:** `docs/plans/PLAN-plan-mode.md` (the substrate — this feature extends
+> its plan grammar, validate, brief and graph seams; its code is in flight on this
+> branch); `docs/plans/PLAN-knowledge-base.md` (graph vocabulary this feature adds to);
+> github.com/mattpocock/skills — `productivity/grilling` and
+> `engineering/domain-modeling` (the two skills this design synthesizes, studied
+> 2026-07-07).
+> **Dogfood note:** the three decisions locked in this feature's own design session
+> (2026-07-07) — ADR storage + `adr:` token, the two-tier interview, glossary deferred —
+> each pass the triple gate below. Task 8 records them as `docs/adr/0001..0003`: the
+> first ADRs ever written, and the fixtures the lint is proven against.
+
+---
+
+## 1. Context and vision
+
+### 1.1 What we are building
+
+csdd's plan mode already treats one class of decision as a first-class object:
+**technology**. The Stack consult pass elicits options, a human decides, the decision
+lands as a `docs/stack.md` Decided row, feats cite it as `stack:<name>`, and
+`csdd plan validate` breaks on an uncited adoption. Elicitation → record → lintable
+reference — the full loop.
+
+Every **other** load-bearing decision — domain shape, boundaries between feats,
+integration patterns, deliberate deviations from the obvious path, scope trade-offs —
+has three destinations today, all of which rot the project long-term:
+
+1. **"Context and vision" prose** — the parser ignores it; when the plan becomes specs
+   and runner sessions execute, the *why* does not travel with the *what*.
+2. **`[ASSUMPTION]` markers** — nothing forces resolution before Present; an assumption
+   that survives approval is a decision made by nobody.
+3. **Nowhere** — the Draft interview's batched multiple-choice ("1B, 2A, 3C") is
+   optimized for speed; decisions with dependencies between them pass bundled with
+   scope facts, undiscussed.
+
+This plan generalizes the stack pattern to **all gate-positive decisions**:
+
+```text
+Decision (passes the triple gate)  →  ADR (docs/adr/NNNN-<slug>.md)
+    →  citation (adr:<slug> in a feat's Refs)  →  brief (inlined for every session)
+```
+
+**The triple gate is the admission contract.** A decision becomes an ADR only when all
+three hold: **hard to reverse** (the cost of changing your mind later is meaningful),
+**surprising without context** (a future reader will wonder "why did they do it this
+way?"), and **the result of a real trade-off** (there were genuine alternatives). If
+any is missing, it is prose or a cheap assumption — never an ADR. This is what designs
+out ADR spam.
+
+### 1.2 The skills synthesis (what we take, what csdd already has better)
+
+The design merges two studied skills. csdd adopts each practice and upgrades it with
+mechanics the skills lack:
+
+| Skill practice | csdd adaptation |
+|---|---|
+| grilling: one question at a time, each with a recommended answer | the **Decision grill** tier of Draft — sequential only for gate-positive decisions; scope facts stay batched (csdd's batch already beats grilling for facts) |
+| grilling: facts from the repo, decisions from the user | already prd law ("source facts; do not re-ask what is recorded"); now enforced on the decisions side too |
+| grilling: do not enact until confirmed | already exists and stronger: `csdd plan approve` is hash-bound |
+| grilling: shared understanding lives only in the conversation (its known gap) | closed: every resolved decision is an ADR file, immune to context loss |
+| domain-modeling: triple-gate ADR admission | adopted verbatim as the admission contract |
+| domain-modeling: minimal ADR format (`NNNN-slug.md`, 1–3 sentences) | adopted, plus a **lintable citation token** (`adr:<slug>`) the format alone lacks |
+| domain-modeling: write the record the moment it crystallises, never batched | the inline-write rule of the grill |
+| domain-modeling: CONTEXT.md glossary / ubiquitous language | **deferred** — own phase, designed with the graph (canonical entity aliases) |
+
+### 1.3 Value thesis (why this build order)
+
+- **The contract pays before the discipline exists.** Once `adr:` resolves in
+  `validate` and `docs/adr/` lints (M1), hand-written ADRs are already first-class —
+  citable, checkable, brief-inlined — with no skill change shipped.
+- **The brief is where the feature earns its keep.** PLAN-plan-mode's law is "anything
+  not covered by a contract is an open decision — the loop surfaces it and stops."
+  ADRs widen contract coverage from *technology* to *design*: a runner session
+  receives the why inline and is forbidden from silently re-deciding it.
+- **The discipline (M2) is template-only work** riding on a proven contract: the prd
+  skill's two-tier interview and the assumption sweep change authored prose, not Go.
+
+---
+
+## 2. Storage (extends the project-wide convention, revision 3)
+
+| Path | Role | Author |
+|---|---|---|
+| `docs/adr/NNNN-<slug>.md` | One decision record: title + 1–3 sentences (context, decision, why); optional `status`/`superseded-by` frontmatter. | Human/LLM prose (the skill writes it); linted by the CLI, never written by it. |
+
+Decisions are **project-scoped, never plan-scoped** (the `docs/stack.md` precedent): a
+decision made while authoring plan X must be visible when plan Y is authored — burying
+it in `docs/plans/<slug>/` recreates the failure mode this feature removes. Numbering
+is **append-only**; files are never renumbered.
+
+---
+
+## 3. Design principles (inviolable)
+
+1. **The triple gate is the admission contract.** Hard to reverse + surprising without
+   context + real trade-off — all three, or it is not an ADR. The skill states the
+   gate verbatim; the reviewer enforces it at approve.
+2. **The CLI never authors decisions.** The skill writes ADR files (authored prose,
+   like `plan.md`); the CLI lints them. Numbering is a mechanical convention
+   (scan highest + 1) covered by lint, not by generation — no `csdd adr` command
+   group in v1.
+3. **Decisions outlive their plan.** Project-level `docs/adr/`, one flat sequence.
+4. **The why travels with the what.** A cited ADR is inlined in full into every brief
+   for that feat; a gate-positive decision not covered by an ADR or stack row is an
+   open decision — the session stops, it never improvises.
+5. **Grill decisions, look up facts.** Anything recoverable from steering, `docs/`,
+   `specs/` or code is never a question; anything gate-positive is never bundled into
+   a batch.
+6. **Aggressive reuse.** `adr:` is a third ref token beside `stack:` and `[[wiki]]` —
+   same tokenizer, same validate pass, same brief assembly, same graph seam. No second
+   mechanism for a solved problem.
+
+---
+
+## 4. Requirements (content of `requirements.md`)
+
+EARS format. Requirement IDs in annotations are explicit comma-separated lists.
+
+### Requirement 1: The ADR contract
+**Objective:** As the toolchain, I want decision records machine-checkable where it
+matters, so citations resolve and the record set stays sound.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL treat as an ADR every `docs/adr/` file matching
+   `NNNN-<slug>.md` (NNNN four-digit zero-padded, slug kebab-case), whose content is
+   an optional frontmatter block followed by a `# <title>` heading and free prose.
+2. THE SYSTEM SHALL parse optional frontmatter keys `status`
+   (`accepted` when absent | `superseded`) and `superseded-by: <NNNN>`.
+3. THE SYSTEM SHALL resolve a slug to at most one file; body length (1–3 sentences)
+   is a skill convention, not a lint.
+
+### Requirement 2: `adr:` refs in the plan grammar
+**Objective:** As the plan parser, I want ADR citations tokenized like stack and wiki
+refs, so downstream passes work from explicit structure.
+**Acceptance Criteria**
+1. WHEN a plan's `Refs` cell contains `adr:<slug>` THEN the system SHALL tokenize it
+   into the feat's `ADRRefs` list, preserving the verbatim token in `Refs`
+   (the `model.go` superset contract).
+2. IF an `adr:` token's slug is empty or not kebab-case THEN `validate` SHALL report
+   a malformed decision ref.
+
+### Requirement 3: ADR lint (`csdd plan validate`)
+**Objective:** As a reviewer (human or runner), I want broken decision wiring surfaced
+mechanically, so the approve gate acts on sound citations.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL report every `adr:<slug>` ref with no matching `docs/adr/` file
+   ("broken decision ref") and every slug matching two or more files
+   ("ambiguous decision ref").
+2. WHERE `docs/adr/` exists THE SYSTEM SHALL report: malformed filenames, duplicate
+   numbers, a missing `# <title>` heading, and a `superseded-by` target that does not
+   exist ("dangling supersession").
+3. THE SYSTEM SHALL report a feat citing an ADR whose status is `superseded`
+   ("cites superseded decision — cite its successor").
+4. IF any violation is found THEN the system SHALL exit non-zero (the R3.5 precedent
+   of PLAN-plan-mode).
+
+### Requirement 4: ADRs in the brief (`csdd plan brief`)
+**Objective:** As a fresh runner session, I want the decisions my feat depends on
+inline in my context pack, so I execute the why instead of re-deriving it.
+**Acceptance Criteria**
+1. WHEN `brief` assembles a step for a feat with `ADRRefs` THEN the system SHALL
+   inline each cited ADR **in full** (title + body — they are short by format, the
+   stack-row treatment, not the wiki path-only treatment).
+2. WHERE a cited ADR does not resolve THE SYSTEM SHALL emit a WARNING line (the
+   broken-wiki-ref precedent in `brief.go`).
+3. THE brief's forbidden-actions block SHALL state: making a decision that passes the
+   triple gate and is not covered by a cited ADR or stack row is an **open decision** —
+   report `blocked` with a revision proposal; never improvise.
+4. THE SYSTEM SHALL remain byte-deterministic (R7.3 of PLAN-plan-mode).
+
+### Requirement 5: The Decision grill (prd skill, Draft pass)
+**Objective:** As the plan author, I want load-bearing decisions discussed one at a
+time and recorded the moment they resolve, so nothing structural passes bundled.
+**Acceptance Criteria**
+1. THE prd SKILL SHALL run Draft in two tiers: the existing batched lettered
+   multiple-choice for scope facts, then a **Decision grill** for every candidate that
+   passes the triple gate (stated verbatim in the skill).
+2. THE grill SHALL put decisions to the human **one at a time**, each with a
+   recommended answer, ordered so decisions that unblock other decisions come first.
+3. WHEN a decision is resolved THEN the skill SHALL write its ADR **immediately**
+   (scan-highest + 1 numbering; never batched) and cite it from the affected feats'
+   `Refs` at Decompose.
+4. THE SKILL SHALL look up facts (steering, `docs/stack.md`, `specs/`, code) instead
+   of asking, and SHALL never put a gate-negative question through the grill.
+
+### Requirement 6: Assumption discipline (prd skill, Present pass)
+**Objective:** As the approver, I want no unowned structural decisions hiding as
+assumptions, so approval means every trade-off was either discussed or knowingly
+deferred.
+**Acceptance Criteria**
+1. WHEN the Present pass begins THEN the skill SHALL sweep every remaining
+   `[ASSUMPTION]`; each that passes the triple gate SHALL be grilled into an ADR or
+   explicitly deferred by the human and re-marked `[DEFERRED-BY-HUMAN]` in `plan.md`.
+2. THE SKILL SHALL NOT present a plan for approval while a gate-positive
+   `[ASSUMPTION]` survives unmarked.
+
+### Requirement 7: The Revise funnel (prd skill)
+**Objective:** As the plan owner, I want run deviations that embody new decisions to
+leave the same trail as authoring-time decisions, so mid-flight choices are not
+second-class.
+**Acceptance Criteria**
+1. WHEN Revise processes a `log.md` deviation whose revision proposal embodies a
+   gate-positive decision THEN the skill SHALL grill it and write a new ADR — or mark
+   the superseded one (`status: superseded`, `superseded-by`) and write its
+   successor — **before** amending `plan.md` for re-approval.
+
+### Requirement 8: quick-prd, the light gate
+**Objective:** As a single-feature author, I want the same admission contract without
+the multi-feat ceremony, so small work leaves the same trail.
+**Acceptance Criteria**
+1. THE quick-prd SKILL SHALL state the triple gate and SHALL record every
+   gate-positive decision to `docs/adr/` in the same format (no sequential grill tier —
+   at single-feature scale decisions surface organically).
+2. THE produced PRD SHALL reference its ADRs so `/prd`'s Draft inherits them as
+   recorded decisions, not re-asked questions.
+
+### Requirement 9: ADRs in the graph
+**Objective:** As a knowledge-base user, I want decisions in the same graph as plans,
+specs and code, so "why" is one hop from "what".
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs THEN the system SHALL emit an `adr` node per record
+   (id from slug; attrs: number, title, status) with edges: feat `cites` adr, and adr
+   `superseded_by` adr.
+2. WHEN `csdd graph analyze` runs THEN the system SHALL surface broken/ambiguous
+   decision refs alongside the existing plan-ref lints, plus an informational
+   "orphan decision" (no inbound `cites`) — decisions may legitimately predate plans;
+   informational only.
+
+### Requirement 10: Satellites (templates + managed docs)
+**Objective:** As a csdd workspace, I want the convention visible everywhere authors
+look, so the mechanism is discoverable without reading this plan.
+**Acceptance Criteria**
+1. THE plan template's `Refs` column comment SHALL document the `adr:<slug>` token.
+2. THE root knowledge section SHALL gain the `docs/adr/` row of §2.
+3. THE managed CLAUDE.md section SHALL gain the moment: decisions passing the triple
+   gate become ADRs — never decide silently, never edit a superseded record.
+4. THE `/prd` command template SHALL describe the two-tier Draft and the ADR trail.
+
+---
+
+## 5. Design (content of `design.md`)
+
+### 5.1 Overview
+One new file in the in-flight plan package (`internal/plan/adr.go` — scan, parse,
+resolve) + surgical touches to `model.go`/`parse.go`/`validate.go`/`brief.go` + one
+graph extractor (`internal/graph/extract_adr.go`) + one paths helper + template edits.
+**Zero new CLI commands** — `validate`, `brief`, and `graph` gain behavior behind
+their existing surfaces.
+
+### 5.2 Goals / Non-Goals
+**Goals:** lintable decision records; `adr:` as the third ref token; broken/ambiguous/
+superseded citation lint; ADRs inlined in briefs with the open-decision rule; the
+two-tier Draft grill; the assumption sweep; the Revise funnel; quick-prd's light gate;
+adr nodes and `cites` edges in the graph.
+**Non-Goals (v1):** a `csdd adr` command group (numbering is lint-covered; promote to
+`csdd adr new` only if drift shows up in practice); glossary / `CONTEXT.md` /
+ubiquitous language (own phase, designed with the graph); ADR refs from spec artifacts
+(plan-level only — briefs carry them into sessions); a status lifecycle beyond
+`superseded-by` (one hop, no state machine); migrating legacy decisions out of
+existing prose; rendering ADRs in the web dashboard.
+
+### 5.3 Reuse map (verified against the current tree)
+| Need | Exists in | Use |
+|---|---|---|
+| Ref token pattern | `internal/plan/parse.go` (`stackRefPrefix`, `reWikiRef`; Refs tokenized ~L174) | add `adrRefPrefix = "adr:"` beside them |
+| Refs model contract | `internal/plan/model.go:46-48` (`WikiRefs`/`StackRefs`/`Refs` superset) | add `ADRRefs []string` |
+| Ref resolution findings | `internal/plan/validate.go:101-117` + normalize helpers (~L313-368) | ADR resolution findings in the same pass |
+| Full-row inlining | `internal/plan/brief.go:67-84` (stack rows §3) | ADR bodies get the same treatment |
+| Broken-ref WARNING | `internal/plan/brief.go:91` (wiki) | mirror for `adr:` |
+| Forbidden-actions text | `internal/plan/brief.go:20` (stack line) | add the open-decision line (R4.3) |
+| Graph extractor seam | `internal/graph/extract_plan.go` (`references`/`uses_tech` edges) | `extract_adr.go` + `cites`/`superseded_by` |
+| Paths | `internal/paths` (`DocsPlans`/`DocsWiki` pattern) | `DocsADR` |
+| Frontmatter | `internal/frontmatter` | ADR `status`/`superseded-by` |
+| Templates | `internal/templater` (embedded, LF-normalized) | skill/command/plan/knowledge edits |
+| Managed CLAUDE.md | `internal/cli/claudemd.go` | the decision moment (R10.3) |
+
+### 5.4 The ADR grammar (deterministic)
+- Filename: `^\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$`. Number = identity (stable,
+  append-only); slug = citation currency.
+- Content: optional frontmatter (`status`, `superseded-by`), then the first `# ` line
+  is the title; everything after is the body (convention: 1–3 sentences — context,
+  decision, why).
+- Resolution: strip the `NNNN-` prefix → slug → file. Two files sharing a slug is an
+  ambiguity finding (rename the newer before merge; citations bind to slugs, so a
+  rename is caught as a broken ref, never silent).
+- `superseded-by` targets a **number** (file identity), not a slug.
+
+### 5.5 Skill mechanics (the discipline, stated once)
+The triple gate lives verbatim in the prd skill's Decision grill section; quick-prd
+carries the same three bullets (accepted duplication — installed skills are
+self-contained files; the gate is three lines and stable). The grill's rules: one
+decision per exchange, recommendation first, dependency order, ADR written before the
+next question is asked (the domain-modeling inline rule), citation wired at Decompose.
+The Present sweep (R6) and Revise funnel (R7) close the two leaks that survive
+authoring: assumptions and mid-run deviations.
+
+### 5.6 CLI surface
+```text
+(unchanged)
+csdd plan validate <slug>   # gains: broken/ambiguous/malformed decision refs,
+                            #        docs/adr well-formedness, cites-superseded
+csdd plan brief <slug>      # gains: "## Decisions (docs/adr — the why)" section
+csdd graph build|analyze    # gains: adr nodes, cites/superseded_by, orphan lint
+```
+
+### 5.7 File structure plan
+```text
+internal/plan/adr.go            # scan docs/adr, parse, resolve slugs   [ADR]
+internal/plan/adr_test.go       # table-driven; fixtures in testdata/
+internal/graph/extract_adr.go   # adr nodes + cites/superseded_by       [Extract]
+docs/adr/0001..0003-*.md        # dogfood: this feature's own decisions (task 8)
+```
+**Modified:** `internal/plan/{model,parse,validate,brief}.go` (+ tests),
+`internal/paths/paths.go` (`DocsADR`), `internal/graph` (vocab + analyze),
+`internal/cli/claudemd.go` (moment), templates:
+`skills/prd/SKILL.md.tmpl`, `skills/quick-prd/SKILL.md.tmpl`,
+`commands/prd.md.tmpl`, `plan/plan.md.tmpl` (Refs comment),
+`root/knowledge-section.md.tmpl` (storage row).
+
+### 5.8 Requirements Traceability
+| Requirement | Components | Interfaces | Flows |
+|---|---|---|---|
+| 1.1, 1.2, 1.3 | ADR | ScanADRs(), ResolveADR() | validate/brief/graph |
+| 2.1, 2.2 | Parse, Model | ParsePlan() | all |
+| 3.1, 3.2, 3.3, 3.4 | Validate | ValidatePlan() | validate |
+| 4.1, 4.2, 4.3, 4.4 | Brief | Brief() | brief |
+| 5.1, 5.2, 5.3, 5.4 | Templates | prd skill Draft | authoring |
+| 6.1, 6.2 | Templates | prd skill Present | authoring |
+| 7.1 | Templates | prd skill Revise | revise |
+| 8.1, 8.2 | Templates | quick-prd skill | authoring |
+| 9.1, 9.2 | Extract | Extract(), AnalyzeGaps() | build/analyze |
+| 10.1, 10.2, 10.3, 10.4 | Templates, CLI | templater, claudemd | init/update |
+
+---
+
+## 6. Tasks (content of `tasks.md`) — TDD, boundaries, dependencies
+
+### Phase 1: The decision contract (M1)
+- [ ] 1. ADR store _Boundary: ADR_
+  - [ ] 1.1 RED — fixtures: filename grammar good/bad, duplicate numbers, frontmatter
+    (`status`, `superseded-by`), missing title, dangling supersession, slug
+    resolution + ambiguity
+    - _Requirements: 1.1, 1.2, 1.3_
+  - [ ] 1.2 GREEN — `internal/plan/adr.go` + `paths.DocsADR`
+    - _Requirements: 1.1, 1.2, 1.3_
+- [ ] 2. `adr:` in the plan grammar (P) _Boundary: Parse_
+  - [ ] 2.1 RED — tokenizer: `adr:<slug>` → `ADRRefs`; verbatim `Refs` superset holds;
+    malformed slug surfaced
+    - _Requirements: 2.1, 2.2_
+  - [ ] 2.2 GREEN — `parse.go` `adrRefPrefix` + `model.go` `ADRRefs`
+    - _Requirements: 2.1, 2.2_
+- [ ] 3. Validate findings _Boundary: Validate_
+  - [ ] 3.1 RED — each R3 finding class incl. cites-superseded; exit codes
+    - _Requirements: 3.1, 3.2, 3.3, 3.4_
+    - _Depends: 1.2, 2.2_
+  - [ ] 3.2 GREEN — `validate.go` wiring
+    - _Requirements: 3.1, 3.2, 3.3, 3.4_
+- [ ] 4. Brief inlining (P) _Boundary: Brief_
+  - [ ] 4.1 RED — cited ADR inlined in full; WARNING on broken ref; open-decision
+    forbidden-actions line present; byte-determinism (double-run equality)
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+    - _Depends: 1.2, 2.2_
+  - [ ] 4.2 GREEN — `brief.go`
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+- [ ] 5. Graph (P) _Boundary: Extract_
+  - [ ] 5.1 RED — adr nodes with attrs, `cites`/`superseded_by` edges, orphan-decision
+    informational, broken-ref lint parity with wiki refs
+    - _Requirements: 9.1, 9.2_
+    - _Depends: 1.2, 2.2_
+  - [ ] 5.2 GREEN — `extract_adr.go` + vocab + analyze rules
+    - _Requirements: 9.1, 9.2_
+
+### Phase 2: The discipline (M2 — template-only, rides on M1)
+- [ ] 6. prd skill: the Decision grill _Boundary: Templates_
+  - [ ] 6.1 RED — installed-skill assertions: triple gate verbatim; grill rules
+    (one-at-a-time, recommendation, dependency order, inline ADR write); two-tier
+    Draft intact (batch tier unchanged); Present sweep + `[DEFERRED-BY-HUMAN]`;
+    Revise funnel incl. supersession; `adr:` in Decompose/completion criteria
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 7.1_
+  - [ ] 6.2 GREEN — `skills/prd/SKILL.md.tmpl` + `commands/prd.md.tmpl`
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 7.1, 10.4_
+- [ ] 7. quick-prd + satellites (P) _Boundary: Templates_
+  - [ ] 7.1 RED — quick-prd gate + record rule + PRD-references-ADRs; plan template
+    Refs comment; knowledge-section row; claudemd moment
+    - _Requirements: 8.1, 8.2, 10.1, 10.2, 10.3_
+  - [ ] 7.2 GREEN — `skills/quick-prd/SKILL.md.tmpl`, `plan/plan.md.tmpl`,
+    `root/knowledge-section.md.tmpl`, `claudemd.go`
+    - _Requirements: 8.1, 8.2, 10.1, 10.2, 10.3_
+- [ ] 8. Dogfood seed + e2e
+  - [ ] 8.1 — author `docs/adr/0001-decision-records-storage.md` (docs/adr + `adr:`
+    token over wiki-page and plan-scoped alternatives),
+    `0002-two-tier-interview.md` (batch facts / grill decisions over pure-grilling
+    and batch-only), `0003-glossary-deferred.md` (ubiquitous language is its own
+    phase — the explicit no); e2e on a fixture workspace: a plan citing them
+    validates clean; broken/ambiguous/superseded variants produce their findings;
+    the brief inlines 0001 in full
+    - _Requirements: 1.1, 3.1, 3.3, 4.1_
+    - _Depends: 3.2, 4.2, 6.2_
+
+**Execution order:** {1, 2} → 3 → {4, 5} → {6, 7} → 8.
+
+---
+
+## 7. Milestones
+
+| Milestone | Delivery | Tasks |
+|---|---|---|
+| **M1 — The decision contract** | `docs/adr/` lints, `adr:` resolves in validate, briefs carry the why, decisions in the graph — hand-written ADRs are first-class before any skill changes | 1–5 |
+| **M2 — The discipline** | two-tier Draft grill, assumption sweep, Revise funnel, quick-prd gate, satellites; dogfood ADRs 0001–0003 recorded and linted | 6–8 |
+| **Post-v1** | `csdd adr new` scaffold (if numbering drift shows up); glossary/`CONTEXT.md` phase (canonical aliases feeding the graph extractor); `adr:` refs from spec artifacts; ADRs in the web dashboard; wiki page ⇄ ADR cross-linking | — |
+
+---
+
+## 8. Risks and decisions
+
+- **Gate applied loosely → ADR spam (the anti-goal).** Mitigation: the gate is stated
+  verbatim in both skills with the domain-modeling contrapositives ("if it's easy to
+  reverse, you'll just reverse it; if it's not surprising, nobody will wonder; if
+  there was no alternative, there is nothing to record"), and the completion criteria
+  make a gate-negative ADR a review finding.
+- **Gate text duplicated across prd and quick-prd (accepted).** Installed skills are
+  self-contained files; the gate is three stable bullets. The single-source
+  alternative (a shared format file) was rejected — it reintroduces the
+  domain-modeling repo's own drift bug across an install boundary.
+- **Slug ambiguity as `docs/adr/` grows (lint-bounded).** Ambiguity is a hard finding;
+  slugs are human-chosen at write time when the namespace is visible.
+- **In-flight substrate (sequenced, not risky).** This plan edits files that exist on
+  this branch but are not on main (`internal/plan/*`, `extract_plan.go`). Tasks 1–5
+  land after (or squashed with) PLAN-plan-mode M1/M3 — never in parallel PRs against
+  the same seams.
+- **Supersession is one hop, not a lifecycle (kept minimal).** `superseded-by`
+  answers "where is the current decision"; chains resolve by hopping. A status
+  machine is post-v1 if ever.
+- **Interview cost (bounded by design).** The grill applies only to gate-positive
+  candidates — typically 2–5 per initiative; scope facts stay batched. Pure
+  grilling's cost was the reason for the two-tier split (ADR 0002).
+- **Body length is a convention, not a lint** (the right-sizing precedent of
+  PLAN-plan-mode §8): the skill teaches 1–3 sentences; a length lint may come later
+  if records bloat.
+
+---
+
+## 9. Appendices
+
+### 9.1 References
+- `docs/plans/PLAN-plan-mode.md` — the substrate: plan grammar, validate, brief,
+  runner, and the contract-chain law this feature extends to design decisions.
+- `docs/plans/PLAN-knowledge-base.md` — graph vocabulary and extractor seam.
+- github.com/mattpocock/skills — `skills/productivity/grilling/SKILL.md` (the
+  interview mechanics) and `skills/engineering/domain-modeling/SKILL.md` (+
+  `ADR-FORMAT.md`, `CONTEXT-FORMAT.md`) — studied 2026-07-07.
+- Michael Nygard, "Documenting Architecture Decisions" (cognitect.com, 2011) — the
+  ADR canon the domain-modeling format minimizes.
+
+### 9.2 Executor notes (this repo / workstation)
+- **Verify:** `make check` (gofmt + vet + race). Distribution gate: `CGO_ENABLED=0`
+  via `make dist`.
+- **CLI pattern:** stdlib `flag` + subcommand switch in `internal/cli/cli.go`;
+  `--json` via the `jsonout` helpers; table-driven tests beside each file.
+- **Line endings:** CRLF working tree over LF index on this workstation — stage only
+  the paths you changed; never `git add -A`. ADR fixtures and templates must be
+  written LF.
+- **Flaky tests:** four update/clean `.old`-backup CLI tests fail non-deterministically
+  on `/mnt/c` (WSL) — re-run before treating as regression.
+- **Go toolchain:** `~/.local/go/bin` (export PATH + GOPATH/GOCACHE).
+- **Before starting:** `git fetch origin` and check open PRs — parallel sessions land
+  related work; this plan's seams are on an in-flight branch.
+- **Commits/PRs:** conventional style (`feat(plan): …`); repo templates forbid AI
+  attribution in commits/PRs.
diff --git a/docs/plans/PLAN-glossary.md b/docs/plans/PLAN-glossary.md
new file mode 100644
index 0000000..88c0e2f
--- /dev/null
+++ b/docs/plans/PLAN-glossary.md
@@ -0,0 +1,419 @@
+# Master Plan — The Glossary (`docs/glossary.md` + the ubiquitous-language discipline)
+
+> **Audience:** the LLM agent (and humans) implementing this feature end-to-end.
+> **Status:** draft for review — revision 1 (2026-07-07). Not yet approved.
+> **Companions:** `docs/plans/PLAN-decision-records.md` (the sibling discipline this
+> plan mirrors — M1 machine contract / M2 authoring discipline; ADR 0003 there records
+> the deferral this plan now resolves); `docs/plans/PLAN-plan-mode.md` (the substrate:
+> validate/analyze seams, in flight on this branch); `docs/plans/PLAN-knowledge-base.md`
+> (graph vocabulary); github.com/mattpocock/skills —
+> `engineering/domain-modeling/CONTEXT-FORMAT.md` (the format this adapts, studied
+> 2026-07-07).
+> **Dogfood note:** csdd's own domain — plan, feat, spec, seed, brief, quality gate,
+> steering, wiki page, stack row, ADR — becomes `docs/glossary.md` in task 6: the
+> glossary's first entries define the tool that lints them, and its `_Avoid_` lists
+> (feature, story, ticket, requirement-doc…) become the lint's first fixtures.
+
+---
+
+## 1. Context and vision
+
+### 1.1 What we are building
+
+csdd now has two normative project-level contracts: `docs/stack.md` (*with which
+technology*, `stack:` refs, Decided-row lint) and `docs/adr/` (*why this way*, `adr:`
+refs, triple-gate admission). Both answer questions; neither fixes **what things are
+called**. Terminology drift is the quietest form of project rot: the plan says
+"customer", a spec says "client", a wiki page says "account", feat slugs mint a fourth
+synonym — and the graph, which links by name, sees four unrelated things.
+
+This plan adds the third contract: **`docs/glossary.md`** — the project's ubiquitous
+language, adapted from domain-modeling's `CONTEXT.md`:
+
+```text
+Term (canonical, one meaning)  →  entry in docs/glossary.md (+ _Avoid_ aliases)
+    →  identifiers minted from canonical terms (feat slugs, spec dirs, wiki pages)
+    →  lint: avoided term in an identifier is a finding
+    →  graph: term nodes + references edges — "where is Customer used?" is a query
+```
+
+The enforcement insight (and the v1 boundary): **identifiers are where names
+crystallize and where matching is deterministic.** A feat slug, a spec directory, a
+wiki page name — token-matching those against canonical terms and `_Avoid_` aliases
+has zero false positives worth arguing about. Prose is where terminology *drifts*, but
+prose matching is fuzzy — so prose stays the skill's discipline (challenge, sharpen,
+record), never the linter's.
+
+### 1.2 The domain-modeling synthesis (what we take, what csdd upgrades)
+
+| domain-modeling practice | csdd adaptation |
+|---|---|
+| `CONTEXT.md` glossary, "totally devoid of implementation details" | `docs/glossary.md` — same purity rule, named for what it is (the `stack.md` sibling), parseable `## Language` grammar |
+| opinionated entries: canonical term + `_Avoid_` synonym list | adopted verbatim — and the `_Avoid_` list becomes **machine-enforceable** (identifier lint) instead of aspirational |
+| challenge conflicting terms, sharpen fuzzy language, stress-test with scenarios | the standalone **glossary skill** — one owner of the discipline, invoked by prd/quick-prd/wiki (the stack-skill composition precedent) |
+| cross-reference user claims against code | upgraded: `csdd graph query` first — the graph already indexes the workspace |
+| update `CONTEXT.md` inline the moment a term resolves, never batched | adopted — the ADR inline-write rule, same muscle |
+| lazy file creation | adopted — the skill creates `docs/glossary.md` on the first resolved term; `csdd init` scaffolds nothing |
+| `CONTEXT-MAP.md` multi-context repos | **deferred post-v1** — csdd targets single-context repos; the map adds real complexity for a rare case |
+| no term lifecycle (its known gap — meanings change silently) | **the tombstone rule:** a renamed canonical term moves to its successor's `_Avoid_` list — the lint then patrols the old name forever |
+
+### 1.3 Value thesis (why this build order)
+
+- **The contract pays before the discipline exists.** Once `docs/glossary.md` parses
+  and identifiers lint (M1), a hand-written glossary already renames the future: every
+  new feat slug, spec dir and wiki page is checked at authoring time.
+- **The graph is why the glossary lives here and not in a skill repo.** Term nodes +
+  `references` edges make language queryable (`csdd graph query customer`), and the
+  canonical/alias table is the entity-resolution seed the knowledge-base extractor has
+  been missing.
+- **The discipline (M2) is template-only work** on a proven contract — the
+  decision-records build order, repeated.
+
+---
+
+## 2. Storage (extends the project-wide convention, revision 3)
+
+| Path | Role | Author |
+|---|---|---|
+| `docs/glossary.md` | The ubiquitous language: canonical terms, tight definitions, `_Avoid_` aliases. A contract, not documentation — zero implementation details. | Human/LLM prose (the glossary skill writes it); parsed and linted by the CLI, never written by it. |
+
+Project-scoped, single file, created lazily by the skill (the `docs/stack.md`
+precedent — no root template). One flat `## Language` section; `###` clusters allowed
+when natural groups emerge.
+
+---
+
+## 3. Design principles (inviolable)
+
+1. **The glossary is a contract, not documentation.** Like `stack.md`: normative,
+   parseable, lint-backed. General programming concepts don't belong — only terms
+   unique to this project's domain.
+2. **The CLI never authors terms.** The skill writes entries; the CLI parses, lints,
+   and graphs them (the stack/ADR precedent). No `csdd glossary` command group.
+3. **Identifiers are the enforcement surface (v1).** Lint bites only where matching is
+   deterministic — feat slugs, spec dirs, wiki page names. Prose terminology is the
+   skill's job; a fuzzy lint that cries wolf trains users to ignore the whole linter.
+4. **Renames leave tombstones.** A replaced canonical term is appended to its
+   successor's `_Avoid_` list in the same edit — the old name stays banned forever,
+   mechanically. This is the term lifecycle, and it needs no state machine.
+5. **One owner of the discipline.** The glossary skill holds the moves (challenge,
+   sharpen, scenario-test, record inline); prd/quick-prd/wiki *invoke* it — they never
+   duplicate its rules (the drift-bug lesson).
+6. **Aggressive reuse.** Parse/normalize/finding/extractor patterns come from the
+   stack, wiki and plan machinery; the graph reuses `references` — one new node type,
+   zero new relations.
+
+---
+
+## 4. Requirements (content of `requirements.md`)
+
+EARS format. Requirement IDs in annotations are explicit comma-separated lists.
+
+### Requirement 1: The glossary contract
+**Objective:** As the toolchain, I want the language machine-readable, so lint and
+graph work from explicit structure.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL parse `docs/glossary.md` entries under `## Language`: a
+   `**<Term>**:` line, definition prose until the next entry, and an optional
+   `_Avoid_: <a>, <b>` line; `###` subheadings group entries into clusters without
+   affecting parsing.
+2. THE SYSTEM SHALL normalize terms and aliases for matching (lowercase, non-alnum
+   collapse — the `normalizeTechName` discipline) and SHALL treat multi-word terms as
+   contiguous token sequences in kebab-case identifiers.
+3. THE SYSTEM SHALL report as well-formedness findings: duplicate canonical terms, an
+   alias colliding with another entry's canonical term or alias, and an entry with no
+   definition prose.
+
+### Requirement 2: Identifier lint at authoring time (`csdd plan validate`)
+**Objective:** As the plan author, I want avoided terms caught before approval, so
+feat names are minted in canonical language.
+**Acceptance Criteria**
+1. WHERE `docs/glossary.md` exists THE SYSTEM SHALL report every feat slug (and the
+   plan slug) containing an `_Avoid_` alias as whole token(s) — "avoided term
+   '<alias>' in '<slug>' — canonical is '<term>'".
+2. WHERE `docs/glossary.md` exists THE SYSTEM SHALL surface its well-formedness
+   findings (R1.3) in the same pass (the ADR-dir precedent of
+   PLAN-decision-records R3.2).
+3. IF any violation is found THEN the system SHALL exit non-zero.
+
+### Requirement 3: Identifier lint workspace-wide (`csdd graph analyze`)
+**Objective:** As a knowledge-base user, I want the whole workspace held to the same
+language, so drift is visible wherever names live.
+**Acceptance Criteria**
+1. WHEN `csdd graph analyze` runs and `docs/glossary.md` exists THEN the system SHALL
+   report avoided-term matches in spec directory names and wiki page names,
+   domain-tagged so `csdd wiki lint` renders the wiki subset (§5.10 — lint is analyze
+   filtered).
+2. THE SYSTEM SHALL report an informational "orphan term" (no inbound `references`
+   edge) — terms may legitimately predate their first use; informational only.
+
+### Requirement 4: Terms in the graph
+**Objective:** As a knowledge-base user, I want language in the same graph as plans,
+specs and code, so "where is this concept used" is a query.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs THEN the system SHALL emit a `term` node per entry
+   (id from the normalized canonical term; attrs: definition, avoid aliases, cluster).
+2. THE SYSTEM SHALL emit a `references` edge from every feat, spec, and wiki page
+   whose identifier tokens match a term or one of its aliases (deterministic
+   whole-token match — alias matches carry an attr naming the matched alias, which is
+   what R3.1 surfaces).
+
+### Requirement 5: The glossary skill
+**Objective:** As any authoring session, I want one owner of the language discipline,
+so terminology is challenged and recorded the same way everywhere.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL install a **glossary skill** with the domain-modeling moves:
+   **challenge** a term conflicting with an existing entry the moment it appears;
+   **sharpen** vague or overloaded terms by proposing a canonical one (with the
+   recommended-answer form of the decision grill); **stress-test** boundaries with
+   concrete edge-case scenarios; **cross-reference** claims via `csdd graph query`
+   before asking the user.
+2. WHEN a term resolves THEN the skill SHALL update `docs/glossary.md` immediately
+   (never batched), creating the file lazily on the first entry.
+3. WHEN a canonical term is renamed THEN the skill SHALL append the old term to the
+   successor's `_Avoid_` list in the same edit (the tombstone rule).
+4. THE SKILL SHALL keep the glossary a contract: definitions of one or two sentences,
+   what it IS not what it does, project-specific terms only, zero implementation
+   details.
+
+### Requirement 6: Flow integration
+**Objective:** As the plan/spec/wiki flows, I want the glossary consulted where names
+are born, so canonical language is the path of least resistance.
+**Acceptance Criteria**
+1. THE prd SKILL's Draft SHALL route terminology conflicts and fuzzy terms surfaced by
+   the interview through the glossary skill, and Decompose SHALL mint feat slugs from
+   canonical terms (validate enforces per R2.1).
+2. THE quick-prd SKILL SHALL carry the same hook (challenge + record, no ceremony).
+3. THE wiki SKILL's Ingest SHALL consult the glossary when naming pages.
+4. THE SYSTEM SHALL install a **`/glossary` slash command** routing to the skill
+   (the `/prd` precedent for user-facing entry points).
+
+### Requirement 7: Satellites (managed docs)
+**Objective:** As a csdd workspace, I want the convention discoverable without reading
+this plan.
+**Acceptance Criteria**
+1. THE root knowledge section SHALL gain the `docs/glossary.md` row of §2.
+2. THE managed CLAUDE.md section SHALL gain the moment: when a domain term is
+   contested or fuzzy, invoke the glossary skill; identifiers use canonical terms;
+   never rename a term without its tombstone.
+
+---
+
+## 5. Design (content of `design.md`)
+
+### 5.1 Overview
+One new shared package `internal/glossary` (parse, normalize, match) consumed by both
+`internal/plan` (validate findings) and `internal/graph` (extractor + analyze) — the
+package exists because both sides need it and `plan` must not import `graph`. Plus one
+graph extractor, one paths helper, one new skill + command template, and hook edits in
+three existing skills. **Zero new CLI commands.**
+
+### 5.2 Goals / Non-Goals
+**Goals:** parseable glossary contract; well-formedness lint; avoided-term identifier
+lint in `plan validate` (feat/plan slugs) and `graph analyze` (spec dirs, wiki pages,
+wiki-lint filtered); `term` nodes + `references` edges; the glossary skill with the
+tombstone rule; prd/quick-prd/wiki hooks; `/glossary` command; satellites.
+**Non-Goals (v1):** multi-context (`CONTEXT-MAP.md`) — post-v1 if a real repo needs
+it; prose linting (even as warnings — deterministic surface only); a `csdd glossary`
+command group; alias-aware `[[wiki-ref]]` resolution (post-v1 — needs care to keep
+ref resolution deterministic); glossary-driven entity dedup inside the extractor
+(post-v1, builds on the same alias table); term pages in the web dashboard; migrating
+existing prose to canonical terms.
+
+### 5.3 Reuse map (verified against the current tree)
+| Need | Exists in | Use |
+|---|---|---|
+| Human-contract parse precedent | `internal/plan/validate.go` `decidedRows`/`decidedTech` (~L305-320) | same shape: `glossary.Parse` → term table |
+| Name normalization | `internal/plan/validate.go` `normalizeTechName`/`normalizeWikiSlug` + `reNonAlnum` (~L343-368) | `normalizeTerm` in `internal/glossary` (single home; plan/graph both import it) |
+| Lint = analyze filtered | `internal/graph/analyze.go:12-13,83` (findings domain-tagged spec\|wiki\|tech) | avoided-term findings tagged so `csdd wiki lint` shows the wiki subset |
+| Graph vocabulary constants | `internal/graph/model.go:34-77` (closed Type/Rel sets + meta mirror) | add `TypeTerm`; **reuse `RelReferences`** — no new relation |
+| Extractor seam | `internal/graph` `Extractor` (`extract_plan.go` precedent) | `extract_glossary.go` |
+| Paths | `internal/paths` (`StackSeg` L32, `Stack()` L116) | `GlossarySeg`, `Glossary()` |
+| Skill shape + composition | `templates/skills/stack/SKILL.md.tmpl` (Propose/Refine, invoked by prd) | `templates/skills/glossary/SKILL.md.tmpl` |
+| User-facing command | `templates/commands/prd.md.tmpl` | `templates/commands/glossary.md.tmpl` |
+| Managed CLAUDE.md | `internal/cli/claudemd.go` | the language moment (R7.2) |
+| Sibling plan mechanics | `docs/plans/PLAN-decision-records.md` (M1 contract / M2 discipline, well-formedness-in-validate precedent) | same two-milestone shape |
+
+### 5.4 The glossary grammar (deterministic)
+- Sections: everything outside `## Language` is free prose (parser ignores — the
+  plan.md discipline). Inside it, an entry is:
+  `**<Term>**:` → definition prose (≥1 line) → optional `_Avoid_: a, b, c`.
+- Matching: identifiers are tokenized on `-`/`_`; a term or alias matches on equal
+  normalized whole tokens; multi-word terms match contiguous token runs
+  (`purchase order` ⇢ `purchase-order-import`). Substring matches never count —
+  `client` does not match `clientele`.
+- Collisions (R1.3) are findings, not silent precedence: the glossary is small and
+  human-curated; ambiguity is fixed at the source.
+
+### 5.5 The discipline (stated once, in the skill)
+The glossary skill owns challenge/sharpen/scenario/record; the prd, quick-prd and wiki
+templates gain only an *invocation hook* ("route terminology through the glossary
+skill"), never the rules themselves — the single-owner answer to the format-file drift
+bug. Sharpening reuses the decision-grill interaction form (one term, a recommended
+canonical, the human decides) without the ADR gate: terms are cheap to record and the
+glossary is its own registry. Where a naming choice *is* gate-positive (a bounded
+concept split, a deliberate divergence from industry vocabulary), the skill hands it
+to the decision grill and the ADR cites the term — the two contracts compose instead
+of overlapping.
+
+### 5.6 CLI surface
+```text
+(unchanged)
+csdd plan validate <slug>   # gains: avoided-term in feat/plan slugs,
+                            #        glossary well-formedness
+csdd graph build            # gains: term nodes, references edges (alias-attributed)
+csdd graph analyze          # gains: avoided-term in spec/wiki identifiers,
+                            #        orphan-term (informational)
+csdd wiki lint              # gains: the wiki subset of the above, for free (filtered)
+```
+
+### 5.7 File structure plan
+```text
+internal/glossary/
+├── glossary.go        # Parse, Term, normalize, Match                [Glossary]
+└── glossary_test.go   # table-driven; fixtures in testdata/
+internal/graph/extract_glossary.go  # term nodes + references edges  [Extract]
+internal/templater/templates/skills/glossary/SKILL.md.tmpl           [Templates]
+internal/templater/templates/commands/glossary.md.tmpl               [Templates]
+docs/glossary.md                    # dogfood: csdd's own language (task 6)
+```
+**Modified:** `internal/plan/validate.go` (findings; drop the local normalizer in
+favor of `internal/glossary`'s if extraction is clean), `internal/paths/paths.go`,
+`internal/graph` (vocab + analyze), `internal/cli/claudemd.go`, templates:
+`skills/prd/SKILL.md.tmpl`, `skills/quick-prd/SKILL.md.tmpl`,
+`skills/wiki/SKILL.md.tmpl` (hooks), `root/knowledge-section.md.tmpl`.
+
+### 5.8 Requirements Traceability
+| Requirement | Components | Interfaces | Flows |
+|---|---|---|---|
+| 1.1, 1.2, 1.3 | Glossary | Parse(), Match() | validate/analyze/build |
+| 2.1, 2.2, 2.3 | Validate | ValidatePlan() | validate |
+| 3.1, 3.2 | Extract | AnalyzeGaps() | analyze/wiki-lint |
+| 4.1, 4.2 | Extract | Extract() | build |
+| 5.1, 5.2, 5.3, 5.4 | Templates | glossary skill | authoring |
+| 6.1, 6.2, 6.3, 6.4 | Templates | prd/quick-prd/wiki hooks, /glossary | authoring |
+| 7.1, 7.2 | Templates, CLI | knowledge-section, claudemd | init/update |
+
+---
+
+## 6. Tasks (content of `tasks.md`) — TDD, boundaries, dependencies
+
+### Phase 1: The language contract (M1)
+- [ ] 1. Glossary package _Boundary: Glossary_
+  - [ ] 1.1 RED — fixtures: entry grammar good/bad, clusters, duplicate terms, alias
+    collisions, empty definitions, normalization, whole-token + multi-word matching
+    (incl. the `clientele` non-match)
+    - _Requirements: 1.1, 1.2, 1.3_
+  - [ ] 1.2 GREEN — `internal/glossary` + `paths.Glossary`
+    - _Requirements: 1.1, 1.2, 1.3_
+- [ ] 2. Validate findings _Boundary: Validate_
+  - [ ] 2.1 RED — avoided-term in feat/plan slugs (canonical named in the message),
+    well-formedness surfaced, absent-glossary = silent, exit codes
+    - _Requirements: 2.1, 2.2, 2.3_
+    - _Depends: 1.2_
+  - [ ] 2.2 GREEN — `validate.go` wiring
+    - _Requirements: 2.1, 2.2, 2.3_
+- [ ] 3. Graph (P) _Boundary: Extract_
+  - [ ] 3.1 RED — term nodes with attrs; `references` edges from feat/spec/wiki
+    identifiers (alias-attributed); avoided-term findings domain-tagged (wiki subset
+    renders in `wiki lint`); orphan-term informational
+    - _Requirements: 3.1, 3.2, 4.1, 4.2_
+    - _Depends: 1.2_
+  - [ ] 3.2 GREEN — `extract_glossary.go` + `TypeTerm` vocab + analyze rules
+    - _Requirements: 3.1, 3.2, 4.1, 4.2_
+
+### Phase 2: The discipline (M2 — template-only, rides on M1)
+- [ ] 4. The glossary skill + `/glossary` _Boundary: Templates_
+  - [ ] 4.1 RED — installed-skill assertions: the four moves; inline-write + lazy
+    creation; the tombstone rule; graph-query-before-asking; contract purity rules;
+    gate-positive naming hands off to the decision grill
+    - _Requirements: 5.1, 5.2, 5.3, 5.4_
+  - [ ] 4.2 GREEN — `skills/glossary/SKILL.md.tmpl` + `commands/glossary.md.tmpl`
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 6.4_
+- [ ] 5. Flow hooks + satellites (P) _Boundary: Templates_
+  - [ ] 5.1 RED — prd Draft/Decompose hooks, quick-prd hook, wiki Ingest hook —
+    invocation only, no duplicated rules; knowledge-section row; claudemd moment
+    - _Requirements: 6.1, 6.2, 6.3, 7.1, 7.2_
+  - [ ] 5.2 GREEN — hook edits + `knowledge-section.md.tmpl` + `claudemd.go`
+    - _Requirements: 6.1, 6.2, 6.3, 7.1, 7.2_
+- [ ] 6. Dogfood seed + e2e
+  - [ ] 6.1 — author csdd's own `docs/glossary.md` (~10 entries: plan, feat, spec,
+    seed, brief, quality gate, steering, wiki page, stack row, ADR — with tombstones
+    like *feature/story* → feat, *PRD* → plan where the distinction bites); e2e on a
+    fixture workspace: an avoided feat slug fails `plan validate`, an avoided wiki
+    page name surfaces in `wiki lint`, term nodes answer `graph query`, and the
+    orphan-term informational fires
+    - _Requirements: 1.1, 2.1, 3.1, 3.2, 4.2_
+    - _Depends: 2.2, 3.2, 4.2_
+
+**Execution order:** 1 → {2, 3} → {4, 5} → 6.
+
+---
+
+## 7. Milestones
+
+| Milestone | Delivery | Tasks |
+|---|---|---|
+| **M1 — The language contract** | `docs/glossary.md` parses and lints; avoided terms caught in `plan validate`/`graph analyze`/`wiki lint`; terms queryable in the graph — a hand-written glossary is first-class before any skill ships | 1–3 |
+| **M2 — The discipline** | glossary skill + `/glossary`, hooks in prd/quick-prd/wiki, satellites; csdd's own glossary dogfooded | 4–6 |
+| **Post-v1** | `CONTEXT-MAP.md` multi-context; alias-aware `[[wiki-ref]]` resolution; glossary-driven entity dedup in the extractor; prose-tier warnings if identifier lint proves too narrow; term pages in the web dashboard | — |
+
+---
+
+## 8. Risks and decisions
+
+- **Generic `_Avoid_` words → false positives (bounded by design).** Whole-token
+  matching only, never substrings; findings name the canonical term so triage is one
+  glance; the glossary is human-curated — an alias too generic to ban is deleted with
+  a one-line edit. If a real repo still hurts, a per-alias opt-out beats loosening the
+  matcher.
+- **Prose drift stays invisible to the machine (accepted, v1).** The deliberate
+  boundary of principle 3: the skill challenges prose, the linter guards identifiers.
+  Widening to prose warnings is a post-v1 call made on evidence, not speculation.
+- **Two disciplines could blur (composed instead).** Terms are cheap (no gate,
+  glossary is the registry); decisions are gated (ADR). The skill's hand-off rule
+  (§5.5) keeps one boundary: *what we call it* → glossary; *why we chose it* → ADR
+  citing the term.
+- **In-flight substrate (sequenced, not risky).** This plan layers on the plan-mode
+  branch and touches the same `validate.go` seam as PLAN-decision-records — land the
+  three in order (plan-mode → decision-records → glossary), never parallel PRs on the
+  same files.
+- **Skill-invocation timing (the domain-modeling structural limit).** Challenge
+  moments need the skill in context; mitigation is placement, not hope — hooks live in
+  the three flows where names are born (prd, quick-prd, wiki) plus the claudemd
+  moment for everything else.
+- **`normalizeTechName` vs `normalizeTerm` (one home).** The normalizer moves to
+  `internal/glossary` only if the extraction is mechanical; duplicating three lines of
+  regex beats a tangled import graph — decided at task 1.2, noted here so the
+  reviewer expects either.
+
+---
+
+## 9. Appendices
+
+### 9.1 References
+- `docs/plans/PLAN-decision-records.md` — the sibling contract (ADR 0003 records this
+  plan's deferral) and the two-milestone shape this mirrors.
+- `docs/plans/PLAN-plan-mode.md` / `docs/plans/PLAN-knowledge-base.md` — substrate and
+  graph vocabulary.
+- github.com/mattpocock/skills — `skills/engineering/domain-modeling/` (`SKILL.md`,
+  `CONTEXT-FORMAT.md`), studied 2026-07-07.
+- Eric Evans, *Domain-Driven Design* (2003) — the ubiquitous-language canon the
+  CONTEXT.md format condenses.
+
+### 9.2 Executor notes (this repo / workstation)
+- **Verify:** `make check` (gofmt + vet + race). Distribution gate: `CGO_ENABLED=0`
+  via `make dist`.
+- **CLI pattern:** stdlib `flag` + subcommand switch in `internal/cli/cli.go`;
+  `--json` via the `jsonout` helpers; table-driven tests beside each file.
+- **Line endings:** CRLF working tree over LF index on this workstation — stage only
+  the paths you changed; never `git add -A`. Glossary fixtures and templates must be
+  written LF.
+- **Flaky tests:** four update/clean `.old`-backup CLI tests fail non-deterministically
+  on `/mnt/c` (WSL) — re-run before treating as regression.
+- **Go toolchain:** `~/.local/go/bin` (export PATH + GOPATH/GOCACHE).
+- **Before starting:** `git fetch origin` and check open PRs — parallel sessions land
+  related work; this plan's seams are on an in-flight branch shared with two sibling
+  plans.
+- **Commits/PRs:** conventional style (`feat(glossary): …`); repo templates forbid AI
+  attribution in commits/PRs.
diff --git a/docs/plans/PLAN-knowledge-base.md b/docs/plans/PLAN-knowledge-base.md
new file mode 100644
index 0000000..b2ad8cf
--- /dev/null
+++ b/docs/plans/PLAN-knowledge-base.md
@@ -0,0 +1,1093 @@
+# Master Plan — csdd Knowledge Base (`csdd graph` + `csdd wiki`)
+
+> **Audience:** the LLM agent that will implement this feature end-to-end.
+> **Status:** approved plan, ready for implementation. Sections 4/5/6 are the pre-authored
+> content of `requirements.md` / `design.md` / `tasks.md` for the csdd spec flow.
+> **Companions:** `docs/graph/README.md` (schema doc), `docs/graph/graph.json` (hand-seeded fixture),
+> `docs/graph/log.md`, `graphify/ANALISE-ARQUITETURA.md` (graphify internals study),
+> `graphify/llm-wiki.md` (Karpathy's LLM-wiki pattern).
+> **Supersedes:** `docs/plans/PLANO-graph-index.md` (Portuguese, graph-only scope).
+> **Revision 2 (2026-07-06):** re-scoped after value review — spec lint (`analyze`) is the
+> immediately-paying core; the Go code extractor is promoted into scope (M3); the full
+> query engine and incremental builds are deferred to the scale milestone (M4), because
+> they only pay off once source code makes the graph large.
+> **Revision 3 (2026-07-06):** storage split by purpose — the compiled knowledge index
+> moved to `docs/graph/` (the only generated subtree in `docs/`); `.csdd/` now holds
+> operational state only (manifests, caches, incremental state); added R14 + task 16
+> (update-manifest migration from `.claude/.csdd-manifest.json` with legacy fallback).
+> **Revision 4 (2026-07-06):** `.csdd/` becomes the **workspace marker** (today it is
+> `.claude/`), and `csdd init` scaffolds the **complete development layout** —
+> `specs/`, `docs/plans|raw|wiki|graph/`, `.claude/`, `.csdd/` — added R15 + task 17.
+> Agent integration added (R16): graph + wiki **skills** driving everything through
+> `csdd`/`npx csdd`, **slash commands** (`/csdd-graph-*`, `/csdd-wiki-*`) for direct
+> user control, and a managed **CLAUDE.md** section teaching the workflow moments.
+> **Revision 5 (2026-07-06):** the **tech contract** (R17, task 18) — `docs/stack.md`
+> pins stack/library decisions as a human-authored contract; manifests are indexed and
+> diffed against it (undeclared/phantom/unrefined tech lints); a **stack skill**
+> (Propose/Refine/Reconcile, human-decision gate) plus `/csdd-stack-*` commands; and
+> CLAUDE.md gains the ask-first + refine-via-Context7/web protocol and the skill's
+> invocation moments. Kills silent architectural decisions.
+
+---
+
+## 1. Context and vision
+
+### 1.1 What we are building
+
+csdd is a spec-driven-development CLI: a single static Go binary that scaffolds and
+governs `specs/` (requirements → design → tasks), `.claude/` (steering, skills, agents),
+`CLAUDE.md`, and `.mcp.json`. Its reason to exist is **traceability** — every task traces
+to a requirement, every component to a criterion.
+
+This plan adds csdd's **knowledge base**, made of two cooperating halves:
+
+1. **`csdd graph`** — **a structured brain for fast, token-cheap, precise consultation
+   of the project's source code.** That sentence is the mission — and its point is that
+   **the LLM should not need to read the whole codebase to understand it**. Instead of
+   consuming thousands of lines to build a mental map, the LLM queries the graph and
+   gets the structure directly: what exists, what connects to what, where the hubs are,
+   which patterns repeat. Understanding comes from traversing relationships (a few
+   hundred tokens), not from re-reading source (hundreds of thousands). Concretely: a
+   deterministic, persistent knowledge graph (`docs/graph/graph.json`, NetworkX node-link
+   format) — retrieval in milliseconds, answers scoped to a token budget, edges that
+   are facts (extracted, not guessed), patterns surfaced by structure (god nodes,
+   communities, dependency chains). It indexes every artifact csdd governs, the
+   documentation under `docs/`, and — from M3, the milestone where the mission is
+   fulfilled — the project's **Go source code**. Along the way it answers the question
+   csdd exists for: *"what connects this requirement to the code, and what breaks if I
+   change this task?"* — queryable traceability + mechanical gap detection across the
+   whole spec.
+
+2. **`csdd wiki`** — a standardized instantiation of **Karpathy's LLM-wiki pattern**
+   (`graphify/llm-wiki.md`): a pipeline that turns **raw sources** the user drops into
+   `docs/raw/` (immutable — articles, notes, transcripts, clippings) into a **solid,
+   structured, LLM-consumable knowledge base** under `docs/wiki/` — a persistent,
+   interlinked markdown wiki. **Content is authored by LLM sessions** (via a skill csdd
+   installs); **structure is scaffolded and linted by the CLI** (deterministic
+   operations only). The wiki is NOT about the specs — it is a general knowledge-base
+   layer over `docs/`. It is also just another corpus for the graph engine — one
+   knowledge base, two faces.
+
+### 1.2 The synthesis of three sources
+
+| Source | What we take |
+|--------|--------------|
+| **graphify** | The *structural technique*: `{nodes,edges}` contract, single canonical ID, confidence tiers, query engine with hub-gating + token budget, incremental replace-per-source. |
+| **Karpathy LLM-wiki** | The *lifecycle*: a persistent artifact "compiled once, kept current"; Ingest/Query/Lint operations; `index.md` + `log.md`; a co-evolved schema doc. |
+| **csdd** | The *domain and discipline*: SDD traceability as a first-class citizen; **deterministic extraction** (no LLM in the binary — honest, reviewable, mechanically validated); CLI as the sole author of generated data. |
+
+### 1.3 The discovery that anchors the approach
+
+csdd artifacts **already carry explicit traceability annotations** (verified in
+`internal/templater/templates/spec/*.tmpl`):
+
+- `tasks.md`: `_Requirements: 1.1, 1.2_`, `_Boundary: X_`, `_Depends: 3.1_`, `(P)` marker, checkboxes.
+- `design.md`: a **Requirements Traceability** table, `**Requirements**: 1.1, 1.2` per component, `**Dependencies**` (Inbound/Outbound/External).
+- `requirements.md`: `### Requirement N` headings + numbered EARS criteria `N.M`.
+- wiki pages (this plan): YAML frontmatter + `[[wikilinks]]` — both explicit.
+
+**Consequence:** ~95% of edges are `EXTRACTED` (explicit links). The extractor is
+deterministic annotation parsing — **pure Go, no tree-sitter, no LLM, no cgo**. The
+distribution constraint (`CGO_ENABLED=0`, 6 release targets, offline single binary)
+stays intact. Source code enters later through the same seam using `go/parser`
+(stdlib, cgo-free).
+
+### 1.4 Value thesis (why this build order)
+
+The prime objective is the **code brain**: the LLM understands the codebase by querying
+its structure, not by reading all of it. Fast (pre-built index, no re-derivation per
+question), token-cheap (budgeted subgraph answers instead of file dumps), precise
+(edges are extracted facts with confidence labels, not similarity guesses) — and,
+above all, **comprehension without exhaustive reading**: architecture questions ("what
+depends on X?", "what implements Y?", "where are the hubs?") answered by traversal, and
+recurring patterns made visible by the graph's shape instead of discovered by scanning
+files. The build order is how we get there without a leap of faith:
+
+- **`csdd graph analyze` pays for itself immediately.** Traceability annotations are
+  write-only today — the templates demand them, nothing consumes them. A mechanical
+  lint of the SDD contract (untested criteria, orphan tasks, unimplemented components,
+  pending references, dependency cycles) is csdd's core promise made checkable. It ships
+  first (M1) and validates the whole substrate (model, IDs, extraction, assembly) on a
+  small corpus.
+- **The code graph fulfills the mission.** A knowledge graph of dozens of markdown
+  artifacts is readable without a graph; the *brain* only exists when source code joins
+  it (M3). The Go extractor is therefore in scope, not a vague future.
+- **Scale machinery follows the corpus, it does not precede it.** The full query engine
+  (IDF, trigrams, hub-gating, **token budgets** — the "cheap" in the mission) and
+  incremental builds (hash-skip, replace-per-source — the "fast" as the codebase grows)
+  were designed by graphify for thousands of nodes. At M1 corpus size a full rebuild is
+  milliseconds and label matching answers queries. Both are specified now (§5.11, §5.9)
+  and implemented in M4, immediately after the code corpus makes them matter.
+
+---
+
+## 2. Storage convention (decided, project-wide — revision 3: split by purpose)
+
+| Directory | Role | Author |
+|-----------|------|--------|
+| **`docs/`** | The **knowledge base** — everything committed and shared: `docs/plans/` (plans), `docs/stack.md` (**the tech contract** — human-authored stack decisions, R17), `docs/raw/` (**immutable raw sources**, user-curated dropzone — read, never modified), `docs/wiki/` (**LLM-authored structured knowledge**), and **`docs/graph/`** — the compiled knowledge index (`graph.json`, `graph.html`, build `log.md`), the **only generated subtree in `docs/`**, marked read-only by its README. | Humans and LLM sessions author prose; the CLI writes **only** `docs/graph/` and never touches `raw/`. |
+| **`.csdd/`** | csdd's **operational state** — the csdd analog of `.git/`: hash manifests (the `csdd update` manifest migrates here from `.claude/.csdd-manifest.json`, R14), incremental build state and caches (M4). No knowledge artifacts. **Its presence at the project root is the workspace marker** (R15): `csdd init` creates it; workspace-requiring commands validate it. | **The CLI only.** `cache/`/`state.json` are local (gitignored) and regenerable; manifests are committed. |
+
+Ownership is assigned **by purpose**: knowledge (committed, shared, reviewed in PRs)
+lives in `docs/`; disposable machine state lives in `.csdd/`. The git story is trivial —
+commit all of `docs/`, ignore `.csdd/` except manifests.
+
+---
+
+## 3. Design principles (inviolable)
+
+1. **100% pure Go, cgo-free.** No new heavy dependency. `norm.NFKC` comes from
+   `golang.org/x/text` (already in `go.sum`); code parsing uses stdlib `go/parser`.
+2. **The CLI never authors prose.** It owns `.csdd/` (operational state) and exactly
+   one generated subtree of the knowledge base — `docs/graph/` — which humans and LLMs
+   treat as read-only. Everything else under `docs/` is human/LLM-authored: the CLI may
+   scaffold and lint it, never write content, and never touch `docs/raw/`. TUI/web are
+   read-only views.
+3. **Deterministic and idempotent.** Same input → byte-identical `docs/graph/graph.json`
+   (clean git diffs). No LLM calls, no wall-clock in output (except the build log).
+4. **Aggressive reuse.** `internal/manifest`, `internal/session/changedetect.go`,
+   `internal/frontmatter`, `internal/paths`, `internal/textutil`, `internal/templater`,
+   `internal/web` embed patterns.
+5. **Honesty over recall.** Structural ambiguity → omission; `AMBIGUOUS` only where real
+   uncertainty exists (for the human gate). Unresolved references are **reported, never
+   silently dropped** — in csdd the gap *is* the product.
+6. **The graph engine is corpus-agnostic.** All corpora enter through one `Extractor`
+   contract (§5.4): spec artifacts, `.claude/`, the wiki (M1), Go source (M3). Nothing
+   downstream of extraction may know which corpus a fragment came from.
+7. **Scale machinery follows the corpus.** Features whose value depends on graph size
+   (full query engine, incremental builds) land only when the corpus that justifies
+   them does (M4, after code indexing). Until then, simpler mechanisms with identical
+   external behavior.
+
+---
+
+## 4. Requirements (content of `requirements.md`)
+
+EARS format (WHEN/IF/WHILE/WHERE/THE SYSTEM SHALL), as the csdd template requires.
+Requirement IDs in annotations are always **explicit comma-separated lists** — range
+shorthand (`3.1–3.5`) is forbidden because the parser does not resolve it.
+
+### Requirement 1: Index workspace artifacts into a graph
+**Objective:** As a maintainer of a csdd workspace, I want artifacts indexed into a
+graph, so I can navigate relationships instead of re-reading files.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs THEN the system SHALL write `docs/graph/graph.json`
+   (node-link) covering all of `specs/`, `.claude/`, `CLAUDE.md`, `.mcp.json`, and
+   `docs/` (when present).
+2. THE SYSTEM SHALL emit one node per artifact/entity with
+   `{id, label, file_type, source_file, source_location}`.
+3. WHERE an artifact carries an explicit traceability annotation THE SYSTEM SHALL mark
+   the edge `EXTRACTED` with `confidence_score` 1.0.
+4. THE SYSTEM SHALL generate deterministic node IDs (NFKC → non-word→`_` → casefold),
+   identical across rebuilds.
+
+### Requirement 2: Query the graph (query / path / explain — v1 surface)
+**Objective:** As an agent or human, I want to look up nodes and trace paths, to find
+what connects to what without re-reading files.
+**Acceptance Criteria**
+1. WHEN `csdd graph query "<terms>"` runs THEN the system SHALL return the matching
+   nodes and their immediate neighborhood, matched by label tiers
+   (exact > prefix > substring), in deterministic order.
+2. WHEN `csdd graph path A B` runs THEN the system SHALL return the shortest path with
+   each edge's real direction, or an error if A resolves to the same node as B.
+3. WHEN `csdd graph explain <label>` runs THEN the system SHALL list the node plus its
+   connections ordered by neighbor degree.
+
+### Requirement 3: Surface traceability gaps (the "Lint" operation for specs)
+**Objective:** As a reviewer, I want the graph to point out contract violations across
+the whole spec, so the human gate acts before merge.
+**Acceptance Criteria**
+1. WHEN `csdd graph analyze` runs THEN the system SHALL list every acceptance criterion
+   with no task realizing it ("untested requirement").
+2. THE SYSTEM SHALL list every task without a `_Requirements` annotation ("orphan task").
+3. THE SYSTEM SHALL list every design component with no task pointing at it via
+   `_Boundary` ("unimplemented component").
+4. IF a `_Depends`/traceability annotation references a nonexistent ID THEN the system
+   SHALL report it as a "pending reference".
+5. IF `depends_on` edges form a cycle THEN the system SHALL report it.
+
+### Requirement 4: Deterministic, logged rebuilds
+**Objective:** As a user, I want every build to be reproducible and recorded, so the
+graph is trustworthy and its history auditable.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs THEN the system SHALL fully rebuild the graph from the
+   corpus, producing byte-identical output for an unchanged corpus. (v1 has no
+   incremental mode; at v1 corpus size a full rebuild is imperceptible — see R13.)
+2. THE SYSTEM SHALL append one line to `docs/graph/log.md` on every build.
+
+### Requirement 5: Pure Go / cgo-free
+**Objective:** As the distribution maintainer, I want the feature to preserve the static
+binary model, so all 6 targets keep compiling without a C toolchain.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL compile with `CGO_ENABLED=0` for the 6 release targets (`make dist`).
+2. THE SYSTEM SHALL NOT introduce a dependency requiring cgo or an external toolchain.
+
+### Requirement 6: CLI + web surfaces
+**Objective:** As a user, I want the graph via CLI and visualized in the dashboard, to
+consume it however fits.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL expose `csdd graph build|query|path|explain|analyze|export` and
+   `csdd wiki init|lint`.
+2. WHEN `csdd graph export` runs THEN the system SHALL write a self-contained
+   `docs/graph/graph.html` (vis-network inlined, no external asset).
+3. WHERE the web dashboard is active THE SYSTEM SHALL serve a "Graph" tab reading
+   `docs/graph/graph.json`, through the same read-only hardening path as existing routes.
+
+### Requirement 7: Storage layout — knowledge in `docs/`, state in `.csdd/`
+**Objective:** As a user, I want generated knowledge in one predictable committed place
+and machine state out of my way, so PRs review knowledge and state stays disposable.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL write generated knowledge artifacts (`graph.json`, `graph.html`,
+   the build `log.md`) under `docs/graph/` and SHALL NOT write generated files anywhere
+   else in `docs/`.
+2. THE SYSTEM SHALL keep `docs/graph/graph.json` byte-stable when the corpus is
+   unchanged (total deterministic ordering of nodes and edges).
+3. THE SYSTEM SHALL treat paths as workspace-root-relative (portable across machines).
+4. THE SYSTEM SHALL keep operational state (caches, incremental state, hash manifests)
+   under `.csdd/`, with everything except committed manifests regenerable from scratch.
+
+### Requirement 8: Interoperability with the graphify format
+**Objective:** As an ecosystem user, I want the graph loadable by NetworkX/graphify
+tooling, to reuse visualizers and loaders.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL emit node-link JSON with keys `{directed, multigraph, graph, nodes, links}`.
+2. THE SYSTEM SHALL use confidence labels `EXTRACTED|INFERRED|AMBIGUOUS`.
+
+### Requirement 9: Wiki scaffolding (`csdd wiki init`)
+**Objective:** As a user adopting the LLM-wiki pattern, I want the CLI to stand up the
+standard structure and teach my LLM how to maintain it, so every csdd workspace gets the
+same disciplined wiki.
+**Acceptance Criteria**
+1. WHEN `csdd wiki init` runs THEN the system SHALL create `docs/raw/` (the immutable
+   source dropzone) and `docs/wiki/` containing `index.md` (content catalog), `log.md`
+   (append-only chronology with the `## [YYYY-MM-DD] <op> | <title>` entry format
+   documented inline), and `pages/`.
+2. THE SYSTEM SHALL install the wiki **schema doc** (conventions, the raw→wiki pipeline,
+   and Ingest/Query/Maintain workflows for the LLM) through csdd's existing
+   steering/skill mechanisms (`internal/templater`): a steering rule plus a `wiki`
+   skill under `.claude/skills/`.
+3. THE SYSTEM SHALL NOT author wiki content and SHALL NOT modify anything under
+   `docs/raw/` — pages are written by LLM sessions following the installed skill; raw
+   sources are read-only for everyone but the user.
+4. WHERE `docs/wiki/` already exists THE SYSTEM SHALL leave existing files untouched and
+   only add missing scaffold files (idempotent; `--force` required to overwrite).
+
+### Requirement 10: Wiki lint (`csdd wiki lint`)
+**Objective:** As a wiki owner, I want mechanical health checks, so the wiki stays
+navigable as it grows (the deterministic half of Karpathy's "Lint").
+**Acceptance Criteria**
+1. WHEN `csdd wiki lint` runs THEN the system SHALL report every broken `[[wikilink]]`
+   (target page absent).
+2. THE SYSTEM SHALL report orphan pages (no inbound `links_to` edge and not listed in
+   `index.md`).
+3. THE SYSTEM SHALL report index desync in both directions: pages missing from
+   `index.md`, and `index.md` entries pointing at missing files.
+4. THE SYSTEM SHALL report `log.md` entries that do not match the documented
+   `## [YYYY-MM-DD] <op> | <title>` format.
+5. THE SYSTEM SHALL report every raw source under `docs/raw/` with no inbound
+   `derived_from` edge ("unprocessed source" — dropped but never ingested).
+6. IF any violation is found THEN the system SHALL exit non-zero (CI-gateable).
+
+### Requirement 11: The wiki is a graph corpus
+**Objective:** As a knowledge-base user, I want wiki pages inside the same graph, so
+queries and analysis span specs and documentation as one knowledge base.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs and `docs/` exists THEN the system SHALL index wiki
+   pages as `wiki_page` nodes carrying frontmatter attributes (tags, dates) and every
+   file under `docs/raw/` as an opaque `raw_source` node (path only, content unparsed).
+2. THE SYSTEM SHALL emit `links_to` edges (`EXTRACTED`, 1.0) for `[[wikilinks]]`,
+   `derived_from` edges (wiki_page → raw_source) for sources cited in page frontmatter
+   (`sources:` list) or links to `raw/` paths, and `references`/`reuses` edges for other
+   repo paths cited in pages.
+3. THE SYSTEM SHALL compute `csdd wiki lint` findings from this same graph (single
+   source of truth — lint is `analyze` filtered to the wiki corpus).
+
+### Requirement 12: Index Go source code (M3 — the code graph)
+**Objective:** As a developer, I want the project's Go source in the same graph, so
+traceability reaches real code and the graph grows with the codebase.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs in a workspace containing `.go` files THEN the system
+   SHALL emit `code` nodes for packages, files, and top-level declarations (functions,
+   methods, types), extracted with stdlib `go/parser` (syntax-only, cgo-free).
+2. THE SYSTEM SHALL emit containment edges (package → file → declaration) and
+   package-import edges, all `EXTRACTED` with score 1.0.
+3. WHERE an artifact or wiki page cites a path that resolves to an indexed Go file THE
+   SYSTEM SHALL link it to the `code` node (`reuses`), replacing the placeholder
+   `code_ref`.
+4. THE SYSTEM SHALL exclude `vendor/`, hidden directories, and `testdata/` fixtures
+   from code indexing by default.
+
+### Requirement 13: Scale engine (M4 — earned by the code corpus)
+**Objective:** As a user of a now-large graph, I want retrieval-grade queries and cheap
+rebuilds, because the code corpus made full scans and label matching insufficient.
+**Acceptance Criteria**
+1. WHEN `csdd graph query` runs THEN the system SHALL score nodes by tiers weighted by
+   IDF, seed at least one node per query term, not expand traversal *through*
+   super-hubs (degree > p99, configurable floor), and render within a `--budget` token
+   budget (default 2000).
+2. WHEN an artifact is unchanged (equal content hash) THEN the system SHALL skip its
+   re-extraction; changed sources SHALL have their entire prior contribution replaced
+   (replace-per-source); deleted sources SHALL be pruned.
+3. WHEN `csdd graph build` runs THEN incremental SHALL be the default and `--full`
+   SHALL force a complete rebuild, with output byte-identical to a full rebuild.
+
+### Requirement 14: `.csdd/` state consolidation (independent of milestones)
+**Objective:** As a csdd user, I want csdd's operational files consolidated in
+`.csdd/`, so `.claude/` stays purely mine.
+**Acceptance Criteria**
+1. WHEN `csdd update` needs its hash manifest THEN the system SHALL read
+   `.csdd/manifest.json`, falling back to the legacy `.claude/.csdd-manifest.json` when
+   the new path is absent, and SHALL write to the new path on the next save
+   (transparent migration).
+2. THE SYSTEM SHALL behave identically for workspaces that only have the legacy
+   manifest (no forced migration, no breakage).
+
+### Requirement 15: `csdd init` scaffolds the complete workspace; `.csdd/` is the marker
+**Objective:** As a user starting a project, I want one command to assemble the whole
+development setup, and one unambiguous signal that a project is csdd-initialized.
+**Acceptance Criteria**
+1. WHEN `csdd init` runs THEN the system SHALL scaffold the complete development
+   layout: the existing `.claude/` core, `specs/`, `docs/plans/`, `docs/raw/`,
+   `docs/wiki/` (index/log/pages via the §5.13 wiki scaffold), `docs/graph/` (with its
+   read-only README), and `.csdd/` (the state dir) — idempotent, adding only missing
+   pieces (`--force` to overwrite).
+2. THE SYSTEM SHALL treat the presence of `.csdd/` at the project root as **the
+   workspace marker**: commands that require an initialized workspace (`graph`, `wiki`)
+   SHALL fail with actionable guidance ("run `csdd init`") when it is absent.
+3. WHERE a legacy workspace has `.claude/` but no `.csdd/` THE SYSTEM SHALL say so
+   explicitly and instruct that re-running `csdd init` upgrades it in place (no data
+   loss, nothing overwritten).
+
+### Requirement 16: Agent integration — skills + CLAUDE.md workflow moments
+**Objective:** As an agent working in a csdd workspace, I want installed skills that
+know how to control the graph and the wiki through the CLI, and a CLAUDE.md that tells
+me *when* to invoke them, so the knowledge base stays current inside the normal
+workflow without ad-hoc prompting.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL install a **graph skill** (`.claude/skills/graph/SKILL.md`) that
+   controls the graph exclusively via the CLI (`csdd graph …`, or `npx csdd graph …`
+   when not installed globally): when to `build` (after editing specs/tasks/code),
+   `query`/`explain`/`path` (before grepping or reading code — the brain-first habit),
+   and `analyze` (before review/commit), including how to consume `--json` output.
+2. THE SYSTEM SHALL install the **wiki skill** (§5.13) that owns content
+   creation/maintenance knowledge (Ingest/Query/Maintain) and uses
+   `csdd wiki init|lint` for the deterministic parts.
+3. WHEN `csdd init` runs THEN the system SHALL wire the managed **CLAUDE.md** section
+   with the knowledge-base workflow moments: consult the graph before searching;
+   rebuild after changing specs/tasks/code; run the wiki Ingest workflow after a file
+   lands in `docs/raw/`; run `csdd graph analyze --strict` and `csdd wiki lint` before
+   commit/PR.
+4. Skills and LLM sessions SHALL NOT write `docs/graph/` or `.csdd/` directly — the CLI
+   is the single mutation path for generated artifacts.
+5. THE SYSTEM SHALL install **user-invocable slash commands** under `.claude/commands/`
+   (reusing the existing mechanism, e.g. `/csdd-commit`) so the user can drive the
+   knowledge base directly: `/csdd-graph-query`, `/csdd-graph-path`,
+   `/csdd-graph-explain`, `/csdd-graph-analyze`, `/csdd-wiki-ingest`,
+   `/csdd-wiki-query`, `/csdd-wiki-lint`, `/csdd-stack-propose`, `/csdd-stack-refine` —
+   thin wrappers that route to the skills/CLI.
+
+### Requirement 17: The tech contract (`docs/stack.md`) — stack decisions are the human's
+**Objective:** As the project owner, I want stack/library/framework decisions written
+as a contract the agent must follow, so architectural choices stay mine, libraries are
+used current and correctly, and silent tech decisions (e.g. assuming Redis as broker
+when the decision was RabbitMQ) stop happening.
+**Acceptance Criteria**
+1. WHEN `csdd init` runs THEN the system SHALL scaffold `docs/stack.md` with three
+   sections: **Decided** (a parseable table `| Domain | Choice | Version | Why | Refs |`),
+   **Rules** (the decision protocol, pre-filled — see 17.4), and **Open questions**.
+   The scaffold SHALL NOT prefill any technology choice — the human authors the
+   contract; the CLI provides structure only.
+2. THE SYSTEM SHALL index every Decided row as a `tech` node, and every dependency
+   declared in manifests (`go.mod`, `package.json`, `pyproject.toml`/`requirements.txt`)
+   as a `tech` node with a `uses_tech` edge from the manifest (`EXTRACTED`), matched to
+   contract entries by normalized name.
+3. WHEN `csdd graph analyze` runs THEN the system SHALL report: dependencies present in
+   manifests but absent from the contract ("**undeclared tech decision**" — the
+   Celery+Redis catcher); contract entries with no detected usage ("phantom tech");
+   and contract entries missing Version or Refs ("unrefined tech").
+4. THE SYSTEM SHALL include the contract protocol in the managed CLAUDE.md section
+   (R16.3): *the contract is law; any technology not listed is an **open decision** —
+   propose options with trade-offs and ask before adopting; before the first use of a
+   listed library in a feature, refine against current documentation (Context7 MCP when
+   configured, else web search) and file the findings as a wiki page linked from the
+   contract's Refs column.*
+5. WHERE the workspace has no `docs/stack.md` THE SYSTEM SHALL treat this as a lint
+   finding ("no tech contract"), not an error — adoption is incremental.
+6. THE SYSTEM SHALL install a **stack skill** (`.claude/skills/stack/SKILL.md`) owning
+   the contract workflows: **Propose** (a new tech need appears → present options with
+   trade-offs → ask the human → amend the Decided table only after approval),
+   **Refine** (run the currency check via Context7 MCP when configured, else web
+   search → file findings as a wiki page → link it in the entry's Refs), and
+   **Reconcile** (react to `analyze` tech findings: undeclared → Propose it or remove
+   the dependency; phantom → confirm intent or drop the entry; unrefined → run Refine).
+   The skill SHALL NOT edit manifests or adopt technology without an explicit human
+   decision.
+7. THE SYSTEM SHALL include the stack-skill invocation moments in the managed CLAUDE.md
+   section: invoke it whenever a new dependency or technology is about to enter the
+   project, whenever `analyze` reports tech findings, and whenever the user mentions
+   adopting or changing technology.
+
+---
+
+## 5. Design (content of `design.md`)
+
+### 5.1 Overview
+- **Purpose:** a structured brain for fast, token-cheap, precise consultation of the
+  project — a deterministic graph over csdd artifacts, documentation, and (M3) Go
+  source code — plus a standardized LLM-wiki lifecycle turning `docs/raw/` into
+  structured knowledge (CLI scaffolds/lints; LLM authors).
+- **Users:** agents (query, wiki ingest), reviewers (analyze/lint/web), csdd itself (gates).
+- **Impact:** new package `internal/graph`, new templates, two new subcommands, one web
+  tab. Zero changes to existing artifact formats.
+
+### 5.2 Goals / Non-Goals
+**Goals:** mechanical spec lint (the core product); queryable traceability; one graph
+across specs, docs, and code; pure Go; clean git diffs; wiki scaffold + lint; scale
+machinery when — and only when — the corpus earns it.
+**Non-Goals (all milestones):** LLM calls inside the binary (wiki *content* belongs to
+LLM sessions via the skill); embeddings; MinHash dedup; hyperedges; Leiden communities
+(per-spec grouping is natural at this scale). **Non-goals for M1–M2 specifically:**
+code indexing (M3), IDF/hub-gating/budget query engine and incremental builds (M4).
+Polyglot code indexing (tree-sitter-WASM over `wazero`) stays post-v1.
+
+### 5.3 Existing architecture analysis (verified reuse map)
+| Need | Already exists in | Use |
+|---|---|---|
+| Per-file content hash | `internal/manifest` (SHA256, relative paths; file lives at `.claude/.csdd-manifest.json` today, migrates to `.csdd/manifest.json` — task 16) | M4 incremental cache fingerprint |
+| size+mtime change detection | `internal/session/changedetect.go` (Snapshot) | M4 incremental fast path |
+| Frontmatter parsing | `internal/frontmatter` | skill/agent/steering/wiki-page nodes |
+| Workspace paths / roots | `internal/paths`, `internal/session` (csddRoots) | corpus discovery |
+| Text hash/normalization | `internal/textutil` | ID helpers |
+| NFKC Unicode | `golang.org/x/text/unicode/norm` (already in go.sum) | ID normalization (no new dep) |
+| Go syntax parsing | stdlib `go/parser`, `go/ast` | M3 code extractor (no new dep) |
+| Asset embedding | `internal/web` (`//go:embed`) | `graph.html` template |
+| Template installation | `internal/templater` (spec/skill/agents/rules templates) | `wiki init` scaffold + skill |
+| CLI registration | `internal/cli/cli.go` `Run()` switch (stdlib `flag`) | `graph` / `wiki` subcommands |
+
+### 5.4 The Extractor contract (first-class)
+
+Everything enters the graph through one seam. Nothing downstream may branch on corpus.
+
+```go
+// A Source is one file of a corpus, already read and root-relative.
+type Source struct {
+    Path    string // workspace-root-relative, forward slashes
+    Content []byte
+}
+
+// A Fragment is one extractor's partial contribution: nodes plus edges whose
+// endpoints may still be symbolic (e.g. "requirement 1.1 of spec X") until
+// Assemble reconciles them against the (spec, N, M) index.
+type Fragment struct {
+    Nodes []Node
+    Edges []Edge
+}
+
+type Extractor interface {
+    // Matches reports whether this extractor handles the given corpus file.
+    Matches(path string) bool
+    // Extract parses one source into fragments. Deterministic; no I/O.
+    Extract(src Source) ([]Fragment, error)
+}
+```
+
+**M1 extractors:** `specExtractor` (requirements/design/tasks/spec.json),
+`claudeExtractor` (steering, skills, agents, `.mcp.json`, `CLAUDE.md`),
+`wikiExtractor` (`docs/**/*.md`, wiki-aware for `docs/wiki/`).
+**M3 extractor:** `goExtractor` (stdlib `go/parser`, syntax-only) for `code` nodes.
+Adding it must not touch Assemble/Query/Export — that is the acceptance test of this
+contract. **Post-v1:** tree-sitter-WASM over `wazero` for polyglot.
+
+### 5.5 The graph model (canonical vocabulary — single source of truth)
+
+`docs/graph/README.md` and the seed `graph.json` mirror this section; if this table changes,
+they change in the same commit.
+
+**Node types** (`file_type`): `spec` · `requirement` · `criterion` · `design`
+(component) · `interface` · `flow` · `task` · `steering` · `skill` · `agent` · `mcp` ·
+`code_ref` (a path cited by an artifact) · `wiki_page` · `raw_source` (an immutable file
+under `docs/raw/`, indexed opaquely) · `tech` (a stack decision from `docs/stack.md` or
+a dependency declared in a manifest) · `code` (a real source symbol, emitted once code
+indexing lands in M3).
+
+```go
+type Node struct {
+    ID, Label, FileType, SourceFile, SourceLocation string
+    Attrs map[string]any // status(done|pending), parallel(bool), phase, tags, ...
+}
+type Edge struct {
+    Source, Target, Relation, Confidence string
+    ConfidenceScore float64
+    SourceFile string
+}
+type Graph struct {
+    Directed, Multigraph bool
+    Meta  map[string]any `json:"graph"`
+    Nodes []Node         `json:"nodes"`
+    Links []Edge         `json:"links"`
+}
+```
+
+**Edge relations** and their extraction source (EXTRACTED unless noted):
+
+| Relation | From → To | Source |
+|---|---|---|
+| `owns` | spec → requirement/design/task | `specs/<name>/` structure |
+| `has_criterion` | requirement → criterion | `### Requirement N` → item `N.M` |
+| `realizes` | task → criterion | `_Requirements: 1.1_` in tasks.md |
+| `traced_to` | criterion → design | Requirements Traceability table row |
+| `implements` | design → interface | Interfaces column / component contract |
+| `exercises` | criterion → flow | Flows column |
+| `refined_by` | criterion → design | `**Requirements**: 1.1` in a component |
+| `in_boundary` | task → design | `_Boundary: X_` |
+| `depends_on` | task → task | `_Depends: 3.1_` |
+| `component_dep` | design → design | `**Dependencies**` Inbound/Outbound |
+| `references` | task/design/wiki_page → code_ref | cited path that does **not** exist on disk (planned) |
+| `reuses` | task/design/wiki_page → code_ref/code | cited path that **does** exist on disk (deterministic check; targets `code` once M3 lands) |
+| `governs` | steering → spec | steering scope (INFERRED) |
+| `related_to` | skill/agent/mcp ↔ * | markdown links / frontmatter (INFERRED) |
+| `links_to` | wiki_page → wiki_page | `[[wikilink]]` |
+| `derived_from` | wiki_page → raw_source | frontmatter `sources:` list / links to `raw/` paths |
+| `uses_tech` | code_ref (manifest) / design → tech | dependency manifests (EXTRACTED); component `**Dependencies**: External` (INFERRED) |
+| `contains` | code → code | package → file → declaration (M3) |
+| `imports` | code → code | package import (M3) |
+
+**Confidence:** `EXTRACTED` (explicit annotation or exact cited path, score 1.0) ·
+`INFERRED` (resolved by name/path matching, discrete 0.55–0.95) · `AMBIGUOUS`
+(uncertain, 0.1–0.3, surfaced for the human gate). Structural ambiguity that is not an
+annotation → **omission**, not a noisy edge.
+
+### 5.6 Extraction rules — artifacts and wiki (the parser spec, deterministic)
+
+- **spec.json** → `spec` node (attrs: phase, development_flow, approvals); `owns`
+  everything under the spec folder.
+- **requirements.md** → each `### Requirement N: Title` creates `requirement`; each item
+  under `**Acceptance Criteria**` becomes `criterion` with ID `crit_<spec>_<N>_<M>` and a
+  `has_criterion` edge.
+- **design.md** →
+  - `## Requirements Traceability` table: each row `| N.M | Comp | iface() | flow |` →
+    `traced_to`, `implements`, `exercises`. One criterion per row; comma-separated lists
+    within a cell are split; **range shorthand is a parse error** surfaced by `analyze`.
+  - `### Comp` under `## Components and Interfaces` → `design`; `**Requirements**: …` →
+    `refined_by`; `**Dependencies**` → `component_dep`.
+  - `## File Structure Plan` (```text block) → `code_ref` per path (`reuses` if the path
+    exists on disk, else `references`).
+- **tasks.md** → each `- [ ] N[.M]. Title` → `task` (attr `status` from `[x]`,
+  `parallel` from `(P)`); annotations `_Requirements:` → `realizes`, `_Boundary:` →
+  `in_boundary`, `_Depends:` → `depends_on`. IDs are comma-separated `N.M` lists only.
+- **.claude/** → `steering/rules`, `skills/**/SKILL.md`, `agents/*.md`, `.mcp.json` →
+  respective nodes via `internal/frontmatter`; internal markdown links → `related_to`.
+- **docs/** → every `*.md` outside `docs/raw/` becomes `wiki_page` (frontmatter →
+  attrs). `[[wikilink]]` (regex `\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]`, target normalized
+  with `NormalizeID`) → `links_to`. Frontmatter `sources:` entries and links to `raw/`
+  paths → `derived_from`. Other markdown links to repo paths → `reuses`/`references`.
+  Pages under `docs/wiki/pages/` additionally participate in wiki lint (index/log
+  checks).
+- **docs/raw/** → every file (any extension) becomes an opaque `raw_source` node —
+  path only, content never parsed (raw is immutable input, not graph material). Its
+  purpose in the graph is provenance (`derived_from` targets) and the "unprocessed
+  source" lint.
+- **docs/stack.md** → each row of the **Decided** table → `tech` node
+  (attrs: domain, version, refs, `status=decided`); Rules/Open sections are prose, not
+  parsed. **Dependency manifests** (`go.mod`, `package.json`,
+  `pyproject.toml`/`requirements.txt`) → the manifest becomes a `code_ref` node and
+  each declared dependency a `tech` node (`status=used`) with a `uses_tech` edge
+  (`EXTRACTED`). Contract↔usage matching by `NormalizeID(name)`; the set differences
+  feed the three tech lints (R17.3).
+
+**Reference resolution:** numeric annotation IDs (`1.1`, `3.1`) resolve to canonical
+criterion/task nodes **at build time** via a `(spec, N, M) → id` index. A reference that
+does not resolve becomes a pending-reference finding in `analyze` — never silently
+dropped (the inverse of graphify's behavior; here the gap is the product).
+
+### 5.7 Extraction rules — Go source (M3)
+
+`extract_go.go`, stdlib `go/parser` in `parser.ParseFile` mode (syntax-only — no
+`go/types`, no module resolution, so no network and no toolchain dependency):
+
+- One `code` node per **package** (dir-level), per **file**, and per top-level
+  **declaration** (func, method with receiver in the label, type, exported var/const
+  blocks). IDs: `MakeID("go", pkgPath, name)`. `source_location` = `file:line`.
+- `contains` edges: package → file → declaration. `imports` edges: package → package
+  (import specs; std-lib imports become nodes only if `--include-std`, default off).
+- Excluded by default: `vendor/`, hidden dirs, `testdata/` (they are fixtures, not
+  project truth); `_test.go` files are included but tagged `attrs.test=true`.
+- **Resolution pass:** existing `code_ref` nodes whose path matches an indexed Go file
+  are replaced by edges to the real `code` file node (upgrades artifact→code
+  traceability from placeholder to real). This pass lives in Assemble, keyed by path —
+  it must not special-case the Go extractor (principle 6).
+- Call graphs and cross-package symbol resolution need `go/types`; explicitly out of
+  scope for M3 (revisit post-v1 if a use case demands it).
+
+### 5.8 Canonical IDs (port of `graphify/ids.py`)
+```go
+func NormalizeID(s string) string {
+    s = norm.NFKC.String(s)                 // golang.org/x/text/unicode/norm
+    s = reNonWord.ReplaceAllString(s, "_")  // [^\p{L}\p{N}]+ → _ (keeps CJK/accents)
+    s = reUnderscores.ReplaceAllString(s, "_")
+    return strings.ToLower(strings.Trim(s, "_")) // pragmatic casefold, v1
+}
+func MakeID(parts ...string) string // join with _, normalize
+```
+Idempotent. Single package, imported by extract and build — graphify's lesson #1.
+
+### 5.9 Assemble / build
+Fragments → `Graph` (DiGraph from the start). Node dedup by ID (last-writer-wins), edge
+dedup by `(source, target, relation)`. Annotation IDs reconciled via the `(spec,N,M)`
+index; cited paths reconciled against indexed code files (M3, §5.7). Total deterministic
+ordering of nodes and edges before serialization (stable git diffs, graphify scar #1090).
+
+**Build strategy:** M1–M3 builds are always **full rebuilds** — at this corpus size they
+are milliseconds, and full rebuild is trivially deterministic (deleted files simply
+vanish). M4 adds incremental (manifest hash-skip + replace-per-source + prune, reusing
+`internal/manifest` and `changedetect`; per-source state in `.csdd/state.json`, local
+and regenerable), becoming the default with `--full` as escape hatch; its output must
+be byte-identical to a full rebuild (tested). Every build appends one line to
+`docs/graph/log.md`.
+
+### 5.10 Analyze
+`GapReport`: criteria without `realizes` (untested), tasks without `realizes` (orphans),
+components without `in_boundary` (unimplemented), pending references, `depends_on`
+cycles — plus god nodes (degree) and per-spec communities. **Wiki lint findings**
+(broken `links_to` targets, orphan `wiki_page` nodes, index/log violations) live in the
+same report tagged with corpus `wiki`; `csdd wiki lint` renders exactly that subset.
+
+### 5.11 Query — two stages
+**M1 (ships first):** tiered label matching — exact > prefix > substring over
+`NormalizeID`-normalized labels — returning matches plus their 1-hop neighborhood,
+deterministic order. `Path(a, b, maxHops)`: shortest undirected path, real edge
+direction in rendering. `Explain(label)`: node + neighbors by degree. This covers a
+corpus of dozens–hundreds of nodes completely.
+**M4 (the graphify `serve.py` engine, earned by the code corpus):** precomputed `Index`
+(`label→[]id`, trigram index, IDF, adjacency); `Query(q, opts)`: stopword-filtered
+terms → tier scoring × IDF → seeds (≥1 per term) → BFS with **hub-gating** (never
+traverse *through* degree > p99, floor 50) → render within `token_budget` (default
+2000). Same CLI surface; only the internals grow.
+
+### 5.12 Export
+`docs/graph/graph.json` (node-link, ordered — written by every build).
+`docs/graph/graph.html` (M5): embedded
+template (`//go:embed`) with inline data (escape `</` → `<\/`), vis-network inlined,
+colors by community/`file_type`.
+
+### 5.13 Agent integration — wiki scaffold, skills, slash commands, CLAUDE.md (templater work)
+
+The wiki is the Karpathy three-layer architecture instantiated on `docs/`:
+**`docs/raw/`** (immutable, user-curated sources) → **`docs/wiki/`** (LLM-authored,
+structured, interlinked knowledge) → **the schema** (skill + steering installed by the
+CLI). The goal: the user can drop *anything* raw and end up with a knowledge base that
+is solid, structured, and cheap for an LLM to consume.
+
+Templates added under `internal/templater/templates/wiki/`:
+- `docs/raw/` — the dropzone. A short `README.md` explains: sources go here verbatim
+  (articles, notes, transcripts, clippings); nothing here is ever edited — not by the
+  CLI, not by the LLM.
+- `docs/wiki/index.md` — catalog skeleton (by-category sections, entry format documented).
+- `docs/wiki/log.md` — chronology skeleton; documents the
+  `## [YYYY-MM-DD] <op> | <title>` format (`op ∈ ingest|query|lint|refactor`) and that
+  `grep "^## \[" log.md | tail -5` must always work.
+- `docs/wiki/pages/` — content home (LLM-authored).
+- `.claude/skills/wiki/SKILL.md` — the **schema doc**: page conventions (frontmatter
+  keys including `sources:` for provenance, `[[wikilinks]]`, one concept per page) and
+  the three workflows —
+  **Ingest** (user drops a source into `docs/raw/` → LLM reads it → writes/extends
+  pages under `pages/` with `sources:` pointing back at the raw file → updates
+  `index.md` → cross-references related pages → appends a log entry),
+  **Query** (read index → drill into pages → synthesize with citations →
+  optionally file the answer back as a new page — explorations compound),
+  **Maintain** (run `csdd wiki lint`, fix findings — including unprocessed raw
+  sources — and look for contradictions/stale claims between pages).
+- **Boundary (stated verbatim in the skill):** the wiki is a knowledge base built from
+  `docs/raw/` — it is not documentation *of the specs*. `specs/` holds feature
+  contracts; the wiki holds knowledge. When a page needs to mention project internals,
+  it links (path or `[[...]]`), never restates — duplicated text is drift waiting to
+  happen and a Maintain finding.
+- `.claude/skills/graph/SKILL.md` — the **graph-controller skill**: drives the graph
+  exclusively through the CLI (`csdd graph …` / `npx csdd graph …`). It encodes the
+  *moments*: `build` after editing specs/tasks/code; `query`/`explain`/`path` before
+  grepping or reading code (the brain-first habit); `analyze --strict` before
+  review/commit; and how to consume `--json` output. Neither skill ever writes
+  `docs/graph/` or `.csdd/` directly — the CLI is the single mutation path (R16.4).
+- `.claude/skills/stack/SKILL.md` — the **tech-contract skill** (R17.6): owns the
+  three contract workflows — **Propose** (options + trade-offs → ask → amend Decided
+  only after approval), **Refine** (Context7 MCP when configured, else web search →
+  wiki page → Refs link), **Reconcile** (act on `analyze` tech findings). Never edits
+  manifests or adopts technology without an explicit human decision.
+- `.claude/commands/` — **user-facing slash commands** (same mechanism as
+  `/csdd-commit`): `/csdd-graph-query`, `/csdd-graph-path`, `/csdd-graph-explain`,
+  `/csdd-graph-analyze`, `/csdd-wiki-ingest`, `/csdd-wiki-query`, `/csdd-wiki-lint`,
+  `/csdd-stack-propose`, `/csdd-stack-refine` — thin wrappers routing to the
+  skills/CLI so the user can drive the knowledge base directly from the prompt.
+- **CLAUDE.md wiring** (reuses the managed-section machinery in
+  `internal/cli/claudemd.go`): `csdd init` writes the knowledge-base workflow moments
+  into CLAUDE.md — consult the graph before searching; rebuild after changing
+  specs/tasks/code; run wiki Ingest when a file lands in `docs/raw/`; run
+  `csdd graph analyze --strict` + `csdd wiki lint` before commit/PR — **plus the tech
+  contract protocol (R17.4)**: `docs/stack.md` is law; unlisted technology = open
+  decision → propose options with trade-offs and ask first; before first use of a
+  contracted lib, refine via Context7 MCP (when configured) or web search and file the
+  findings as a wiki page linked from the contract's Refs — **and the stack-skill
+  invocation moments (R17.7)**: invoke the stack skill when a new dependency/technology
+  is about to enter the project, when `analyze` reports tech findings, and when the
+  user mentions adopting or changing technology.
+- A steering rule pointing agents at the knowledge base: *"consult `docs/graph/graph.json`
+  (`csdd graph query`) and `docs/wiki/index.md` before grepping."*
+Idempotent: existing files are never overwritten without `--force`; `docs/raw/` contents
+are never touched.
+
+### 5.14 CLI surface
+```text
+csdd graph build   [--root DIR] [--json]        # full rebuild (M4: incremental default, --full)
+csdd graph query   "<terms>" [--json]           # M4 adds --budget N, --hops N
+csdd graph path    <A> <B> [--max-hops N] [--json]
+csdd graph explain <label> [--json]
+csdd graph analyze [--json] [--strict]          # --strict: exit non-zero on findings
+csdd graph export  [--out PATH]                 # M5: graph.html
+csdd wiki  init    [--force] [--root DIR]
+csdd wiki  lint    [--json]                     # exits non-zero on findings (R10.5)
+```
+Registered as `case "graph"` / `case "wiki"` in `internal/cli/cli.go` `Run()`, following
+the existing stdlib-`flag` + subcommand-switch pattern and `jsonout` conventions.
+
+**Workspace marker & init (R15).** Today the marker is `.claude/` (see the doc comment
+in `internal/paths/paths.go`); this plan moves it to `.csdd/`. A shared
+`RequireWorkspace(root)` helper (in `internal/paths` or `internal/workspace`) checks for
+`.csdd/` and returns the actionable error; `graph` and `wiki` subcommands call it first.
+`csdd init` (`internal/cli/init.go`) is extended to compose the full development setup:
+existing `.claude/` scaffolding + `specs/` + `docs/plans|raw|wiki|graph/` (reusing the
+§5.13 wiki templates and the `docs/graph/` README) + `.csdd/`. Idempotent — re-running
+adds only what is missing, which is also the upgrade path for legacy workspaces that
+predate `.csdd/`.
+
+### 5.15 Web
+A "Graph" tab (`internal/web/frontend/src/Graph.tsx` + route) rendering
+`docs/graph/graph.json` with vis-network. The JSON is served through the dashboard's existing
+read-only hardening path (host guard, redaction — see PR #43); no new write endpoint.
+
+### 5.16 File structure plan
+```text
+internal/graph/
+├── model.go          # Node, Edge, Graph; node-link (un)marshal              [Model]
+├── ids.go            # NormalizeID, MakeID                                    [Model]
+├── extract.go        # Extractor contract; corpus walk; dispatch             [Extract]
+├── extract_spec.go   # requirements.md / design.md / tasks.md / spec.json    [Extract]
+├── extract_claude.go # steering / skills / agents / mcp / CLAUDE.md          [Extract]
+├── extract_wiki.go   # docs/**.md: frontmatter, [[wikilinks]], cited paths   [Extract]
+├── extract_go.go     # M3: go/parser → code nodes, contains/imports          [Extract]
+├── build.go          # fragments → Graph (merge, reconcile IDs, dedup, sort) [Assemble]
+├── analyze.go        # gaps, wiki lint findings, god nodes, cycles           [Analyze]
+├── query.go          # M1: label tiers + path + explain; M4: full engine     [Query]
+├── export.go         # graph.json writer; M5: graph.html                     [Export]
+├── incremental.go    # M4: manifest + changedetect → replace-per-source      [Incremental]
+└── *_test.go         # table-driven; fixtures in internal/graph/testdata/
+internal/cli/
+├── graph.go          # `csdd graph …` subcommand                             [CLI]
+└── wiki.go           # `csdd wiki …` subcommand                              [CLI]
+internal/templater/templates/wiki/   # wiki scaffold + wiki/graph SKILL.md + slash commands + steering + CLAUDE.md section  [WikiScaffold]
+internal/web/frontend/src/
+└── Graph.tsx (+ route/tab)          # M5: vis-network view                   [Web]
+```
+**Modified files:** `internal/cli/cli.go` (register both subcommands), `internal/web`
+(tab route), `internal/templater` (template registration).
+
+### 5.17 Requirements Traceability
+| Requirement | Components | Interfaces | Flows |
+|---|---|---|---|
+| 1.1 | Extract, Assemble | Build() | build |
+| 1.2 | Model | — | build |
+| 1.3 | Extract | Extract() | build |
+| 1.4 | Model | NormalizeID(), MakeID() | build |
+| 2.1 | Query | Query() | query |
+| 2.2 | Query | Path() | query |
+| 2.3 | Query | Explain() | query |
+| 3.1 | Analyze | AnalyzeGaps() | analyze |
+| 3.2 | Analyze | AnalyzeGaps() | analyze |
+| 3.3 | Analyze | AnalyzeGaps() | analyze |
+| 3.4 | Analyze | AnalyzeGaps() | analyze |
+| 3.5 | Analyze | AnalyzeGaps() | analyze |
+| 4.1 | Assemble, Export | Build() | build |
+| 4.2 | Export | Build() | build |
+| 5.1 | (all) | — | ci |
+| 5.2 | (all) | — | ci |
+| 6.1 | CLI | graph/wiki subcommands | build/query/analyze |
+| 6.2 | Export | Export() | export |
+| 6.3 | Web | Graph.tsx | web |
+| 7.1 | Export | Build(), Export() | build |
+| 7.2 | Assemble, Export | Build() | build |
+| 7.3 | Model | — | build |
+| 7.4 | Incremental | Build() | build |
+| 8.1 | Model | MarshalNodeLink() | build |
+| 8.2 | Model | — | build |
+| 9.1 | WikiScaffold | WikiInit() | wiki-init |
+| 9.2 | WikiScaffold | WikiInit() | wiki-init |
+| 9.3 | WikiScaffold | — | wiki-init |
+| 9.4 | WikiScaffold | WikiInit() | wiki-init |
+| 10.1 | Analyze | WikiLint() | wiki-lint |
+| 10.2 | Analyze | WikiLint() | wiki-lint |
+| 10.3 | Analyze | WikiLint() | wiki-lint |
+| 10.4 | Analyze | WikiLint() | wiki-lint |
+| 10.5 | Analyze | WikiLint() | wiki-lint |
+| 10.6 | CLI | wiki subcommand | wiki-lint |
+| 11.1 | Extract | Extract() | build |
+| 11.2 | Extract | Extract() | build |
+| 11.3 | Analyze | WikiLint() | wiki-lint |
+| 12.1 | Extract | Extract() | build |
+| 12.2 | Extract | Extract() | build |
+| 12.3 | Assemble | Build() | build |
+| 12.4 | Extract | Extract() | build |
+| 13.1 | Query | Query() | query |
+| 13.2 | Incremental | Build() | build |
+| 13.3 | Incremental, CLI | Build() | build |
+| 14.1 | CLI | manifest Load()/Save() | update |
+| 14.2 | CLI | manifest Load()/Save() | update |
+| 15.1 | CLI, WikiScaffold | init | init |
+| 15.2 | CLI | RequireWorkspace() | init |
+| 15.3 | CLI | RequireWorkspace() | init |
+| 16.1 | WikiScaffold | graph SKILL.md | init |
+| 16.2 | WikiScaffold | wiki SKILL.md | wiki-init |
+| 16.3 | CLI | claudemd section | init |
+| 16.4 | WikiScaffold | skill templates | init |
+| 16.5 | WikiScaffold | commands templates | init |
+| 17.1 | CLI, WikiScaffold | init | init |
+| 17.2 | Extract | Extract() | build |
+| 17.3 | Analyze | AnalyzeGaps() | analyze |
+| 17.4 | CLI | claudemd section | init |
+| 17.5 | Analyze | AnalyzeGaps() | analyze |
+| 17.6 | WikiScaffold | stack SKILL.md | init |
+| 17.7 | CLI | claudemd section | init |
+
+---
+
+## 6. Tasks (content of `tasks.md`) — TDD, boundaries, dependencies
+
+All `_Requirements:` lists are explicit and comma-separated (no ranges).
+
+### Phase 1: Foundation (M1)
+- [ ] 1. Model + IDs _Boundary: Model_
+  - [ ] 1.1 RED — tests for `NormalizeID`/`MakeID` (idempotence, NFKC, unicode) and node-link round-trip
+    - _Requirements: 1.4, 8.1_
+  - [ ] 1.2 GREEN — minimal `model.go` + `ids.go`
+    - _Requirements: 1.2, 1.4, 8.1, 8.2_
+
+### Phase 2: The lint core (M1)
+- [ ] 2. Artifact extractors (P) _Boundary: Extract_
+  - [ ] 2.1 RED — fixtures in `testdata/` (requirements/design/tasks/spec.json/.claude) + per-parser tests, including a fixture that mirrors `internal/templater/templates/spec/*.tmpl` and fails if templates drift
+    - _Requirements: 1.1, 1.3_
+    - _Depends: 1.2_
+  - [ ] 2.2 GREEN — `extract.go` (Extractor contract + walk) + `extract_spec.go` + `extract_claude.go`
+    - _Requirements: 1.1, 1.3_
+- [ ] 3. Wiki extractor (P) _Boundary: Extract_
+  - [ ] 3.1 RED — fixtures for wiki pages: frontmatter (incl. `sources:` provenance), `[[wikilinks]]` (incl. `|alias` and `#anchor` forms), cited paths existing/missing, `docs/raw/` files → opaque `raw_source` nodes, `derived_from` edges, orphan/broken-link/unprocessed-source cases
+    - _Requirements: 11.1, 11.2_
+    - _Depends: 1.2_
+  - [ ] 3.2 GREEN — `extract_wiki.go`
+    - _Requirements: 11.1, 11.2_
+- [ ] 4. Assemble + dedup _Boundary: Assemble_
+  - [ ] 4.1 RED — merge, `(spec,N,M)` ID reconciliation, edge/node dedup, total deterministic ordering (byte-stable double-build test)
+    - _Requirements: 1.1, 4.1, 7.2_
+    - _Depends: 1.2, 2.2, 3.2_
+  - [ ] 4.2 GREEN — `build.go` (full rebuild; log append via Export)
+    - _Requirements: 1.1, 4.1, 4.2, 7.2_
+- [ ] 5. Analyze: gaps + wiki lint core _Boundary: Analyze_
+  - [ ] 5.1 RED — untested criterion, orphan task, unimplemented component, pending reference, `depends_on` cycle; broken wikilink, orphan page, index desync, log format, unprocessed raw source
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 10.1, 10.2, 10.3, 10.4, 10.5_
+    - _Depends: 4.2_
+  - [ ] 5.2 GREEN — `analyze.go` (GapReport with corpus tags)
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 10.1, 10.2, 10.3, 10.4, 10.5, 11.3_
+
+### Phase 3: Surfaces (M1 + M2)
+- [ ] 6. Query v1: label tiers + path + explain (P) _Boundary: Query_
+  - [ ] 6.1 RED — exact/prefix/substring tiers, deterministic order, 1-hop neighborhood; shortest path with real direction; explain by neighbor degree
+    - _Requirements: 2.1, 2.2, 2.3_
+    - _Depends: 4.2_
+  - [ ] 6.2 GREEN — `query.go` (v1 internals)
+    - _Requirements: 2.1, 2.2, 2.3_
+- [ ] 7. Export: graph.json writer (P) _Boundary: Export_
+  - [ ] 7.1 RED — stable node-link output, root-relative paths, log.md append line
+    - _Requirements: 4.2, 7.1, 7.3, 8.1_
+    - _Depends: 4.2_
+  - [ ] 7.2 GREEN — `export.go` (json + log; html comes in task 13)
+    - _Requirements: 4.2, 7.1_
+- [ ] 8. Agent-integration templates: wiki scaffold + skills + slash commands (P) _Boundary: WikiScaffold_
+  - [ ] 8.1 RED — `wiki init` creates raw dropzone + index/log/pages + wiki skill + steering (with the raw→wiki pipeline and boundary text); graph-controller skill; stack skill (Propose/Refine/Reconcile, human-decision gate); slash commands under `.claude/commands/`; idempotent; no-clobber without `--force`; never touches `docs/raw/` contents; skills contain no direct writes to `docs/graph/`/`.csdd/`
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 16.1, 16.2, 16.4, 16.5, 17.6_
+  - [ ] 8.2 GREEN — `internal/templater/templates/wiki/` (+ graph/stack skills + commands templates) + install wiring
+    - _Requirements: 9.1, 9.2, 9.4, 16.1, 16.2, 16.5, 17.6_
+- [ ] 9. CLI `csdd graph` + `csdd wiki` _Boundary: CLI_
+  - [ ] 9.1 RED — command surface, flags, `--json` output, exit codes (`analyze --strict`, lint non-zero on findings)
+    - _Requirements: 6.1, 10.6_
+    - _Depends: 5.2, 6.2, 7.2, 8.2_
+  - [ ] 9.2 GREEN — `internal/cli/graph.go` + `internal/cli/wiki.go` + registration in `cli.go`
+    - _Requirements: 6.1, 10.6_
+
+### Phase 4: The code graph (M3)
+- [ ] 10. Go source extractor _Boundary: Extract_
+  - [ ] 10.1 RED — fixture mini-module in `testdata/`: packages/files/decls/imports; `vendor/`+`testdata/` exclusion; `_test.go` tagging; cited-path resolution upgrading `code_ref`→`code`
+    - _Requirements: 12.1, 12.2, 12.3, 12.4_
+    - _Depends: 4.2_
+  - [ ] 10.2 GREEN — `extract_go.go` + resolution pass in Assemble (no downstream special-casing — the Extractor-contract acceptance test)
+    - _Requirements: 12.1, 12.2, 12.3, 12.4_
+
+### Phase 5: The scale engine (M4)
+- [ ] 11. Full query engine _Boundary: Query_
+  - [ ] 11.1 RED — tier scoring × IDF, seeds per term, BFS hub-gating (p99 floor 50), token budget rendering; same CLI surface as v1
+    - _Requirements: 13.1_
+    - _Depends: 6.2, 10.2_
+  - [ ] 11.2 GREEN — `query.go` (M4 internals swap; v1 tests keep passing)
+    - _Requirements: 13.1_
+- [ ] 12. Incremental builds _Boundary: Incremental_
+  - [ ] 12.1 RED — skip-by-hash, replace-per-source, prune deleted, `--full`; output byte-identical to a full rebuild
+    - _Requirements: 7.4, 13.2, 13.3_
+    - _Depends: 4.2, 10.2_
+  - [ ] 12.2 GREEN — `incremental.go` (reuses `internal/manifest` + `internal/session/changedetect.go`); incremental becomes the default
+    - _Requirements: 7.4, 13.2, 13.3_
+
+### Phase 6: Visualization + validation (M5)
+- [ ] 13. HTML export (P) _Boundary: Export_
+  - [ ] 13.1 RED — self-contained html (no external asset, `</` escaped)
+    - _Requirements: 6.2_
+    - _Depends: 7.2_
+  - [ ] 13.2 GREEN — embedded vis-network template in `export.go`
+    - _Requirements: 6.2_
+- [ ] 14. Web Graph tab (P) _Boundary: Web_
+  - [ ] 14.1 RED — render test reading `docs/graph/graph.json` through the hardened read-only route
+    - _Requirements: 6.3_
+    - _Depends: 7.2_
+  - [ ] 14.2 GREEN — `Graph.tsx` + route
+    - _Requirements: 6.3_
+- [ ] 15. E2E golden path + CI gate
+  - [ ] 15.1 e2e on a fixture workspace: `graph build` → `analyze` → `query`; `wiki init` → `lint`; double-build byte-stability; `CGO_ENABLED=0` for all `make dist` targets in CI
+    - _Requirements: 5.1, 5.2_
+    - _Depends: 9.2_
+
+### Phase 7: Workspace & state consolidation (independent — any time after M1)
+- [ ] 16. Migrate the update manifest to `.csdd/` _Boundary: CLI_
+  - [ ] 16.1 RED — read-fallback to legacy `.claude/.csdd-manifest.json`, write to `.csdd/manifest.json` on save, identical behavior for legacy-only workspaces
+    - _Requirements: 14.1, 14.2_
+  - [ ] 16.2 GREEN — path change in `internal/manifest` callers + `internal/paths` constant
+    - _Requirements: 14.1, 14.2_
+- [ ] 17. Init: full layout + workspace marker _Boundary: CLI_
+  - [ ] 17.1 RED — `init` creates `specs/`, `docs/plans|raw|wiki|graph/`, `.csdd/`; wires the CLAUDE.md knowledge-base section (workflow moments incl. stack protocol + stack-skill invocation moments); idempotence/no-clobber; `RequireWorkspace` errors for `graph`/`wiki` when `.csdd/` is absent; legacy-upgrade message when only `.claude/` exists
+    - _Requirements: 15.1, 15.2, 15.3, 16.3, 17.7_
+    - _Depends: 8.2_
+  - [ ] 17.2 GREEN — extend `internal/cli/init.go` + `RequireWorkspace` helper + CLAUDE.md section (via `claudemd` machinery) + wiring in `graph`/`wiki` subcommands
+    - _Requirements: 15.1, 15.2, 15.3, 16.3, 17.7_
+
+### Phase 8: Tech contract (parallel after task 5; template with task 17)
+- [ ] 18. `docs/stack.md` contract: extractor + lints + scaffold _Boundary: Extract_
+  - [ ] 18.1 RED — fixtures: Decided-table parsing → `tech` nodes; `go.mod`/`package.json`/`pyproject.toml` deps → `tech` usage + `uses_tech`; lints (undeclared tech decision, phantom tech, unrefined tech, no-contract finding); scaffold template with Rules protocol prefilled and no choices prefilled; CLAUDE.md moments include the contract protocol
+    - _Requirements: 17.1, 17.2, 17.3, 17.4, 17.5_
+    - _Depends: 4.2_
+  - [ ] 18.2 GREEN — `extract_stack.go` (contract + manifests) + analyze rules + init template + CLAUDE.md section text
+    - _Requirements: 17.1, 17.2, 17.3, 17.4, 17.5_
+
+**Execution order (deps):** 1 → {2, 3, 8} → 4 → {5, 6, 7} → 9 → 10 → {11, 12} → {13, 14, 15}.
+`(P)` tasks are parallelizable across distinct boundaries. Tasks 13–15 need only task 9
+(plus 7 for exports) — they may start before 10–12 if sequencing favors it. Task 16 is
+independent of the graph pipeline and may ship any time after M1.
+
+---
+
+## 7. Milestones
+
+| Milestone | Delivery | Tasks |
+|---|---|---|
+| **M1 — Spec lint (the immediately-paying core)** | `csdd graph build` writes `docs/graph/graph.json` (specs + `.claude/` + `docs/`); `analyze` reports every traceability gap; `query`/`path`/`explain` v1 | 1–7, 9 |
+| **M2 — Wiki standard + agent integration + tech contract** | `wiki init` scaffolds the `docs/raw/` → `docs/wiki/` pipeline; wiki + graph skills, `/csdd-graph-*` and `/csdd-wiki-*` slash commands, CLAUDE.md workflow moments incl. the stack protocol; `wiki lint` gates health incl. unprocessed sources; `docs/stack.md` contract indexed + tech lints | 3, 8, 9, 18 |
+| **M3 — Code graph (the original vision)** | Go source in the same graph via `go/parser`; artifact-cited paths resolve to real code nodes; the graph now grows with the codebase | 10 |
+| **M4 — Scale engine (earned by M3)** | full query engine (IDF × tiers, hub-gating, budget); incremental builds by default with `--full` | 11, 12 |
+| **M5 — Visualization + validation** | `graph.html` export; web dashboard tab; e2e golden path; `CGO_ENABLED=0` CI gate | 13–15 |
+| **M6 — Workspace & state consolidation (independent; any time after M1)** | `csdd init` scaffolds the complete dev layout (`specs/`, `docs/*`, `.claude/`, `.csdd/`); `.csdd/` becomes the workspace marker with legacy-upgrade path; update manifest migrated to `.csdd/manifest.json` with read-fallback | 16, 17 |
+| **Post-v1** | always-on hooks (post-command/commit rebuild); "consult the graph before grep" steering everywhere; polyglot code indexing (tree-sitter-WASM over `wazero` spike); `go/types` call graphs if a use case demands | — |
+
+---
+
+## 8. Risks and decisions
+
+- **cgo-free (locked).** Annotation parsing needs no tree-sitter; Go code parsing uses
+  stdlib `go/parser` (syntax-only). Polyglot indexing enters post-v1 through the
+  Extractor seam via a tree-sitter-WASM/`wazero` spike.
+- **No LLM in the binary (locked).** Wiki content is authored by LLM sessions following
+  the installed skill; the CLI does only deterministic scaffold/lint. This is the
+  csdd-shaped split of Karpathy's pattern.
+- **Scale machinery deferred, not dropped (decided in revision 2).** Full query engine
+  and incremental builds are specified (§5.11, §5.9) but implemented in M4, after the
+  code corpus justifies them. Guard: the M4 swap must keep all M1 query tests passing
+  and incremental output byte-identical to full rebuilds.
+- **Wiki/specs knowledge duplication.** The skill states the boundary verbatim (§5.13):
+  specs = per-feature contracts; wiki = cross-feature synthesis; wiki pages link to
+  specs, never restate them. Contradiction with specs is a Maintain finding.
+- **Git-diff stability.** Total deterministic ordering (§5.9); double-build
+  byte-equality is an explicit test (tasks 4.1, 15.1).
+- **Template drift.** Parsers depend on `internal/templater/templates/spec/*.tmpl`;
+  fixtures mirror the templates and a dedicated test fails when templates change without
+  a parser update (task 2.1).
+- **Vocabulary drift.** §5.5 is the single source of truth; `docs/graph/README.md` and the
+  seed must change in the same commit (enforced by review, optionally by a test reading
+  both).
+- **Range shorthand.** `_Requirements: 3.1–3.5_` style ranges are a parse error surfaced
+  by `analyze`, not a supported syntax — one less ambiguity in the format.
+- **Generated island inside `docs/` (decided in revision 3).** Moving the knowledge
+  index to `docs/graph/` trades the simple "CLI never writes docs/" invariant for a
+  purpose-based split (knowledge vs. state) with a much cleaner git story. Guard: the
+  README in `docs/graph/` declares it read-only, and R7.1 forbids generated files
+  anywhere else in `docs/`.
+- **Manifest migration compat (task 16).** Read-fallback to
+  `.claude/.csdd-manifest.json` keeps existing workspaces working; writes go to
+  `.csdd/manifest.json` on the next save. Independent of the graph milestones.
+
+---
+
+## 9. Appendices
+
+### 9.1 graphify → csdd map
+| graphify (Python) | csdd (Go) |
+|---|---|
+| `ids.py` | `internal/graph/ids.go` |
+| `extract.py` + extractors | `internal/graph/extract*.go` (annotation parsers + `go/parser`) |
+| `build.py` | `internal/graph/build.go` |
+| `analyze.py` | `internal/graph/analyze.go` (gaps + wiki lint = the focus) |
+| `serve.py` (query engine) | `internal/graph/query.go` (v1 lite; M4 full port) |
+| `export.py` | `internal/graph/export.go` |
+| `cache.py` + manifest | `internal/manifest` + `internal/session/changedetect.go` (M4 reuse) |
+| `graphify-out/` | `docs/graph/` (knowledge index) + `.csdd/` (operational state) |
+
+### 9.2 Karpathy LLM-wiki → csdd map
+| LLM-wiki | csdd |
+|---|---|
+| Raw sources (immutable) | `docs/raw/` — user-curated dropzone, read-only for CLI and LLM |
+| The wiki (LLM-authored) | `docs/wiki/` (pages by LLM sessions via the skill, `sources:` provenance) |
+| The schema (CLAUDE.md/AGENTS.md) | `.claude/skills/wiki/SKILL.md` + steering rule (installed by `wiki init`) |
+| Ingest | LLM workflow in the skill (CLI never authors content) |
+| Query | LLM workflow + `csdd graph query` over the same graph |
+| Lint | `csdd wiki lint` (deterministic half) + skill's Maintain workflow (semantic half) |
+| `index.md` / `log.md` | `docs/wiki/index.md` / `docs/wiki/log.md` (scaffolded, format-linted) |
+| "compiled once, kept current" | `csdd graph build` on every change (M4: incremental) |
+
+### 9.3 References
+- `graphify/ANALISE-ARQUITETURA.md` — graphify internals; decisions ported here.
+- `graphify/llm-wiki.md` — Karpathy's pattern (source of the wiki lifecycle).
+- `docs/graph/README.md` — schema doc for the knowledge index. `docs/graph/graph.json` — hand-seeded fixture. `.csdd/README.md` — the state-dir contract.
+- `internal/templater/templates/spec/*.tmpl` — ground truth of artifact formats.
+- `docs/plans/PLANO-graph-index.md` — superseded Portuguese predecessor (graph-only).
+
+### 9.4 Executor notes (this repo / workstation)
+- **Verify:** `make check` (gofmt + vet + race tests). Distribution gate:
+  `CGO_ENABLED=0` via `make dist VERSION=vX.Y.Z` (6 targets).
+- **CLI pattern:** stdlib `flag` + subcommand switch in `internal/cli/cli.go` `Run()`;
+  `--json` output goes through the `jsonout` helpers; tests are table-driven next to
+  each file.
+- **Line endings:** the working tree on this workstation is CRLF over an LF index —
+  stage only the specific paths you changed; **never `git add -A`**.
+- **Flaky tests:** four update/clean `.old`-backup CLI tests fail non-deterministically
+  on `/mnt/c` (WSL) — re-run before treating as a regression.
+- **Go toolchain (this workstation):** not on the default PATH; it lives at
+  `~/.local/go/bin` (export PATH + GOPATH/GOCACHE).
+- **Before starting:** `git fetch origin` and check open PRs — parallel sessions may
+  have landed related work.
+- **Commits/PRs:** conventional style (`feat(graph): …`); repo templates forbid
+  AI/assistant attribution in generated commits and PRs (#42).
+- **Dogfood:** once M1 lands, run `csdd graph build` on this repo and convert this
+  plan's sections 4/5/6 into `specs/knowledge-base/` via the csdd spec flow; the seed
+  `docs/graph/graph.json` then gets regenerated deterministically. M3's first real corpus is
+  csdd's own `internal/` tree — the graph indexing the tool that builds it.
diff --git a/docs/plans/PLAN-plan-mode.md b/docs/plans/PLAN-plan-mode.md
new file mode 100644
index 0000000..40200e6
--- /dev/null
+++ b/docs/plans/PLAN-plan-mode.md
@@ -0,0 +1,667 @@
+# Master Plan — csdd Plan Mode (`csdd plan` + `csdd sandbox`)
+
+> **Audience:** the LLM agent (and humans) implementing this feature end-to-end.
+> **Status:** draft for review — revision 1 (2026-07-06). Not yet approved.
+> **Companions:** `docs/plans/PLAN-knowledge-base.md` (the archetype this formalizes —
+> and the substrate: graph, wiki and stack are *consumed* by this feature);
+> github.com/snarktank/ralph (PRD skill + autonomous loop mechanics, studied 2026-07-06);
+> github.com/protonspy/devcontainer-claude-code (sandbox template base, rebased onto
+> language-agnostic Ubuntu in this design); code.claude.com/docs/en/devcontainer
+> (official sandbox reference and security model).
+> **Dogfood note:** this document is written in the format §4/§5/§6 define — the feature
+> planning itself. Once `csdd plan init` exists (task 4), this file migrates to
+> `docs/plans/plan-mode/plan.md` and becomes the first plan ever validated, approved,
+> and (M4) executed by `csdd plan run`.
+
+---
+
+## 1. Context and vision
+
+### 1.1 What we are building
+
+csdd governs the spec flow: `requirements → design → tasks`, gated by human approvals
+and mechanical validation. This plan adds the layer **above** specs: the **plan** — a
+structured, contract-bound document in `docs/plans/` that decomposes an initiative into
+**feats**, where each feat becomes exactly one spec in `specs/`. On top of it,
+**autonomous execution**: `csdd plan run` drives fresh `claude -p` sessions through the
+spec flow and implementation, csdd controlling and validating every step, with the
+human gate moved upstream to a single `csdd plan approve`.
+
+The hierarchy:
+
+```text
+Plan (docs/plans/<slug>/)  →  Feats (rows of the plan)  →  Specs (specs/<feat>/)  →  Tasks
+```
+
+**The contract is the secret.** Autonomy is not trust in the model — it is an authority
+chain of contracts, every link mechanically checkable: the **plan** (approved,
+hash-bound) says *what* and *in which order*; **`docs/stack.md`** says *with which
+technology*; the **spec validators** say *whether each artifact honors the format*;
+the **quality gates** say *whether the code works*; `csdd graph analyze --strict` says
+*whether traceability holds*. Anything not covered by a contract is an **open
+decision** — the loop surfaces it and stops that feat; it never improvises.
+
+### 1.2 The Ralph synthesis (what we take, what we already have better)
+
+Ralph (snarktank/ralph) proved the loop shape: a PRD of right-sized stories, a fresh
+AI session per story, deterministic sequencing outside the model, mechanical gates
+before commit, learnings persisted between iterations. csdd adopts the shape and
+upgrades every organ:
+
+| Ralph | csdd plan mode |
+|---|---|
+| `prd.json` + `passes: false` flags | plan + **derived status** (computed from `specs/` — no stored flags to desync) |
+| story picked by priority | `csdd plan next` (deps + milestones + `(P)`, returns the exact *step*) |
+| `prompt.md` hand-rolled context | `csdd plan brief` — deterministic context pack (feat row, seeds, stack rows, wiki refs, executor notes) |
+| `progress.txt` append-only learnings | the wiki (structured, interlinked, graph-indexed) |
+| `AGENTS.md` conventions | steering + managed CLAUDE.md (already installed by csdd) |
+| typecheck + tests | spec validators + plan quality gates + `graph analyze --strict` + `wiki lint` |
+| `ralph.sh` bash orchestrator | `csdd plan run` — the runner in Go, inside the binary |
+| trust the loop on the host | `csdd sandbox` — devcontainer with default-deny egress; bypass only inside |
+
+### 1.3 Value thesis (why this build order)
+
+- **The plan document pays before any automation exists.** `PLAN-knowledge-base.md`
+  already proved the format's worth for a human-driven build. Formalizing it +
+  `validate`/`status` (M1) makes every future initiative start structured and
+  mechanically linted — and dogfoods the parser on this very file.
+- **The sandbox is independent and unblocks safe experimentation** (M2). It is useful
+  today for any Claude Code work, not just the loop.
+- **The bridge (approve/next/brief/generate, M3) is already a usable workflow** —
+  a human or a supervised session can follow `next` manually long before the runner
+  exists.
+- **The runner (M4) is the smallest possible machine** because everything hard —
+  sequencing, context assembly, validation, status — already shipped as CLI commands
+  it merely calls in a loop.
+
+---
+
+## 2. Storage (extends the project-wide convention, revision 3)
+
+| Path | Role | Author |
+|---|---|---|
+| `docs/plans/<slug>/plan.md` | The plan document — vision, decisions, **feat table**, quality gates, executor notes. | Human/LLM prose; scaffolded and linted by the CLI, never written by it. |
+| `docs/plans/<slug>/seeds/<feat>/*.md` | Optional pre-authored spec artifacts (requirements/design/tasks seeds) consumed by `plan generate`. | Human/LLM. |
+| `docs/plans/<slug>/plan.json` | Approval state: `{schema_version, name, approvals: {approved, content_hash, approved_at}}`. | **CLI only** (`plan approve`) — the `spec.json` precedent. |
+| `docs/plans/<slug>/log.md` | Append-only run journal (one mechanical entry per runner event — the `docs/graph/log.md` precedent). | **CLI only** (`plan run`). |
+| `.csdd/plan/<slug>/` | Transient runner state (session ids, last verdicts, block markers). Regenerable, gitignored. | CLI only. |
+
+Feat **status is never stored** — it is derived from `specs/<feat>/` reality on every
+read (R5). The committed knowledge is the plan and its journal; the machine state is
+disposable.
+
+---
+
+## 3. Design principles (inviolable)
+
+1. **The CLI never authors prose.** It scaffolds, parses, lints, derives, sequences,
+   and appends mechanical log/state entries (`plan.json`, `log.md`) — plan content is
+   human/LLM-authored via the installed skill.
+2. **No LLM inference in the binary.** Refined for this feature: `csdd plan run` may
+   **orchestrate the local `claude` CLI as a subprocess** — it never calls a model API
+   itself, and every other command works with no `claude` installed.
+3. **The LLM authors; the runner approves.** Sessions produce artifacts and verdicts.
+   `csdd spec approve`, commits, and loop advancement are executed by the runner, and
+   only after the mechanical gates pass. A session that tries to self-approve or to
+   write `plan.md`, `plan.json`, `docs/graph/` or `.csdd/` is a hard failure (R9.6).
+4. **Derived status, single source of truth.** `specs/` is reality; the plan never
+   duplicates it.
+5. **Deviation is an event, not an improvisation.** Unforeseen problems produce a
+   structured blocked-verdict logged to `log.md`; folding it into the plan is a human
+   (re-approval) act. Hash drift always pauses autonomy.
+6. **Human gates: exactly two.** `csdd plan approve` before, the pull request after.
+   Everything between is contract-checked machine work.
+7. **Sandbox before bypass.** `--dangerously-skip-permissions` is only ever passed when
+   `csdd sandbox doctor` proves the session is inside the hardened container.
+8. **Aggressive reuse.** Spec lifecycle (`internal/cli/spec.go`), validator
+   (`internal/validator`), graph (`internal/graph` Extractor seam), templater, paths,
+   web hardening (PR #43) — nothing here invents a second mechanism for a solved
+   problem.
+
+---
+
+## 4. Requirements (content of `requirements.md`)
+
+EARS format. Requirement IDs in annotations are explicit comma-separated lists.
+
+### Requirement 1: Plan scaffolding (`csdd plan init`)
+**Objective:** As a project owner, I want one command to stand up a structured plan,
+so every initiative starts in the standard format.
+**Acceptance Criteria**
+1. WHEN `csdd plan init <slug>` runs THEN the system SHALL create
+   `docs/plans/<slug>/{plan.md, seeds/}` from the plan template, with all required
+   sections present and no content prefilled beyond structure and inline format docs.
+2. WHERE the plan directory already exists THE SYSTEM SHALL add only missing files
+   (idempotent; `--force` required to overwrite).
+3. IF the workspace marker (`.csdd/`) is absent THEN the system SHALL fail with the
+   actionable `csdd init` guidance (R15 of the knowledge-base plan).
+
+### Requirement 2: The plan document contract (parseable core)
+**Objective:** As the toolchain, I want the plan machine-readable where it matters,
+so sequencing, validation and the graph work from explicit structure.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL parse a `## Feats` table with columns
+   `| # | Feat | Objective | Depends | Milestone | (P) | Refs |` where `Feat` is a
+   slug valid as a spec directory name, `Depends` is an explicit comma-separated list
+   of feat slugs (range shorthand is a parse error), and `Refs` holds zero or more
+   `[[wiki-page]]` and `stack:<name>` tokens.
+2. THE SYSTEM SHALL parse a `## Quality Gates` section of `- <label>: <command>` lines
+   (e.g. `- verify: make check`); the gate list is the plan's own verification
+   contract, executed by the runner after every implementation step.
+3. THE SYSTEM SHALL treat `## Executor Notes` as an opaque block passed verbatim into
+   every brief (R7), and frontmatter keys `name`, `status (draft|approved|superseded)`.
+4. WHERE `seeds/<feat>/` contains `requirements.md`/`design.md`/`tasks.md` THE SYSTEM
+   SHALL associate them with that feat for `plan generate` (R8).
+
+### Requirement 3: Plan lint (`csdd plan validate`)
+**Objective:** As a reviewer (human or runner), I want structural violations surfaced
+mechanically, so the approve gate acts on a sound document.
+**Acceptance Criteria**
+1. WHEN `csdd plan validate <slug>` runs THEN the system SHALL report: feat-table
+   grammar violations, duplicate/invalid slugs, `Depends` references to nonexistent
+   feats, and dependency cycles.
+2. THE SYSTEM SHALL report every `stack:<name>` ref with no matching row in the
+   `docs/stack.md` Decided table ("undeclared tech in plan") and every `[[wiki-page]]`
+   ref with no matching page ("broken plan ref").
+3. THE SYSTEM SHALL report an empty or missing `## Quality Gates` section.
+4. THE SYSTEM SHALL run the EARS lint over any `seeds/*/requirements.md`.
+5. IF any violation is found THEN the system SHALL exit non-zero (CI-gateable).
+
+### Requirement 4: The human gate (`csdd plan approve`)
+**Objective:** As the project owner, I want my approval bound to exact content, so
+autonomy is authorized against what I read, not what the file later became.
+**Acceptance Criteria**
+1. WHEN `csdd plan approve <slug>` runs and `validate` passes THEN the system SHALL
+   write `plan.json` with `approved: true` and a content hash covering `plan.md` and
+   `seeds/**`.
+2. WHEN plan content changes after approval THEN `status`, `next` and `run` SHALL
+   detect the hash mismatch ("drift") and `run` SHALL refuse autonomous execution
+   until re-approval.
+3. IF `validate` reports findings THEN `approve` SHALL fail listing them.
+
+### Requirement 5: Derived status (`csdd plan status`)
+**Objective:** As anyone observing the plan, I want per-feat progress computed from
+reality, so there is no second bookkeeping to desync.
+**Acceptance Criteria**
+1. WHEN `csdd plan status <slug>` runs THEN the system SHALL derive each feat's state
+   from `specs/<feat>/`: `pending` (no spec), `requirements|design|tasks` phase
+   progress (from `spec.json` approvals), `ready` (ready_for_implementation),
+   `implementing` (tasks partially checked), `done` (all tasks checked), plus
+   `blocked` when `.csdd/plan/<slug>/` holds a block marker for the feat.
+2. THE SYSTEM SHALL surface plan-level flags: approval state, drift, and unprocessed
+   deviation entries in `log.md`.
+3. THE SYSTEM SHALL support `--json` for consumption by the runner, the web tab, and
+   scripts.
+
+### Requirement 6: The sequencer (`csdd plan next`)
+**Objective:** As the runner (or a human following the plan by hand), I want csdd to
+name the exact next step, so the loop stays dumb and the intelligence stays in the CLI.
+**Acceptance Criteria**
+1. WHEN `csdd plan next <slug>` runs THEN the system SHALL select the first feat, in
+   table order within milestone order, whose `Depends` are all `done` and which is not
+   `done`/`blocked`, and return the next **step** within it: `spec-requirements`,
+   `spec-design`, `spec-tasks`, or `task <N.M>` (honoring tasks.md order, `_Depends:`
+   and `(P)` semantics).
+2. THE SYSTEM SHALL emit the step as `--json` `{feat, step, reason}` and as text.
+3. THE SYSTEM SHALL exit with distinct codes: step available (0), plan complete (3),
+   nothing unblocked (4), drift/not-approved (5).
+
+### Requirement 7: The context pack (`csdd plan brief`)
+**Objective:** As a fresh `claude -p` session, I want a surgical, deterministic
+context pack, so each iteration starts precise without inheriting noise.
+**Acceptance Criteria**
+1. WHEN `csdd plan brief <slug> --step` runs THEN the system SHALL assemble, from
+   explicit content only: the step contract (artifact to produce, gates that will run,
+   forbidden actions per R9.6), the feat row and objective, the feat's seeds, every
+   `stack:` ref resolved to its full Decided row, every `[[wiki-page]]` ref resolved
+   to path + frontmatter description, the Executor Notes verbatim, and the graph-first
+   consultation instructions (`csdd graph query` before reading code).
+2. THE SYSTEM SHALL NOT inline wiki page bodies (the session reads what it needs —
+   token discipline); stack rows are inlined in full (they are one-line contracts).
+3. THE SYSTEM SHALL be deterministic: same plan + same step → byte-identical brief.
+
+### Requirement 8: Plan → spec bridge (`csdd plan generate`)
+**Objective:** As the loop (or a human), I want a feat's spec born from the plan,
+so specs inherit the plan's intent and provenance.
+**Acceptance Criteria**
+1. WHEN `csdd plan generate <slug> <feat>` runs THEN the system SHALL scaffold
+   `specs/<feat>/` through the existing spec-init machinery, pre-seeding artifacts
+   from `seeds/<feat>/` when present.
+2. THE SYSTEM SHALL record provenance in `spec.json` (`plan: <slug>`), which the graph
+   extractor turns into a `plans` edge.
+3. IF the plan is not approved THEN the system SHALL warn (human use) and, WHEN invoked
+   by `plan run`, SHALL fail.
+
+### Requirement 9: The runner (`csdd plan run`) — a layer above the spec flow
+**Objective:** As the project owner, I want csdd itself to drive the loop — spawning
+fresh sessions, validating everything between steps, approving only on green — so
+autonomous development is csdd-controlled end to end.
+**Acceptance Criteria**
+1. WHEN `csdd plan run <slug>` starts THEN the system SHALL verify: plan approved and
+   drift-free, `claude` CLI available, and the execution mode — `--autonomous`
+   requires `csdd sandbox doctor` to pass and adds
+   `--dangerously-skip-permissions`; otherwise the runner operates supervised with
+   `--permission-mode acceptEdits`.
+2. THE SYSTEM SHALL iterate: `next` → `brief` → spawn
+   `claude -p <brief> --output-format json --json-schema <verdict schema>` (with
+   `--max-budget-usd` from `--session-budget` only when set; the default is no
+   per-session cap — sessions run under the Claude account's own limits) → parse the verdict →
+   run the gates for the step (spec phase: `csdd spec validate`; implementation task:
+   the plan's Quality Gates plus `csdd graph analyze --strict`; wiki lint when wiki
+   files changed) → on green, the RUNNER SHALL execute `csdd spec approve` (spec
+   phases) or `git commit` scoped to the session's changed paths (implementation),
+   then append a `log.md` entry.
+3. IF a gate fails THEN the system SHALL retry the step with the failure output
+   appended to the brief, up to `--max-retries` (default 2), then mark the feat
+   blocked and continue with other unblocked feats.
+4. IF the session verdict is `blocked` THEN the system SHALL append the structured
+   deviation (reason + revision proposal) to `log.md`, mark the feat blocked, and
+   continue; WHEN no unblocked feat remains THE SYSTEM SHALL exit with the
+   nothing-unblocked code.
+5. THE SYSTEM SHALL re-check plan drift every iteration and SHALL stop autonomous
+   execution immediately on mismatch.
+6. THE SYSTEM SHALL treat as a hard step failure any session that modified `plan.md`,
+   `plan.json`, `docs/graph/`, or `.csdd/` (verified mechanically from the git status
+   of the workspace), and SHALL never let a session execute approvals.
+7. THE SYSTEM SHALL honor `--max-iterations` (default 25) and report totals
+   (steps, retries, blocks, spend when available) on exit.
+
+### Requirement 10: Sandbox scaffolding (`csdd sandbox init`)
+**Objective:** As a user, I want one command to install the hardened devcontainer at
+the project root, so bypass-mode Claude runs isolated and language-agnostic.
+**Acceptance Criteria**
+1. WHEN `csdd sandbox init` runs THEN the system SHALL scaffold `.devcontainer/` with
+   the four-file template: `devcontainer.json`, `Dockerfile`
+   (`mcr.microsoft.com/devcontainers/base:ubuntu-24.04`, non-root `vscode` user, no
+   language runtime baked in), `init-firewall.sh` (default-deny egress with
+   self-verification), and `allowed-domains.txt` (Anthropic/GitHub/npm/VS Code plus
+   Ubuntu apt domains; language-registry presets commented).
+2. THE SYSTEM SHALL support `--feature <name>` (adds the devcontainer feature block and
+   uncomments its registry domains), `--allow-domain <d>` (appends), and `--hardened`
+   (sets the build arg restricting sudo to the firewall script).
+3. THE SYSTEM SHALL write all four files LF-normalized (the firewall script must
+   survive CRLF working trees) and be idempotent (`--force` to overwrite).
+
+### Requirement 11: Sandbox verification (`csdd sandbox doctor`)
+**Objective:** As the runner, I want a mechanical proof of isolation, so bypass is
+gated on evidence, not configuration hope.
+**Acceptance Criteria**
+1. WHEN `csdd sandbox doctor` runs THEN the system SHALL verify: `DEVCONTAINER=true`,
+   a non-root user, and the firewall active (a control domain unreachable AND
+   `api.anthropic.com` reachable), exiting 0 only when all hold.
+2. THE SYSTEM SHALL report each check individually (`--json` included) so failures are
+   actionable.
+
+### Requirement 12: Plans in the graph
+**Objective:** As a knowledge-base user, I want plans and feats in the same graph, so
+traceability spans plan → spec → requirement → task → code.
+**Acceptance Criteria**
+1. WHEN `csdd graph build` runs THEN the system SHALL emit a `plan` node per plan and
+   a `feat` node per feat row, with edges: plan `owns` feat, feat `plans` spec (or a
+   pending reference when the spec does not exist yet), feat `depends_on` feat, feat
+   `references` wiki pages, feat `uses_tech` stack entries.
+2. WHEN `csdd graph analyze` runs THEN the system SHALL report: spec with no inbound
+   `plans` edge ("unplanned spec" — informational, incremental adoption), feat
+   dependency cycles, and broken plan refs, alongside the existing lints.
+
+### Requirement 13: Plans in the web dashboard
+**Objective:** As an observer, I want plans visible in `csdd web`, so progress and
+health are readable without the terminal.
+**Acceptance Criteria**
+1. WHERE the dashboard is active THE SYSTEM SHALL serve a "Plans" tab listing plans
+   with approval/drift badges, and a per-plan view rendering the feat table with
+   derived status, milestone progress, and blocked flags — all read-only through the
+   existing hardened route path (host guard, redaction; PR #43).
+2. THE SYSTEM SHALL render the run journal (`log.md`) in the per-plan view.
+
+### Requirement 14: Agent integration — the PRD skill, `/prd`, CLAUDE.md moments
+**Objective:** As an agent in a csdd workspace, I want a PRD skill that generates and
+executes the whole plan flow through the CLI, so plan mode is the default way big work
+starts — one command from idea to validated plan.
+**Acceptance Criteria**
+1. THE SYSTEM SHALL install a **PRD skill** (`.claude/skills/prd/SKILL.md`) that owns
+   the authoring pipeline and drives every mechanical step through the CLI
+   (`csdd plan …`, or `npx csdd plan …` when not installed globally): **Draft**
+   (clarifying-questions interview with lettered options → goals/non-goals/user
+   stories), **Research** (docs via Context7 MCP when configured, else web → findings
+   filed as wiki pages, cited in Refs), **Stack consult** (invoke the stack skill's
+   Propose for any new tech — human decides), **Decompose** (right-sizing rule: one
+   feat = one spec, implementable in a short session chain; explicit deps;
+   milestones; seeds per feat), and **Revise** (fold `log.md` deviations into the
+   plan for re-approval). The skill scaffolds with `csdd plan init`, lints with
+   `csdd plan validate` after every authoring pass, and ends by presenting the
+   validated plan for the human `csdd plan approve`.
+2. THE SYSTEM SHALL install the **`/prd` slash command** as the primary entry point
+   (routes to the PRD skill), plus thin wrappers `/csdd-plan-validate`,
+   `/csdd-plan-status`, `/csdd-plan-run`.
+3. WHEN `csdd init` runs THEN the managed CLAUDE.md section SHALL gain the moments:
+   run `/prd` before multi-feature work; never edit an approved plan or execute
+   approvals during a run; deviations go through the Revise workflow.
+4. THE SKILL SHALL position the existing `quick-prd` skill as the lightweight
+   single-feature on-ramp: `/prd` is for initiatives that decompose into multiple
+   feats; `quick-prd` output (`docs/product/`) is an accepted *input* to Draft.
+
+---
+
+## 5. Design (content of `design.md`)
+
+### 5.1 Overview
+New package `internal/plan` (parse, validate, derive, sequence, brief, run) +
+`internal/cli/plan.go` and `internal/cli/sandbox.go` + template subtrees `plan/` and
+`sandbox/` + one graph extractor + one web tab. Zero changes to spec artifact formats;
+one additive field in `spec.json` (`plan`).
+
+### 5.2 Goals / Non-Goals
+**Goals:** formalized plan contract; mechanical plan lint; derived status; step
+sequencer; deterministic briefs; plan-seeded specs; the Go runner over `claude -p`;
+hardened sandbox scaffold + doctor; graph/web/skill integration.
+**Non-Goals (v1):** parallel feat execution in worktrees (`(P)` feats run sequentially
+in v1; the annotation is honored for ordering only); multi-plan orchestration;
+runner support for non-Claude agents; editing/merging plan revisions mechanically
+(prose is human/LLM work); csdd-published devcontainer *feature* (post-v1 idea);
+**container lifecycle management** — `csdd sandbox` only scaffolds the setup; starting,
+rebuilding and stopping the environment is the developer's act (IDE "Reopen in
+Container" / devcontainer tooling), and the runner never launches containers — it runs
+*inside* whatever environment the developer started, proving isolation via `doctor`.
+
+### 5.3 Reuse map (verified against the current tree)
+| Need | Exists in | Use |
+|---|---|---|
+| CLI dispatch pattern | `internal/cli/cli.go` switch + `parseFlags` | `plan`/`sandbox` cases |
+| Spec lifecycle + approvals | `internal/cli/spec.go` (`SpecJSON`, phase gates, content-hash drift) | runner drives it; `plan.json` mirrors the pattern |
+| Artifact validation | `internal/validator` | gates; EARS lint reused for seeds |
+| Frontmatter | `internal/frontmatter` | plan.md frontmatter |
+| Paths | `internal/paths` (`DocsPlans` already exists) | plan/sandbox layout |
+| Graph extractor seam | `internal/graph` `Extractor` | `extract_plan.go` |
+| Templates | `internal/templater` (embedded, LF-normalized) | `templates/plan/`, `templates/sandbox/` |
+| Web hardening | `internal/web` read-only routes (PR #43) | Plans tab |
+| Managed CLAUDE.md | `internal/cli/claudemd.go` | plan-mode moments |
+
+### 5.4 The plan grammar (parser spec, deterministic)
+- Frontmatter: `name`, `status`. Prose sections are free except the three parseable
+  ones: `## Feats` (table per R2.1 — one feat per row, cells trimmed, `Refs` tokenized
+  by whitespace), `## Quality Gates` (`- label: command` lines), `## Executor Notes`
+  (opaque). Unknown sections are preserved and ignored.
+- `Depends` cells resolve against feat slugs only (never spec dirs) at parse time;
+  unresolved → validate finding, never dropped.
+- Hashing (R4): SHA-256 over `plan.md` bytes + sorted `seeds/**` (path, bytes) pairs —
+  same discipline as `phaseContentHash`.
+
+### 5.5 Derivation (status) and sequencing (next)
+`status.go` reads `spec.json` + `tasks.md` checkboxes through the same parsing the
+graph's `extract_spec.go` uses (shared helpers, not duplicated regexes). `seq.go` is a
+pure function of (parsed plan, derived statuses, block markers) → `Step`; total
+deterministic ordering (milestone → table order → phase order → tasks.md order) so the
+same workspace always yields the same next step.
+
+### 5.6 The runner
+```go
+type Verdict struct {
+    Status   string // done | blocked
+    Summary  string
+    Revision string // populated when Status == blocked
+}
+```
+`runner.go`: loop { drift check → `next` → `brief` → `exec.Command("claude", "-p",
+brief, "--output-format", "json", "--json-schema", verdictSchema, budgetFlags...,
+modeFlags...)` → parse → gates → advance/retry/block → journal }. Gates and approvals
+run in the runner's process (never delegated to the session). Changed-path audit
+(R9.6) via `git status --porcelain` diffed against the step's allowed roots. Journal
+entries are single mechanical lines: `## [YYYY-MM-DD] <step> | <feat> | <outcome>`.
+Mode selection: `--autonomous` → `sandbox doctor` must pass → bypass flag; default
+supervised → `--permission-mode acceptEdits`. All `claude` flags used are pinned in
+one table in the code with a doctor-style preflight (`claude --version` logged).
+
+### 5.7 Sandbox
+Templates are the four files delivered with this design (Ubuntu 24.04 devcontainers
+base; Claude Code + gh as devcontainer features; toolchains via features/apt;
+`allowed-domains.txt` externalized; `HARDENED` build arg for the sudo policy).
+`doctor.go` implements R11 with no network beyond the two probe requests.
+**Scope boundary:** `sandbox init` produces the setup and stops there. The workflow is:
+developer runs `csdd sandbox init` once → opens the environment through their IDE
+(Reopen in Container) or devcontainer tooling → inside it, runs
+`npx csdd plan run <slug> --autonomous`. csdd never invokes docker/devcontainer
+commands; `doctor` is its only relationship with the running environment.
+
+### 5.8 CLI surface
+```text
+csdd plan     init <slug> | validate <slug> | approve <slug> | status <slug> [--json]
+              next <slug> [--json] | brief <slug> --step [--json]
+              generate <slug> <feat> | run <slug> [--autonomous] [--session-budget N]
+                                       [--max-iterations N] [--max-retries N]
+csdd sandbox  init [--feature F]... [--allow-domain D]... [--hardened] [--force]
+              doctor [--json]
+```
+
+### 5.9 File structure plan
+```text
+internal/plan/
+├── model.go        # PlanDoc, Feat, Step, Verdict, plan.json          [Model]
+├── parse.go        # plan.md grammar (feats/gates/notes/frontmatter)  [Parse]
+├── validate.go     # R3 findings                                     [Validate]
+├── status.go       # R5 derivation                                   [Status]
+├── seq.go          # R6 next                                         [Sequencer]
+├── brief.go        # R7 assembly                                     [Brief]
+├── runner.go       # R9 loop (exec claude, gates, journal)           [Runner]
+├── sandbox.go      # R10 scaffold ops + R11 doctor                   [Sandbox]
+└── *_test.go       # table-driven; fixtures in internal/plan/testdata/
+internal/cli/
+├── plan.go         # `csdd plan …`                                   [CLI]
+└── sandbox.go      # `csdd sandbox …`                                [CLI]
+internal/graph/extract_plan.go                                        [Extract]
+internal/templater/templates/plan/     # plan.md.tmpl + skill + commands + claudemd
+internal/templater/templates/sandbox/  # devcontainer.json, Dockerfile,
+                                       # init-firewall.sh, allowed-domains.txt
+internal/web/frontend/src/Plans.tsx (+ route/tab)                     [Web]
+```
+**Modified:** `internal/cli/cli.go` (register), `internal/cli/spec.go` (`plan` field),
+`internal/graph` (vocab: `plan`/`feat` nodes, `plans` edge), `internal/web` (tab),
+`internal/templater` (registration), `claudemd` section.
+
+### 5.10 Requirements Traceability
+| Requirement | Components | Interfaces | Flows |
+|---|---|---|---|
+| 1.1, 1.2, 1.3 | CLI, Templates | PlanInit() | init |
+| 2.1, 2.2, 2.3, 2.4 | Parse, Model | ParsePlan() | all |
+| 3.1, 3.2, 3.3, 3.4, 3.5 | Validate | ValidatePlan() | validate |
+| 4.1, 4.2, 4.3 | CLI, Model | PlanApprove(), Hash() | approve |
+| 5.1, 5.2, 5.3 | Status | DeriveStatus() | status |
+| 6.1, 6.2, 6.3 | Sequencer | Next() | next |
+| 7.1, 7.2, 7.3 | Brief | Brief() | brief |
+| 8.1, 8.2, 8.3 | CLI, Templates | PlanGenerate() | generate |
+| 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7 | Runner | Run() | run |
+| 10.1, 10.2, 10.3 | Sandbox, Templates | SandboxInit() | sandbox-init |
+| 11.1, 11.2 | Sandbox | Doctor() | doctor |
+| 12.1, 12.2 | Extract | Extract(), AnalyzeGaps() | build/analyze |
+| 13.1, 13.2 | Web | Plans.tsx | web |
+| 14.1, 14.2, 14.3, 14.4 | Templates, CLI | prd skill / `/prd` / claudemd | init |
+
+---
+
+## 6. Tasks (content of `tasks.md`) — TDD, boundaries, dependencies
+
+### Phase 1: The plan contract (M1)
+- [ ] 1. Model + parser _Boundary: Parse_
+  - [ ] 1.1 RED — fixtures: feat table (good/bad grammar, dep lists, Refs tokens),
+    quality gates, executor notes, frontmatter, hash determinism
+    - _Requirements: 2.1, 2.2, 2.3, 2.4_
+  - [ ] 1.2 GREEN — `model.go` + `parse.go`
+    - _Requirements: 2.1, 2.2, 2.3, 2.4_
+- [ ] 2. Validate _Boundary: Validate_
+  - [ ] 2.1 RED — each R3 finding class incl. stack/wiki ref resolution and dep cycles
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+    - _Depends: 1.2_
+  - [ ] 2.2 GREEN — `validate.go`
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+- [ ] 3. Derived status (P) _Boundary: Status_
+  - [ ] 3.1 RED — fixture workspace: feats in every state; block markers; drift flag
+    - _Requirements: 5.1, 5.2, 5.3_
+    - _Depends: 1.2_
+  - [ ] 3.2 GREEN — `status.go` (shared spec-parsing helpers with `internal/graph`)
+    - _Requirements: 5.1, 5.2, 5.3_
+- [ ] 4. CLI init/validate/status + plan template (P) _Boundary: CLI_
+  - [ ] 4.1 RED — command surface, flags, `--json`, exit codes, idempotent scaffold
+    - _Requirements: 1.1, 1.2, 1.3_
+    - _Depends: 2.2, 3.2_
+  - [ ] 4.2 GREEN — `internal/cli/plan.go` (partial) + `templates/plan/plan.md.tmpl`
+    - _Requirements: 1.1, 1.2, 1.3_
+- [ ] 5. Graph extractor + analyze lints (P) _Boundary: Extract_
+  - [ ] 5.1 RED — plan/feat nodes, plans/depends_on/references/uses_tech edges,
+    pending refs, unplanned-spec + cycle findings
+    - _Requirements: 12.1, 12.2_
+    - _Depends: 1.2_
+  - [ ] 5.2 GREEN — `extract_plan.go` + vocab + analyze rules
+    - _Requirements: 12.1, 12.2_
+
+### Phase 2: Sandbox (M2 — independent; may ship first)
+- [ ] 6. Sandbox templates + init _Boundary: Sandbox_
+  - [ ] 6.1 RED — four-file scaffold, LF enforcement, `--feature`/`--allow-domain`
+    edits, `--hardened` arg, idempotence
+    - _Requirements: 10.1, 10.2, 10.3_
+  - [ ] 6.2 GREEN — `templates/sandbox/` + `sandbox.go` init + `cli/sandbox.go`
+    - _Requirements: 10.1, 10.2, 10.3_
+- [ ] 7. Doctor _Boundary: Sandbox_
+  - [ ] 7.1 RED — each check individually reportable; probe stubs; exit codes
+    - _Requirements: 11.1, 11.2_
+    - _Depends: 6.2_
+  - [ ] 7.2 GREEN — `Doctor()`
+    - _Requirements: 11.1, 11.2_
+
+### Phase 3: The bridge (M3)
+- [ ] 8. Approve + drift _Boundary: Model_
+  - [ ] 8.1 RED — hash over plan.md+seeds, refuse on findings, drift detection paths
+    - _Requirements: 4.1, 4.2, 4.3_
+    - _Depends: 2.2_
+  - [ ] 8.2 GREEN — `PlanApprove()` + plan.json IO
+    - _Requirements: 4.1, 4.2, 4.3_
+- [ ] 9. Sequencer (P) _Boundary: Sequencer_
+  - [ ] 9.1 RED — dep/milestone/order matrix, step progression incl. task-level,
+    exit codes 0/3/4/5, determinism (double-run equality)
+    - _Requirements: 6.1, 6.2, 6.3_
+    - _Depends: 3.2, 8.2_
+  - [ ] 9.2 GREEN — `seq.go`
+    - _Requirements: 6.1, 6.2, 6.3_
+- [ ] 10. Brief (P) _Boundary: Brief_
+  - [ ] 10.1 RED — byte-determinism; stack rows inlined; wiki refs as path+description;
+    forbidden-actions text present; seeds included
+    - _Requirements: 7.1, 7.2, 7.3_
+    - _Depends: 9.2_
+  - [ ] 10.2 GREEN — `brief.go`
+    - _Requirements: 7.1, 7.2, 7.3_
+- [ ] 11. Generate (P) _Boundary: CLI_
+  - [ ] 11.1 RED — spec scaffold with seeds, `plan` provenance in spec.json,
+    approved-plan enforcement
+    - _Requirements: 8.1, 8.2, 8.3_
+    - _Depends: 8.2_
+  - [ ] 11.2 GREEN — `PlanGenerate()` + spec.json field
+    - _Requirements: 8.1, 8.2, 8.3_
+- [ ] 12. PRD skill + `/prd` + CLAUDE.md moments (P) _Boundary: Templates_
+  - [ ] 12.1 RED — skill workflows present (Draft/Research/Stack/Decompose/Revise),
+    CLI-driven via `csdd plan`/`npx csdd plan` (no direct approve/graph writes),
+    `/prd` + wrapper commands, claudemd section, quick-prd positioning
+    - _Requirements: 14.1, 14.2, 14.3, 14.4_
+  - [ ] 12.2 GREEN — `templates/plan/` prd skill + commands + claudemd wiring
+    - _Requirements: 14.1, 14.2, 14.3, 14.4_
+
+### Phase 4: The runner (M4)
+- [ ] 13. Runner core _Boundary: Runner_
+  - [ ] 13.1 RED — with a stub `claude` binary in testdata: verdict parsing, gate
+    pipeline, retry-with-failure-appended, block marker + continue, path audit
+    (R9.6), journal format
+    - _Requirements: 9.2, 9.3, 9.4, 9.6_
+    - _Depends: 9.2, 10.2, 11.2_
+  - [ ] 13.2 GREEN — `runner.go`
+    - _Requirements: 9.2, 9.3, 9.4, 9.6_
+- [ ] 14. Run orchestration _Boundary: Runner_
+  - [ ] 14.1 RED — preflight (approval/drift/claude present), mode selection via
+    doctor, budgets, iteration cap, exit summary, drift-stop mid-run
+    - _Requirements: 9.1, 9.5, 9.7_
+    - _Depends: 13.2, 7.2_
+  - [ ] 14.2 GREEN — `Run()` + `csdd plan run` wiring
+    - _Requirements: 9.1, 9.5, 9.7_
+
+### Phase 5: Surfaces + validation (M5)
+- [ ] 15. Web Plans tab (P) _Boundary: Web_
+  - [ ] 15.1 RED — hardened read-only routes for plan list/detail/journal
+    - _Requirements: 13.1, 13.2_
+    - _Depends: 3.2_
+  - [ ] 15.2 GREEN — `Plans.tsx` + routes
+    - _Requirements: 13.1, 13.2_
+- [ ] 16. E2E golden path
+  - [ ] 16.1 e2e on a fixture workspace: init → author → validate → approve →
+    generate → (stub runner) run one feat to done → status/graph/web agree;
+    `CGO_ENABLED=0` for all dist targets
+    - _Requirements: 9.1, 9.2, 5.1_
+    - _Depends: 14.2, 15.2_
+
+**Execution order:** 1 → {2, 3, 5} → 4 → 8 → {9, 11, 12} → 10 → 13 → 14 → {15, 16}.
+Phase 2 (6–7) is independent and may ship any time, including first.
+
+---
+
+## 7. Milestones
+
+| Milestone | Delivery | Tasks |
+|---|---|---|
+| **M1 — The plan contract** | template + `init/validate/status`; plans in the graph; dogfood: this file passes `validate` | 1–5 |
+| **M2 — Sandbox (independent)** | `.devcontainer/` scaffold + `doctor`; safe bypass exists before the loop does | 6–7 |
+| **M3 — The bridge** | `approve/next/brief/generate` + plan skill; the workflow is followable by hand or supervised session | 8–12 |
+| **M4 — The runner** | `csdd plan run` (supervised + autonomous); deviation protocol live | 13–14 |
+| **M5 — Surfaces** | web Plans tab + journal view; e2e golden path | 15–16 |
+| **Post-v1** | `(P)` feats in parallel worktrees (`claude -w`); csdd-published devcontainer feature; stack.md-driven sandbox suggestions; live run streaming in the dashboard | — |
+
+---
+
+## 8. Risks and decisions
+
+- **`claude` CLI coupling (accepted, contained).** The runner shells out to `claude`;
+  flags may drift across versions. Guard: all used flags live in one table, a preflight
+  logs `claude --version`, and every other csdd command works without `claude`
+  installed (principle 2).
+- **Gate gaming (designed out).** Sessions cannot approve, cannot touch
+  `plan.md`/`plan.json`/`docs/graph/`/`.csdd/` (mechanical path audit, R9.6), and the
+  runner owns commits. The contract chain is the only path to advancement.
+- **Runaway spend (bounded).** `--max-iterations` and retry caps bound the loop;
+  totals land in the exit summary and journal. Per-session `--max-budget-usd` is
+  **off by default** (sessions run under the Claude account's own limits) and set
+  only via an explicit `--session-budget` when a tighter ceiling is wanted.
+- **Firewall is best-effort under full sudo (documented trade-off).** `HARDENED=true`
+  is the recommended sandbox build for unattended runs; doctor reports the sudo
+  policy so `run --autonomous` can warn.
+- **Prose/machine boundary (kept).** The CLI writes only `plan.json` and `log.md`
+  (mechanical formats with precedents: `spec.json`, `docs/graph/log.md`). Revisions
+  remain human/LLM acts followed by re-approval.
+- **Right-sizing is a convention, not a lint (v1).** The skill teaches it; a
+  seeds-size heuristic lint may come later if runs show oversized feats.
+- **This document predates its own tooling.** It follows the §4/§5/§6 convention so
+  the M1 parser can be pointed at it; migration to `docs/plans/plan-mode/` happens
+  when task 4 lands.
+
+---
+
+## 9. Appendices
+
+### 9.1 References
+- `docs/plans/PLAN-knowledge-base.md` — the archetype and the substrate (graph, wiki,
+  stack are prerequisites this feature consumes).
+- github.com/snarktank/ralph — PRD skill (`skills/prd/SKILL.md`) and loop mechanics.
+- github.com/protonspy/devcontainer-claude-code — sandbox base (this design rebases it
+  onto language-agnostic Ubuntu; draft files delivered 2026-07-06).
+- code.claude.com/docs/en/devcontainer — official reference: firewall, non-root
+  requirement for bypass, credential caveats (never mount host secrets; trusted repos
+  only).
+
+### 9.2 Executor notes (this repo / workstation)
+- **Verify:** `make check` (gofmt + vet + race). Distribution gate: `CGO_ENABLED=0`
+  via `make dist` (6 targets).
+- **CLI pattern:** stdlib `flag` + subcommand switch in `internal/cli/cli.go`;
+  `--json` via the `jsonout` helpers; table-driven tests beside each file.
+- **Line endings:** CRLF working tree over LF index on this workstation — stage only
+  the paths you changed; never `git add -A`. Sandbox files must be written LF.
+- **Flaky tests:** four update/clean `.old`-backup CLI tests fail non-deterministically
+  on `/mnt/c` (WSL) — re-run before treating as regression.
+- **Go toolchain:** `~/.local/go/bin` (export PATH + GOPATH/GOCACHE).
+- **Before starting:** `git fetch origin` and check open PRs — parallel sessions land
+  related work.
+- **Commits/PRs:** conventional style (`feat(plan): …`); repo templates forbid
+  AI attribution in commits/PRs.
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index b96625e..6819017 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -56,6 +56,10 @@ func Run(args []string, templates embed.FS) int {
 		return runSteering(rest, templates)
 	case "spec":
 		return runSpec(rest, templates)
+	case "plan":
+		return runPlan(rest, templates)
+	case "sandbox":
+		return runSandbox(rest, templates)
 	case "skill":
 		return runSkill(rest, templates)
 	case "agent":
@@ -140,6 +144,8 @@ RESOURCES
   destroy                     Tear the workspace back down (.claude/, CLAUDE.md, .mcp.json, pre-push); keeps specs/. Asks to confirm; --force to skip.
   steering {init,create,list,show,delete,validate}
   spec     {init,list,show,status,generate,approve,validate,test-report,delete}
+  plan     {init,validate,approve,status,next,brief,generate,run}   Plans decompose an initiative into feats (docs/plans/<slug>/); each feat becomes one spec.
+  sandbox  {init,doctor}                        Scaffold a hardened default-deny-egress devcontainer; doctor proves isolation before bypass mode.
   skill    {create,list,show,add-reference,add-script,add-asset,validate,delete}
   agent    {create,list,show,delete}
   mcp      {add,install,presets,list,show,remove,enable,disable,validate}
diff --git a/internal/cli/glossary_cli_test.go b/internal/cli/glossary_cli_test.go
new file mode 100644
index 0000000..0e54e03
--- /dev/null
+++ b/internal/cli/glossary_cli_test.go
@@ -0,0 +1,128 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestGlossarySkillAndCommandInstalled asserts the M2 template surface: the
+// glossary skill (four moves, tombstone, lazy inline write, graph-query-first,
+// contract purity, gate-positive hand-off), the /glossary command, the flow
+// hooks in prd/quick-prd/wiki, and the knowledge-section + CLAUDE.md moment.
+func TestGlossarySkillAndCommandInstalled(t *testing.T) {
+	dir := freshWorkspace(t)
+
+	// The skill installs and passes the skill validator.
+	if _, err := os.Stat(filepath.Join(dir, ".claude", "skills", "glossary", "SKILL.md")); err != nil {
+		t.Fatalf("glossary skill not installed: %v", err)
+	}
+	if code, _, errOut := run(t, "skill", "validate", "glossary", "--root", dir); code != 0 {
+		t.Errorf("glossary skill failed validation (code=%d): %s", code, errOut)
+	}
+	if _, err := os.Stat(filepath.Join(dir, ".claude", "commands", "glossary.md")); err != nil {
+		t.Errorf("/glossary command not installed: %v", err)
+	}
+
+	gl := readFile(t, filepath.Join(dir, ".claude", "skills", "glossary", "SKILL.md"))
+	for _, want := range []string{
+		"Challenge", "Sharpen", "Stress-test", "Cross-reference", // four moves
+		"tombstone",           // the tombstone rule
+		"immediately",         // inline write
+		"lazily",              // lazy creation
+		"csdd graph query",    // graph-query-before-asking
+		"zero implementation", // contract purity
+		"decision grill",      // gate-positive hand-off
+	} {
+		if !strings.Contains(gl, want) {
+			t.Errorf("glossary skill missing %q", want)
+		}
+	}
+
+	// Flow hooks — invocation only.
+	prd := readFile(t, filepath.Join(dir, ".claude", "skills", "prd", "SKILL.md"))
+	if !strings.Contains(prd, "glossary skill") || !strings.Contains(prd, "canonical terms") {
+		t.Errorf("prd skill missing glossary Draft/Decompose hook")
+	}
+	quick := readFile(t, filepath.Join(dir, ".claude", "skills", "quick-prd", "SKILL.md"))
+	if !strings.Contains(quick, "glossary skill") {
+		t.Errorf("quick-prd skill missing glossary hook")
+	}
+	wiki := readFile(t, filepath.Join(dir, ".claude", "skills", "wiki", "SKILL.md"))
+	if !strings.Contains(wiki, "glossary") || !strings.Contains(wiki, "canonical terms") {
+		t.Errorf("wiki skill missing glossary Ingest hook")
+	}
+
+	// Satellites.
+	claudemd := readFile(t, filepath.Join(dir, "CLAUDE.md"))
+	for _, want := range []string{"docs/glossary.md", "canonical term", "tombstone"} {
+		if !strings.Contains(claudemd, want) {
+			t.Errorf("CLAUDE.md managed section missing glossary moment %q", want)
+		}
+	}
+}
+
+const glossaryPlan = `---
+name: shop
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | client-sync | sync the buyer records | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+const dogfoodGlossary = `## Language
+
+**Customer**: A person or organization that buys.
+_Avoid_: client, account
+
+**Feat**: One row of a plan's Feats table.
+_Avoid_: feature
+`
+
+// TestGlossaryLintE2E drives the identifier lint end to end: an avoided feat slug
+// fails plan validate; an avoided wiki page name surfaces in wiki lint; term nodes
+// answer graph query; and the orphan-term informational fires.
+func TestGlossaryLintE2E(t *testing.T) {
+	dir := freshWorkspace(t)
+	mustWrite(t, filepath.Join(dir, "docs", "glossary.md"), dogfoodGlossary)
+
+	// 1. An avoided feat slug ("client-sync" — client is avoided) fails validate.
+	if code, _, e := run(t, "plan", "init", "shop", "--root", dir); code != 0 {
+		t.Fatalf("plan init: %s", e)
+	}
+	mustWrite(t, filepath.Join(dir, "docs", "plans", "shop", "plan.md"), glossaryPlan)
+	code, _, errOut := run(t, "plan", "validate", "shop", "--root", dir)
+	if code != 2 || !strings.Contains(errOut, "avoided term 'client'") {
+		t.Errorf("avoided feat slug should fail validate; code=%d err=%s", code, errOut)
+	}
+
+	// 2. An avoided wiki page name surfaces in wiki lint (corpus-filtered).
+	mustWrite(t, filepath.Join(dir, "docs", "wiki", "pages", "account-portal.md"), "# Account Portal\n")
+	code, out, _ := run(t, "wiki", "lint", "--root", dir)
+	if code != 2 || !strings.Contains(out, "avoided term 'account'") {
+		t.Errorf("avoided wiki page name should surface in wiki lint; code=%d out=%s", code, out)
+	}
+
+	// 3. Term nodes answer graph query.
+	if code, _, e := run(t, "graph", "build", "--root", dir); code != 0 {
+		t.Fatalf("graph build: %s", e)
+	}
+	code, out, _ = run(t, "graph", "query", "Customer", "--root", dir)
+	if code != 0 || !strings.Contains(strings.ToLower(out), "customer") {
+		t.Errorf("graph query should find the Customer term node; code=%d out=%s", code, out)
+	}
+
+	// 4. The orphan-term informational fires (Feat is unused here).
+	code, out, _ = run(t, "graph", "analyze", "--root", dir)
+	if !strings.Contains(out, "orphan term") {
+		t.Errorf("expected an orphan_term finding in analyze; out=%s", out)
+	}
+}
diff --git a/internal/cli/plan.go b/internal/cli/plan.go
new file mode 100644
index 0000000..245071d
--- /dev/null
+++ b/internal/cli/plan.go
@@ -0,0 +1,543 @@
+package cli
+
+import (
+	"embed"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/plan"
+	"github.com/protonspy/csdd/internal/render"
+	"github.com/protonspy/csdd/internal/templater"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// runPlan dispatches `csdd plan <action> ...`. M1 ships init/validate/status;
+// approve/next/brief/generate/run land in later milestones (§5.8).
+func runPlan(args []string, templates embed.FS) int {
+	action, rest, err := parseAction("plan", args)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if isHelpFlag(action) {
+		help(os.Stdout)
+		return 0
+	}
+	switch action {
+	case "init":
+		return planInit(rest, templates)
+	case "validate":
+		return planValidate(rest)
+	case "status":
+		return planStatus(rest)
+	case "approve":
+		return planApprove(rest)
+	case "next":
+		return planNext(rest)
+	case "brief":
+		return planBrief(rest)
+	case "generate":
+		return planGenerate(rest, templates)
+	case "run":
+		return planRun(rest)
+	default:
+		render.Err("unknown plan action: " + action)
+		return 1
+	}
+}
+
+func planRun(args []string) int {
+	fs := flag.NewFlagSet("plan run", flag.ContinueOnError)
+	var root string
+	var autonomous bool
+	var sessionBudget float64
+	var maxIterations, maxRetries int
+	addRoot(fs, &root)
+	fs.BoolVar(&autonomous, "autonomous", false, "Run bypass-mode (--dangerously-skip-permissions); requires a verified sandbox (`sandbox doctor`).")
+	fs.Float64Var(&sessionBudget, "session-budget", 0, "Per-session cap in USD (claude --max-budget-usd). Default 0 = no cap; the session runs under the Claude account's own limits.")
+	fs.IntVar(&maxIterations, "max-iterations", 25, "Maximum loop iterations before stopping.")
+	fs.IntVar(&maxRetries, "max-retries", 2, "Retries per step before marking the feat blocked.")
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan run SLUG [--autonomous] [--session-budget N] [--max-iterations N] [--max-retries N]")
+		return 1
+	}
+	slug := positionals[0]
+	if err := workspace.SafeName(slug, "plan"); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	sum, err := plan.Run(plan.RunOptions{
+		Root:          r,
+		Slug:          slug,
+		Autonomous:    autonomous,
+		SessionBudget: sessionBudget,
+		MaxIterations: maxIterations,
+		MaxRetries:    maxRetries,
+		Out:           os.Stdout,
+	})
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	// Surface the run outcome as a distinct exit code (R9.4/R9.7); the summary is
+	// already printed by the runner.
+	return sum.Outcome
+}
+
+// requireWorkspaceMarker enforces R1.3: every plan command operates inside an
+// initialized workspace (.csdd/ present), failing with actionable guidance
+// otherwise instead of silently scaffolding into a non-workspace directory.
+func requireWorkspaceMarker(root string) error {
+	if !pathExists(paths.State(root)) {
+		return fmt.Errorf("not a csdd workspace: no %s/ found under %s. Run `%s init` first", paths.StateDir, root, prog())
+	}
+	return nil
+}
+
+func planInit(args []string, templates embed.FS) int {
+	fs := flag.NewFlagSet("plan init", flag.ContinueOnError)
+	var root string
+	var force bool
+	addRoot(fs, &root)
+	addForce(fs, &force)
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan init SLUG")
+		return 1
+	}
+	slug := positionals[0]
+	if err := workspace.KebabCheck(slug, "plan"); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if err := requireWorkspaceMarker(r); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+
+	dir := plan.Dir(r, slug)
+	content, err := templater.Render(templates, "templates/plan/plan.md.tmpl", map[string]string{"Name": slug})
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+
+	// Idempotent scaffold (R1.2): create only what is missing; --force overwrites.
+	planMD := filepath.Join(dir, "plan.md")
+	switch {
+	case pathExists(planMD) && !force:
+		render.Info(workspace.Relative(r, planMD) + " exists; left untouched (--force to overwrite)")
+	default:
+		if err := workspace.WriteFile(planMD, content, force); err != nil {
+			render.Err(err.Error())
+			return 1
+		}
+		render.OK("created " + workspace.Relative(r, planMD))
+	}
+	seeds := filepath.Join(dir, "seeds")
+	if !pathExists(seeds) {
+		if err := mkdirAll(seeds); err != nil {
+			render.Err(err.Error())
+			return 1
+		}
+		render.OK("created " + workspace.Relative(r, seeds) + "/")
+	}
+	render.Info(fmt.Sprintf("next: author the feats, then `%s plan validate %s`", prog(), slug))
+	return 0
+}
+
+// resolvePlan is the shared preamble for validate/status: resolve the root and
+// load+parse the plan, mapping the common failures to exit 1.
+func resolvePlan(root, slug string) (string, *plan.PlanDoc, int) {
+	if err := workspace.SafeName(slug, "plan"); err != nil {
+		render.Err(err.Error())
+		return "", nil, 1
+	}
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		render.Err(err.Error())
+		return "", nil, 1
+	}
+	doc, err := plan.Load(r, slug)
+	if err != nil {
+		render.Err(err.Error())
+		return "", nil, 1
+	}
+	return r, doc, 0
+}
+
+func planValidate(args []string) int {
+	fs := flag.NewFlagSet("plan validate", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan validate SLUG [--json]")
+		return 1
+	}
+	slug := positionals[0]
+	r, doc, code := resolvePlan(root, slug)
+	if code != 0 {
+		return code
+	}
+	issues := plan.ValidatePlan(doc, r)
+	if jsonOut {
+		emitJSON(validationJSON{Target: slug, OK: len(issues) == 0, Issues: issuesToJSON(issues)})
+		if len(issues) > 0 {
+			return 2
+		}
+		return 0
+	}
+	if len(issues) == 0 {
+		render.OK(slug + ": validation passed")
+		return 0
+	}
+	for _, i := range issues {
+		render.Err(i.String())
+	}
+	return 2
+}
+
+func planStatus(args []string) int {
+	fs := flag.NewFlagSet("plan status", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan status SLUG [--json]")
+		return 1
+	}
+	slug := positionals[0]
+	r, doc, code := resolvePlan(root, slug)
+	if code != 0 {
+		return code
+	}
+	st, err := plan.DeriveStatus(r, doc)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if jsonOut {
+		return emitJSON(st)
+	}
+	printPlanStatus(st)
+	return 0
+}
+
+func planApprove(args []string) int {
+	fs := flag.NewFlagSet("plan approve", flag.ContinueOnError)
+	var root string
+	var force bool
+	addRoot(fs, &root)
+	addForce(fs, &force)
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan approve SLUG")
+		return 1
+	}
+	r, doc, code := resolvePlan(root, positionals[0])
+	if code != 0 {
+		return code
+	}
+	issues := plan.ValidatePlan(doc, r)
+	if len(issues) > 0 {
+		for _, i := range issues {
+			render.Err(i.String())
+		}
+		if !force {
+			render.Err("approval blocked by validation findings; fix them or pass --force")
+			return 2
+		}
+		render.Warn("approving despite validation findings (--force)")
+	}
+	if err := plan.ApprovePlan(r, doc, time.Now()); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	render.OK(doc.Slug + ": approved (bound to the current plan.md + seeds hash)")
+	return 0
+}
+
+func planNext(args []string) int {
+	fs := flag.NewFlagSet("plan next", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan next SLUG [--json]")
+		return 1
+	}
+	r, doc, code := resolvePlan(root, positionals[0])
+	if code != 0 {
+		return code
+	}
+	// The sequencer gates on approval so `next` reports drift/not-approved as its
+	// own exit code (R6.3), matching what `run` sees.
+	step, outcome, err := plan.Next(r, doc, true)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	switch outcome {
+	case plan.SeqStep:
+		if jsonOut {
+			return emitJSON(step)
+		}
+		render.OK(step.Feat + " → " + step.Step)
+		if step.Reason != "" {
+			render.Info(step.Reason)
+		}
+		return 0
+	case plan.SeqComplete:
+		if jsonOut {
+			emitJSON(map[string]string{"status": "complete"})
+		} else {
+			render.OK("plan complete: every feat is done")
+		}
+		return 3
+	case plan.SeqNothing:
+		if jsonOut {
+			emitJSON(map[string]string{"status": "nothing_unblocked"})
+		} else {
+			render.Warn("nothing unblocked: remaining feats are blocked or waiting on blocked deps")
+		}
+		return 4
+	default: // SeqNotReady
+		if jsonOut {
+			emitJSON(map[string]string{"status": "not_ready"})
+		} else {
+			render.Err("plan is not approved or has drifted; run `" + prog() + " plan approve " + doc.Slug + "`")
+		}
+		return 5
+	}
+}
+
+func planBrief(args []string) int {
+	fs := flag.NewFlagSet("plan brief", flag.ContinueOnError)
+	var root, feat, step string
+	addRoot(fs, &root)
+	fs.StringVar(&feat, "feat", "", "Feat to brief (with --step; default: the sequencer's next step).")
+	fs.StringVar(&step, "step", "", "Step to brief, e.g. 'spec-requirements' or 'task 1.2' (with --feat).")
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 1 {
+		render.Err("usage: " + prog() + " plan brief SLUG [--feat F --step S]")
+		return 1
+	}
+	r, doc, code := resolvePlan(root, positionals[0])
+	if code != 0 {
+		return code
+	}
+	var target plan.Step
+	if feat != "" || step != "" {
+		if feat == "" || step == "" {
+			render.Err("--feat and --step must be given together")
+			return 1
+		}
+		target = plan.Step{Feat: feat, Step: step}
+	} else {
+		s, outcome, err := plan.Next(r, doc, false)
+		if err != nil {
+			render.Err(err.Error())
+			return 1
+		}
+		if outcome != plan.SeqStep {
+			render.Err("no next step to brief (plan complete or nothing unblocked)")
+			return 1
+		}
+		target = s
+	}
+	out, err := plan.Brief(r, doc, target)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	fmt.Print(out)
+	return 0
+}
+
+func planGenerate(args []string, templates embed.FS) int {
+	fs := flag.NewFlagSet("plan generate", flag.ContinueOnError)
+	var root string
+	var force, requireApproved bool
+	addRoot(fs, &root)
+	addForce(fs, &force)
+	fs.BoolVar(&requireApproved, "require-approved", false, "Fail unless the plan is approved and drift-free (used by `plan run`).")
+	positionals, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(positionals) < 2 {
+		render.Err("usage: " + prog() + " plan generate SLUG FEAT")
+		return 1
+	}
+	slug, feat := positionals[0], positionals[1]
+	r, doc, code := resolvePlan(root, slug)
+	if code != 0 {
+		return code
+	}
+	if err := workspace.SafeName(feat, "feat"); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if _, ok := doc.Feat(feat); !ok {
+		render.Err("feat '" + feat + "' is not in plan '" + slug + "'")
+		return 1
+	}
+	approved, drift, _ := plan.IsApproved(r, slug)
+	if !approved || drift {
+		if requireApproved {
+			render.Err("plan '" + slug + "' is not approved or has drifted; approve before generating")
+			return 1
+		}
+		render.Warn("plan '" + slug + "' is not approved; generating anyway (human use)")
+	}
+
+	specDir := filepath.Join(paths.Specs(r), feat)
+	if !pathExists(specDir) {
+		if err := SpecInit(templates, SpecInitOptions{Root: r, Feature: feat}); err != nil {
+			render.Err(err.Error())
+			return 1
+		}
+	} else {
+		render.Info("spec '" + feat + "' already exists; seeding missing artifacts and provenance")
+	}
+	seeded, err := seedSpecFromPlan(r, slug, feat, force)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	for _, s := range seeded {
+		render.OK("seeded specs/" + feat + "/" + s + " (review before approving)")
+	}
+	render.OK("generated spec for feat '" + feat + "' (provenance: plan=" + slug + ")")
+	return 0
+}
+
+// seedSpecFromPlan records plan provenance on the spec and copies any pre-authored
+// seed artifacts (requirements/design/tasks) from docs/plans/<slug>/seeds/<feat>/
+// into the spec, marking each seeded phase generated (not approved — a human/
+// runner still reviews). It returns the artifact basenames it seeded.
+func seedSpecFromPlan(root, slug, feat string, force bool) ([]string, error) {
+	specDir := filepath.Join(paths.Specs(root), feat)
+	data, err := loadSpecJSON(specDir)
+	if err != nil {
+		return nil, err
+	}
+	data.Plan = slug
+	seedDir := filepath.Join(plan.Dir(root, slug), "seeds", feat)
+	var seeded []string
+	for _, art := range workspace.SpecPhases {
+		seedFile := filepath.Join(seedDir, art+".md")
+		if !pathExists(seedFile) {
+			continue
+		}
+		target := filepath.Join(specDir, art+".md")
+		if pathExists(target) && !force {
+			continue
+		}
+		content, rerr := os.ReadFile(seedFile)
+		if rerr != nil {
+			return nil, rerr
+		}
+		if err := workspace.WriteFile(target, string(content), true); err != nil {
+			return nil, err
+		}
+		a := data.Approvals[art]
+		a.Generated = true
+		a.Approved = false
+		a.ContentHash = ""
+		if data.Approvals == nil {
+			data.Approvals = map[string]ApprovalFlag{}
+		}
+		data.Approvals[art] = a
+		data.Phase = phaseFor(art)
+		data.ReadyForImplementation = false
+		seeded = append(seeded, art+".md")
+	}
+	if err := saveSpecJSON(specDir, data); err != nil {
+		return nil, err
+	}
+	return seeded, nil
+}
+
+// printPlanStatus renders the human table: plan-level flags, then one line per
+// feat with its derived state and (where meaningful) task progress.
+func printPlanStatus(st plan.PlanStatus) {
+	fmt.Println(render.Bold("plan: " + st.Slug))
+	approved := render.Yellow("draft")
+	if st.Approved {
+		approved = render.Green("approved")
+	}
+	fmt.Println("approval: " + approved)
+	if st.Drift {
+		fmt.Println("drift:    " + render.Red("plan.md/seeds changed since approval — re-approve before running"))
+	}
+	if st.Deviations > 0 {
+		fmt.Println("deviations: " + render.Yellow(fmt.Sprintf("%d unprocessed in log.md", st.Deviations)))
+	}
+	if len(st.Feats) == 0 {
+		render.Info("no feats defined")
+		return
+	}
+	maxName := len("feat")
+	for _, f := range st.Feats {
+		if len(f.Slug) > maxName {
+			maxName = len(f.Slug)
+		}
+	}
+	// States are printed plain (no ANSI) so the fixed-width columns stay aligned
+	// regardless of terminal color support.
+	fmt.Printf("  %-3s %-*s  %-13s  %-10s  %s\n", "#", maxName, "feat", "state", "milestone", "progress")
+	for _, f := range st.Feats {
+		progress := ""
+		if f.TasksTotal > 0 {
+			progress = fmt.Sprintf("%d/%d tasks", f.TasksChecked, f.TasksTotal)
+		}
+		if f.BlockReason != "" {
+			progress = f.BlockReason
+		}
+		fmt.Printf("  %-3s %-*s  %-13s  %-10s  %s\n", f.Num, maxName, f.Slug, f.State, f.Milestone, progress)
+	}
+}
diff --git a/internal/cli/plan_adr_test.go b/internal/cli/plan_adr_test.go
new file mode 100644
index 0000000..7dea73b
--- /dev/null
+++ b/internal/cli/plan_adr_test.go
@@ -0,0 +1,129 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestADRDisciplineInstalledSkills asserts the M2 template surface: the triple
+// gate and grill live in the prd skill, the light gate in quick-prd, the adr:
+// token in the plan template, and the decision moment in the managed CLAUDE.md
+// section.
+func TestADRDisciplineInstalledSkills(t *testing.T) {
+	dir := freshWorkspace(t)
+
+	prd := readFile(t, filepath.Join(dir, ".claude", "skills", "prd", "SKILL.md"))
+	for _, want := range []string{
+		"Hard to reverse", "Surprising without context", "real trade-off", // triple gate
+		"One decision per exchange", "Recommendation first", "Dependency order", // grill rules
+		"Tier 1", "Tier 2", // two-tier Draft
+		"the moment it resolves", // inline ADR write
+		"[DEFERRED-BY-HUMAN]",    // Present sweep
+		"superseded-by",          // Revise funnel supersession
+		"adr:<slug>",             // Decompose citation
+	} {
+		if !strings.Contains(prd, want) {
+			t.Errorf("prd SKILL.md missing decision-grill element %q", want)
+		}
+	}
+
+	quick := readFile(t, filepath.Join(dir, ".claude", "skills", "quick-prd", "SKILL.md"))
+	for _, want := range []string{"Hard to reverse", "docs/adr/", "recorded decisions"} {
+		if !strings.Contains(quick, want) {
+			t.Errorf("quick-prd SKILL.md missing light-gate element %q", want)
+		}
+	}
+
+	// The plan template Refs comment ships via the scaffold, not an installed file.
+	if code, _, e := run(t, "plan", "init", "reftmpl", "--root", dir); code != 0 {
+		t.Fatalf("plan init: %s", e)
+	}
+	planTmpl := readFile(t, filepath.Join(dir, "docs", "plans", "reftmpl", "plan.md"))
+	if !strings.Contains(planTmpl, "adr:<slug>") {
+		t.Errorf("plan template Refs comment should document adr:<slug>")
+	}
+
+	claudemd := readFile(t, filepath.Join(dir, "CLAUDE.md"))
+	for _, want := range []string{"docs/adr/", "triple gate", "Never decide silently", "superseded"} {
+		if !strings.Contains(claudemd, want) {
+			t.Errorf("CLAUDE.md managed section missing decision moment %q", want)
+		}
+	}
+}
+
+const adrCitePlan = `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | adr:pick-store |
+
+## Quality Gates
+
+- verify: make check
+`
+
+// TestADRValidateE2E drives the decision-ref lint through the real CLI: a plan
+// citing a present ADR validates clean; broken, ambiguous, and cites-superseded
+// variants each fail with exit 2; and the brief inlines the cited record in full.
+func TestADRValidateE2E(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan init: %s", e)
+	}
+	mustWrite(t, filepath.Join(dir, "docs", "plans", "photos", "plan.md"), adrCitePlan)
+	adrPath := func(name string) string { return filepath.Join(dir, "docs", "adr", name) }
+
+	// Clean citation.
+	mustWrite(t, adrPath("0001-pick-store.md"), "# Store under docs/adr\n\nBODY_TOKEN: append-only.\n")
+	if code, _, e := run(t, "plan", "validate", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan citing a present ADR should validate clean: %s", e)
+	}
+
+	// The brief inlines the cited ADR in full.
+	code, out, _ := run(t, "plan", "brief", "photos", "--feat", "upload", "--step", "task 1.1", "--root", dir)
+	if code != 0 {
+		t.Fatalf("plan brief failed: %d", code)
+	}
+	if !strings.Contains(out, "Store under docs/adr") || !strings.Contains(out, "BODY_TOKEN") {
+		t.Errorf("brief should inline the cited ADR in full:\n%s", out)
+	}
+	if !strings.Contains(out, "OPEN DECISION") {
+		t.Errorf("brief should carry the open-decision forbidden line")
+	}
+
+	// Broken citation: rewrite the ADR to a different slug.
+	mustWrite(t, adrPath("0001-pick-store.md"), "# renamed\n\nbody\n") // still slug pick-store
+	mustWrite(t, filepath.Join(dir, "docs", "plans", "photos", "plan.md"),
+		strings.Replace(adrCitePlan, "adr:pick-store", "adr:ghost", 1))
+	if code, _, _ := run(t, "plan", "validate", "photos", "--root", dir); code != 2 {
+		t.Errorf("broken decision ref should fail validate (exit 2), got %d", code)
+	}
+
+	// Ambiguous citation: two records share the pick-store slug. Findings print to
+	// stderr, so assert against errOut.
+	mustWrite(t, filepath.Join(dir, "docs", "plans", "photos", "plan.md"), adrCitePlan)
+	mustWrite(t, adrPath("0001-pick-store.md"), "# one\n\nbody\n")
+	mustWrite(t, adrPath("0005-pick-store.md"), "# five\n\nbody\n")
+	if code, _, errOut := run(t, "plan", "validate", "photos", "--root", dir); code != 2 || !strings.Contains(errOut, "ambiguous decision ref") {
+		t.Errorf("ambiguous decision ref should fail validate; code=%d err=%s", code, errOut)
+	}
+
+	// Cites-superseded: drop the duplicate so the slug resolves uniquely to 0001,
+	// then mark 0001 superseded by a successor.
+	if err := os.Remove(adrPath("0005-pick-store.md")); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, adrPath("0001-pick-store.md"),
+		"---\nstatus: superseded\nsuperseded-by: 0002\n---\n# old\n\nbody\n")
+	mustWrite(t, adrPath("0002-pick-store-v2.md"), "# new\n\nbody\n")
+	code, _, errOut := run(t, "plan", "validate", "photos", "--root", dir)
+	if code != 2 || !strings.Contains(errOut, "cites superseded") {
+		t.Errorf("citing a superseded ADR should fail validate with a cites-superseded finding; code=%d err=%s", code, errOut)
+	}
+}
diff --git a/internal/cli/plan_bridge_cli_test.go b/internal/cli/plan_bridge_cli_test.go
new file mode 100644
index 0000000..b897615
--- /dev/null
+++ b/internal/cli/plan_bridge_cli_test.go
@@ -0,0 +1,151 @@
+package cli
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// scaffoldApprovedPlan lays down an authored plan with one seed, then approves it,
+// returning the workspace root. The seed is written BEFORE approval so the
+// approval hash covers it (adding it after would register as drift).
+func scaffoldApprovedPlan(t *testing.T) string {
+	t.Helper()
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan init failed: %s", e)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "docs", "plans", "photos", "plan.md"), []byte(authoredPlan), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// A trivial (EARS-clean) seed for upload, written BEFORE approval so the hash
+	// covers it.
+	seed := filepath.Join(dir, "docs", "plans", "photos", "seeds", "upload", "requirements.md")
+	if err := os.MkdirAll(filepath.Dir(seed), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(seed, []byte("# Requirements\n\nSeeded intent.\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if code, out, e := run(t, "plan", "approve", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan approve failed (code=%d): %s / %s", code, out, e)
+	}
+	return dir
+}
+
+func TestPlanApproveWritesJSON(t *testing.T) {
+	dir := scaffoldApprovedPlan(t)
+	data, err := os.ReadFile(filepath.Join(dir, "docs", "plans", "photos", "plan.json"))
+	if err != nil {
+		t.Fatalf("plan.json not written: %v", err)
+	}
+	var pj struct {
+		Approvals struct {
+			Approved    bool   `json:"approved"`
+			ContentHash string `json:"content_hash"`
+		} `json:"approvals"`
+	}
+	if err := json.Unmarshal(data, &pj); err != nil {
+		t.Fatal(err)
+	}
+	if !pj.Approvals.Approved || pj.Approvals.ContentHash == "" {
+		t.Errorf("plan.json should record approved+hash, got %+v", pj.Approvals)
+	}
+}
+
+func TestPlanGenerateProvenanceAndSeed(t *testing.T) {
+	dir := scaffoldApprovedPlan(t)
+	code, out, errOut := run(t, "plan", "generate", "photos", "upload", "--root", dir)
+	if code != 0 {
+		t.Fatalf("plan generate failed (code=%d): %s / %s", code, out, errOut)
+	}
+	// The spec exists with plan provenance.
+	specJSON, err := os.ReadFile(filepath.Join(dir, "specs", "upload", "spec.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(specJSON), `"plan": "photos"`) {
+		t.Errorf("spec.json missing plan provenance: %s", specJSON)
+	}
+	// The seed was copied into the spec and marked generated.
+	if _, err := os.Stat(filepath.Join(dir, "specs", "upload", "requirements.md")); err != nil {
+		t.Errorf("seed requirements.md not copied into the spec: %v", err)
+	}
+	if !strings.Contains(string(specJSON), `"generated": true`) {
+		t.Errorf("seeded phase should be marked generated: %s", specJSON)
+	}
+}
+
+func TestPlanNextAndBriefCLI(t *testing.T) {
+	dir := scaffoldApprovedPlan(t)
+	if code, _, e := run(t, "plan", "generate", "photos", "upload", "--root", dir); code != 0 {
+		t.Fatalf("generate failed: %s", e)
+	}
+	// upload now has a generated (unapproved) requirements → next is its requirements step.
+	code, out, _ := run(t, "plan", "next", "photos", "--root", dir, "--json")
+	if code != 0 {
+		t.Fatalf("plan next exit=%d out=%s", code, out)
+	}
+	if !strings.Contains(out, `"feat": "upload"`) || !strings.Contains(out, `"step": "spec-requirements"`) {
+		t.Errorf("unexpected next step: %s", out)
+	}
+	// brief prints a context pack for that step.
+	code, out, errOut := run(t, "plan", "brief", "photos", "--root", dir)
+	if code != 0 {
+		t.Fatalf("plan brief failed (code=%d): %s", code, errOut)
+	}
+	if !strings.Contains(out, "Brief — photos / upload") || !strings.Contains(out, "Forbidden actions") {
+		t.Errorf("brief output incomplete: %s", out)
+	}
+}
+
+func TestPlanGenerateRequireApprovedFails(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("init failed: %s", e)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "docs", "plans", "photos", "plan.md"), []byte(authoredPlan), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Not approved: --require-approved must refuse.
+	code, _, errOut := run(t, "plan", "generate", "photos", "upload", "--root", dir, "--require-approved")
+	if code == 0 {
+		t.Errorf("generate --require-approved should fail on an unapproved plan")
+	}
+	if !strings.Contains(errOut, "not approved") {
+		t.Errorf("expected not-approved error, got %q", errOut)
+	}
+}
+
+func TestPlanRunPreflightCLI(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("init failed: %s", e)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "docs", "plans", "photos", "plan.md"), []byte(authoredPlan), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Unapproved plan: run refuses before ever spawning a session.
+	code, _, errOut := run(t, "plan", "run", "photos", "--root", dir)
+	if code == 0 {
+		t.Errorf("plan run should refuse an unapproved plan")
+	}
+	if !strings.Contains(errOut, "not approved") {
+		t.Errorf("expected not-approved preflight error, got %q", errOut)
+	}
+}
+
+func TestPlanNextDriftExitCode(t *testing.T) {
+	dir := scaffoldApprovedPlan(t)
+	// Edit plan.md after approval → drift → next exits 5.
+	planMD := filepath.Join(dir, "docs", "plans", "photos", "plan.md")
+	if err := os.WriteFile(planMD, []byte(authoredPlan+"\n<!-- drift -->\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	code, _, _ := run(t, "plan", "next", "photos", "--root", dir)
+	if code != 5 {
+		t.Errorf("drifted plan next should exit 5, got %d", code)
+	}
+}
diff --git a/internal/cli/plan_cli_test.go b/internal/cli/plan_cli_test.go
new file mode 100644
index 0000000..df5f3f5
--- /dev/null
+++ b/internal/cli/plan_cli_test.go
@@ -0,0 +1,130 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const authoredPlan = `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | |
+| 2 | thumbs | Thumbnails | upload | M1 | P | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+func TestPlanInitScaffold(t *testing.T) {
+	dir := freshWorkspace(t)
+	code, out, errOut := run(t, "plan", "init", "photos", "--root", dir)
+	if code != 0 {
+		t.Fatalf("plan init failed (code=%d): out=%s err=%s", code, out, errOut)
+	}
+	planMD := filepath.Join(dir, "docs", "plans", "photos", "plan.md")
+	if _, err := os.Stat(planMD); err != nil {
+		t.Fatalf("plan.md not created: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "docs", "plans", "photos", "seeds")); err != nil {
+		t.Errorf("seeds/ not created: %v", err)
+	}
+	// The scaffold has all sections but no authored content, so it must not
+	// validate yet (no feats, no gates).
+	code, _, _ = run(t, "plan", "validate", "photos", "--root", dir)
+	if code != 2 {
+		t.Errorf("fresh scaffold should fail validate with exit 2, got %d", code)
+	}
+}
+
+func TestPlanInitIdempotentAndForce(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("first init failed: %s", e)
+	}
+	planMD := filepath.Join(dir, "docs", "plans", "photos", "plan.md")
+	if err := os.WriteFile(planMD, []byte(authoredPlan), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// A second init must not clobber the authored content.
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("second init failed: %s", e)
+	}
+	data, _ := os.ReadFile(planMD)
+	if !strings.Contains(string(data), "Ingest photos") {
+		t.Errorf("idempotent init overwrote authored plan.md")
+	}
+	// --force restores the template.
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir, "--force"); code != 0 {
+		t.Fatalf("forced init failed: %s", e)
+	}
+	data, _ = os.ReadFile(planMD)
+	if strings.Contains(string(data), "Ingest photos") {
+		t.Errorf("--force should have overwritten the authored plan.md")
+	}
+}
+
+func TestPlanInitRequiresWorkspace(t *testing.T) {
+	bare := t.TempDir() // no `csdd init`, so no .csdd/ marker
+	code, _, errOut := run(t, "plan", "init", "photos", "--root", bare)
+	if code == 0 {
+		t.Fatal("plan init should fail outside a csdd workspace")
+	}
+	if !strings.Contains(errOut, "not a csdd workspace") {
+		t.Errorf("expected workspace guidance, got %q", errOut)
+	}
+}
+
+func TestPlanValidateAndStatus(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("init failed: %s", e)
+	}
+	planMD := filepath.Join(dir, "docs", "plans", "photos", "plan.md")
+	if err := os.WriteFile(planMD, []byte(authoredPlan), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	code, out, errOut := run(t, "plan", "validate", "photos", "--root", dir)
+	if code != 0 {
+		t.Fatalf("authored plan should validate (code=%d): out=%s err=%s", code, out, errOut)
+	}
+
+	// status --json exposes the derived per-feat state (both feats pending — no
+	// specs exist yet).
+	code, out, _ = run(t, "plan", "status", "photos", "--root", dir, "--json")
+	if code != 0 {
+		t.Fatalf("status --json failed: %d", code)
+	}
+	if !strings.Contains(out, `"feat": "upload"`) || !strings.Contains(out, `"state": "pending"`) {
+		t.Errorf("status JSON missing derived feats: %s", out)
+	}
+
+	// Human status renders the plan header and feat table.
+	code, out, _ = run(t, "plan", "status", "photos", "--root", dir)
+	if code != 0 || !strings.Contains(out, "plan: photos") || !strings.Contains(out, "thumbs") {
+		t.Errorf("human status incomplete (code=%d): %s", code, out)
+	}
+}
+
+func TestPlanValidateJSONExitCode(t *testing.T) {
+	dir := freshWorkspace(t)
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("init failed: %s", e)
+	}
+	// The unauthored scaffold has findings; --json must still exit 2.
+	code, out, _ := run(t, "plan", "validate", "photos", "--root", dir, "--json")
+	if code != 2 {
+		t.Errorf("validate --json should exit 2 on findings, got %d", code)
+	}
+	if !strings.Contains(out, `"ok": false`) {
+		t.Errorf("validate --json should report ok=false: %s", out)
+	}
+}
diff --git a/internal/cli/plan_e2e_test.go b/internal/cli/plan_e2e_test.go
new file mode 100644
index 0000000..4e04b7f
--- /dev/null
+++ b/internal/cli/plan_e2e_test.go
@@ -0,0 +1,168 @@
+package cli
+
+import (
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/protonspy/csdd/internal/graph"
+	"github.com/protonspy/csdd/internal/plan"
+)
+
+// e2ePlan is a minimal one-feat plan so the golden path drives a single feat all
+// the way to done without the full spec-authoring gauntlet (covered elsewhere).
+const e2ePlan = `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+// mustWrite writes content under an ensured parent directory.
+func mustWrite(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestPlanRunE2EGoldenPath exercises the whole plan-mode surface end to end:
+// init → author → validate → approve → generate → (stub) run one feat to done,
+// then asserts the three read surfaces — CLI status, the graph, and the web
+// read-model — all agree on the outcome.
+func TestPlanRunE2EGoldenPath(t *testing.T) {
+	dir := freshWorkspace(t)
+
+	// 1. Author + approve the plan through the real CLI.
+	if code, _, e := run(t, "plan", "init", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan init: %s", e)
+	}
+	mustWrite(t, filepath.Join(dir, "docs", "plans", "photos", "plan.md"), e2ePlan)
+	if code, _, e := run(t, "plan", "validate", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan validate should pass on an authored plan: %s", e)
+	}
+	if code, _, e := run(t, "plan", "approve", "photos", "--root", dir); code != 0 {
+		t.Fatalf("plan approve: %s", e)
+	}
+
+	// 2. Generate the feat's spec — this stamps plan provenance (spec.json plan=photos).
+	if code, _, e := run(t, "plan", "generate", "photos", "upload", "--root", dir); code != 0 {
+		t.Fatalf("plan generate: %s", e)
+	}
+
+	// 3. Simulate the spec having been authored + approved (that flow is tested on
+	//    its own); leave one implementation task unchecked for the runner to close.
+	specDir := filepath.Join(dir, "specs", "upload")
+	mustWrite(t, filepath.Join(specDir, "spec.json"),
+		`{"feature_name":"upload","plan":"photos","ready_for_implementation":true,`+
+			`"approvals":{"requirements":{"generated":true,"approved":true},`+
+			`"design":{"generated":true,"approved":true},`+
+			`"tasks":{"generated":true,"approved":true}}}`)
+	mustWrite(t, filepath.Join(specDir, "tasks.md"), "- [ ] 1. Implement upload\n")
+
+	// 4. Run the plan with a stub runner (no real claude/git): the session reports
+	//    done, gates pass, and the commit hook closes the task so Next advances.
+	now := time.Date(2026, 7, 7, 0, 0, 0, 0, time.UTC)
+	hooks := plan.Hooks{
+		Session: func(plan.Step, string, plan.SessionMode, float64) (plan.Verdict, error) {
+			return plan.Verdict{Status: plan.VerdictDone}, nil
+		},
+		CSDD:         func(string, ...string) (bool, string) { return true, "" },
+		Gate:         func(string, string) (bool, string) { return true, "" },
+		ChangedPaths: func(string) ([]string, error) { return []string{"specs/upload/impl.go"}, nil },
+		Commit: func(_ string, _ string, _ []string) error {
+			mustWrite(t, filepath.Join(specDir, "tasks.md"), "- [x] 1. Implement upload\n")
+			return nil
+		},
+		Doctor:          func() plan.SandboxReport { return plan.SandboxReport{OK: true} },
+		ClaudeAvailable: func() bool { return true },
+		Now:             func() time.Time { return now },
+	}
+	sum, err := plan.Run(plan.RunOptions{Root: dir, Slug: "photos", MaxIterations: 5, Out: io.Discard, Hooks: hooks})
+	if err != nil {
+		t.Fatalf("plan run: %v", err)
+	}
+	if !sum.Completed || sum.Outcome != plan.OutcomeComplete {
+		t.Fatalf("expected a complete run, got %+v", sum)
+	}
+
+	// 5a. STATUS agrees: the feat is done, plan approved and drift-free.
+	code, out, _ := run(t, "plan", "status", "photos", "--root", dir, "--json")
+	if code != 0 {
+		t.Fatalf("plan status --json exit %d", code)
+	}
+	var st plan.PlanStatus
+	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &st); err != nil {
+		t.Fatalf("decode status json: %v\n%s", err, out)
+	}
+	if len(st.Feats) != 1 || st.Feats[0].State != plan.StateDone {
+		t.Errorf("status should report upload done, got %+v", st.Feats)
+	}
+	if !st.Approved || st.Drift {
+		t.Errorf("plan should be approved and drift-free, got approved=%v drift=%v", st.Approved, st.Drift)
+	}
+
+	// 5b. GRAPH agrees: plan + feat nodes exist, the feat plans its (existing)
+	//     spec, and upload is not flagged as an unplanned spec.
+	g, err := graph.Build(dir)
+	if err != nil {
+		t.Fatalf("graph build: %v", err)
+	}
+	var hasPlan, hasFeat, hasPlansEdge bool
+	for _, n := range g.Nodes {
+		switch n.FileType {
+		case graph.TypePlan:
+			hasPlan = true
+		case graph.TypeFeat:
+			hasFeat = true
+		}
+	}
+	for _, e := range g.Links {
+		if e.Relation == graph.RelPlans {
+			hasPlansEdge = true
+		}
+	}
+	if !hasPlan || !hasFeat || !hasPlansEdge {
+		t.Errorf("graph missing plan structure: plan=%v feat=%v plansEdge=%v", hasPlan, hasFeat, hasPlansEdge)
+	}
+	for _, f := range graph.Analyze(g, dir).Findings {
+		if f.Kind == "unplanned_spec" && strings.Contains(f.Label+f.Message, "upload") {
+			t.Errorf("upload is planned; must not be flagged unplanned: %+v", f)
+		}
+	}
+
+	// 5c. WEB agrees: the /api/plan route serves plan.DeriveStatus — the same
+	//     derivation, so it must show the same done state.
+	doc, err := plan.Load(dir, "photos")
+	if err != nil {
+		t.Fatal(err)
+	}
+	webSt, err := plan.DeriveStatus(dir, doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(webSt.Feats) != 1 || webSt.Feats[0].State != plan.StateDone {
+		t.Errorf("web read-model should show upload done, got %+v", webSt.Feats)
+	}
+
+	// The runner journaled the completion with the deterministic timestamp.
+	logData, _ := os.ReadFile(filepath.Join(dir, "docs", "plans", "photos", "log.md"))
+	if !strings.Contains(string(logData), "## [2026-07-07] task 1 | upload | done") {
+		t.Errorf("run journal missing the completion line:\n%s", logData)
+	}
+}
diff --git a/internal/cli/plan_skill_test.go b/internal/cli/plan_skill_test.go
new file mode 100644
index 0000000..a969fc9
--- /dev/null
+++ b/internal/cli/plan_skill_test.go
@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestPRDSkillAndCommandsInstalled(t *testing.T) {
+	dir := freshWorkspace(t)
+
+	// The PRD skill and the /prd + wrapper commands ship with `csdd init`.
+	mustExist := []string{
+		".claude/skills/prd/SKILL.md",
+		".claude/commands/prd.md",
+		".claude/commands/csdd-plan-validate.md",
+		".claude/commands/csdd-plan-status.md",
+		".claude/commands/csdd-plan-run.md",
+	}
+	for _, p := range mustExist {
+		if _, err := os.Stat(filepath.Join(dir, p)); err != nil {
+			t.Errorf("init did not install %s: %v", p, err)
+		}
+	}
+
+	// The installed PRD skill passes the skill validator (required sections, etc.).
+	if code, _, errOut := run(t, "skill", "validate", "prd", "--root", dir); code != 0 {
+		t.Errorf("prd skill failed validation (code=%d): %s", code, errOut)
+	}
+}
+
+func TestPlanModeMomentsInClaudeMD(t *testing.T) {
+	dir := freshWorkspace(t)
+	data, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	for _, want := range []string{"Plan mode", "/prd", "Never edit an approved plan", "Revise"} {
+		if !strings.Contains(text, want) {
+			t.Errorf("CLAUDE.md managed section missing plan-mode moment %q", want)
+		}
+	}
+}
diff --git a/internal/cli/sandbox.go b/internal/cli/sandbox.go
new file mode 100644
index 0000000..3910984
--- /dev/null
+++ b/internal/cli/sandbox.go
@@ -0,0 +1,110 @@
+package cli
+
+import (
+	"embed"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/plan"
+	"github.com/protonspy/csdd/internal/render"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// runSandbox dispatches `csdd sandbox <action>`: init (scaffold the hardened
+// devcontainer) and doctor (prove isolation before bypass mode).
+func runSandbox(args []string, templates embed.FS) int {
+	action, rest, err := parseAction("sandbox", args)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if isHelpFlag(action) {
+		help(os.Stdout)
+		return 0
+	}
+	switch action {
+	case "init":
+		return sandboxInit(rest, templates)
+	case "doctor":
+		return sandboxDoctor(rest)
+	default:
+		render.Err("unknown sandbox action: " + action)
+		return 1
+	}
+}
+
+func sandboxInit(args []string, templates embed.FS) int {
+	fs := flag.NewFlagSet("sandbox init", flag.ContinueOnError)
+	var root string
+	var hardened, force bool
+	var features, allowDomains stringSliceFlag
+	addRoot(fs, &root)
+	fs.Var(&features, "feature", "Add a toolchain devcontainer feature (repeatable): "+strings.Join(plan.SandboxFeatureNames(), "|"))
+	fs.Var(&allowDomains, "allow-domain", "Add a host to the egress allow-list (repeatable).")
+	fs.BoolVar(&hardened, "hardened", false, "Restrict the vscode user's sudo to the firewall script (recommended for --autonomous runs).")
+	addForce(fs, &force)
+	if _, err := parseFlags(fs, args); err != nil {
+		return failOnFlagParse(err)
+	}
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	written, err := plan.SandboxInit(templates, plan.SandboxOptions{
+		Root:         r,
+		Features:     features.values,
+		AllowDomains: allowDomains.values,
+		Hardened:     hardened,
+		Force:        force,
+	})
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if len(written) == 0 {
+		render.Info(".devcontainer/ already scaffolded; nothing changed (--force to regenerate)")
+		return 0
+	}
+	for _, name := range written {
+		render.OK("wrote .devcontainer/" + name)
+	}
+	render.Info("next: open the folder in your IDE (\"Reopen in Container\"), then inside run `" + prog() + " sandbox doctor`")
+	return 0
+}
+
+// sandboxProbes lets tests drive `sandbox doctor` without a real container or
+// network. Its zero value means real probes (Doctor fills the defaults).
+var sandboxProbes plan.DoctorProbes
+
+func sandboxDoctor(args []string) int {
+	fs := flag.NewFlagSet("sandbox doctor", flag.ContinueOnError)
+	var jsonOut bool
+	addJSON(fs, &jsonOut)
+	if _, err := parseFlags(fs, args); err != nil {
+		return failOnFlagParse(err)
+	}
+	report := plan.Doctor(sandboxProbes)
+	if jsonOut {
+		emitJSON(report)
+		if report.OK {
+			return 0
+		}
+		return 1
+	}
+	for _, c := range report.Checks {
+		mark := render.Red("✗")
+		if c.OK {
+			mark = render.Green("✓")
+		}
+		fmt.Printf("  %s %-18s %s\n", mark, c.Name, c.Detail)
+	}
+	if report.OK {
+		render.OK("sandbox verified: isolation is enforced")
+		return 0
+	}
+	render.Err("sandbox NOT verified — do not pass --dangerously-skip-permissions here")
+	return 1
+}
diff --git a/internal/cli/sandbox_cli_test.go b/internal/cli/sandbox_cli_test.go
new file mode 100644
index 0000000..e01bdd5
--- /dev/null
+++ b/internal/cli/sandbox_cli_test.go
@@ -0,0 +1,58 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/protonspy/csdd/internal/plan"
+)
+
+func TestSandboxInitCLI(t *testing.T) {
+	dir := t.TempDir()
+	code, out, errOut := run(t, "sandbox", "init", "--root", dir, "--feature", "go", "--hardened")
+	if code != 0 {
+		t.Fatalf("sandbox init failed (code=%d): %s / %s", code, out, errOut)
+	}
+	for _, name := range []string{"devcontainer.json", "Dockerfile", "init-firewall.sh", "allowed-domains.txt"} {
+		if _, err := os.Stat(filepath.Join(dir, ".devcontainer", name)); err != nil {
+			t.Errorf("missing .devcontainer/%s: %v", name, err)
+		}
+	}
+	// Idempotent re-run reports no change.
+	code, out, _ = run(t, "sandbox", "init", "--root", dir)
+	if code != 0 || !strings.Contains(out, "already scaffolded") {
+		t.Errorf("re-init should be idempotent, got code=%d out=%q", code, out)
+	}
+}
+
+func TestSandboxDoctorCLIExitCodes(t *testing.T) {
+	// Stub the probes so the CLI doctor path is exercised without a container
+	// or the network. Restore afterward.
+	orig := sandboxProbes
+	t.Cleanup(func() { sandboxProbes = orig })
+
+	sandboxProbes = plan.DoctorProbes{
+		Getenv:    func(string) string { return "true" },
+		Geteuid:   func() int { return 1000 },
+		Reachable: func(hp string) bool { return hp != "example.com:443" },
+	}
+	if code, _, _ := run(t, "sandbox", "doctor"); code != 0 {
+		t.Errorf("doctor should exit 0 when isolation holds, got %d", code)
+	}
+
+	// A leaking control host fails the firewall check → non-zero exit.
+	sandboxProbes = plan.DoctorProbes{
+		Getenv:    func(string) string { return "true" },
+		Geteuid:   func() int { return 1000 },
+		Reachable: func(hp string) bool { return true },
+	}
+	code, out, _ := run(t, "sandbox", "doctor", "--json")
+	if code == 0 {
+		t.Errorf("doctor should exit non-zero when the firewall leaks")
+	}
+	if !strings.Contains(out, `"ok": false`) {
+		t.Errorf("doctor --json should report ok=false: %s", out)
+	}
+}
diff --git a/internal/cli/spec.go b/internal/cli/spec.go
index 6b6e399..a05c0f2 100644
--- a/internal/cli/spec.go
+++ b/internal/cli/spec.go
@@ -40,6 +40,11 @@ type SpecJSON struct {
 	ReadyForImplementation bool                    `json:"ready_for_implementation"`
 	CreatedAt              string                  `json:"created_at"`
 
+	// Plan records the plan slug this spec was generated from (`csdd plan
+	// generate`), the provenance the graph turns into a `plans` edge. Absent for
+	// specs created directly via `csdd spec init`.
+	Plan string `json:"plan,omitempty"`
+
 	// extra preserves any keys a newer csdd wrote that this binary does not model,
 	// so round-tripping spec.json through an older binary never silently drops
 	// them. Unexported ⇒ ignored by encoding/json; merged back in saveSpecJSON.
@@ -50,7 +55,7 @@ type SpecJSON struct {
 // on disk is captured into SpecJSON.extra and round-tripped untouched.
 var knownSpecKeys = []string{
 	"schema_version", "feature_name", "language", "phase", "development_flow",
-	"approvals", "ready_for_implementation", "created_at",
+	"approvals", "ready_for_implementation", "created_at", "plan",
 }
 
 // defaultDevelopmentFlow is the flow assumed when none is selected and steering
diff --git a/internal/glossary/glossary.go b/internal/glossary/glossary.go
new file mode 100644
index 0000000..5d76e22
--- /dev/null
+++ b/internal/glossary/glossary.go
@@ -0,0 +1,266 @@
+// Package glossary parses and matches docs/glossary.md — the project's
+// ubiquitous-language contract (canonical terms + _Avoid_ aliases). It is a leaf
+// shared package consumed by both internal/plan (validate findings) and
+// internal/graph (term nodes + references edges + analyze); it exists so the
+// parse/normalize/match logic lives in one place while keeping plan and graph
+// free of a dependency on each other.
+//
+// The contract, like docs/stack.md, is authored prose the CLI never writes — this
+// package only reads, parses, and lints it.
+package glossary
+
+import (
+	"os"
+	"regexp"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+)
+
+// Term is one glossary entry: a canonical name, its definition, the aliases it
+// bans (_Avoid_), and the cluster (### subheading) it sits under. canonTokens and
+// aliasTokens are the precomputed whole-token sequences the matcher compares
+// against identifier tokens.
+type Term struct {
+	Canonical  string
+	Definition string
+	Avoid      []string
+	Cluster    string
+	Line       int
+
+	canonTokens []string
+	aliasTokens [][]string
+}
+
+// Issue is a glossary well-formedness problem (R1.3), carried with its 1-based
+// line in docs/glossary.md. Consumers map it into their own finding type.
+type Issue struct {
+	Line int
+	Msg  string
+}
+
+// Match is one hit of an identifier against the glossary. Alias is empty when the
+// identifier matched the canonical term; otherwise it names the avoided alias that
+// matched (which is what the avoided-term lint surfaces).
+type Match struct {
+	Canonical string
+	Alias     string
+}
+
+// Glossary is a parsed docs/glossary.md. Present records whether the file exists —
+// every lint and the extractor are gated on it (an absent glossary is silent).
+type Glossary struct {
+	Present bool
+	Terms   []Term
+	issues  []Issue
+}
+
+var (
+	// reTermLine matches an entry head: `**<Term>**:` optionally followed by inline
+	// definition prose on the same line.
+	reTermLine = regexp.MustCompile(`^\*\*(.+?)\*\*:\s*(.*)$`)
+	// reAvoidLine matches the optional `_Avoid_: a, b, c` line of an entry.
+	reAvoidLine = regexp.MustCompile(`^_Avoid_:\s*(.*)$`)
+	// reNonAlnum collapses every run of non-alphanumerics — the normalizeTechName
+	// discipline, kept local so plan and graph share one home for term matching.
+	reNonAlnum = regexp.MustCompile(`[^a-z0-9]+`)
+)
+
+// Load reads docs/glossary.md under root and parses it. A missing file yields a
+// not-present, empty glossary (the lazy-creation convention: absent is silent).
+func Load(root string) *Glossary {
+	data, err := os.ReadFile(paths.Glossary(root))
+	if err != nil {
+		return &Glossary{}
+	}
+	g := Parse(string(data))
+	g.Present = true
+	return g
+}
+
+// Parse reads a glossary body. Only the `## Language` section is structured;
+// everything else is free prose the parser ignores (the plan.md discipline).
+// Within it, an entry is `**<Term>**:` then definition prose (≥1 line) then an
+// optional `_Avoid_: …` line; `###` subheadings set the current cluster without
+// affecting parsing. Present is left false — callers use Load to set it from file
+// existence.
+func Parse(content string) *Glossary {
+	g := &Glossary{}
+	lines := strings.Split(textutil.NormalizeNewlines(content), "\n")
+	inLang := false
+	cluster := ""
+	var cur *Term
+	flush := func() {
+		if cur != nil {
+			g.Terms = append(g.Terms, *cur)
+			cur = nil
+		}
+	}
+	for i, raw := range lines {
+		trimmed := strings.TrimSpace(strings.TrimRight(raw, " \t"))
+		if strings.HasPrefix(trimmed, "## ") {
+			flush()
+			title := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(trimmed, "## ")))
+			inLang = title == "language"
+			cluster = ""
+			continue
+		}
+		if !inLang {
+			continue
+		}
+		if strings.HasPrefix(trimmed, "### ") {
+			flush()
+			cluster = strings.TrimSpace(strings.TrimPrefix(trimmed, "### "))
+			continue
+		}
+		if m := reTermLine.FindStringSubmatch(trimmed); m != nil {
+			flush()
+			cur = &Term{Canonical: strings.TrimSpace(m[1]), Cluster: cluster, Line: i + 1}
+			if rest := strings.TrimSpace(m[2]); rest != "" {
+				cur.Definition = rest
+			}
+			continue
+		}
+		if cur == nil {
+			continue
+		}
+		if m := reAvoidLine.FindStringSubmatch(trimmed); m != nil {
+			for _, a := range strings.Split(m[1], ",") {
+				if t := strings.TrimSpace(a); t != "" {
+					cur.Avoid = append(cur.Avoid, t)
+				}
+			}
+			continue
+		}
+		if trimmed != "" {
+			if cur.Definition != "" {
+				cur.Definition += " "
+			}
+			cur.Definition += trimmed
+		}
+	}
+	flush()
+	for i := range g.Terms {
+		g.Terms[i].canonTokens = tokenize(g.Terms[i].Canonical)
+		for _, a := range g.Terms[i].Avoid {
+			g.Terms[i].aliasTokens = append(g.Terms[i].aliasTokens, tokenize(a))
+		}
+	}
+	g.finalize()
+	return g
+}
+
+// Issues returns the well-formedness problems found during parsing (R1.3).
+func (g *Glossary) Issues() []Issue { return g.issues }
+
+// Match returns every glossary hit for an identifier (a feat/plan slug, spec
+// directory, or wiki page name). Matching is deterministic whole-token: the
+// identifier is split on non-alphanumerics and a term (or alias) matches only when
+// its token sequence appears as a contiguous run — so a multi-word term like
+// "purchase order" matches `purchase-order-import` but "client" never matches
+// `clientele`. A term contributes a canonical Match and a separate Match per
+// matching alias.
+func (g *Glossary) Match(identifier string) []Match {
+	idTokens := tokenize(identifier)
+	if len(idTokens) == 0 {
+		return nil
+	}
+	var out []Match
+	for i := range g.Terms {
+		t := &g.Terms[i]
+		if containsRun(idTokens, t.canonTokens) {
+			out = append(out, Match{Canonical: t.Canonical})
+		}
+		for j, at := range t.aliasTokens {
+			if containsRun(idTokens, at) {
+				out = append(out, Match{Canonical: t.Canonical, Alias: t.Avoid[j]})
+			}
+		}
+	}
+	return out
+}
+
+// NormalizeTerm reduces a term or alias to a comparable collapsed key (lowercase,
+// non-alphanumerics removed). Used for collision detection and node ids; the
+// whole-token matcher uses tokenize instead so word boundaries are preserved.
+func NormalizeTerm(s string) string {
+	return reNonAlnum.ReplaceAllString(strings.ToLower(strings.TrimSpace(s)), "")
+}
+
+// tokenize splits a string into lowercased alphanumeric tokens, dropping empties.
+func tokenize(s string) []string {
+	fields := reNonAlnum.Split(strings.ToLower(strings.TrimSpace(s)), -1)
+	out := fields[:0]
+	for _, f := range fields {
+		if f != "" {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// containsRun reports whether needle appears as a contiguous whole-token run in
+// hay. An empty needle never matches.
+func containsRun(hay, needle []string) bool {
+	if len(needle) == 0 || len(needle) > len(hay) {
+		return false
+	}
+	for i := 0; i+len(needle) <= len(hay); i++ {
+		ok := true
+		for j := range needle {
+			if hay[i+j] != needle[j] {
+				ok = false
+				break
+			}
+		}
+		if ok {
+			return true
+		}
+	}
+	return false
+}
+
+// finalize records the well-formedness findings (R1.3): duplicate canonical
+// terms, an entry with no definition, and an alias colliding with another entry's
+// canonical term or with an alias claimed by a different term.
+func (g *Glossary) finalize() {
+	canonLine := map[string]int{}
+	for i := range g.Terms {
+		t := &g.Terms[i]
+		key := NormalizeTerm(t.Canonical)
+		if _, ok := canonLine[key]; ok {
+			g.issues = append(g.issues, Issue{Line: t.Line, Msg: "duplicate glossary term '" + t.Canonical + "'"})
+		} else if key != "" {
+			canonLine[key] = t.Line
+		}
+		if strings.TrimSpace(t.Definition) == "" {
+			g.issues = append(g.issues, Issue{Line: t.Line, Msg: "glossary term '" + t.Canonical + "' has no definition"})
+		}
+	}
+	aliasOwner := map[string]string{}
+	for i := range g.Terms {
+		t := &g.Terms[i]
+		for _, a := range t.Avoid {
+			ak := NormalizeTerm(a)
+			if ak == "" {
+				continue
+			}
+			if _, ok := canonLine[ak]; ok {
+				g.issues = append(g.issues, Issue{
+					Line: t.Line,
+					Msg:  "glossary alias '" + a + "' of term '" + t.Canonical + "' collides with a canonical term",
+				})
+				continue
+			}
+			if prev, ok := aliasOwner[ak]; ok && prev != t.Canonical {
+				g.issues = append(g.issues, Issue{
+					Line: t.Line,
+					Msg:  "glossary alias '" + a + "' is claimed by two terms ('" + prev + "' and '" + t.Canonical + "')",
+				})
+				continue
+			}
+			aliasOwner[ak] = t.Canonical
+		}
+	}
+}
diff --git a/internal/glossary/glossary_test.go b/internal/glossary/glossary_test.go
new file mode 100644
index 0000000..5c8cb85
--- /dev/null
+++ b/internal/glossary/glossary_test.go
@@ -0,0 +1,136 @@
+package glossary
+
+import (
+	"strings"
+	"testing"
+)
+
+const sampleGlossary = `# Glossary
+
+Free prose outside the section is ignored.
+
+## Language
+
+### Core
+
+**Feat**: One row of a plan's Feats table; becomes exactly one spec.
+_Avoid_: feature, story
+
+**Purchase Order**: A buyer's request to procure goods.
+_Avoid_: PO
+
+### Money
+
+**Invoice**: A bill issued against a purchase order.
+`
+
+func parse(t *testing.T) *Glossary {
+	t.Helper()
+	g := Parse(sampleGlossary)
+	if len(g.Terms) != 3 {
+		t.Fatalf("got %d terms, want 3: %+v", len(g.Terms), g.Terms)
+	}
+	return g
+}
+
+func TestParseEntriesAndClusters(t *testing.T) {
+	g := parse(t)
+	if g.Terms[0].Canonical != "Feat" || g.Terms[0].Cluster != "Core" {
+		t.Errorf("term 0 = %+v", g.Terms[0])
+	}
+	if g.Terms[0].Definition == "" || !strings.Contains(g.Terms[0].Definition, "one spec") {
+		t.Errorf("term 0 definition = %q", g.Terms[0].Definition)
+	}
+	if len(g.Terms[0].Avoid) != 2 || g.Terms[0].Avoid[0] != "feature" {
+		t.Errorf("term 0 avoid = %v", g.Terms[0].Avoid)
+	}
+	if g.Terms[2].Cluster != "Money" {
+		t.Errorf("term 2 cluster = %q, want Money", g.Terms[2].Cluster)
+	}
+}
+
+func TestMatchWholeTokenAndMultiWord(t *testing.T) {
+	g := parse(t)
+	cases := []struct {
+		id       string
+		canon    string // expected canonical of the (first) match, "" for none
+		viaAlias string // expected alias, "" for canonical/none
+	}{
+		{"feat-store", "Feat", ""},                      // canonical whole-token
+		{"feature-flags", "Feat", "feature"},            // avoided alias
+		{"purchase-order-import", "Purchase Order", ""}, // multi-word contiguous run
+		{"po-sync", "Purchase Order", "PO"},             // alias
+		{"defeature", "", ""},                           // substring must NOT match
+		{"clientele", "", ""},                           // the canonical non-match guard
+	}
+	for _, tc := range cases {
+		got := g.Match(tc.id)
+		if tc.canon == "" {
+			if len(got) != 0 {
+				t.Errorf("%q: expected no match, got %+v", tc.id, got)
+			}
+			continue
+		}
+		found := false
+		for _, m := range got {
+			if m.Canonical == tc.canon && m.Alias == tc.viaAlias {
+				found = true
+			}
+		}
+		if !found {
+			t.Errorf("%q: expected match {canon=%q alias=%q}, got %+v", tc.id, tc.canon, tc.viaAlias, got)
+		}
+	}
+}
+
+func TestWellFormednessFindings(t *testing.T) {
+	src := `## Language
+
+**Customer**: A person who buys.
+_Avoid_: client
+
+**Customer**: A duplicate canonical.
+
+**Order**:
+_Avoid_: customer
+
+**Blank**:
+`
+	g := Parse(src)
+	msgs := []string{}
+	for _, i := range g.Issues() {
+		msgs = append(msgs, i.Msg)
+	}
+	joined := strings.Join(msgs, "\n")
+	for _, want := range []string{
+		"duplicate glossary term 'Customer'",
+		"glossary alias 'customer' of term 'Order' collides with a canonical term",
+		"glossary term 'Blank' has no definition",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("missing well-formedness issue %q; got:\n%s", want, joined)
+		}
+	}
+}
+
+func TestNormalizeTerm(t *testing.T) {
+	for _, tc := range []struct{ in, want string }{
+		{"Purchase Order", "purchaseorder"},
+		{"purchase-order", "purchaseorder"},
+		{"Feat", "feat"},
+	} {
+		if got := NormalizeTerm(tc.in); got != tc.want {
+			t.Errorf("NormalizeTerm(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestAbsentGlossaryIsNotPresent(t *testing.T) {
+	g := Load(t.TempDir())
+	if g.Present {
+		t.Error("absent docs/glossary.md should not be Present")
+	}
+	if len(g.Terms) != 0 {
+		t.Error("absent glossary should have no terms")
+	}
+}
diff --git a/internal/graph/analyze.go b/internal/graph/analyze.go
index 219c951..45cafa2 100644
--- a/internal/graph/analyze.go
+++ b/internal/graph/analyze.go
@@ -6,6 +6,8 @@ import (
 	"regexp"
 	"sort"
 	"strings"
+
+	"github.com/protonspy/csdd/internal/glossary"
 )
 
 // Finding is one mechanical contract violation surfaced by analyze. Corpus tags
@@ -36,9 +38,11 @@ type GapReport struct {
 
 // Corpus tags.
 const (
-	corpusSpec = "spec"
-	corpusWiki = "wiki"
-	corpusTech = "tech"
+	corpusSpec     = "spec"
+	corpusWiki     = "wiki"
+	corpusTech     = "tech"
+	corpusPlan     = "plan"
+	corpusGlossary = "glossary"
 )
 
 // Finding kinds.
@@ -59,6 +63,13 @@ const (
 	kindPhantomTech         = "phantom_tech"
 	kindUnrefinedTech       = "unrefined_tech"
 	kindNoTechContract      = "no_tech_contract"
+	kindUnplannedSpec       = "unplanned_spec"
+	kindFeatDependencyCycle = "feat_dependency_cycle"
+	kindBrokenPlanRef       = "broken_plan_ref"
+	kindBrokenDecisionRef   = "broken_decision_ref"
+	kindOrphanDecision      = "orphan_decision"
+	kindAvoidedTerm         = "avoided_term"
+	kindOrphanTerm          = "orphan_term"
 )
 
 // Analyze runs every mechanical check over an assembled graph. root is used only
@@ -69,6 +80,8 @@ func Analyze(g *Graph, root string) GapReport {
 	r.Findings = append(r.Findings, specFindings(g)...)
 	r.Findings = append(r.Findings, wikiFindings(g, root)...)
 	r.Findings = append(r.Findings, techFindings(g, root)...)
+	r.Findings = append(r.Findings, planFindings(g)...)
+	r.Findings = append(r.Findings, glossaryFindings(g, root)...)
 	r.GodNodes = godNodes(g)
 	sortFindings(r.Findings)
 	return r
@@ -310,6 +323,138 @@ func techFindings(g *Graph, root string) []Finding {
 	return out
 }
 
+// planFindings surfaces the plan-corpus lints (R12.2): specs no feat plans
+// ("unplanned spec", informational), feat dependency cycles, and broken plan
+// [[wiki-page]] refs. Broken refs are read from the feat node's wiki_refs attr
+// (not from a dangling edge) so a not-yet-created page is caught precisely.
+func planFindings(g *Graph) []Finding {
+	es := buildEdgeSets(g)
+	wikiPresent := map[string]bool{}
+	adrPresent := map[string]bool{}
+	for _, n := range g.Nodes {
+		switch n.FileType {
+		case TypeWikiPage:
+			wikiPresent[n.ID] = true
+		case TypeADR:
+			adrPresent[n.ID] = true
+		}
+	}
+	var out []Finding
+	for _, n := range g.Nodes {
+		switch n.FileType {
+		case TypeSpec:
+			if !es.hasIn(RelPlans, n.ID) {
+				out = append(out, Finding{
+					Kind: kindUnplannedSpec, Corpus: corpusPlan, NodeID: n.ID, Label: n.Label,
+					Message: "spec is not planned by any feat (informational; plans adopt incrementally)",
+					File:    n.SourceFile,
+				})
+			}
+		case TypeFeat:
+			for _, ref := range attrStrings(n.Attrs["wiki_refs"]) {
+				if !wikiPresent[wikiTargetID(ref)] {
+					out = append(out, Finding{
+						Kind: kindBrokenPlanRef, Corpus: corpusPlan, NodeID: n.ID, Label: n.Label,
+						Message: "broken plan ref [[" + ref + "]] (no matching wiki page)", File: n.SourceFile,
+					})
+				}
+			}
+			for _, ref := range attrStrings(n.Attrs["adr_refs"]) {
+				if !adrPresent[adrNodeID(ref)] {
+					out = append(out, Finding{
+						Kind: kindBrokenDecisionRef, Corpus: corpusPlan, NodeID: n.ID, Label: n.Label,
+						Message: "broken decision ref adr:" + ref + " (no matching record under docs/adr/)", File: n.SourceFile,
+					})
+				}
+			}
+		case TypeADR:
+			// Orphan decision: no feat cites it. Informational — decisions may
+			// legitimately predate the plans that will cite them (R9.2).
+			if !es.hasIn(RelCites, n.ID) {
+				out = append(out, Finding{
+					Kind: kindOrphanDecision, Corpus: corpusPlan, NodeID: n.ID, Label: n.Label,
+					Message: "orphan decision: no feat cites this ADR (informational; decisions may predate plans)",
+					File:    n.SourceFile,
+				})
+			}
+		}
+	}
+	for _, cyc := range dependsCyclesForType(g, TypeFeat) {
+		out = append(out, Finding{
+			Kind: kindFeatDependencyCycle, Corpus: corpusPlan,
+			Message: "feat dependency cycle: " + strings.Join(cyc, " → "),
+		})
+	}
+	return out
+}
+
+// glossaryFindings surfaces the ubiquitous-language lints (R3): an avoided alias
+// in a spec directory or wiki page name (domain-tagged so `csdd wiki lint` renders
+// the wiki subset), and an orphan term with no inbound `references` edge
+// (informational — terms may legitimately predate their first use). Feat/plan
+// slugs are linted by `plan validate`, not here. An absent glossary is silent.
+func glossaryFindings(g *Graph, root string) []Finding {
+	gl := glossary.Load(root)
+	var out []Finding
+	if gl.Present {
+		for _, n := range g.Nodes {
+			var corpus string
+			switch {
+			case n.FileType == TypeSpec:
+				corpus = corpusSpec
+			case isWikiContentPage(n):
+				corpus = corpusWiki
+			default:
+				continue
+			}
+			id := glossaryIdentifier(n)
+			for _, m := range gl.Match(id) {
+				if m.Alias == "" {
+					continue
+				}
+				out = append(out, Finding{
+					Kind: kindAvoidedTerm, Corpus: corpus, NodeID: n.ID, Label: n.Label,
+					Message: "avoided term '" + m.Alias + "' in '" + id + "' — canonical is '" + m.Canonical + "'",
+					File:    n.SourceFile,
+				})
+			}
+		}
+	}
+	es := buildEdgeSets(g)
+	for _, n := range g.Nodes {
+		if n.FileType != TypeTerm {
+			continue
+		}
+		if !es.hasIn(RelReferences, n.ID) {
+			out = append(out, Finding{
+				Kind: kindOrphanTerm, Corpus: corpusGlossary, NodeID: n.ID, Label: n.Label,
+				Message: "orphan term: no identifier references it (informational; terms may predate their use)",
+				File:    n.SourceFile,
+			})
+		}
+	}
+	return out
+}
+
+// attrStrings coerces a node attribute to a string slice, tolerating both the
+// in-memory []string an extractor writes and the []any a reloaded graph carries
+// after JSON round-tripping.
+func attrStrings(v any) []string {
+	switch t := v.(type) {
+	case []string:
+		return t
+	case []any:
+		out := make([]string, 0, len(t))
+		for _, e := range t {
+			if s, ok := e.(string); ok {
+				out = append(out, s)
+			}
+		}
+		return out
+	}
+	return nil
+}
+
 func asBool(v any) bool {
 	b, _ := v.(bool)
 	return b
@@ -443,19 +588,30 @@ func logFormatFindings(root string) []Finding {
 
 // --- depends_on cycle detection (Tarjan SCC) --------------------------------
 
-// dependencyCycles returns the node-label cycles among depends_on edges, one per
-// strongly-connected component of size > 1 (or a self-loop), deterministically
-// ordered.
+// dependencyCycles returns the task-dependency cycles among depends_on edges, one
+// per strongly-connected component of size > 1 (or a self-loop), deterministically
+// ordered. It is scoped to task nodes; feat-level cycles are reported separately
+// (planFindings) so each carries the right label and corpus.
 func dependencyCycles(g *Graph) [][]string {
+	return dependsCyclesForType(g, TypeTask)
+}
+
+// dependsCyclesForType returns the depends_on cycles among nodes of the given
+// file type, as node-label lists.
+func dependsCyclesForType(g *Graph, fileType string) [][]string {
 	adj := map[string][]string{}
 	label := map[string]string{}
 	selfLoop := map[string]bool{}
 	nodes := map[string]bool{}
+	isType := map[string]bool{}
 	for _, n := range g.Nodes {
 		label[n.ID] = n.Label
+		if n.FileType == fileType {
+			isType[n.ID] = true
+		}
 	}
 	for _, e := range g.Links {
-		if e.Relation != RelDependsOn {
+		if e.Relation != RelDependsOn || !isType[e.Source] || !isType[e.Target] {
 			continue
 		}
 		if e.Source == e.Target {
diff --git a/internal/graph/extract.go b/internal/graph/extract.go
index 529e0e0..264e133 100644
--- a/internal/graph/extract.go
+++ b/internal/graph/extract.go
@@ -45,6 +45,9 @@ func defaultExtractors() []Extractor {
 		&specExtractor{},
 		&claudeExtractor{},
 		&stackExtractor{},
+		&planExtractor{},
+		&adrExtractor{},
+		&glossaryExtractor{},
 		&wikiExtractor{},
 		&goExtractor{},
 	}
diff --git a/internal/graph/extract_adr.go b/internal/graph/extract_adr.go
new file mode 100644
index 0000000..8e6ec89
--- /dev/null
+++ b/internal/graph/extract_adr.go
@@ -0,0 +1,131 @@
+package graph
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+)
+
+// adrExtractor indexes the decision records under docs/adr/. Each well-formed
+// NNNN-<slug>.md becomes an `adr` node (id from its slug — the citation currency
+// a feat's `adr:<slug>` ref resolves to); the superseded-by number is carried as
+// a node attr and resolved into an `adr superseded_by adr` edge at assembly, where
+// the full number→node map is available (the assembleSpecOwnership precedent).
+//
+// The extractor claims the whole docs/adr/ subtree so a README index or a
+// malformed file is never mis-indexed as a wiki page — it is claimed and returns
+// no fragment. It must dispatch BEFORE the wiki extractor, which would otherwise
+// treat every docs/ markdown file as a page.
+type adrExtractor struct{}
+
+const adrPrefix = "docs/adr/"
+
+// reADRGraphFile mirrors internal/plan's filename grammar; the graph re-parses
+// independently so it carries no dependency on the plan feature package (the
+// self-containment extract_plan.go keeps toward internal/plan).
+var reADRGraphFile = regexp.MustCompile(`^(\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$`)
+
+func (adrExtractor) Matches(p string) bool {
+	return strings.HasPrefix(p, adrPrefix) && strings.HasSuffix(p, ".md")
+}
+
+func (adrExtractor) Extract(src Source) ([]Fragment, error) {
+	name := src.Path[len(adrPrefix):]
+	if strings.Contains(name, "/") {
+		return nil, nil // nested files under docs/adr/ are not records
+	}
+	m := reADRGraphFile.FindStringSubmatch(name)
+	if m == nil {
+		return nil, nil // README, malformed filenames: claimed, not indexed
+	}
+	number, _ := strconv.Atoi(m[1])
+	slug := m[2]
+
+	fm := frontmatter.Parse(string(src.Content))
+	status := strings.ToLower(strings.TrimSpace(fm.AsString("status", "")))
+	if status == "" {
+		status = "accepted"
+	}
+	title := adrTitle(fm.Body)
+	label := title
+	if label == "" {
+		label = slug
+	}
+
+	attrs := map[string]any{"number": number, "status": status, "slug": slug}
+	if title != "" {
+		attrs["title"] = title
+	}
+	if sb := strings.TrimSpace(fm.AsString("superseded-by", "")); sb != "" {
+		if n, err := strconv.Atoi(sb); err == nil {
+			attrs["superseded_by"] = n
+		}
+	}
+	return []Fragment{{Nodes: []Node{{
+		ID: adrNodeID(slug), Label: label, FileType: TypeADR,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}}, nil
+}
+
+// adrNodeID is the canonical id for a decision record — slug-based, so a feat's
+// `adr:<slug>` citation (extract_plan's cites edge) resolves to it by slug.
+func adrNodeID(slug string) string { return MakeID("adr", slug) }
+
+// adrTitle returns the first `# ` heading of an ADR body, or "".
+func adrTitle(body string) string {
+	for _, raw := range normLines([]byte(body)) {
+		t := strings.TrimSpace(raw)
+		if strings.HasPrefix(t, "# ") {
+			return strings.TrimSpace(strings.TrimPrefix(t, "# "))
+		}
+	}
+	return ""
+}
+
+// resolveADRSupersession synthesizes `adr superseded_by adr` edges from each
+// record's superseded_by number attr, using the whole-graph number→node map. A
+// number that names no record produces no edge (validate reports it as a dangling
+// supersession); the graph carries only resolvable links.
+func resolveADRSupersession(g *Graph) {
+	byNumber := map[int]string{}
+	for _, n := range g.Nodes {
+		if n.FileType == TypeADR {
+			if num, ok := attrInt(n.Attrs["number"]); ok {
+				byNumber[num] = n.ID
+			}
+		}
+	}
+	for _, n := range g.Nodes {
+		if n.FileType != TypeADR {
+			continue
+		}
+		target, ok := attrInt(n.Attrs["superseded_by"])
+		if !ok {
+			continue
+		}
+		if tid, found := byNumber[target]; found && tid != n.ID {
+			g.Links = append(g.Links, Edge{
+				Source: n.ID, Target: tid, Relation: RelSupersededBy,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: n.SourceFile,
+			})
+		}
+	}
+	g.Links = dedupEdges(g.Links)
+}
+
+// attrInt coerces a node attribute to an int, tolerating both the int an
+// extractor writes in-memory and the float64 a reloaded graph carries after JSON
+// round-tripping.
+func attrInt(v any) (int, bool) {
+	switch t := v.(type) {
+	case int:
+		return t, true
+	case int64:
+		return int(t), true
+	case float64:
+		return int(t), true
+	}
+	return 0, false
+}
diff --git a/internal/graph/extract_adr_test.go b/internal/graph/extract_adr_test.go
new file mode 100644
index 0000000..dda7f55
--- /dev/null
+++ b/internal/graph/extract_adr_test.go
@@ -0,0 +1,114 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeADRFixture(t *testing.T, dir string) {
+	t.Helper()
+	files := map[string]string{
+		"docs/plans/dr/plan.md": `---
+name: dr
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | store | Storage layer | — | M1 | | adr:pick-store adr:ghost |
+`,
+		"docs/adr/0001-pick-store.md": "# Store under docs/adr\n\nContext, decision, why.\n",
+		"docs/adr/0002-old-way.md":    "---\nstatus: superseded\nsuperseded-by: 0003\n---\n# The old way\n\nreplaced\n",
+		"docs/adr/0003-new-way.md":    "# The new way\n\nthe successor\n",
+		"docs/adr/0004-orphan.md":     "# An orphan decision\n\nnobody cites this\n",
+		"docs/adr/README.md":          "# Decision records\n\nindex, not an ADR\n",
+	}
+	for rel, content := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func buildADRFixture(t *testing.T) (*Graph, string) {
+	t.Helper()
+	dir := t.TempDir()
+	writeADRFixture(t, dir)
+	ex := []Extractor{&planExtractor{}, &adrExtractor{}, &wikiExtractor{}}
+	g, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	return g, dir
+}
+
+func TestADRExtractorNodesAndEdges(t *testing.T) {
+	g, _ := buildADRFixture(t)
+
+	// adr node with attrs.
+	n := nodeByID(g, adrNodeID("pick-store"))
+	if n == nil || n.FileType != TypeADR {
+		t.Fatalf("adr node missing or wrong type: %+v", n)
+	}
+	if num, _ := attrInt(n.Attrs["number"]); num != 1 {
+		t.Errorf("adr number attr = %v, want 1", n.Attrs["number"])
+	}
+	if n.Attrs["status"] != "accepted" {
+		t.Errorf("adr status attr = %v, want accepted", n.Attrs["status"])
+	}
+	if n.Attrs["title"] != "Store under docs/adr" {
+		t.Errorf("adr title attr = %v", n.Attrs["title"])
+	}
+
+	// README.md must not become an adr node (or a wiki page).
+	if nodeByID(g, adrNodeID("readme")) != nil {
+		t.Errorf("README.md should not be an adr node")
+	}
+
+	// feat cites adr (resolved).
+	if !hasEdge(g, featNodeID("dr", "store"), RelCites, adrNodeID("pick-store")) {
+		t.Errorf("missing feat cites adr edge")
+	}
+	// superseded_by edge 0002 → 0003.
+	if !hasEdge(g, adrNodeID("old-way"), RelSupersededBy, adrNodeID("new-way")) {
+		t.Errorf("missing adr superseded_by adr edge")
+	}
+}
+
+func TestADRExtractorFindings(t *testing.T) {
+	g, dir := buildADRFixture(t)
+	report := Analyze(g, dir)
+	has := func(kind, sub string) bool {
+		for _, f := range report.Findings {
+			if f.Kind == kind && (sub == "" || strings.Contains(f.Message, sub)) {
+				return true
+			}
+		}
+		return false
+	}
+	if !has(kindBrokenDecisionRef, "adr:ghost") {
+		t.Errorf("expected broken_decision_ref for adr:ghost")
+	}
+	if !has(kindOrphanDecision, "") {
+		t.Errorf("expected orphan_decision for 0004-orphan")
+	}
+	// pick-store IS cited → not orphan.
+	for _, f := range report.Findings {
+		if f.Kind == kindOrphanDecision && f.NodeID == adrNodeID("pick-store") {
+			t.Errorf("pick-store is cited; should not be orphan")
+		}
+	}
+	// The broken decision ref is plan-corpus (parity with broken_plan_ref).
+	for _, f := range report.Findings {
+		if f.Kind == kindBrokenDecisionRef && f.Corpus != corpusPlan {
+			t.Errorf("broken_decision_ref should be plan corpus, got %q", f.Corpus)
+		}
+	}
+}
diff --git a/internal/graph/extract_glossary.go b/internal/graph/extract_glossary.go
new file mode 100644
index 0000000..dc4a9b0
--- /dev/null
+++ b/internal/graph/extract_glossary.go
@@ -0,0 +1,102 @@
+package graph
+
+import (
+	"path"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/glossary"
+)
+
+// glossaryExtractor indexes docs/glossary.md — the ubiquitous-language contract.
+// Each entry becomes a `term` node (id from the normalized canonical term); the
+// `references` edges from the feats, specs, and wiki pages that use each term are
+// synthesized at assembly (resolveGlossaryRefs), where every identifier-bearing
+// node is present and the glossary can be matched against all of them at once.
+//
+// It must dispatch BEFORE the wiki extractor, which would otherwise treat
+// docs/glossary.md as an ordinary wiki page.
+type glossaryExtractor struct{}
+
+func (glossaryExtractor) Matches(p string) bool { return p == "docs/glossary.md" }
+
+func (glossaryExtractor) Extract(src Source) ([]Fragment, error) {
+	gl := glossary.Parse(string(src.Content))
+	var frag Fragment
+	for _, term := range gl.Terms {
+		attrs := map[string]any{}
+		if term.Definition != "" {
+			attrs["definition"] = term.Definition
+		}
+		if len(term.Avoid) > 0 {
+			attrs["avoid"] = term.Avoid
+		}
+		if term.Cluster != "" {
+			attrs["cluster"] = term.Cluster
+		}
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: termNodeID(term.Canonical), Label: term.Canonical, FileType: TypeTerm,
+			SourceFile: src.Path, SourceLocation: loc(term.Line - 1), Attrs: attrs,
+		})
+	}
+	return []Fragment{frag}, nil
+}
+
+// termNodeID is the canonical id for a glossary term — normalized from the
+// canonical term so a feat/spec/wiki identifier that token-matches it resolves to
+// the same node regardless of spelling.
+func termNodeID(canonical string) string { return MakeID("term", canonical) }
+
+// glossaryIdentifier returns the kebab identifier a node is matched by: the feat
+// slug, the spec directory name, or the wiki page filename. Nodes with no
+// meaningful identifier return "".
+func glossaryIdentifier(n Node) string {
+	switch {
+	case n.FileType == TypeFeat:
+		return asString(n.Attrs["slug"])
+	case n.FileType == TypeSpec:
+		if m := reSpecMember.FindStringSubmatch(n.SourceFile); m != nil {
+			return m[1]
+		}
+		return n.Label
+	case isWikiContentPage(n):
+		return strings.TrimSuffix(path.Base(n.SourceFile), ".md")
+	}
+	return ""
+}
+
+// resolveGlossaryRefs synthesizes `references` edges from every feat/spec/wiki
+// page whose identifier tokens match a term or one of its aliases (R4.2), so
+// "where is <term> used?" is a graph query. Both canonical and alias matches
+// produce an edge (deduped per term); the avoided-alias distinction is recomputed
+// from the glossary by analyze, which surfaces the lint (R3.1).
+func resolveGlossaryRefs(g *Graph, root string) {
+	gl := glossary.Load(root)
+	if !gl.Present {
+		return
+	}
+	termExists := map[string]bool{}
+	for _, n := range g.Nodes {
+		if n.FileType == TypeTerm {
+			termExists[n.ID] = true
+		}
+	}
+	for _, n := range g.Nodes {
+		id := glossaryIdentifier(n)
+		if id == "" {
+			continue
+		}
+		seen := map[string]bool{}
+		for _, m := range gl.Match(id) {
+			tid := termNodeID(m.Canonical)
+			if !termExists[tid] || seen[tid] {
+				continue
+			}
+			seen[tid] = true
+			g.Links = append(g.Links, Edge{
+				Source: n.ID, Target: tid, Relation: RelReferences,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: n.SourceFile, Ref: id,
+			})
+		}
+	}
+	g.Links = dedupEdges(g.Links)
+}
diff --git a/internal/graph/extract_glossary_test.go b/internal/graph/extract_glossary_test.go
new file mode 100644
index 0000000..89e4a33
--- /dev/null
+++ b/internal/graph/extract_glossary_test.go
@@ -0,0 +1,129 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeGlossaryFixture(t *testing.T, dir string) {
+	t.Helper()
+	files := map[string]string{
+		"docs/glossary.md": `## Language
+
+**Feat**: One row of a plan's Feats table; becomes exactly one spec.
+_Avoid_: feature, story
+
+**Customer**: A person who buys.
+_Avoid_: client
+
+**Widget**: An unused term nobody references.
+`,
+		// A plan whose feat slug uses the canonical term "feat" and another feat
+		// whose slug uses an avoided alias "client".
+		"docs/plans/g/plan.md": `---
+name: g
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | feat-store | store feats | — | M1 | | |
+| 2 | thumbs | thumbs | — | M1 | | |
+`,
+		// A wiki page whose name uses an avoided alias.
+		"docs/wiki/pages/client-portal.md": "# Client Portal\n",
+		// A spec directory whose name uses the canonical customer term.
+		"specs/customer-sync/spec.json": `{"feature_name":"customer-sync"}`,
+	}
+	for rel, content := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func buildGlossaryFixture(t *testing.T) (*Graph, string) {
+	t.Helper()
+	dir := t.TempDir()
+	writeGlossaryFixture(t, dir)
+	ex := []Extractor{&specExtractor{}, &planExtractor{}, &glossaryExtractor{}, &wikiExtractor{}}
+	g, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	return g, dir
+}
+
+func TestGlossaryExtractorNodesAndEdges(t *testing.T) {
+	g, _ := buildGlossaryFixture(t)
+
+	// term node with attrs.
+	n := nodeByID(g, termNodeID("Feat"))
+	if n == nil || n.FileType != TypeTerm {
+		t.Fatalf("term node missing or wrong type: %+v", n)
+	}
+	if !strings.Contains(asString(n.Attrs["definition"]), "one spec") {
+		t.Errorf("term definition attr = %v", n.Attrs["definition"])
+	}
+	if av := attrStrings(n.Attrs["avoid"]); len(av) != 2 {
+		t.Errorf("term avoid attr = %v, want 2", n.Attrs["avoid"])
+	}
+
+	// references edge: feat-store (canonical "feat") → term Feat.
+	if !hasEdge(g, featNodeID("g", "feat-store"), RelReferences, termNodeID("Feat")) {
+		t.Errorf("missing feat→term references edge for canonical use")
+	}
+	// references edge: customer-sync spec (canonical "customer") → term Customer.
+	if !hasEdge(g, specNodeID("customer-sync"), RelReferences, termNodeID("Customer")) {
+		t.Errorf("missing spec→term references edge")
+	}
+	// references edge: client-portal wiki page (alias "client") → term Customer.
+	if !hasEdge(g, wikiPageID("docs/wiki/pages/client-portal.md"), RelReferences, termNodeID("Customer")) {
+		t.Errorf("missing wiki→term references edge for alias use")
+	}
+}
+
+func TestGlossaryFindings(t *testing.T) {
+	g, dir := buildGlossaryFixture(t)
+	report := Analyze(g, dir)
+	has := func(kind, corpus, sub string) bool {
+		for _, f := range report.Findings {
+			if f.Kind == kind && (corpus == "" || f.Corpus == corpus) && (sub == "" || strings.Contains(f.Message, sub)) {
+				return true
+			}
+		}
+		return false
+	}
+	// Avoided alias in a wiki page name → corpusWiki (so wiki lint renders it).
+	if !has(kindAvoidedTerm, corpusWiki, "client") {
+		t.Errorf("expected avoided_term (wiki) for client-portal")
+	}
+	// The wiki-lint filter surfaces exactly the wiki subset.
+	wiki := WikiFindings(report)
+	sawAvoided := false
+	for _, f := range wiki {
+		if f.Kind == kindAvoidedTerm {
+			sawAvoided = true
+		}
+	}
+	if !sawAvoided {
+		t.Errorf("wiki lint subset should include the avoided-term finding")
+	}
+	// Orphan term (Widget) is informational.
+	if !has(kindOrphanTerm, "", "orphan term") {
+		t.Errorf("expected orphan_term for Widget")
+	}
+	// Feat and Customer are referenced → not orphans.
+	for _, f := range report.Findings {
+		if f.Kind == kindOrphanTerm && (f.NodeID == termNodeID("Feat") || f.NodeID == termNodeID("Customer")) {
+			t.Errorf("%s is referenced; should not be orphan", f.NodeID)
+		}
+	}
+}
diff --git a/internal/graph/extract_plan.go b/internal/graph/extract_plan.go
new file mode 100644
index 0000000..b4d0de0
--- /dev/null
+++ b/internal/graph/extract_plan.go
@@ -0,0 +1,281 @@
+package graph
+
+import (
+	"path"
+	"regexp"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+)
+
+// planExtractor indexes the plan layer under docs/plans/<slug>/: the plan.md
+// becomes a plan node plus a feat node per row of its `## Feats` table, wired to
+// the specs they plan, the feats they depend on, the wiki pages they reference,
+// and the tech they use. It claims the whole <slug>/ subtree so seeds and state
+// files are never mis-indexed as wiki pages (a seed requirements.md would
+// otherwise collide with real wiki pages on its base name).
+//
+// Extraction performs no I/O (the Extractor contract), so a feat's `plans` edge
+// is emitted unconditionally and resolves at assembly iff the spec exists; a
+// feat whose spec is not yet generated simply has an unresolved (silently
+// dropped) plans edge — the normal pre-generation state, not a finding.
+type planExtractor struct{}
+
+const plansPrefix = "docs/plans/"
+
+func (planExtractor) Matches(p string) bool {
+	if !strings.HasPrefix(p, plansPrefix) {
+		return false
+	}
+	// Only files inside a <slug>/ subdirectory are the structured plan layout;
+	// a top-level docs/plans/PLAN-*.md draft stays an ordinary wiki page.
+	return strings.Contains(p[len(plansPrefix):], "/")
+}
+
+func (planExtractor) Extract(src Source) ([]Fragment, error) {
+	if path.Base(src.Path) != "plan.md" {
+		return nil, nil // seeds, plan.json, log.md are claimed but not indexed
+	}
+	slug := planSlugFromPath(src.Path)
+	if slug == "" {
+		return nil, nil
+	}
+	return extractPlan(slug, src), nil
+}
+
+// planSlugFromPath extracts <slug> from docs/plans/<slug>/plan.md.
+func planSlugFromPath(p string) string {
+	rest := strings.TrimPrefix(p, plansPrefix)
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		return rest[:i]
+	}
+	return ""
+}
+
+func planNodeID(slug string) string       { return MakeID("plan", slug) }
+func featNodeID(slug, feat string) string { return MakeID("feat", slug, feat) }
+
+// planFeatRow is one parsed feat, kept local to the graph so extraction stays
+// self-contained (the same posture extract_spec.go takes toward the validator).
+type planFeatRow struct {
+	num       string
+	slug      string
+	objective string
+	depends   []string
+	milestone string
+	parallel  bool
+	wikiRefs  []string
+	stackRefs []string
+	adrRefs   []string
+	line      int
+}
+
+func extractPlan(slug string, src Source) []Fragment {
+	fm := frontmatter.Parse(string(src.Content))
+	name := fm.AsString("name", "")
+	if name == "" {
+		name = slug
+	}
+	planID := planNodeID(slug)
+	planAttrs := map[string]any{}
+	if s := fm.AsString("status", ""); s != "" {
+		planAttrs["status"] = s
+	}
+	frag := Fragment{Nodes: []Node{{
+		ID: planID, Label: name, FileType: TypePlan,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: planAttrs,
+	}}}
+
+	rows := parsePlanFeats(src.Content)
+	known := map[string]bool{}
+	for _, r := range rows {
+		known[r.slug] = true
+	}
+	for _, r := range rows {
+		fid := featNodeID(slug, r.slug)
+		attrs := map[string]any{"plan": slug, "parallel": r.parallel}
+		if r.num != "" {
+			attrs["number"] = r.num
+		}
+		if r.milestone != "" {
+			attrs["milestone"] = r.milestone
+		}
+		if len(r.wikiRefs) > 0 {
+			attrs["wiki_refs"] = r.wikiRefs
+		}
+		if len(r.stackRefs) > 0 {
+			attrs["stack_refs"] = r.stackRefs
+		}
+		if len(r.adrRefs) > 0 {
+			attrs["adr_refs"] = r.adrRefs
+		}
+		// The feat slug is carried explicitly so the glossary assembly pass can
+		// token-match it against canonical terms (the node id is normalized and
+		// the label is the objective, so neither recovers the slug reliably).
+		attrs["slug"] = r.slug
+		label := r.slug
+		if r.objective != "" {
+			label = r.objective
+		}
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: fid, Label: label, FileType: TypeFeat,
+			SourceFile: src.Path, SourceLocation: loc(r.line - 1), Attrs: attrs,
+		})
+		// plan owns feat.
+		frag.Edges = append(frag.Edges, Edge{
+			Source: planID, Target: fid, Relation: RelOwns,
+			Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+		})
+		// feat plans spec (resolves iff the spec folder exists).
+		frag.Edges = append(frag.Edges, Edge{
+			Source: fid, Target: specNodeID(r.slug), Relation: RelPlans,
+			Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: r.slug,
+		})
+		// feat depends_on feat — only for deps that name a real feat of this plan,
+		// so the graph never carries a dangling dependency (plan validate reports
+		// unknown deps separately).
+		for _, dep := range r.depends {
+			if known[dep] {
+				frag.Edges = append(frag.Edges, Edge{
+					Source: fid, Target: featNodeID(slug, dep), Relation: RelDependsOn,
+					Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: dep,
+				})
+			}
+		}
+		// feat references wiki pages; broken ones are surfaced from the node Attrs
+		// in analyze (planFindings), not from a dangling edge.
+		for _, page := range r.wikiRefs {
+			frag.Edges = append(frag.Edges, Edge{
+				Source: fid, Target: wikiTargetID(page), Relation: RelReferences,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: page,
+			})
+		}
+		// feat uses_tech.
+		for _, tech := range r.stackRefs {
+			frag.Edges = append(frag.Edges, Edge{
+				Source: fid, Target: techID(tech), Relation: RelUsesTech,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: tech,
+			})
+		}
+		// feat cites adr; a broken citation is surfaced from the node's adr_refs
+		// attr in analyze (planFindings), not from a dangling edge — the wiki-ref
+		// precedent above.
+		for _, ref := range r.adrRefs {
+			frag.Edges = append(frag.Edges, Edge{
+				Source: fid, Target: adrNodeID(ref), Relation: RelCites,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+			})
+		}
+	}
+	return []Fragment{frag}
+}
+
+// parsePlanFeats scans a plan.md for its `## Feats` table and returns one row per
+// feat, matched by header column name. It mirrors the internal/plan grammar; the
+// graph re-parses independently so it carries no dependency on the plan feature
+// package (the same self-containment extract_spec.go keeps toward the validator).
+func parsePlanFeats(content []byte) []planFeatRow {
+	lines := normLines(content)
+	section := ""
+	var cols map[string]int
+	var out []planFeatRow
+	for i, raw := range lines {
+		trimmed := strings.TrimSpace(rtrim(raw))
+		if strings.HasPrefix(trimmed, "## ") {
+			section = strings.ToLower(strings.TrimSpace(strings.TrimPrefix(trimmed, "## ")))
+			cols = nil
+			continue
+		}
+		if section != "feats" || !strings.HasPrefix(trimmed, "|") {
+			continue
+		}
+		cells := splitCells(trimmed)
+		if isTableSeparator(cells) {
+			continue
+		}
+		if cols == nil {
+			cols = map[string]int{}
+			for idx, c := range cells {
+				cols[strings.ToLower(strings.TrimSpace(c))] = idx
+			}
+			continue
+		}
+		get := func(name string) string {
+			idx, ok := cols[name]
+			if !ok || idx >= len(cells) {
+				return ""
+			}
+			return strings.TrimSpace(cells[idx])
+		}
+		slug := get("feat")
+		if slug == "" {
+			continue
+		}
+		r := planFeatRow{
+			num:       get("#"),
+			slug:      slug,
+			objective: collapseSpaces(get("objective")),
+			depends:   planSplitDepends(get("depends")),
+			milestone: get("milestone"),
+			parallel:  planParallel(get("(p)")),
+			line:      i + 1,
+		}
+		r.wikiRefs, r.stackRefs, r.adrRefs = planTokenizeRefs(get("refs"))
+		out = append(out, r)
+	}
+	return out
+}
+
+func planSplitDepends(cell string) []string {
+	cell = strings.TrimSpace(cell)
+	if cell == "" || cell == "-" || cell == "—" || strings.EqualFold(cell, "none") {
+		return nil
+	}
+	var out []string
+	for _, part := range strings.Split(cell, ",") {
+		if t := strings.TrimSpace(part); t != "" {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+func planParallel(cell string) bool {
+	switch strings.ToLower(strings.TrimSpace(cell)) {
+	case "p", "(p)", "yes", "y", "x", "true", "✓", "*":
+		return true
+	}
+	return false
+}
+
+// planTokenizeRefs splits a Refs cell on whitespace into [[wiki]], stack:, and
+// adr: tokens, reusing the wiki-link regex so a plan ref and a wiki body resolve
+// the same target. Only well-formed (kebab-case) adr slugs are returned, so the
+// graph never mints a cites edge to a garbage id (validate reports the malformed
+// slug against the citing feat).
+func planTokenizeRefs(cell string) (wiki, stack, adr []string) {
+	for _, tok := range strings.Fields(cell) {
+		if m := reWikiLink.FindStringSubmatch(tok); m != nil {
+			if t := strings.TrimSpace(m[1]); t != "" && !strings.ContainsAny(t, "<>") {
+				wiki = append(wiki, t)
+			}
+			continue
+		}
+		if strings.HasPrefix(tok, "stack:") {
+			if name := strings.TrimSpace(strings.TrimPrefix(tok, "stack:")); name != "" {
+				stack = append(stack, name)
+			}
+			continue
+		}
+		if strings.HasPrefix(tok, "adr:") {
+			if slug := strings.TrimSpace(strings.TrimPrefix(tok, "adr:")); reADRRefSlug.MatchString(slug) {
+				adr = append(adr, slug)
+			}
+		}
+	}
+	return wiki, stack, adr
+}
+
+// reADRRefSlug is the kebab-case grammar a graph-side adr citation must satisfy
+// before it becomes a cites edge (mirrors internal/plan's ValidADRSlug).
+var reADRRefSlug = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
diff --git a/internal/graph/extract_plan_test.go b/internal/graph/extract_plan_test.go
new file mode 100644
index 0000000..266623a
--- /dev/null
+++ b/internal/graph/extract_plan_test.go
@@ -0,0 +1,135 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writePlanFixture lays down a workspace with a plan, one existing spec (upload)
+// and one absent spec (thumbs), a stack contract, and one wiki page, crafted to
+// exercise every plan node/edge and every plan finding.
+func writePlanFixture(t *testing.T, dir string) {
+	t.Helper()
+	files := map[string]string{
+		"docs/plans/photos/plan.md": `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | stack:go [[storage-design]] |
+| 2 | thumbs | Thumbnails | upload | M1 | P | [[missing-page]] |
+| 3 | ring-a | A | ring-b | M2 | | |
+| 4 | ring-b | B | ring-a | M2 | | |
+`,
+		// upload's spec exists → its plans edge resolves; no other feat plans it.
+		"specs/upload/spec.json": `{"feature_name":"upload","ready_for_implementation":false}`,
+		// unplanned-spot has a spec but no feat plans it → unplanned_spec finding.
+		"specs/unplanned-spot/spec.json": `{"feature_name":"unplanned-spot"}`,
+		"docs/stack.md": `# Tech contract
+## Decided
+| Domain | Choice | Version | Why | Refs |
+|---|---|---|---|---|
+| Language | Go | 1.22 | speed | — |
+`,
+		"docs/wiki/pages/storage-design.md": "# Storage Design\n",
+	}
+	for rel, content := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func buildPlanFixture(t *testing.T) (*Graph, string) {
+	t.Helper()
+	dir := t.TempDir()
+	writePlanFixture(t, dir)
+	ex := []Extractor{&specExtractor{}, &stackExtractor{}, &planExtractor{}, &wikiExtractor{}}
+	g, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	return g, dir
+}
+
+func TestPlanExtractorNodesAndEdges(t *testing.T) {
+	g, _ := buildPlanFixture(t)
+
+	planID := planNodeID("photos")
+	if n := nodeByID(g, planID); n == nil || n.FileType != TypePlan {
+		t.Fatalf("plan node missing or wrong type: %+v", n)
+	}
+	uploadFeat := featNodeID("photos", "upload")
+	if n := nodeByID(g, uploadFeat); n == nil || n.FileType != TypeFeat {
+		t.Fatalf("upload feat node missing: %+v", n)
+	}
+
+	// plan owns feat.
+	if !hasEdge(g, planID, RelOwns, uploadFeat) {
+		t.Errorf("missing plan owns feat edge")
+	}
+	// feat plans spec — resolves because specs/upload/ exists.
+	if !hasEdge(g, uploadFeat, RelPlans, specNodeID("upload")) {
+		t.Errorf("missing (resolved) feat plans spec edge")
+	}
+	// feat plans spec for thumbs is dropped (spec absent) — that's the normal
+	// pre-generation state, not a finding.
+	if hasEdge(g, featNodeID("photos", "thumbs"), RelPlans, specNodeID("thumbs")) {
+		t.Errorf("thumbs plans edge should be unresolved/dropped (no spec yet)")
+	}
+	// feat depends_on feat.
+	if !hasEdge(g, featNodeID("photos", "thumbs"), RelDependsOn, uploadFeat) {
+		t.Errorf("missing feat depends_on feat edge")
+	}
+	// feat references wiki page (resolved).
+	if !hasEdge(g, uploadFeat, RelReferences, wikiTargetID("storage-design")) {
+		t.Errorf("missing feat references wiki edge")
+	}
+	// feat uses_tech.
+	if !hasEdge(g, uploadFeat, RelUsesTech, techID("go")) {
+		t.Errorf("missing feat uses_tech edge")
+	}
+}
+
+func TestPlanExtractorFindings(t *testing.T) {
+	g, dir := buildPlanFixture(t)
+	report := Analyze(g, dir)
+
+	has := func(kind string) bool {
+		for _, f := range report.Findings {
+			if f.Kind == kind {
+				return true
+			}
+		}
+		return false
+	}
+	if !has(kindUnplannedSpec) {
+		t.Errorf("expected unplanned_spec finding (unplanned-spot)")
+	}
+	if !has(kindBrokenPlanRef) {
+		t.Errorf("expected broken_plan_ref finding ([[missing-page]])")
+	}
+	if !has(kindFeatDependencyCycle) {
+		t.Errorf("expected feat_dependency_cycle finding (ring-a ↔ ring-b)")
+	}
+	// The feat cycle must NOT be mislabeled as a task cycle.
+	for _, f := range report.Findings {
+		if f.Kind == kindDependencyCycle {
+			t.Errorf("feat cycle should not be reported as a task dependency cycle: %+v", f)
+		}
+	}
+	// upload IS planned → no unplanned finding for it.
+	for _, f := range report.Findings {
+		if f.Kind == kindUnplannedSpec && f.NodeID == specNodeID("upload") {
+			t.Errorf("upload is planned; should not be flagged unplanned")
+		}
+	}
+}
diff --git a/internal/graph/extract_spec.go b/internal/graph/extract_spec.go
index 02d2f0a..a7b369a 100644
--- a/internal/graph/extract_spec.go
+++ b/internal/graph/extract_spec.go
@@ -62,6 +62,7 @@ func extractSpecJSON(spec string, src Source) ([]Fragment, error) {
 		Phase           string          `json:"phase"`
 		DevelopmentFlow string          `json:"development_flow"`
 		Ready           bool            `json:"ready_for_implementation"`
+		Plan            string          `json:"plan"`
 		Approvals       json.RawMessage `json:"approvals"`
 	}
 	// A malformed spec.json still yields a bare spec node so the folder is indexed.
@@ -81,10 +82,20 @@ func extractSpecJSON(spec string, src Source) ([]Fragment, error) {
 		attrs["language"] = doc.Language
 	}
 	attrs["ready_for_implementation"] = doc.Ready
-	return []Fragment{{Nodes: []Node{{
+	frag := Fragment{Nodes: []Node{{
 		ID: specNodeID(spec), Label: label, FileType: TypeSpec,
 		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
-	}}}}, nil
+	}}}
+	// spec.json provenance (`plan`) → a plans edge from the owning feat (R8.2).
+	// It resolves only when that feat node exists (the plan still lists the row),
+	// mirroring the edge the plan extractor emits; dedup collapses the pair.
+	if doc.Plan != "" {
+		frag.Edges = append(frag.Edges, Edge{
+			Source: featNodeID(doc.Plan, spec), Target: specNodeID(spec), Relation: RelPlans,
+			Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: spec,
+		})
+	}
+	return []Fragment{frag}, nil
 }
 
 var reRequirementHeading = regexp.MustCompile(`^###\s+Requirement\s+(\d+)\s*:?\s*(.*)$`)
diff --git a/internal/graph/incremental.go b/internal/graph/incremental.go
index 7bbb361..cedc709 100644
--- a/internal/graph/incremental.go
+++ b/internal/graph/incremental.go
@@ -89,6 +89,8 @@ func assemble(root string, nodes []Node, edges []Edge) *Graph {
 	g.Nodes = dedupNodes(nodes)
 	g.Links = dedupEdges(edges)
 	assembleSpecOwnership(g)
+	resolveADRSupersession(g)
+	resolveGlossaryRefs(g, root)
 	resolveCitedPaths(g, root)
 	resolveGoImports(g, root)
 	g.Pending = resolveReferences(g)
diff --git a/internal/graph/model.go b/internal/graph/model.go
index 755f526..52fb9b2 100644
--- a/internal/graph/model.go
+++ b/internal/graph/model.go
@@ -48,6 +48,10 @@ const (
 	TypeRawSource = "raw_source"
 	TypeTech      = "tech"
 	TypeCode      = "code"
+	TypePlan      = "plan"
+	TypeFeat      = "feat"
+	TypeADR       = "adr"
+	TypeTerm      = "term"
 )
 
 // Edge relation values — the canonical edge vocabulary (PLAN §5.5).
@@ -71,6 +75,9 @@ const (
 	RelUsesTech     = "uses_tech"
 	RelContains     = "contains"
 	RelImports      = "imports"
+	RelPlans        = "plans"
+	RelCites        = "cites"
+	RelSupersededBy = "superseded_by"
 )
 
 // NodeTypes and EdgeRelations mirror the seed graph.json meta block so the
@@ -79,14 +86,16 @@ const (
 var NodeTypes = []string{
 	TypeSpec, TypeRequire, TypeCriterion, TypeDesign, TypeInterface, TypeFlow,
 	TypeTask, TypeSteering, TypeSkill, TypeAgent, TypeMCP, TypeCodeRef,
-	TypeWikiPage, TypeRawSource, TypeTech, TypeCode,
+	TypeWikiPage, TypeRawSource, TypeTech, TypeCode, TypePlan, TypeFeat,
+	TypeADR, TypeTerm,
 }
 
 var EdgeRelations = []string{
 	RelOwns, RelHasCriterion, RelRealizes, RelTracedTo, RelImplements,
 	RelExercises, RelRefinedBy, RelInBoundary, RelDependsOn, RelComponentDep,
 	RelReferences, RelReuses, RelGoverns, RelRelatedTo, RelLinksTo,
-	RelDerivedFrom, RelUsesTech, RelContains, RelImports,
+	RelDerivedFrom, RelUsesTech, RelContains, RelImports, RelPlans,
+	RelCites, RelSupersededBy,
 }
 
 // Node is one artifact or entity. The five fixed fields are always present;
diff --git a/internal/paths/paths.go b/internal/paths/paths.go
index a15198f..a679ab1 100644
--- a/internal/paths/paths.go
+++ b/internal/paths/paths.go
@@ -29,7 +29,9 @@ const (
 	DocsRawSeg   = "raw"
 	DocsWikiSeg  = "wiki"
 	DocsGraphSeg = "graph"
+	DocsADRSeg   = "adr"
 	StackSeg     = "stack.md"
+	GlossarySeg  = "glossary.md"
 )
 
 // Entry-point files at the workspace root.
@@ -38,6 +40,11 @@ const (
 	MCPFile   = ".mcp.json" // Model Context Protocol server config (Claude Code convention)
 )
 
+// DevcontainerDir is the standard devcontainer location at the project root,
+// scaffolded by `csdd sandbox init` (the hardened, default-deny-egress
+// environment that gates bypass-mode Claude runs).
+const DevcontainerDir = ".devcontainer"
+
 // Relative segment names. Most live under .claude/; specs/ lives at the root.
 const (
 	SpecsSeg     = "specs"               // repo-root: per-feature SDD contracts
@@ -108,11 +115,23 @@ func DocsWiki(root string) string { return filepath.Join(root, DocsSeg, DocsWiki
 // DocsGraph returns docs/graph/, the only generated subtree in docs/.
 func DocsGraph(root string) string { return filepath.Join(root, DocsSeg, DocsGraphSeg) }
 
+// DocsADR returns docs/adr/, the human/LLM-authored decision records (one flat,
+// append-only, project-scoped sequence). Linted by the CLI, never written by it.
+func DocsADR(root string) string { return filepath.Join(root, DocsSeg, DocsADRSeg) }
+
 // Stack returns docs/stack.md, the human-authored tech contract.
 func Stack(root string) string { return filepath.Join(root, DocsSeg, StackSeg) }
 
+// Glossary returns docs/glossary.md, the human/LLM-authored ubiquitous-language
+// contract (canonical terms + _Avoid_ aliases). Parsed and linted by the CLI,
+// never written by it.
+func Glossary(root string) string { return filepath.Join(root, DocsSeg, GlossarySeg) }
+
 // MCP returns the repo-root .mcp.json.
 func MCP(root string) string { return filepath.Join(root, MCPFile) }
 
+// Devcontainer returns the .devcontainer/ directory under root.
+func Devcontainer(root string) string { return filepath.Join(root, DevcontainerDir) }
+
 // Entry returns the repo-root CLAUDE.md.
 func Entry(root string) string { return filepath.Join(root, EntryFile) }
diff --git a/internal/plan/adr.go b/internal/plan/adr.go
new file mode 100644
index 0000000..5a124c2
--- /dev/null
+++ b/internal/plan/adr.go
@@ -0,0 +1,267 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+	"github.com/protonspy/csdd/internal/validator"
+)
+
+// ADR status values (R1.2). An ADR with no `status` frontmatter is "accepted".
+const (
+	ADRStatusAccepted   = "accepted"
+	ADRStatusSuperseded = "superseded"
+)
+
+// reADRFile is the decision-record filename grammar (§5.4): a four-digit
+// zero-padded number, a hyphen, then a kebab-case slug, `.md`. The number is
+// identity (stable, append-only); the slug is the citation currency.
+var reADRFile = regexp.MustCompile(`^(\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$`)
+
+// reADRSlug is the grammar an `adr:<slug>` citation token must satisfy — the same
+// kebab-case rule as the filename slug, kept local so the finding is decision-ref
+// specific.
+var reADRSlug = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+
+// ADR is one parsed decision record under docs/adr/. Number is its identity (the
+// NNNN filename prefix); Slug is its citation currency (the kebab tail). Title is
+// the first `# ` heading; Body is everything after it (convention: 1–3 sentences).
+// Status defaults to accepted; SupersededBy is the number of the successor record
+// (0 when absent). File is the workspace-relative path, for findings.
+type ADR struct {
+	Number       int
+	Slug         string
+	Title        string
+	Body         string
+	Status       string
+	SupersededBy int
+	File         string
+}
+
+// adrIssue is a docs/adr well-formedness problem (malformed filename, duplicate
+// number, missing title, dangling supersession), kept minimal like gramIssue so
+// ValidatePlan lifts it into a validator.Issue with the ADR's own file path.
+type adrIssue struct {
+	file string
+	msg  string
+}
+
+// ADRSet is the parsed docs/adr/ directory: every well-formed record indexed by
+// slug and by number, plus the well-formedness issues discovered while scanning.
+// Present records whether the directory exists at all (R3.2 is gated on it).
+type ADRSet struct {
+	Present  bool
+	All      []*ADR
+	bySlug   map[string][]*ADR
+	byNumber map[int][]*ADR
+	issues   []adrIssue
+}
+
+// ScanADRs reads and parses docs/adr/, returning the record set. It never fails:
+// a malformed record becomes a well-formedness issue carried on the set (surfaced
+// by ValidatePlan), never a hard error — the lenient discipline the whole package
+// shares so a half-authored corpus still lints. A missing directory yields an
+// empty, not-present set.
+func ScanADRs(root string) *ADRSet {
+	s := &ADRSet{bySlug: map[string][]*ADR{}, byNumber: map[int][]*ADR{}}
+	dir := paths.DocsADR(root)
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return s // absent directory: not present, no records, no findings
+	}
+	s.Present = true
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+			continue
+		}
+		if strings.EqualFold(e.Name(), "README.md") {
+			continue // the conventional index is not a decision record
+		}
+		rel := filepath.ToSlash(filepath.Join("docs", paths.DocsADRSeg, e.Name()))
+		m := reADRFile.FindStringSubmatch(e.Name())
+		if m == nil {
+			s.issues = append(s.issues, adrIssue{
+				file: rel,
+				msg:  "malformed ADR filename '" + e.Name() + "': expected NNNN-<kebab-slug>.md",
+			})
+			continue
+		}
+		num, _ := strconv.Atoi(m[1])
+		data, rerr := os.ReadFile(filepath.Join(dir, e.Name()))
+		if rerr != nil {
+			continue
+		}
+		adr := parseADR(num, m[2], rel, string(data))
+		if adr.Title == "" {
+			s.issues = append(s.issues, adrIssue{
+				file: rel,
+				msg:  "ADR has no '# <title>' heading",
+			})
+		}
+		s.All = append(s.All, adr)
+		s.bySlug[adr.Slug] = append(s.bySlug[adr.Slug], adr)
+		s.byNumber[adr.Number] = append(s.byNumber[adr.Number], adr)
+	}
+	sort.Slice(s.All, func(i, j int) bool { return s.All[i].Number < s.All[j].Number })
+	s.finalize()
+	return s
+}
+
+// parseADR reads one record's content: optional frontmatter (`status`,
+// `superseded-by`), then the first `# ` line is the title and the remainder is the
+// body. superseded-by targets a number (file identity), not a slug.
+func parseADR(num int, slug, file, content string) *ADR {
+	fm := frontmatter.Parse(content)
+	adr := &ADR{Number: num, Slug: slug, File: file, Status: ADRStatusAccepted}
+	if st := strings.ToLower(strings.TrimSpace(fm.AsString("status", ""))); st != "" {
+		adr.Status = st
+	}
+	if sb := strings.TrimSpace(fm.AsString("superseded-by", "")); sb != "" {
+		// Atoi handles the zero-padded NNNN form; a malformed value leaves
+		// SupersededBy 0, so the dangling-supersession check only fires for a
+		// parseable number that names no record, matching intent.
+		if n, err := strconv.Atoi(sb); err == nil {
+			adr.SupersededBy = n
+		}
+	}
+	body := fm.Body
+	lines := strings.Split(textutil.NormalizeNewlines(body), "\n")
+	titleIdx := -1
+	for i, raw := range lines {
+		t := strings.TrimSpace(raw)
+		if strings.HasPrefix(t, "# ") {
+			adr.Title = strings.TrimSpace(strings.TrimPrefix(t, "# "))
+			titleIdx = i
+			break
+		}
+	}
+	if titleIdx >= 0 {
+		adr.Body = strings.TrimSpace(strings.Join(lines[titleIdx+1:], "\n"))
+	}
+	return adr
+}
+
+// finalize records the well-formedness issues that need the whole set: duplicate
+// numbers (R3.2) and dangling supersession (R3.2). Slug ambiguity is not an issue
+// here — it is a finding raised against the citing feat when a slug is resolved
+// (ValidatePlan), so a duplicated slug nobody cites is silent by design.
+func (s *ADRSet) finalize() {
+	nums := make([]int, 0, len(s.byNumber))
+	for n := range s.byNumber {
+		nums = append(nums, n)
+	}
+	sort.Ints(nums)
+	for _, n := range nums {
+		recs := s.byNumber[n]
+		if len(recs) > 1 {
+			for _, r := range recs {
+				s.issues = append(s.issues, adrIssue{
+					file: r.File,
+					msg:  "duplicate ADR number " + fourDigit(n) + " (numbers are identity; renumber the newer record)",
+				})
+			}
+		}
+	}
+	for _, r := range s.All {
+		if r.SupersededBy != 0 && len(s.byNumber[r.SupersededBy]) == 0 {
+			s.issues = append(s.issues, adrIssue{
+				file: r.File,
+				msg:  "dangling supersession: superseded-by " + fourDigit(r.SupersededBy) + " names no ADR",
+			})
+		}
+	}
+}
+
+// ADRResolution is the outcome of resolving one `adr:<slug>` citation.
+type ADRResolution int
+
+const (
+	// ADRResolved: exactly one record matches the slug.
+	ADRResolved ADRResolution = iota
+	// ADRMissing: no record matches the slug (broken decision ref).
+	ADRMissing
+	// ADRAmbiguous: two or more records share the slug (ambiguous decision ref).
+	ADRAmbiguous
+)
+
+// Resolve maps a citation slug to at most one record (R1.3). It returns the
+// record (nil unless resolved) and the resolution outcome.
+func (s *ADRSet) Resolve(slug string) (*ADR, ADRResolution) {
+	recs := s.bySlug[slug]
+	switch len(recs) {
+	case 0:
+		return nil, ADRMissing
+	case 1:
+		return recs[0], ADRResolved
+	default:
+		return nil, ADRAmbiguous
+	}
+}
+
+// Issues returns the docs/adr well-formedness problems as validator-ready
+// (file, message) pairs. ValidatePlan only surfaces these WHERE the directory
+// exists (R3.2).
+func (s *ADRSet) issuesResolved() []adrIssue { return s.issues }
+
+// fourDigit renders a number as the zero-padded NNNN identity form.
+func fourDigit(n int) string {
+	str := itoa(n)
+	for len(str) < 4 {
+		str = "0" + str
+	}
+	return str
+}
+
+// ValidADRSlug reports whether s is a well-formed citation slug (kebab-case).
+func ValidADRSlug(s string) bool { return reADRSlug.MatchString(s) }
+
+// adrRefIssues resolves a feat's adr:<slug> citations against the record set and
+// returns the findings: a malformed slug (R2.2), a slug matching no record
+// ("broken decision ref", R3.1), a slug matching two or more ("ambiguous decision
+// ref", R3.1), and a citation of a superseded record ("cites superseded decision",
+// R3.3). It is imported by ValidatePlan; kept here so the ADR grammar and its
+// findings live together.
+func adrRefIssues(f Feat, adrs *ADRSet) []validator.Issue {
+	var out []validator.Issue
+	for _, slug := range f.ADRRefs {
+		if !ValidADRSlug(slug) {
+			label := slug
+			if label == "" {
+				label = "(empty)"
+			}
+			out = append(out, validator.Issue{
+				File: "plan.md", Line: f.Line,
+				Msg: "feat '" + f.Slug + "' has a malformed decision ref 'adr:" + label + "' (slug must be kebab-case)",
+			})
+			continue
+		}
+		adr, res := adrs.Resolve(slug)
+		switch res {
+		case ADRMissing:
+			out = append(out, validator.Issue{
+				File: "plan.md", Line: f.Line,
+				Msg: "feat '" + f.Slug + "' has a broken decision ref 'adr:" + slug + "' (no matching record under docs/adr/)",
+			})
+		case ADRAmbiguous:
+			out = append(out, validator.Issue{
+				File: "plan.md", Line: f.Line,
+				Msg: "feat '" + f.Slug + "' has an ambiguous decision ref 'adr:" + slug + "' (two or more records share this slug; renumber the newer)",
+			})
+		case ADRResolved:
+			if adr.Status == ADRStatusSuperseded {
+				out = append(out, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' cites superseded decision 'adr:" + slug + "' — cite its successor",
+				})
+			}
+		}
+	}
+	return out
+}
diff --git a/internal/plan/adr_test.go b/internal/plan/adr_test.go
new file mode 100644
index 0000000..f3108e0
--- /dev/null
+++ b/internal/plan/adr_test.go
@@ -0,0 +1,259 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/protonspy/csdd/internal/validator"
+)
+
+// writeADRs lays down docs/adr/<name> files under root.
+func writeADRs(t *testing.T, root string, files map[string]string) {
+	t.Helper()
+	dir := filepath.Join(root, "docs", "adr")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for name, content := range files {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestScanADRsParsesRecords(t *testing.T) {
+	root := t.TempDir()
+	writeADRs(t, root, map[string]string{
+		"0001-store-under-docs-adr.md": "# Store decision records under docs/adr/\n\nContext. Decision. Why.\n",
+		"0002-two-tier-interview.md": `---
+status: superseded
+superseded-by: 0003
+---
+# Two-tier interview
+
+Batch facts, grill decisions.
+`,
+		"0003-two-tier-refined.md": "# The refined interview\n\nSupersedes 0002.\n",
+	})
+	s := ScanADRs(root)
+	if !s.Present {
+		t.Fatal("expected Present")
+	}
+	if len(s.All) != 3 {
+		t.Fatalf("got %d records, want 3", len(s.All))
+	}
+	if len(s.issuesResolved()) != 0 {
+		t.Errorf("expected no well-formedness issues, got %+v", s.issuesResolved())
+	}
+
+	a1, res := s.Resolve("store-under-docs-adr")
+	if res != ADRResolved {
+		t.Fatalf("0001 resolution = %v", res)
+	}
+	if a1.Number != 1 || a1.Status != ADRStatusAccepted {
+		t.Errorf("0001 = %+v", a1)
+	}
+	if a1.Title != "Store decision records under docs/adr/" {
+		t.Errorf("0001 title = %q", a1.Title)
+	}
+	if !strings.Contains(a1.Body, "Context. Decision. Why.") {
+		t.Errorf("0001 body = %q", a1.Body)
+	}
+
+	a2, _ := s.Resolve("two-tier-interview")
+	if a2.Status != ADRStatusSuperseded || a2.SupersededBy != 3 {
+		t.Errorf("0002 = %+v", a2)
+	}
+}
+
+func TestScanADRsAbsentIsSilent(t *testing.T) {
+	s := ScanADRs(t.TempDir())
+	if s.Present {
+		t.Error("absent docs/adr should not be Present")
+	}
+	if len(s.All) != 0 || len(s.issuesResolved()) != 0 {
+		t.Error("absent docs/adr should yield nothing")
+	}
+}
+
+func TestScanADRsWellFormedness(t *testing.T) {
+	root := t.TempDir()
+	writeADRs(t, root, map[string]string{
+		"0001-good.md":       "# Good\n\nbody\n",
+		"0001-dup-number.md": "# Dup number\n\nbody\n",                             // duplicate number 0001
+		"no-number.md":       "# Bad filename\n\nbody\n",                           // malformed filename
+		"0007-no-title.md":   "just prose, no heading\n",                           // missing title
+		"0008-dangles.md":    "---\nsuperseded-by: 0099\n---\n# Dangles\n\nbody\n", // dangling supersession
+		"README.md":          "# Index\n\nnot an ADR\n",                            // ignored
+	})
+	s := ScanADRs(root)
+	msgs := map[string]bool{}
+	for _, i := range s.issuesResolved() {
+		msgs[i.msg] = true
+	}
+	want := []string{
+		"malformed ADR filename",
+		"duplicate ADR number 0001",
+		"ADR has no '# <title>' heading",
+		"dangling supersession: superseded-by 0099",
+	}
+	for _, w := range want {
+		found := false
+		for m := range msgs {
+			if strings.Contains(m, w) {
+				found = true
+			}
+		}
+		if !found {
+			t.Errorf("missing well-formedness issue containing %q; got %+v", w, s.issuesResolved())
+		}
+	}
+	// README.md must never be flagged as malformed.
+	for m := range msgs {
+		if strings.Contains(m, "README") {
+			t.Errorf("README.md should be ignored, not flagged: %q", m)
+		}
+	}
+}
+
+func TestScanADRsAmbiguousSlug(t *testing.T) {
+	root := t.TempDir()
+	writeADRs(t, root, map[string]string{
+		"0002-shared.md": "# Two\n\nbody\n",
+		"0005-shared.md": "# Five\n\nbody\n",
+	})
+	s := ScanADRs(root)
+	if _, res := s.Resolve("shared"); res != ADRAmbiguous {
+		t.Errorf("shared slug resolution = %v, want ambiguous", res)
+	}
+	if _, res := s.Resolve("nope"); res != ADRMissing {
+		t.Errorf("unknown slug resolution = %v, want missing", res)
+	}
+}
+
+// A plan citing ADRs is exercised end-to-end through ValidatePlan.
+func adrPlanWorkspace(t *testing.T, refs string) (root string, doc *PlanDoc) {
+	t.Helper()
+	root = t.TempDir()
+	writeADRs(t, root, map[string]string{
+		"0001-accepted.md": "# Accepted decision\n\nWe chose X because Y.\n",
+		"0002-old.md":      "---\nstatus: superseded\nsuperseded-by: 0003\n---\n# Old decision\n\nreplaced\n",
+		"0003-new.md":      "# New decision\n\nthe successor\n",
+		"0004-twin.md":     "# Twin A\n\nbody\n",
+		"0009-twin-dup.md": "# Twin B\n\nbody\n", // NOTE: different slug, so not ambiguous
+	})
+	// Add a genuine ambiguity: two files sharing slug "dupe".
+	writeADRs(t, root, map[string]string{
+		"0006-dupe.md": "# Dupe six\n\nbody\n",
+		"0007-dupe.md": "# Dupe seven\n\nbody\n",
+	})
+	src := "---\nname: demo\nstatus: draft\n---\n" +
+		"## Feats\n\n" +
+		"| # | Feat | Objective | Depends | Milestone | (P) | Refs |\n" +
+		"|---|------|-----------|---------|-----------|-----|------|\n" +
+		"| 1 | thing | do it | — | M1 | | " + refs + " |\n\n" +
+		"## Quality Gates\n\n- verify: make check\n"
+	doc = Parse(src)
+	doc.Slug = "demo"
+	return root, doc
+}
+
+func TestValidateADRRefs(t *testing.T) {
+	cases := []struct {
+		name    string
+		refs    string
+		wantSub string
+	}{
+		{"broken", "adr:ghost", "broken decision ref 'adr:ghost'"},
+		{"ambiguous", "adr:dupe", "ambiguous decision ref 'adr:dupe'"},
+		{"malformed", "adr:Not_Kebab", "malformed decision ref 'adr:Not_Kebab'"},
+		{"empty", "adr:", "malformed decision ref 'adr:(empty)'"},
+		{"cites-superseded", "adr:old", "cites superseded decision 'adr:old'"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			root, doc := adrPlanWorkspace(t, tc.refs)
+			issues := ValidatePlan(doc, root)
+			found := false
+			for _, i := range issues {
+				if strings.Contains(i.Msg, tc.wantSub) {
+					found = true
+				}
+			}
+			if !found {
+				t.Errorf("want an issue containing %q; got:\n%s", tc.wantSub, joinIssues(issues))
+			}
+		})
+	}
+}
+
+func TestValidateADRCleanCitation(t *testing.T) {
+	root, doc := adrPlanWorkspace(t, "adr:accepted adr:new")
+	for _, i := range ValidatePlan(doc, root) {
+		if strings.Contains(i.Msg, "decision ref") || strings.Contains(i.Msg, "superseded") {
+			t.Errorf("clean citation raised a decision finding: %s", i.Msg)
+		}
+	}
+}
+
+const adrBriefPlan = `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | thing | Do the thing | — | M1 | | adr:pick-store adr:ghost-ref |
+
+## Quality Gates
+
+- verify: make check
+`
+
+func TestBriefInlinesADRs(t *testing.T) {
+	root := setupWorkspace(t, "p", adrBriefPlan)
+	writeADRs(t, root, map[string]string{
+		"0001-pick-store.md": "# We store records under docs/adr\n\nDECISION_BODY_TOKEN: append-only, project-scoped.\n",
+	})
+	step := Step{Feat: "thing", Step: "task 1.1", Reason: "implement"}
+	doc, err := Load(root, "p")
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := Brief(root, doc, step)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Determinism.
+	if out2, _ := Brief(root, doc, step); out != out2 {
+		t.Errorf("ADR brief is not byte-deterministic")
+	}
+	// The resolved ADR is inlined in full (title + body).
+	if !strings.Contains(out, "We store records under docs/adr") {
+		t.Errorf("brief should inline the ADR title:\n%s", out)
+	}
+	if !strings.Contains(out, "DECISION_BODY_TOKEN") {
+		t.Errorf("brief should inline the ADR body in full (unlike wiki):\n%s", out)
+	}
+	// A broken ADR ref is a WARNING, not a hard omission.
+	if !strings.Contains(out, "adr:ghost-ref") || !strings.Contains(out, "WARNING") {
+		t.Errorf("brief should warn on the unresolved ADR ref:\n%s", out)
+	}
+	// The open-decision forbidden-actions line is present (R4.3).
+	if !strings.Contains(out, "OPEN DECISION") {
+		t.Errorf("brief should carry the open-decision forbidden-actions line:\n%s", out)
+	}
+}
+
+func joinIssues(issues []validator.Issue) string {
+	var b strings.Builder
+	for _, i := range issues {
+		b.WriteString("  - ")
+		b.WriteString(i.Msg)
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
diff --git a/internal/plan/approve.go b/internal/plan/approve.go
new file mode 100644
index 0000000..d913409
--- /dev/null
+++ b/internal/plan/approve.go
@@ -0,0 +1,51 @@
+package plan
+
+import (
+	"time"
+)
+
+// ApprovePlan writes plan.json binding an approval to the exact current content
+// of plan.md + seeds/** (R4.1). It assumes validation has already passed (the CLI
+// runs ValidatePlan and refuses on findings first); this function is purely the
+// mechanical state write — the plan analog of SpecApprove's final step, and the
+// only place a plan is marked approved (design principle 3). now is injected so
+// callers and tests stay deterministic where they need to be.
+func ApprovePlan(root string, doc *PlanDoc, now time.Time) error {
+	dir := Dir(root, doc.Slug)
+	h, err := HashPlan(dir)
+	if err != nil {
+		return err
+	}
+	name := doc.Name
+	if name == "" {
+		name = doc.Slug
+	}
+	return SavePlanJSON(dir, PlanJSON{
+		Name: name,
+		Approvals: PlanApproval{
+			Approved:    true,
+			ContentHash: h,
+			ApprovedAt:  now.UTC().Format("2006-01-02T15:04:05Z"),
+		},
+	})
+}
+
+// IsApproved reports a plan's approval state and whether its content has drifted
+// since approval (R4.2). Drift is a hash mismatch between the stored approval and
+// the current plan.md + seeds/**; an unapproved plan is (false, false).
+// next/run consult this to refuse autonomous execution on drift.
+func IsApproved(root, slug string) (approved, drift bool, err error) {
+	dir := Dir(root, slug)
+	pj, ok, err := LoadPlanJSON(dir)
+	if err != nil || !ok || !pj.Approvals.Approved {
+		return false, false, err
+	}
+	if pj.Approvals.ContentHash == "" {
+		return true, false, nil // approved by an older writer with no hash — trust it
+	}
+	h, herr := HashPlan(dir)
+	if herr != nil {
+		return true, false, herr
+	}
+	return true, h != pj.Approvals.ContentHash, nil
+}
diff --git a/internal/plan/brief.go b/internal/plan/brief.go
new file mode 100644
index 0000000..0378255
--- /dev/null
+++ b/internal/plan/brief.go
@@ -0,0 +1,247 @@
+package plan
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+	"github.com/protonspy/csdd/internal/paths"
+)
+
+// forbiddenActions is the verbatim R9.6 contract every brief carries: the session
+// authors artifacts and returns a verdict, nothing more. The runner owns
+// approvals, commits, and all plan/graph/state writes.
+var forbiddenActions = []string{
+	"Do NOT edit plan.md, plan.json, docs/graph/, or .csdd/ — these are the runner's; touching them fails the step.",
+	"Do NOT run `csdd spec approve`, `csdd plan approve`, or `git commit` — the runner performs approvals and commits only after the gates pass.",
+	"Do NOT adopt a technology that is not in docs/stack.md — that is an open decision; stop and report it in your verdict instead.",
+	"Do NOT make a decision that is hard to reverse, surprising without context, and the result of a real trade-off unless a cited ADR or stack row already covers it — that is an OPEN DECISION; return a `blocked` verdict with a revision proposal, never improvise.",
+	"If you hit an unforeseen problem you cannot solve within this step's contract, return a `blocked` verdict with a revision proposal — never improvise around the plan.",
+}
+
+// Brief assembles the deterministic context pack for one step (R7). It draws only
+// on explicit content — the feat row, its seeds, resolved stack rows, resolved
+// wiki refs (path + description, never the body), the Executor Notes, and the
+// step contract — so the same plan and step always produce a byte-identical
+// brief (R7.3). It inlines stack rows in full but never wiki bodies (R7.2).
+func Brief(root string, doc *PlanDoc, step Step) (string, error) {
+	feat, ok := doc.Feat(step.Feat)
+	if !ok {
+		return "", fmt.Errorf("feat %q is not in plan %q", step.Feat, doc.Slug)
+	}
+	var b strings.Builder
+	w := func(format string, a ...any) { fmt.Fprintf(&b, format, a...) }
+
+	w("# Brief — %s / %s\n\n", doc.Slug, feat.Slug)
+	w("You are a fresh session executing ONE step of an approved csdd plan. Do exactly\n")
+	w("this step's contract, then return the verdict schema. Nothing more.\n\n")
+
+	// 1. Step contract.
+	produce, gates := stepContract(doc, step)
+	w("## Step: %s\n\n", step.Step)
+	if step.Reason != "" {
+		w("%s\n\n", step.Reason)
+	}
+	w("**Produce:** %s\n\n", produce)
+	w("**Gates that will run (all must pass before this step advances):**\n")
+	for _, g := range gates {
+		w("- %s\n", g)
+	}
+	w("\n**Forbidden actions:**\n")
+	for _, f := range forbiddenActions {
+		w("- %s\n", f)
+	}
+	w("\n")
+
+	// 2. Feat context.
+	w("## Feat: %s\n\n", feat.Slug)
+	w("- Objective: %s\n", orDash(feat.Objective))
+	w("- Milestone: %s\n", orDash(feat.Milestone))
+	if len(feat.Depends) > 0 {
+		w("- Depends on (already done): %s\n", strings.Join(feat.Depends, ", "))
+	}
+	w("\n")
+
+	// 3. Stack rows — inlined in full (they are one-line contracts).
+	if len(feat.StackRefs) > 0 {
+		rows := decidedRows(root)
+		w("## Tech contract (docs/stack.md — use ONLY these)\n\n")
+		for _, name := range feat.StackRefs {
+			if r, ok := rows[normalizeTechName(name)]; ok {
+				w("- **%s** (%s) — version %s. %s", orDash(r.Choice), orDash(r.Domain), orDash(r.Version), orDash(r.Why))
+				if r.Refs != "" {
+					w(" Refs: %s", r.Refs)
+				}
+				w("\n")
+			} else {
+				w("- **%s** — WARNING: not found in the Decided table (validate should have caught this).\n", name)
+			}
+		}
+		w("\n")
+	}
+
+	// 3b. Decisions — cited ADRs inlined in full (they are short by format, the
+	// stack-row treatment; the why travels with the what, principle 4).
+	if len(feat.ADRRefs) > 0 {
+		adrs := ScanADRs(root)
+		w("## Decisions (docs/adr — the why)\n\n")
+		for _, slug := range feat.ADRRefs {
+			adr, res := adrs.Resolve(slug)
+			if res != ADRResolved {
+				w("- **adr:%s** — WARNING: does not resolve to a docs/adr record (validate should have caught this).\n", slug)
+				continue
+			}
+			w("### %s (adr:%s)\n\n", orDash(adr.Title), adr.Slug)
+			if adr.Status == ADRStatusSuperseded {
+				w("_status: superseded")
+				if adr.SupersededBy != 0 {
+					w(" by %s", fourDigit(adr.SupersededBy))
+				}
+				w("_\n\n")
+			}
+			if adr.Body != "" {
+				w("%s\n\n", adr.Body)
+			}
+		}
+	}
+
+	// 4. Wiki refs — path + description only (the session reads what it needs).
+	if len(feat.WikiRefs) > 0 {
+		w("## Reference pages (read what you need; do not assume the content)\n\n")
+		for _, ref := range feat.WikiRefs {
+			path, desc := wikiRefInfo(root, ref)
+			if path == "" {
+				w("- [[%s]] — WARNING: no matching page under docs/wiki/pages/.\n", ref)
+				continue
+			}
+			if desc != "" {
+				w("- %s — %s\n", path, desc)
+			} else {
+				w("- %s\n", path)
+			}
+		}
+		w("\n")
+	}
+
+	// 5. Seeds — pre-authored artifacts to fold into this feat's spec.
+	if seeds := featSeedFiles(root, doc.Slug, feat.Slug); len(seeds) > 0 {
+		w("## Seeds (pre-authored inputs for this feat's spec)\n\n")
+		for _, s := range seeds {
+			w("- %s\n", s)
+		}
+		w("\n")
+	}
+
+	// 6. Executor Notes — verbatim.
+	if doc.ExecutorNotes != "" {
+		w("## Executor Notes\n\n%s\n\n", doc.ExecutorNotes)
+	}
+
+	// 7. Graph-first consultation.
+	w("## Consult the knowledge graph BEFORE reading code\n\n")
+	w("- `csdd graph query <term>` — find the nodes for a concept.\n")
+	w("- `csdd graph explain <id>` — see a node's neighborhood and provenance.\n")
+	w("- `csdd graph path <a> <b>` — trace how two artifacts connect.\n")
+	w("Traverse the graph to locate the relevant code; do not grep the whole tree.\n")
+
+	return b.String(), nil
+}
+
+// stepContract returns the artifact to produce and the gates that will run for a
+// step (R7.1). Spec-phase steps are gated by the spec validator; an implementation
+// task is gated by the plan's own Quality Gates plus graph traceability.
+func stepContract(doc *PlanDoc, step Step) (produce string, gates []string) {
+	feat := step.Feat
+	switch {
+	case step.Step == StepSpecRequirements:
+		return fmt.Sprintf("specs/%s/requirements.md (EARS acceptance criteria) via `csdd spec generate %s --artifact requirements`", feat, feat),
+			[]string{fmt.Sprintf("`csdd spec validate %s`", feat)}
+	case step.Step == StepSpecDesign:
+		return fmt.Sprintf("specs/%s/design.md (components, traceability, file plan) via `csdd spec generate %s --artifact design`", feat, feat),
+			[]string{fmt.Sprintf("`csdd spec validate %s`", feat)}
+	case step.Step == StepSpecTasks:
+		return fmt.Sprintf("specs/%s/tasks.md (boundary/depends-annotated tasks) via `csdd spec generate %s --artifact tasks`", feat, feat),
+			[]string{fmt.Sprintf("`csdd spec validate %s`", feat)}
+	case strings.HasPrefix(step.Step, StepTaskPrefix):
+		id := strings.TrimSpace(strings.TrimPrefix(step.Step, StepTaskPrefix))
+		g := planGateCommands(doc)
+		g = append(g, "`csdd graph analyze --strict` (traceability holds)")
+		return fmt.Sprintf("the implementation and tests for task %s in specs/%s/tasks.md; check the box when done", id, feat), g
+	default:
+		return step.Step, planGateCommands(doc)
+	}
+}
+
+// planGateCommands renders the plan's Quality Gates as backticked commands, or a
+// placeholder note when the plan declared none.
+func planGateCommands(doc *PlanDoc) []string {
+	if len(doc.Gates) == 0 {
+		return []string{"(no Quality Gates declared in the plan)"}
+	}
+	out := make([]string, 0, len(doc.Gates))
+	for _, g := range doc.Gates {
+		out = append(out, fmt.Sprintf("`%s` (%s)", g.Command, g.Label))
+	}
+	return out
+}
+
+// wikiRefInfo resolves a [[wiki-page]] ref to its workspace path and frontmatter
+// description (or title), reading only the frontmatter — never inlining the body
+// (R7.2). Returns empty path when no page matches.
+func wikiRefInfo(root, ref string) (path, desc string) {
+	dir := filepath.Join(paths.DocsWiki(root), "pages")
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return "", ""
+	}
+	target := normalizeWikiSlug(ref)
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+			continue
+		}
+		if normalizeWikiSlug(strings.TrimSuffix(e.Name(), ".md")) != target {
+			continue
+		}
+		rel := filepath.ToSlash(filepath.Join("docs", "wiki", "pages", e.Name()))
+		data, err := os.ReadFile(filepath.Join(dir, e.Name()))
+		if err != nil {
+			return rel, ""
+		}
+		fm := frontmatter.Parse(string(data))
+		d := fm.AsString("description", "")
+		if d == "" {
+			d = fm.AsString("title", "")
+		}
+		return rel, d
+	}
+	return "", ""
+}
+
+// featSeedFiles returns the workspace paths of every file under
+// docs/plans/<slug>/seeds/<feat>/, sorted, for the brief's seed list.
+func featSeedFiles(root, slug, feat string) []string {
+	dir := filepath.Join(seedsDir(Dir(root, slug)), feat)
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	var out []string
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		out = append(out, filepath.ToSlash(filepath.Join("docs", "plans", slug, "seeds", feat, e.Name())))
+	}
+	sort.Strings(out)
+	return out
+}
+
+func orDash(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "—"
+	}
+	return s
+}
diff --git a/internal/plan/brief_test.go b/internal/plan/brief_test.go
new file mode 100644
index 0000000..7d28602
--- /dev/null
+++ b/internal/plan/brief_test.go
@@ -0,0 +1,108 @@
+package plan
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const briefPlan = `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest and store photos | — | M1 | | stack:go [[storage-design]] |
+
+## Quality Gates
+
+- verify: make check
+- e2e: go test ./e2e/...
+
+## Executor Notes
+
+Run gofmt before committing. Never touch generated files.
+`
+
+func briefFor(t *testing.T, root, slug string, step Step) string {
+	t.Helper()
+	doc, err := Load(root, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := Brief(root, doc, step)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func TestBriefContentAndDeterminism(t *testing.T) {
+	root := setupWorkspace(t, "p", briefPlan)
+	// A wiki page with a frontmatter description (its body must NOT be inlined).
+	writeFile(t, filepath.Join(root, "docs", "wiki", "pages", "storage-design.md"),
+		"---\ntitle: Storage Design\ndescription: How photos are stored and addressed.\n---\n# Storage Design\nSECRET_BODY_TOKEN should not appear in the brief.\n")
+	// A seed for the feat.
+	writeFile(t, filepath.Join(root, "docs", "plans", "p", "seeds", "upload", "requirements.md"), "# seed reqs\n")
+
+	step := Step{Feat: "upload", Step: StepSpecRequirements, Reason: "start requirements"}
+	out := briefFor(t, root, "p", step)
+
+	// Determinism: same plan + step → byte-identical brief.
+	if out2 := briefFor(t, root, "p", step); out != out2 {
+		t.Errorf("brief is not byte-deterministic")
+	}
+
+	// Stack row inlined in full (the Decided row for Go).
+	if !strings.Contains(out, "Go") || !strings.Contains(out, "1.22") {
+		t.Errorf("brief should inline the full stack row: %s", out)
+	}
+	// Wiki ref as path + description, NOT the page body.
+	if !strings.Contains(out, "docs/wiki/pages/storage-design.md") {
+		t.Errorf("brief should cite the wiki page path")
+	}
+	if !strings.Contains(out, "How photos are stored") {
+		t.Errorf("brief should include the wiki frontmatter description")
+	}
+	if strings.Contains(out, "SECRET_BODY_TOKEN") {
+		t.Errorf("brief must NOT inline the wiki page body (token leaked)")
+	}
+	// Forbidden actions and Executor Notes verbatim.
+	if !strings.Contains(out, "Do NOT edit plan.md") {
+		t.Errorf("brief should carry the forbidden-actions contract")
+	}
+	if !strings.Contains(out, "Run gofmt before committing") {
+		t.Errorf("brief should carry the Executor Notes verbatim")
+	}
+	// Seeds listed.
+	if !strings.Contains(out, "docs/plans/p/seeds/upload/requirements.md") {
+		t.Errorf("brief should list the feat's seeds")
+	}
+	// Step gate: the spec validator for this feat.
+	if !strings.Contains(out, "csdd spec validate upload") {
+		t.Errorf("requirements step should name the spec-validate gate")
+	}
+}
+
+func TestBriefTaskStepGates(t *testing.T) {
+	root := setupWorkspace(t, "p", briefPlan)
+	step := Step{Feat: "upload", Step: "task 1.2", Reason: "implement task 1.2"}
+	out := briefFor(t, root, "p", step)
+	// Implementation task runs the plan's Quality Gates plus graph analyze.
+	if !strings.Contains(out, "make check") {
+		t.Errorf("task step should list the plan Quality Gates")
+	}
+	if !strings.Contains(out, "graph analyze --strict") {
+		t.Errorf("task step should list the graph traceability gate")
+	}
+}
+
+func TestBriefUnknownFeat(t *testing.T) {
+	root := setupWorkspace(t, "p", briefPlan)
+	doc, _ := Load(root, "p")
+	if _, err := Brief(root, doc, Step{Feat: "ghost", Step: StepSpecRequirements}); err == nil {
+		t.Errorf("Brief should error for a feat not in the plan")
+	}
+}
diff --git a/internal/plan/load.go b/internal/plan/load.go
new file mode 100644
index 0000000..05e5eb5
--- /dev/null
+++ b/internal/plan/load.go
@@ -0,0 +1,115 @@
+package plan
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/manifest"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+)
+
+// Dir returns the plan directory docs/plans/<slug>/ under root.
+func Dir(root, slug string) string {
+	return filepath.Join(paths.DocsPlans(root), slug)
+}
+
+// planMDPath / seedsDir / planJSONPath / logPath are the fixed files inside a
+// plan directory (§2), centralized so the layout lives in one place.
+func planMDPath(dir string) string   { return filepath.Join(dir, "plan.md") }
+func seedsDir(dir string) string     { return filepath.Join(dir, "seeds") }
+func planJSONPath(dir string) string { return filepath.Join(dir, "plan.json") }
+
+// Load reads and parses docs/plans/<slug>/plan.md, tagging the result with the
+// directory slug. A missing plan.md is an error; a malformed table is not (it
+// becomes grammar findings on the returned doc, per Parse).
+func Load(root, slug string) (*PlanDoc, error) {
+	dir := Dir(root, slug)
+	data, err := os.ReadFile(planMDPath(dir))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("plan not found: %s (looked for %s)", slug, filepath.ToSlash(planMDPath(Dir("", slug))))
+		}
+		return nil, err
+	}
+	doc := Parse(string(data))
+	doc.Slug = slug
+	return doc, nil
+}
+
+// List returns the slugs of every plan under docs/plans/ (a directory holding a
+// plan.md), in lexical order. Top-level draft files like PLAN-*.md are not plans.
+func List(root string) ([]string, error) {
+	base := paths.DocsPlans(root)
+	entries, err := os.ReadDir(base)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	var out []string
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		if _, err := os.Stat(planMDPath(filepath.Join(base, e.Name()))); err == nil {
+			out = append(out, e.Name())
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// HashPlan computes the approval-binding content hash over plan.md plus every
+// file under seeds/, sorted by workspace path (R4.1, §5.4). Content is
+// line-ending normalized (via manifest.Hash) so a CRLF re-checkout never looks
+// like drift — the exact discipline phaseContentHash uses for specs. The
+// per-file path is folded into the hashed stream so renaming a seed changes the
+// hash even when its bytes do not.
+func HashPlan(dir string) (string, error) {
+	var b strings.Builder
+	planMD, err := os.ReadFile(planMDPath(dir))
+	if err != nil {
+		return "", err
+	}
+	writeHashEntry(&b, "plan.md", planMD)
+
+	var seeds []string
+	_ = filepath.WalkDir(seedsDir(dir), func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return nil // seeds/ is optional; an unreadable entry is simply skipped
+		}
+		if !d.IsDir() {
+			seeds = append(seeds, p)
+		}
+		return nil
+	})
+	sort.Strings(seeds)
+	for _, p := range seeds {
+		data, err := os.ReadFile(p)
+		if err != nil {
+			continue
+		}
+		rel, err := filepath.Rel(dir, p)
+		if err != nil {
+			rel = p
+		}
+		writeHashEntry(&b, filepath.ToSlash(rel), data)
+	}
+	return manifest.Hash(b.String()), nil
+}
+
+// writeHashEntry appends one canonical (path, content) record to the hash stream.
+// The NUL delimiter cannot appear in a text path or normalized markdown body, so
+// no two distinct file sets can collide onto the same stream.
+func writeHashEntry(b *strings.Builder, relPath string, content []byte) {
+	b.WriteString(relPath)
+	b.WriteByte('\n')
+	b.WriteString(textutil.NormalizeNewlines(string(content)))
+	b.WriteString("\n\x00\n")
+}
diff --git a/internal/plan/model.go b/internal/plan/model.go
new file mode 100644
index 0000000..9e2d0dd
--- /dev/null
+++ b/internal/plan/model.go
@@ -0,0 +1,140 @@
+// Package plan implements csdd's plan layer: the structured, contract-bound
+// document under docs/plans/<slug>/ that sits ABOVE specs. A plan decomposes an
+// initiative into feats, where each feat becomes exactly one spec in specs/. This
+// package owns the machine-readable core of that document — parsing the grammar
+// (§5.4), linting it (R3), deriving per-feat status from specs/ reality (R5),
+// sequencing the next step (R6), assembling deterministic briefs (R7), and (M4)
+// driving the autonomous runner (R9).
+//
+// Design principle 1 holds here as it does in internal/cli/spec.go: this package
+// never authors prose. It scaffolds, parses, derives, sequences, and appends
+// mechanical state (plan.json, log.md); the plan's content is human/LLM-authored.
+package plan
+
+// Frontmatter status values for a plan document (R2.3).
+const (
+	StatusDraft      = "draft"
+	StatusApproved   = "approved"
+	StatusSuperseded = "superseded"
+)
+
+// validStatuses is the closed set of plan frontmatter status values.
+var validStatuses = []string{StatusDraft, StatusApproved, StatusSuperseded}
+
+// ValidStatus reports whether s is a recognized plan frontmatter status.
+func ValidStatus(s string) bool {
+	for _, v := range validStatuses {
+		if v == s {
+			return true
+		}
+	}
+	return false
+}
+
+// Feat is one row of the `## Feats` table (R2.1). A feat becomes exactly one
+// spec directory, so Slug must be a valid spec-directory name (kebab-case). The
+// reference lists are pre-tokenized: WikiRefs holds [[wiki-page]] targets (inner
+// text only) and StackRefs holds stack:<name> technology names; Refs preserves
+// the raw whitespace-separated tokens verbatim for the brief's provenance.
+type Feat struct {
+	Num       string   // the "#" column, as written (display/order only)
+	Slug      string   // the Feat slug — a spec-directory name
+	Objective string   // the Objective column
+	Depends   []string // explicit feat slugs (range shorthand is never expanded)
+	Milestone string   // the Milestone column
+	Parallel  bool     // the (P) column — honored for ordering only in v1
+	WikiRefs  []string // [[wiki-page]] targets, brackets/aliases stripped
+	StackRefs []string // stack:<name> technology names
+	ADRRefs   []string // adr:<slug> decision-record slugs (verbatim, incl. malformed)
+	Refs      []string // every Refs token verbatim (superset of the three above)
+	Line      int      // 1-based source line of the row (for findings)
+}
+
+// Gate is one `## Quality Gates` line (R2.2): `- <label>: <command>`. The gate
+// list is the plan's own verification contract — the runner executes every gate
+// after each implementation step (R9.2).
+type Gate struct {
+	Label   string
+	Command string
+	Line    int // 1-based source line (for findings)
+}
+
+// PlanDoc is a parsed plan.md. Slug is set by the loader from the directory name,
+// not the document; Name/Status come from frontmatter. Feats/Gates/ExecutorNotes
+// are the three parseable regions (§5.4); unknown sections are ignored. Grammar
+// issues found during parsing (malformed table shape, missing columns) are
+// carried on the doc so ValidatePlan can surface them alongside semantic findings.
+type PlanDoc struct {
+	Slug          string
+	Name          string
+	Status        string
+	Feats         []Feat
+	Gates         []Gate
+	ExecutorNotes string
+
+	// grammar holds structural parse problems (table shape / missing columns).
+	// Unexported: callers reach them via ValidatePlan, never directly.
+	grammar []gramIssue
+}
+
+// gramIssue is a structural parse problem, kept minimal so model.go carries no
+// dependency on internal/validator. ValidatePlan lifts these into validator.Issue.
+type gramIssue struct {
+	line int
+	msg  string
+}
+
+// Feat returns the feat with the given slug and whether it was found.
+func (d *PlanDoc) Feat(slug string) (Feat, bool) {
+	for _, f := range d.Feats {
+		if f.Slug == slug {
+			return f, true
+		}
+	}
+	return Feat{}, false
+}
+
+// FeatSlugs returns the feat slugs in table order.
+func (d *PlanDoc) FeatSlugs() []string {
+	out := make([]string, 0, len(d.Feats))
+	for _, f := range d.Feats {
+		out = append(out, f.Slug)
+	}
+	return out
+}
+
+// planSchemaVersion is the current plan.json schema. Written on every save so a
+// future csdd can detect and migrate older layouts (the spec.json precedent).
+const planSchemaVersion = 1
+
+// PlanApproval binds an approval to exact content. ContentHash covers plan.md +
+// seeds/** (R4.1) so any post-approval edit is detectable as drift (R4.2).
+type PlanApproval struct {
+	Approved    bool   `json:"approved"`
+	ContentHash string `json:"content_hash,omitempty"`
+	ApprovedAt  string `json:"approved_at,omitempty"`
+}
+
+// PlanJSON is the CLI-only approval-state file at docs/plans/<slug>/plan.json
+// (§2). It is the plan analog of spec.json: written only by `plan approve`, never
+// by a session.
+type PlanJSON struct {
+	SchemaVersion int          `json:"schema_version,omitempty"`
+	Name          string       `json:"name"`
+	Approvals     PlanApproval `json:"approvals"`
+}
+
+// Verdict is the structured result a runner session returns for one step (§5.6).
+// Status is "done" or "blocked"; Revision carries the deviation proposal when the
+// session blocks (principle 5 — deviation is an event, not an improvisation).
+type Verdict struct {
+	Status   string `json:"status"`
+	Summary  string `json:"summary"`
+	Revision string `json:"revision,omitempty"`
+}
+
+// Verdict status values.
+const (
+	VerdictDone    = "done"
+	VerdictBlocked = "blocked"
+)
diff --git a/internal/plan/parse.go b/internal/plan/parse.go
new file mode 100644
index 0000000..ed01342
--- /dev/null
+++ b/internal/plan/parse.go
@@ -0,0 +1,258 @@
+package plan
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+	"github.com/protonspy/csdd/internal/textutil"
+)
+
+// featColumns is the fixed column vocabulary of the `## Feats` table (R2.1),
+// matched case-insensitively against the header row. Each data row is read by
+// column name (not position) so a well-formed table survives incidental column
+// reordering, while a missing column is reported precisely.
+var featColumns = []string{"#", "feat", "objective", "depends", "milestone", "(p)", "refs"}
+
+// reWikiRef extracts the target of a [[wiki-page]] token, tolerating an alias or
+// fragment (`[[page|Alias]]`, `[[page#Section]]`) exactly as the wiki extractor
+// does, so a Refs cell and a wiki body resolve links identically.
+var reWikiRef = regexp.MustCompile(`^\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]$`)
+
+// stackRefPrefix is the token prefix that declares a technology dependency in a
+// feat's Refs cell (resolved against the docs/stack.md Decided table by validate).
+const stackRefPrefix = "stack:"
+
+// adrRefPrefix is the token prefix that cites a decision record in a feat's Refs
+// cell (resolved against docs/adr/ by validate — the third ref token beside
+// stack: and [[wiki]]).
+const adrRefPrefix = "adr:"
+
+// Parse reads a plan.md body into a PlanDoc. It never fails: a malformed feat
+// table yields grammar issues carried on the doc (surfaced by ValidatePlan),
+// never a hard error — the same lenient discipline the graph extractors use so a
+// half-authored document still lints instead of crashing. Slug is not set here
+// (the loader supplies it from the directory name).
+func Parse(content string) *PlanDoc {
+	doc := &PlanDoc{}
+	fm := frontmatter.Parse(content)
+	doc.Name = fm.AsString("name", "")
+	doc.Status = fm.AsString("status", "")
+
+	lines := strings.Split(textutil.NormalizeNewlines(content), "\n")
+	section := ""               // lowercased current H2 title
+	var featCols map[string]int // header column → index, nil until the header row
+	var notes []string          // verbatim Executor Notes lines
+
+	for i, raw := range lines {
+		line := strings.TrimRight(raw, " \t")
+		trimmed := strings.TrimSpace(line)
+
+		if strings.HasPrefix(trimmed, "## ") {
+			title := strings.TrimSpace(strings.TrimPrefix(trimmed, "## "))
+			section = strings.ToLower(title)
+			featCols = nil // a new section resets any in-progress feat table
+			continue
+		}
+
+		switch section {
+		case "feats":
+			if !strings.HasPrefix(trimmed, "|") {
+				continue
+			}
+			cells := splitCells(trimmed)
+			if isTableSeparator(cells) {
+				continue
+			}
+			if featCols == nil {
+				featCols = parseFeatHeader(doc, cells, i+1)
+				continue
+			}
+			if f, ok := parseFeatRow(doc, featCols, cells, i+1); ok {
+				doc.Feats = append(doc.Feats, f)
+			}
+		case "quality gates":
+			if g, ok := parseGate(trimmed, i+1); ok {
+				doc.Gates = append(doc.Gates, g)
+			}
+		case "executor notes":
+			notes = append(notes, raw)
+		}
+	}
+
+	doc.ExecutorNotes = strings.TrimSpace(strings.Join(notes, "\n"))
+	return doc
+}
+
+// parseFeatHeader records the index of each recognized column and reports any
+// required column that is absent, so `plan validate` can point at the exact gap.
+func parseFeatHeader(doc *PlanDoc, cells []string, line int) map[string]int {
+	cols := map[string]int{}
+	for idx, c := range cells {
+		cols[strings.ToLower(strings.TrimSpace(c))] = idx
+	}
+	for _, want := range featColumns {
+		if _, ok := cols[want]; !ok {
+			doc.grammar = append(doc.grammar, gramIssue{
+				line: line, msg: "Feats table is missing the '" + want + "' column",
+			})
+		}
+	}
+	return cols
+}
+
+// parseFeatRow builds a Feat from one data row. A row with fewer cells than the
+// header declares is a grammar issue (and still parsed as far as it goes, so a
+// truncated row never silently vanishes). A row whose Feat cell is empty is
+// skipped entirely — it carries no addressable feat.
+func parseFeatRow(doc *PlanDoc, cols map[string]int, cells []string, line int) (Feat, bool) {
+	get := func(name string) string {
+		idx, ok := cols[name]
+		if !ok || idx >= len(cells) {
+			return ""
+		}
+		return strings.TrimSpace(cells[idx])
+	}
+	if len(cells) < len(cols) {
+		doc.grammar = append(doc.grammar, gramIssue{
+			line: line,
+			msg:  "malformed feat row: expected " + itoa(len(cols)) + " columns, got " + itoa(len(cells)),
+		})
+	}
+	slug := get("feat")
+	if slug == "" {
+		return Feat{}, false
+	}
+	f := Feat{
+		Num:       get("#"),
+		Slug:      slug,
+		Objective: get("objective"),
+		Depends:   splitDepends(get("depends")),
+		Milestone: get("milestone"),
+		Parallel:  parseParallel(get("(p)")),
+		Line:      line,
+	}
+	f.WikiRefs, f.StackRefs, f.ADRRefs, f.Refs = tokenizeRefs(get("refs"))
+	return f, true
+}
+
+// parseGate matches a `- <label>: <command>` bullet. Non-matching lines under
+// the section are prose and ignored.
+var reGate = regexp.MustCompile(`^-\s+([^:]+):\s*(.+?)\s*$`)
+
+func parseGate(trimmed string, line int) (Gate, bool) {
+	m := reGate.FindStringSubmatch(trimmed)
+	if m == nil {
+		return Gate{}, false
+	}
+	return Gate{Label: strings.TrimSpace(m[1]), Command: strings.TrimSpace(m[2]), Line: line}, true
+}
+
+// splitDepends splits a Depends cell into verbatim feat-slug tokens. Empty and
+// the "none" placeholders ("-", "—") collapse to no dependencies. Range shorthand
+// is preserved as a single token (never expanded) so validate can report it.
+func splitDepends(cell string) []string {
+	cell = strings.TrimSpace(cell)
+	if cell == "" || cell == "-" || cell == "—" || strings.EqualFold(cell, "none") {
+		return nil
+	}
+	var out []string
+	for _, part := range strings.Split(cell, ",") {
+		if t := strings.TrimSpace(part); t != "" {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// parseParallel reads the (P) column. Any affirmative marker means parallel; the
+// blank and "none" placeholders mean sequential.
+func parseParallel(cell string) bool {
+	switch strings.ToLower(strings.TrimSpace(cell)) {
+	case "p", "(p)", "yes", "y", "x", "true", "✓", "*":
+		return true
+	}
+	return false
+}
+
+// tokenizeRefs splits a Refs cell on whitespace and classifies each token into
+// wiki refs ([[page]]), stack refs (stack:name), and adr refs (adr:slug),
+// returning the three plus the raw token list. An adr: token's slug is captured
+// verbatim — including empty or non-kebab — so validate can report it malformed
+// (R2.2). Unrecognized tokens are kept only in raw (the brief may still show
+// them; validate ignores them).
+func tokenizeRefs(cell string) (wiki, stack, adr, raw []string) {
+	for _, tok := range strings.Fields(cell) {
+		raw = append(raw, tok)
+		if m := reWikiRef.FindStringSubmatch(tok); m != nil {
+			wiki = append(wiki, strings.TrimSpace(m[1]))
+			continue
+		}
+		if strings.HasPrefix(tok, stackRefPrefix) {
+			if name := strings.TrimSpace(strings.TrimPrefix(tok, stackRefPrefix)); name != "" {
+				stack = append(stack, name)
+			}
+			continue
+		}
+		if strings.HasPrefix(tok, adrRefPrefix) {
+			adr = append(adr, strings.TrimSpace(strings.TrimPrefix(tok, adrRefPrefix)))
+		}
+	}
+	return wiki, stack, adr, raw
+}
+
+// --- shared parsing helpers (kept local so the package has no graph dependency) ---
+
+// splitCells splits a markdown table row into trimmed cell values (leading and
+// trailing pipe removed), mirroring internal/graph's helper of the same name.
+func splitCells(row string) []string {
+	row = strings.TrimSpace(row)
+	row = strings.TrimPrefix(row, "|")
+	row = strings.TrimSuffix(row, "|")
+	parts := strings.Split(row, "|")
+	for i := range parts {
+		parts[i] = strings.TrimSpace(parts[i])
+	}
+	return parts
+}
+
+// isTableSeparator reports whether a table row is the `|---|---|` divider.
+func isTableSeparator(cells []string) bool {
+	if len(cells) == 0 {
+		return false
+	}
+	for _, c := range cells {
+		c = strings.TrimSpace(c)
+		if c == "" {
+			continue
+		}
+		if strings.Trim(c, "-: ") != "" {
+			return false
+		}
+	}
+	return true
+}
+
+// itoa is a tiny int→string used in grammar messages (avoids importing strconv
+// for one call and keeps message construction allocation-light).
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var b [20]byte
+	i := len(b)
+	for n > 0 {
+		i--
+		b[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		b[i] = '-'
+	}
+	return string(b[i:])
+}
diff --git a/internal/plan/parse_test.go b/internal/plan/parse_test.go
new file mode 100644
index 0000000..200c276
--- /dev/null
+++ b/internal/plan/parse_test.go
@@ -0,0 +1,250 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+const goodPlan = `---
+name: photo-sharing
+status: draft
+---
+
+# Photo Sharing — Plan
+
+Some prose the parser ignores.
+
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload-pipeline | Ingest and store photos | — | M1 |  | stack:go [[storage-design]] |
+| 2 | thumbnailer | Generate thumbnails | upload-pipeline | M1 | P | stack:libvips |
+| 3 | share-links | Signed share URLs | upload-pipeline, thumbnailer | M2 | yes | [[share-security]] [[url-signing]] |
+
+## Quality Gates
+
+- verify: make check
+- e2e: go test ./e2e/...
+
+## Executor Notes
+
+Run gofmt before committing.
+Never touch generated files.
+
+## Something Unknown
+
+Ignored entirely.
+`
+
+func TestParseFrontmatterAndSections(t *testing.T) {
+	doc := Parse(goodPlan)
+	if doc.Name != "photo-sharing" {
+		t.Errorf("Name = %q, want photo-sharing", doc.Name)
+	}
+	if doc.Status != StatusDraft {
+		t.Errorf("Status = %q, want draft", doc.Status)
+	}
+	if len(doc.grammar) != 0 {
+		t.Errorf("expected no grammar issues, got %v", doc.grammar)
+	}
+	wantNotes := "Run gofmt before committing.\nNever touch generated files."
+	if doc.ExecutorNotes != wantNotes {
+		t.Errorf("ExecutorNotes = %q, want %q", doc.ExecutorNotes, wantNotes)
+	}
+}
+
+func TestParseFeats(t *testing.T) {
+	doc := Parse(goodPlan)
+	if len(doc.Feats) != 3 {
+		t.Fatalf("got %d feats, want 3", len(doc.Feats))
+	}
+
+	f0 := doc.Feats[0]
+	if f0.Num != "1" || f0.Slug != "upload-pipeline" || f0.Objective != "Ingest and store photos" {
+		t.Errorf("feat 0 = %+v", f0)
+	}
+	if len(f0.Depends) != 0 {
+		t.Errorf("feat 0 Depends = %v, want none (— placeholder)", f0.Depends)
+	}
+	if f0.Parallel {
+		t.Errorf("feat 0 should not be parallel")
+	}
+	if !reflect.DeepEqual(f0.StackRefs, []string{"go"}) {
+		t.Errorf("feat 0 StackRefs = %v, want [go]", f0.StackRefs)
+	}
+	if !reflect.DeepEqual(f0.WikiRefs, []string{"storage-design"}) {
+		t.Errorf("feat 0 WikiRefs = %v, want [storage-design]", f0.WikiRefs)
+	}
+
+	f1 := doc.Feats[1]
+	if !f1.Parallel {
+		t.Errorf("feat 1 (P)=P should be parallel")
+	}
+	if !reflect.DeepEqual(f1.Depends, []string{"upload-pipeline"}) {
+		t.Errorf("feat 1 Depends = %v", f1.Depends)
+	}
+
+	f2 := doc.Feats[2]
+	if !reflect.DeepEqual(f2.Depends, []string{"upload-pipeline", "thumbnailer"}) {
+		t.Errorf("feat 2 Depends = %v, want two", f2.Depends)
+	}
+	if !f2.Parallel {
+		t.Errorf("feat 2 (P)=yes should be parallel")
+	}
+	if !reflect.DeepEqual(f2.WikiRefs, []string{"share-security", "url-signing"}) {
+		t.Errorf("feat 2 WikiRefs = %v", f2.WikiRefs)
+	}
+	if f2.Line != 16 {
+		t.Errorf("feat 2 Line = %d, want 16", f2.Line)
+	}
+}
+
+func TestParseGates(t *testing.T) {
+	doc := Parse(goodPlan)
+	want := []Gate{
+		{Label: "verify", Command: "make check", Line: 20},
+		{Label: "e2e", Command: "go test ./e2e/...", Line: 21},
+	}
+	if len(doc.Gates) != len(want) {
+		t.Fatalf("got %d gates, want %d: %+v", len(doc.Gates), len(want), doc.Gates)
+	}
+	for i := range want {
+		if doc.Gates[i].Label != want[i].Label || doc.Gates[i].Command != want[i].Command {
+			t.Errorf("gate %d = %+v, want %+v", i, doc.Gates[i], want[i])
+		}
+	}
+}
+
+func TestParseWikiRefAlias(t *testing.T) {
+	wiki, stack, adr, raw := tokenizeRefs("[[page|Alias]] [[other#Section]] stack:chi adr:pick-x bare-token")
+	if !reflect.DeepEqual(wiki, []string{"page", "other"}) {
+		t.Errorf("wiki = %v, want [page other]", wiki)
+	}
+	if !reflect.DeepEqual(stack, []string{"chi"}) {
+		t.Errorf("stack = %v, want [chi]", stack)
+	}
+	if !reflect.DeepEqual(adr, []string{"pick-x"}) {
+		t.Errorf("adr = %v, want [pick-x]", adr)
+	}
+	if len(raw) != 5 {
+		t.Errorf("raw = %v, want 5 tokens", raw)
+	}
+}
+
+// A bare "adr:" with no slug is captured as an empty-string ref so validate can
+// report it malformed (R2.2), rather than being silently dropped.
+func TestParseADRRefEmptySlugCaptured(t *testing.T) {
+	_, _, adr, _ := tokenizeRefs("adr: adr:good-one")
+	if !reflect.DeepEqual(adr, []string{"", "good-one"}) {
+		t.Errorf("adr = %q, want [\"\" \"good-one\"]", adr)
+	}
+}
+
+func TestParseMalformedFeatRow(t *testing.T) {
+	// A row missing the Refs cell (only 6 of 7 columns) is a grammar issue but
+	// the feat is still captured.
+	src := `## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | lonely | too few cells | — | M1 | |
+`
+	doc := Parse(src)
+	if len(doc.Feats) != 1 {
+		t.Fatalf("expected the truncated feat to still be captured, got %d", len(doc.Feats))
+	}
+	if len(doc.grammar) == 0 {
+		t.Errorf("expected a grammar issue for the short row")
+	}
+}
+
+func TestParseMissingColumn(t *testing.T) {
+	src := `## Feats
+
+| # | Feat | Objective | Depends | Milestone | Refs |
+|---|------|-----------|---------|-----------|------|
+| 1 | thing | do it | — | M1 | |
+`
+	doc := Parse(src)
+	var found bool
+	for _, g := range doc.grammar {
+		if g.msg == "Feats table is missing the '(p)' column" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected a missing-(p)-column grammar issue, got %v", doc.grammar)
+	}
+}
+
+func TestParseEmpty(t *testing.T) {
+	doc := Parse("")
+	if doc.Name != "" || len(doc.Feats) != 0 || len(doc.Gates) != 0 {
+		t.Errorf("empty content should yield an empty doc, got %+v", doc)
+	}
+}
+
+func TestHashPlanDeterministicAndSensitive(t *testing.T) {
+	dir := t.TempDir()
+	writeFile(t, filepath.Join(dir, "plan.md"), goodPlan)
+	writeFile(t, filepath.Join(dir, "seeds", "upload-pipeline", "requirements.md"), "# seed\n")
+
+	h1, err := HashPlan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h2, err := HashPlan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h1 != h2 {
+		t.Errorf("hash not deterministic: %s vs %s", h1, h2)
+	}
+
+	// Editing a seed changes the hash.
+	writeFile(t, filepath.Join(dir, "seeds", "upload-pipeline", "requirements.md"), "# seed edited\n")
+	h3, err := HashPlan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h3 == h1 {
+		t.Errorf("hash should change when a seed changes")
+	}
+
+	// A CRLF re-checkout of plan.md must NOT look like drift (normalized hashing).
+	writeFile(t, filepath.Join(dir, "seeds", "upload-pipeline", "requirements.md"), "# seed\n")
+	writeFile(t, filepath.Join(dir, "plan.md"), replaceLF(goodPlan))
+	h4, err := HashPlan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h4 != h1 {
+		t.Errorf("CRLF plan.md must hash identically to LF; got %s vs %s", h4, h1)
+	}
+}
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// replaceLF converts LF to CRLF to exercise line-ending-insensitive hashing.
+func replaceLF(s string) string {
+	out := make([]byte, 0, len(s)+len(s)/20)
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\n' {
+			out = append(out, '\r', '\n')
+			continue
+		}
+		out = append(out, s[i])
+	}
+	return string(out)
+}
diff --git a/internal/plan/planjson.go b/internal/plan/planjson.go
new file mode 100644
index 0000000..301e934
--- /dev/null
+++ b/internal/plan/planjson.go
@@ -0,0 +1,42 @@
+package plan
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// LoadPlanJSON reads docs/plans/<slug>/plan.json. A missing file is not an error
+// (a plan is unapproved until `plan approve` writes it): it returns exists=false
+// with a zero-value doc so callers branch on approval without special-casing I/O.
+func LoadPlanJSON(dir string) (PlanJSON, bool, error) {
+	var pj PlanJSON
+	data, err := os.ReadFile(planJSONPath(dir))
+	if os.IsNotExist(err) {
+		return pj, false, nil
+	}
+	if err != nil {
+		return pj, false, err
+	}
+	if err := json.Unmarshal(data, &pj); err != nil {
+		return pj, true, fmt.Errorf("parse %s: %w", planJSONPath(dir), err)
+	}
+	return pj, true, nil
+}
+
+// SavePlanJSON writes plan.json atomically, stamping the schema version. It is
+// the plan analog of saveSpecJSON — the only writer of approval state, invoked
+// solely by `plan approve` (design principle 3).
+func SavePlanJSON(dir string, pj PlanJSON) error {
+	if pj.SchemaVersion == 0 {
+		pj.SchemaVersion = planSchemaVersion
+	}
+	b, err := json.MarshalIndent(pj, "", "  ")
+	if err != nil {
+		return err
+	}
+	b = append(b, '\n')
+	return workspace.AtomicWrite(planJSONPath(dir), b, 0o644)
+}
diff --git a/internal/plan/runner.go b/internal/plan/runner.go
new file mode 100644
index 0000000..1af3f2a
--- /dev/null
+++ b/internal/plan/runner.go
@@ -0,0 +1,437 @@
+package plan
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// SessionMode is the permission posture a runner session runs under. It is part
+// of the exported Hooks contract so external drivers (and tests) can construct a
+// Session stub.
+type SessionMode int
+
+const (
+	// ModeSupervised passes --permission-mode acceptEdits: edits apply but the
+	// human is in the loop for anything riskier.
+	ModeSupervised SessionMode = iota
+	// ModeAutonomous passes --dangerously-skip-permissions; only ever selected
+	// after `sandbox doctor` proves isolation (principle 7).
+	ModeAutonomous
+)
+
+func (m SessionMode) String() string {
+	if m == ModeAutonomous {
+		return "autonomous"
+	}
+	return "supervised"
+}
+
+// forbiddenChangeRoots are the workspace subtrees a session must never modify
+// (R9.6). The runner owns the plan tree, the graph, and the state dir; a session
+// touching any of them is a hard step failure, verified from the git working tree
+// AFTER the session and BEFORE the runner writes its own journal/markers.
+var forbiddenChangeRoots = []string{".csdd/", "docs/graph/", "docs/plans/"}
+
+// Hooks are the runner's seams onto the outside world. Every field has a real
+// default (installed by Run); tests inject stubs so the whole loop — verdict
+// parsing, gate pipeline, retries, block markers, path audit, journal — runs with
+// no `claude`, `git`, or subprocess at all.
+type Hooks struct {
+	// Session runs one claude session for a step and returns its parsed verdict.
+	Session func(step Step, brief string, mode SessionMode, budgetUSD float64) (Verdict, error)
+	// CSDD runs `csdd <args...>` in root, returning success and combined output.
+	CSDD func(root string, args ...string) (bool, string)
+	// Gate runs a shell gate command in root, returning success and output.
+	Gate func(root, command string) (bool, string)
+	// ChangedPaths returns the workspace-relative paths dirty in the working tree.
+	ChangedPaths func(root string) ([]string, error)
+	// Commit stages paths and commits them with msg.
+	Commit func(root, msg string, paths []string) error
+	// Doctor proves sandbox isolation (autonomous mode only).
+	Doctor func() SandboxReport
+	// ClaudeAvailable reports whether the `claude` CLI is on PATH.
+	ClaudeAvailable func() bool
+	// Now returns the current time (journal timestamps; injected for determinism).
+	Now func() time.Time
+}
+
+// RunOptions configures a `csdd plan run` invocation.
+type RunOptions struct {
+	Root          string
+	Slug          string
+	Autonomous    bool
+	SessionBudget float64 // per-session --max-budget-usd; 0 = no cap (Claude account limits)
+	MaxIterations int     // default 25
+	MaxRetries    int     // default 2
+	Out           io.Writer
+	Hooks         Hooks
+}
+
+// Run outcomes, chosen so the CLI can surface them as distinct exit codes.
+const (
+	OutcomeComplete = 0 // every feat is done
+	OutcomeNothing  = 4 // nothing unblocked (mirrors the sequencer)
+	OutcomeDrift    = 5 // plan drifted mid-run
+	OutcomeCapped   = 6 // hit the iteration cap without finishing
+)
+
+// RunSummary is the totals reported on exit (R9.7).
+type RunSummary struct {
+	Steps     int
+	Retries   int
+	Blocks    int
+	Completed bool
+	Reason    string
+	Outcome   int
+}
+
+// Run drives the plan loop (R9): preflight, then repeatedly drift-check → next →
+// brief → session → audit → gates → advance/retry/block → journal, until the plan
+// completes, nothing is unblocked, drift is detected, or the iteration cap is hit.
+func Run(opts RunOptions) (RunSummary, error) {
+	fillRunDefaults(&opts)
+	h := opts.Hooks
+	out := opts.Out
+	logf := func(format string, a ...any) { fmt.Fprintf(out, format+"\n", a...) }
+
+	doc, err := Load(opts.Root, opts.Slug)
+	if err != nil {
+		return RunSummary{}, err
+	}
+
+	// Preflight (R9.1): approval + drift, claude present, mode selection.
+	approved, drift, err := IsApproved(opts.Root, opts.Slug)
+	if err != nil {
+		return RunSummary{}, err
+	}
+	if !approved {
+		return RunSummary{}, fmt.Errorf("plan %q is not approved; run `csdd plan approve %s` first", opts.Slug, opts.Slug)
+	}
+	if drift {
+		return RunSummary{}, fmt.Errorf("plan %q has drifted since approval; re-approve before running", opts.Slug)
+	}
+	if !h.ClaudeAvailable() {
+		return RunSummary{}, fmt.Errorf("the `claude` CLI is not available on PATH; the runner needs it to spawn sessions")
+	}
+	mode := ModeSupervised
+	if opts.Autonomous {
+		rep := h.Doctor()
+		if !rep.OK {
+			return RunSummary{}, fmt.Errorf("--autonomous requires a verified sandbox; `sandbox doctor` failed — refusing to pass --dangerously-skip-permissions")
+		}
+		mode = ModeAutonomous
+	}
+	logf("plan run %s (%s mode, %s, max %d iterations)", opts.Slug, mode, budgetLabel(opts.SessionBudget), opts.MaxIterations)
+
+	var sum RunSummary
+	for iter := 0; iter < opts.MaxIterations; iter++ {
+		// R9.5: re-check drift every iteration; stop autonomy immediately on mismatch.
+		if _, drift, err := IsApproved(opts.Root, opts.Slug); err != nil {
+			return sum, err
+		} else if drift {
+			sum.Reason = "stopped: plan drifted mid-run (re-approve to continue)"
+			sum.Outcome = OutcomeDrift
+			logf(sum.Reason)
+			return summarize(out, sum), nil
+		}
+
+		step, outcome, err := Next(opts.Root, doc, true)
+		if err != nil {
+			return sum, err
+		}
+		switch outcome {
+		case SeqComplete:
+			sum.Completed = true
+			sum.Outcome = OutcomeComplete
+			sum.Reason = "plan complete: every feat is done"
+			logf(sum.Reason)
+			return summarize(out, sum), nil
+		case SeqNothing:
+			sum.Outcome = OutcomeNothing
+			sum.Reason = "nothing unblocked: remaining feats are blocked or waiting on blocked deps"
+			logf(sum.Reason)
+			return summarize(out, sum), nil
+		case SeqNotReady:
+			sum.Outcome = OutcomeDrift
+			sum.Reason = "plan not approved or drifted"
+			logf(sum.Reason)
+			return summarize(out, sum), nil
+		}
+
+		logf("→ %s / %s", step.Feat, step.Step)
+		advanced := executeStep(opts, doc, step, mode, &sum)
+		if !advanced {
+			sum.Blocks++
+		}
+	}
+	sum.Outcome = OutcomeCapped
+	sum.Reason = fmt.Sprintf("reached the iteration cap (%d)", opts.MaxIterations)
+	logf(sum.Reason)
+	return summarize(out, sum), nil
+}
+
+// executeStep runs one step with retries (R9.2/R9.3). It returns whether the step
+// advanced (green) or was blocked (retries exhausted, forbidden change, or a
+// blocked verdict). A blocked feat gets a marker so the sequencer skips it and
+// the loop continues with other unblocked feats (R9.4).
+func executeStep(opts RunOptions, doc *PlanDoc, step Step, mode SessionMode, sum *RunSummary) bool {
+	h := opts.Hooks
+	out := opts.Out
+	logf := func(format string, a ...any) { fmt.Fprintf(out, format+"\n", a...) }
+
+	baseBrief, err := Brief(opts.Root, doc, step)
+	if err != nil {
+		logf("  brief error: %v", err)
+		block(opts, step, "brief assembly failed: "+err.Error())
+		return false
+	}
+
+	// Scaffold a spec before its requirements step (R8; runner-owned).
+	if step.Step == StepSpecRequirements {
+		specDir := filepath.Join(opts.Root, "specs", step.Feat)
+		if _, statErr := os.Stat(specDir); statErr != nil {
+			if ok, o := h.CSDD(opts.Root, "plan", "generate", opts.Slug, step.Feat, "--require-approved"); !ok {
+				block(opts, step, "scaffold (plan generate) failed: "+firstLine(o))
+				return false
+			}
+		}
+	}
+
+	var lastFailure string
+	for attempt := 0; attempt <= opts.MaxRetries; attempt++ {
+		if attempt > 0 {
+			sum.Retries++
+			logf("  retry %d/%d", attempt, opts.MaxRetries)
+		}
+		brief := baseBrief
+		if lastFailure != "" {
+			brief += "\n\n## Previous attempt failed — fix this\n\n" + lastFailure + "\n"
+		}
+
+		verdict, err := h.Session(step, brief, mode, opts.SessionBudget)
+		if err != nil {
+			lastFailure = "session error: " + err.Error()
+			continue
+		}
+		if verdict.Status == VerdictBlocked {
+			// A structured deviation: journal it and stop this feat (R9.4).
+			journalDeviation(opts, step, verdict)
+			block(opts, step, deviationReason(verdict))
+			logf("  blocked by session: %s", firstLine(verdict.Summary))
+			return false
+		}
+
+		// R9.6 path audit: the session must not have touched the plan/graph/state.
+		if bad := auditForbidden(opts); bad != "" {
+			lastFailure = "modified a forbidden path (" + bad + "); the runner owns the plan, graph, and state — revert it"
+			logf("  hard failure: %s", lastFailure)
+			continue
+		}
+
+		// Gates.
+		if ok, output := runGates(opts, step); !ok {
+			lastFailure = "gate failed:\n" + output
+			logf("  gate failed")
+			continue
+		}
+
+		// Green: the runner performs the advance (approval or commit), never the session.
+		if err := advance(opts, step); err != nil {
+			lastFailure = "advance failed: " + err.Error()
+			logf("  advance failed: %v", err)
+			continue
+		}
+		sum.Steps++
+		journal(opts, step, "done")
+		logf("  ✓ %s", step.Step)
+		return true
+	}
+
+	// Retries exhausted.
+	journal(opts, step, "blocked")
+	block(opts, step, "gates failed after "+itoa(opts.MaxRetries)+" retries: "+firstLine(lastFailure))
+	logf("  ✗ blocked after retries")
+	return false
+}
+
+// runGates runs the gates for a step: the spec validator for a spec phase, or the
+// plan's Quality Gates plus graph traceability for an implementation task (R9.2).
+func runGates(opts RunOptions, step Step) (bool, string) {
+	h := opts.Hooks
+	if _, ok := specPhaseOf(step.Step); ok {
+		return h.CSDD(opts.Root, "spec", "validate", step.Feat)
+	}
+	// Implementation task: plan Quality Gates first, then graph analyze.
+	doc, err := Load(opts.Root, opts.Slug)
+	if err != nil {
+		return false, err.Error()
+	}
+	for _, g := range doc.Gates {
+		if ok, o := h.Gate(opts.Root, g.Command); !ok {
+			return false, fmt.Sprintf("[%s] %s\n%s", g.Label, g.Command, o)
+		}
+	}
+	if ok, o := h.CSDD(opts.Root, "graph", "analyze", "--strict"); !ok {
+		return false, "graph analyze --strict:\n" + o
+	}
+	return true, ""
+}
+
+// advance performs the green-path mutation the runner (never the session) owns:
+// approve the spec phase, or commit the implementation scoped to the session's
+// changed paths (R9.2).
+func advance(opts RunOptions, step Step) error {
+	h := opts.Hooks
+	if phase, ok := specPhaseOf(step.Step); ok {
+		if approved, o := h.CSDD(opts.Root, "spec", "approve", step.Feat, "--phase", phase); !approved {
+			return fmt.Errorf("spec approve %s --phase %s: %s", step.Feat, phase, firstLine(o))
+		}
+		return nil
+	}
+	changed, err := h.ChangedPaths(opts.Root)
+	if err != nil {
+		return err
+	}
+	if len(changed) == 0 {
+		return fmt.Errorf("no changes to commit for %s", step.Step)
+	}
+	return h.Commit(opts.Root, fmt.Sprintf("feat(%s): %s", step.Feat, step.Step), changed)
+}
+
+// auditForbidden returns the first changed path under a forbidden root, or "".
+func auditForbidden(opts RunOptions) string {
+	changed, err := opts.Hooks.ChangedPaths(opts.Root)
+	if err != nil {
+		return "" // a git error is not a forbidden-change signal
+	}
+	for _, p := range changed {
+		p = filepath.ToSlash(p)
+		for _, root := range forbiddenChangeRoots {
+			if strings.HasPrefix(p, root) {
+				return p
+			}
+		}
+	}
+	return ""
+}
+
+// specPhaseOf maps a spec-phase step to its phase name (requirements/design/
+// tasks) and reports whether the step is a spec phase.
+func specPhaseOf(step string) (string, bool) {
+	switch step {
+	case StepSpecRequirements:
+		return "requirements", true
+	case StepSpecDesign:
+		return "design", true
+	case StepSpecTasks:
+		return "tasks", true
+	}
+	return "", false
+}
+
+// --- journal + block markers ------------------------------------------------
+
+// journal appends one mechanical line to the run journal (log.md): the
+// `## [YYYY-MM-DD] <step> | <feat> | <outcome>` format (§5.6). CLI-only writer.
+func journal(opts RunOptions, step Step, outcome string) {
+	date := opts.Hooks.Now().UTC().Format("2006-01-02")
+	line := fmt.Sprintf("## [%s] %s | %s | %s\n", date, step.Step, step.Feat, outcome)
+	appendFile(filepath.Join(Dir(opts.Root, opts.Slug), "log.md"), line)
+}
+
+// journalDeviation appends the blocked entry plus the session's revision proposal,
+// so the human can fold it back in via the Revise workflow (principle 5).
+func journalDeviation(opts RunOptions, step Step, v Verdict) {
+	date := opts.Hooks.Now().UTC().Format("2006-01-02")
+	var b strings.Builder
+	fmt.Fprintf(&b, "## [%s] %s | %s | %s\n", date, step.Step, step.Feat, VerdictBlocked)
+	if v.Summary != "" {
+		fmt.Fprintf(&b, "- reason: %s\n", oneLine(v.Summary))
+	}
+	if v.Revision != "" {
+		fmt.Fprintf(&b, "- revision: %s\n", oneLine(v.Revision))
+	}
+	appendFile(filepath.Join(Dir(opts.Root, opts.Slug), "log.md"), b.String())
+}
+
+// block writes a block marker so the sequencer skips the feat and the loop
+// continues with others (R9.4). Markers live under the transient state dir.
+func block(opts RunOptions, step Step, reason string) {
+	path := filepath.Join(stateDir(opts.Root, opts.Slug), "blocked", step.Feat)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err == nil {
+		_ = os.WriteFile(path, []byte(reason+"\n"), 0o644)
+	}
+}
+
+func deviationReason(v Verdict) string {
+	if v.Summary != "" {
+		return "session blocked: " + oneLine(v.Summary)
+	}
+	return "session returned a blocked verdict"
+}
+
+// --- small helpers ----------------------------------------------------------
+
+func fillRunDefaults(opts *RunOptions) {
+	// SessionBudget <= 0 means "no per-session cap" — the session runs under the
+	// Claude account's own limits (the default). A positive value pins
+	// --max-budget-usd for a tighter ceiling.
+	if opts.SessionBudget < 0 {
+		opts.SessionBudget = 0
+	}
+	if opts.MaxIterations <= 0 {
+		opts.MaxIterations = 25
+	}
+	if opts.MaxRetries < 0 {
+		opts.MaxRetries = 2
+	}
+	if opts.MaxRetries == 0 {
+		opts.MaxRetries = 2
+	}
+	if opts.Out == nil {
+		opts.Out = io.Discard
+	}
+	installRealHooks(&opts.Hooks)
+}
+
+func summarize(out io.Writer, sum RunSummary) RunSummary {
+	fmt.Fprintf(out, "totals: %d steps, %d retries, %d blocks\n", sum.Steps, sum.Retries, sum.Blocks)
+	return sum
+}
+
+func appendFile(path, content string) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return
+	}
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		return
+	}
+	defer func() { _ = f.Close() }()
+	_, _ = f.WriteString(content)
+}
+
+func firstLine(s string) string {
+	s = strings.TrimSpace(s)
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+	return s
+}
+
+func oneLine(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
+
+// budgetLabel describes the per-session budget for the run log: the Claude
+// account's own limit when unset, else the explicit USD cap.
+func budgetLabel(budgetUSD float64) string {
+	if budgetUSD <= 0 {
+		return "budget: account limit"
+	}
+	return fmt.Sprintf("budget: $%.2f/session", budgetUSD)
+}
diff --git a/internal/plan/runner_exec.go b/internal/plan/runner_exec.go
new file mode 100644
index 0000000..26e428a
--- /dev/null
+++ b/internal/plan/runner_exec.go
@@ -0,0 +1,210 @@
+package plan
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"regexp"
+	"runtime"
+	"strings"
+	"time"
+)
+
+// installRealHooks fills any nil hook with its production implementation, so
+// tests can inject just the seams they care about and get real behavior for the
+// rest (in practice tests inject them all). The real hooks shell out to `claude`,
+// `csdd`, `git`, and the shell — the runner's process performs every gate and
+// approval; the session only authors (principle 3).
+func installRealHooks(h *Hooks) {
+	if h.Now == nil {
+		h.Now = time.Now
+	}
+	if h.ClaudeAvailable == nil {
+		h.ClaudeAvailable = func() bool {
+			_, err := exec.LookPath("claude")
+			return err == nil
+		}
+	}
+	if h.Doctor == nil {
+		h.Doctor = func() SandboxReport { return Doctor(DoctorProbes{}) }
+	}
+	if h.Session == nil {
+		h.Session = execClaudeSession
+	}
+	if h.CSDD == nil {
+		h.CSDD = execCSDD
+	}
+	if h.Gate == nil {
+		h.Gate = execShellGate
+	}
+	if h.ChangedPaths == nil {
+		h.ChangedPaths = gitChangedPaths
+	}
+	if h.Commit == nil {
+		h.Commit = gitCommit
+	}
+}
+
+// verdictSchema is the JSON schema the session must satisfy — the runner's
+// contract with the model (§5.6). Pinned here alongside the flags in one place.
+const verdictSchema = `{"type":"object","required":["status","summary"],` +
+	`"properties":{"status":{"enum":["done","blocked"]},"summary":{"type":"string"},"revision":{"type":"string"}}}`
+
+// claudeFlags are every `claude` flag the runner relies on, pinned in one place so
+// a version drift is a single, reviewable edit (risk register §8).
+var claudeFlags = struct {
+	print, outputFormat, jsonSchema, maxBudget, permissionMode, bypass string
+}{
+	print:          "-p",
+	outputFormat:   "--output-format",
+	jsonSchema:     "--json-schema",
+	maxBudget:      "--max-budget-usd",
+	permissionMode: "--permission-mode",
+	bypass:         "--dangerously-skip-permissions",
+}
+
+// execClaudeSession spawns a fresh `claude -p` session for a step and parses its
+// verdict from the JSON output envelope.
+func execClaudeSession(step Step, brief string, mode SessionMode, budgetUSD float64) (Verdict, error) {
+	args := []string{
+		claudeFlags.print, brief,
+		claudeFlags.outputFormat, "json",
+		claudeFlags.jsonSchema, verdictSchema,
+	}
+	// A positive budget pins --max-budget-usd; the default (<=0) leaves it off so
+	// the session runs under the Claude account's own limits.
+	if budgetUSD > 0 {
+		args = append(args, claudeFlags.maxBudget, fmt.Sprintf("%.2f", budgetUSD))
+	}
+	if mode == ModeAutonomous {
+		args = append(args, claudeFlags.bypass)
+	} else {
+		args = append(args, claudeFlags.permissionMode, "acceptEdits")
+	}
+	cmd := exec.Command("claude", args...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return Verdict{}, fmt.Errorf("claude session failed: %v: %s", err, strings.TrimSpace(stderr.String()))
+	}
+	return parseVerdict(stdout.Bytes())
+}
+
+var reJSONObject = regexp.MustCompile(`(?s)\{.*\}`)
+
+// parseVerdict extracts the Verdict from a claude JSON output. It first tries the
+// `result` field of the standard envelope, then falls back to the last JSON object
+// carrying a "status" field, so a plain-JSON or enveloped response both parse.
+func parseVerdict(output []byte) (Verdict, error) {
+	// Direct verdict object.
+	var v Verdict
+	if json.Unmarshal(output, &v) == nil && v.Status != "" {
+		return normalizeVerdict(v)
+	}
+	// Standard `--output-format json` envelope: {"result":"<text or json>", ...}.
+	var env struct {
+		Result string `json:"result"`
+	}
+	if json.Unmarshal(output, &env) == nil && env.Result != "" {
+		if json.Unmarshal([]byte(env.Result), &v) == nil && v.Status != "" {
+			return normalizeVerdict(v)
+		}
+		if m := reJSONObject.FindString(env.Result); m != "" {
+			if json.Unmarshal([]byte(m), &v) == nil && v.Status != "" {
+				return normalizeVerdict(v)
+			}
+		}
+	}
+	// Last-ditch: any embedded JSON object with a status.
+	if m := reJSONObject.FindString(string(output)); m != "" {
+		if json.Unmarshal([]byte(m), &v) == nil && v.Status != "" {
+			return normalizeVerdict(v)
+		}
+	}
+	return Verdict{}, fmt.Errorf("could not parse a verdict from the session output")
+}
+
+func normalizeVerdict(v Verdict) (Verdict, error) {
+	v.Status = strings.ToLower(strings.TrimSpace(v.Status))
+	if v.Status != VerdictDone && v.Status != VerdictBlocked {
+		return Verdict{}, fmt.Errorf("invalid verdict status %q (want done|blocked)", v.Status)
+	}
+	return v, nil
+}
+
+// csddBinary is the path to the csdd binary the runner shells out to. It prefers
+// the currently-running executable so `plan run` uses the same version for the
+// gates and approvals it drives.
+func csddBinary() string {
+	if p, err := os.Executable(); err == nil {
+		return p
+	}
+	return "csdd"
+}
+
+// execCSDD runs a csdd subcommand in root, returning success and combined output.
+func execCSDD(root string, args ...string) (bool, string) {
+	full := append([]string{"--root", root}, args...)
+	cmd := exec.Command(csddBinary(), full...)
+	out, err := cmd.CombinedOutput()
+	return err == nil, string(out)
+}
+
+// execShellGate runs a gate command through the platform shell in root.
+func execShellGate(root, command string) (bool, string) {
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("cmd", "/c", command)
+	} else {
+		cmd = exec.Command("sh", "-c", command)
+	}
+	cmd.Dir = root
+	out, err := cmd.CombinedOutput()
+	return err == nil, string(out)
+}
+
+// gitChangedPaths returns the workspace-relative paths dirty in the working tree
+// (staged, unstaged, and untracked), via `git status --porcelain`.
+func gitChangedPaths(root string) ([]string, error) {
+	cmd := exec.Command("git", "status", "--porcelain")
+	cmd.Dir = root
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, err
+	}
+	var paths []string
+	for _, line := range strings.Split(string(out), "\n") {
+		if len(line) < 4 {
+			continue
+		}
+		// Format: "XY <path>" (or "XY <old> -> <new>" for renames).
+		p := strings.TrimSpace(line[3:])
+		if i := strings.Index(p, " -> "); i >= 0 {
+			p = p[i+4:]
+		}
+		paths = append(paths, strings.Trim(p, `"`))
+	}
+	return paths, nil
+}
+
+// gitCommit stages the given paths and commits them with msg.
+func gitCommit(root, msg string, paths []string) error {
+	addArgs := append([]string{"add", "--"}, paths...)
+	if out, err := runGit(root, addArgs...); err != nil {
+		return fmt.Errorf("git add: %v: %s", err, out)
+	}
+	if out, err := runGit(root, "commit", "-m", msg); err != nil {
+		return fmt.Errorf("git commit: %v: %s", err, out)
+	}
+	return nil
+}
+
+func runGit(root string, args ...string) (string, error) {
+	cmd := exec.Command("git", args...)
+	cmd.Dir = root
+	out, err := cmd.CombinedOutput()
+	return string(out), err
+}
diff --git a/internal/plan/runner_test.go b/internal/plan/runner_test.go
new file mode 100644
index 0000000..eca69ee
--- /dev/null
+++ b/internal/plan/runner_test.go
@@ -0,0 +1,296 @@
+package plan
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+const runnerPlan = `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | |
+| 2 | b | B | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+var allApproved = map[string]bool{"requirements": true, "design": true, "tasks": true}
+
+// approvedRunnerWorkspace lays down the plan, approves it, and returns the root.
+func approvedRunnerWorkspace(t *testing.T) string {
+	t.Helper()
+	root := setupWorkspace(t, "p", runnerPlan)
+	doc, err := Load(root, "p")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := ApprovePlan(root, doc, time.Unix(0, 0)); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+// fixedNow is a deterministic clock for journal timestamps.
+func fixedNow() time.Time { return time.Date(2026, 7, 7, 0, 0, 0, 0, time.UTC) }
+
+// baseHooks returns hooks that always succeed and change nothing, so the loop
+// would run to the iteration cap unless a test's stubs advance state.
+func baseHooks() Hooks {
+	return Hooks{
+		Session:         func(Step, string, SessionMode, float64) (Verdict, error) { return Verdict{Status: VerdictDone}, nil },
+		CSDD:            func(string, ...string) (bool, string) { return true, "" },
+		Gate:            func(string, string) (bool, string) { return true, "" },
+		ChangedPaths:    func(string) ([]string, error) { return []string{"specs/a/foo.go"}, nil },
+		Commit:          func(string, string, []string) error { return nil },
+		Doctor:          func() SandboxReport { return SandboxReport{OK: true} },
+		ClaudeAvailable: func() bool { return true },
+		Now:             fixedNow,
+	}
+}
+
+func TestParseVerdict(t *testing.T) {
+	cases := []struct {
+		name    string
+		in      string
+		want    string
+		wantErr bool
+	}{
+		{"plain", `{"status":"done","summary":"ok"}`, VerdictDone, false},
+		{"blocked", `{"status":"blocked","summary":"stuck","revision":"split it"}`, VerdictBlocked, false},
+		{"envelope", `{"type":"result","result":"{\"status\":\"done\",\"summary\":\"ok\"}"}`, VerdictDone, false},
+		{"envelope prose+json", `{"result":"Here is my verdict: {\"status\":\"blocked\",\"summary\":\"x\"}"}`, VerdictBlocked, false},
+		{"uppercase", `{"status":"DONE","summary":"ok"}`, VerdictDone, false},
+		{"garbage", `not json at all`, "", true},
+		{"bad status", `{"status":"maybe","summary":"?"}`, "", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			v, err := parseVerdict([]byte(tc.in))
+			if tc.wantErr {
+				if err == nil {
+					t.Errorf("expected error, got %+v", v)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if v.Status != tc.want {
+				t.Errorf("status = %q, want %q", v.Status, tc.want)
+			}
+		})
+	}
+}
+
+func TestRunnerPreflight(t *testing.T) {
+	// Unapproved plan.
+	root := setupWorkspace(t, "p", runnerPlan)
+	if _, err := Run(RunOptions{Root: root, Slug: "p", Hooks: baseHooks(), Out: &bytes.Buffer{}}); err == nil {
+		t.Errorf("expected preflight failure for unapproved plan")
+	}
+
+	// Approved but claude missing.
+	root2 := approvedRunnerWorkspace(t)
+	h := baseHooks()
+	h.ClaudeAvailable = func() bool { return false }
+	if _, err := Run(RunOptions{Root: root2, Slug: "p", Hooks: h, Out: &bytes.Buffer{}}); err == nil || !strings.Contains(err.Error(), "claude") {
+		t.Errorf("expected claude-missing failure, got %v", err)
+	}
+
+	// Autonomous with a failing sandbox doctor.
+	h2 := baseHooks()
+	h2.Doctor = func() SandboxReport { return SandboxReport{OK: false} }
+	if _, err := Run(RunOptions{Root: root2, Slug: "p", Autonomous: true, Hooks: h2, Out: &bytes.Buffer{}}); err == nil || !strings.Contains(err.Error(), "sandbox") {
+		t.Errorf("expected sandbox failure for --autonomous, got %v", err)
+	}
+}
+
+func TestRunnerPathAuditBlocks(t *testing.T) {
+	root := approvedRunnerWorkspace(t)
+	// Both feats ready with a task; the session "touches" a forbidden path.
+	writeSpec(t, root, "a", allApproved, true, "- [ ] 1. do it\n")
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n") // b already done
+	h := baseHooks()
+	h.ChangedPaths = func(string) ([]string, error) { return []string{"docs/graph/graph.json"}, nil }
+
+	sum, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 5, MaxRetries: 1, Out: &bytes.Buffer{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum.Blocks == 0 {
+		t.Errorf("forbidden path change should block the feat")
+	}
+	if _, blocked := blockMarker(root, "p", "a"); !blocked {
+		t.Errorf("expected a block marker for feat a")
+	}
+	if sum.Steps != 0 {
+		t.Errorf("no step should have advanced, got %d", sum.Steps)
+	}
+}
+
+func TestRunnerRetryAppendsFailure(t *testing.T) {
+	root := approvedRunnerWorkspace(t)
+	writeSpec(t, root, "a", allApproved, true, "- [ ] 1. do it\n")
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n")
+
+	var briefs []string
+	gateCalls := 0
+	h := baseHooks()
+	h.Session = func(step Step, brief string, _ SessionMode, _ float64) (Verdict, error) {
+		briefs = append(briefs, brief)
+		return Verdict{Status: VerdictDone}, nil
+	}
+	h.Gate = func(string, string) (bool, string) {
+		gateCalls++
+		if gateCalls == 1 {
+			return false, "FAIL: expected 3 got 4"
+		}
+		return true, ""
+	}
+	// On the successful attempt the "session" checks the task box so the feat
+	// completes and the loop terminates.
+	h.Commit = func(string, string, []string) error {
+		writeFile(t, filepath.Join(root, "specs", "a", "tasks.md"), "- [x] 1. do it\n")
+		return nil
+	}
+
+	sum, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 5, MaxRetries: 2, Out: &bytes.Buffer{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum.Retries != 1 {
+		t.Errorf("expected 1 retry, got %d", sum.Retries)
+	}
+	if len(briefs) < 2 || !strings.Contains(briefs[1], "Previous attempt failed") || !strings.Contains(briefs[1], "expected 3 got 4") {
+		t.Errorf("retry brief should append the gate failure, got %v", briefs)
+	}
+	if !sum.Completed {
+		t.Errorf("run should complete once the retried step passes")
+	}
+}
+
+func TestRunnerBlockedVerdictContinues(t *testing.T) {
+	root := approvedRunnerWorkspace(t)
+	writeSpec(t, root, "a", allApproved, true, "- [ ] 1. do it\n")
+	writeSpec(t, root, "b", allApproved, true, "- [ ] 1. do it\n")
+
+	h := baseHooks()
+	h.Session = func(step Step, _ string, _ SessionMode, _ float64) (Verdict, error) {
+		if step.Feat == "a" {
+			return Verdict{Status: VerdictBlocked, Summary: "cannot resolve", Revision: "split feat a"}, nil
+		}
+		return Verdict{Status: VerdictDone}, nil
+	}
+	// b advances by checking its box on commit.
+	h.Commit = func(_ string, _ string, _ []string) error {
+		writeFile(t, filepath.Join(root, "specs", "b", "tasks.md"), "- [x] 1. do it\n")
+		return nil
+	}
+
+	sum, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 8, MaxRetries: 1, Out: &bytes.Buffer{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// a is blocked, b advanced; the loop ends with nothing unblocked.
+	if _, blocked := blockMarker(root, "p", "a"); !blocked {
+		t.Errorf("feat a should be blocked")
+	}
+	if sum.Steps < 1 {
+		t.Errorf("feat b should have advanced despite a being blocked")
+	}
+	if sum.Outcome != OutcomeNothing {
+		t.Errorf("expected OutcomeNothing after b done and a blocked, got %d", sum.Outcome)
+	}
+	// The deviation is journaled with its revision.
+	logData, _ := os.ReadFile(filepath.Join(Dir(root, "p"), "log.md"))
+	if !strings.Contains(string(logData), "| a | blocked") || !strings.Contains(string(logData), "split feat a") {
+		t.Errorf("deviation not journaled with revision: %s", logData)
+	}
+}
+
+func TestRunnerJournalFormat(t *testing.T) {
+	root := approvedRunnerWorkspace(t)
+	writeSpec(t, root, "a", allApproved, true, "- [ ] 1. do it\n")
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n")
+	h := baseHooks()
+	h.Commit = func(string, string, []string) error {
+		writeFile(t, filepath.Join(root, "specs", "a", "tasks.md"), "- [x] 1. do it\n")
+		return nil
+	}
+	if _, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 5, Out: &bytes.Buffer{}}); err != nil {
+		t.Fatal(err)
+	}
+	logData, _ := os.ReadFile(filepath.Join(Dir(root, "p"), "log.md"))
+	if !strings.Contains(string(logData), "## [2026-07-07] task 1 | a | done") {
+		t.Errorf("journal line format wrong: %s", logData)
+	}
+}
+
+func TestRunnerDriftStopsMidRun(t *testing.T) {
+	root := approvedRunnerWorkspace(t)
+	writeSpec(t, root, "a", allApproved, true, "- [ ] 1. do it\n")
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n")
+	h := baseHooks()
+	// The "session" drifts the plan by editing plan.md — the runner must stop on
+	// the next iteration's drift check rather than keep going.
+	h.Session = func(Step, string, SessionMode, float64) (Verdict, error) {
+		writeFile(t, filepath.Join(Dir(root, "p"), "plan.md"), runnerPlan+"\n<!-- drift -->\n")
+		return Verdict{Status: VerdictDone}, nil
+	}
+	sum, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 5, Out: &bytes.Buffer{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum.Outcome != OutcomeDrift {
+		t.Errorf("expected OutcomeDrift after mid-run edit, got %d (%s)", sum.Outcome, sum.Reason)
+	}
+}
+
+func TestRunnerSpecPhaseApproval(t *testing.T) {
+	// A pending feat drives the spec flow: the runner scaffolds, the session
+	// authors, and the runner approves each phase via the CSDD hook.
+	root := approvedRunnerWorkspace(t)
+	// Make b already done so only a is in play.
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n")
+
+	approvals := map[string]bool{}
+	h := baseHooks()
+	h.CSDD = func(_ string, args ...string) (bool, string) {
+		// Simulate the spec lifecycle the real csdd would perform.
+		switch {
+		case len(args) >= 2 && args[0] == "plan" && args[1] == "generate":
+			writeSpec(t, root, "a", map[string]bool{}, false, "")
+		case len(args) >= 4 && args[0] == "spec" && args[1] == "approve":
+			phase := args[len(args)-1]
+			approvals[phase] = true
+			ready := approvals["requirements"] && approvals["design"] && approvals["tasks"]
+			tasks := ""
+			if ready {
+				tasks = "- [x] 1. done\n"
+			}
+			writeSpec(t, root, "a", approvals, ready, tasks)
+		}
+		return true, ""
+	}
+	sum, err := Run(RunOptions{Root: root, Slug: "p", Hooks: h, MaxIterations: 10, Out: &bytes.Buffer{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !sum.Completed {
+		t.Errorf("spec-phase-driven run should complete, got %+v", sum)
+	}
+	if !approvals["requirements"] || !approvals["design"] || !approvals["tasks"] {
+		t.Errorf("all three phases should have been approved by the runner: %v", approvals)
+	}
+}
diff --git a/internal/plan/sandbox.go b/internal/plan/sandbox.go
new file mode 100644
index 0000000..d416b82
--- /dev/null
+++ b/internal/plan/sandbox.go
@@ -0,0 +1,269 @@
+package plan
+
+import (
+	"embed"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/templater"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// nodeFeatureID is the devcontainer feature the base scaffold always installs
+// (Claude Code's Node runtime). A `--feature node` is therefore a no-op.
+const nodeFeatureID = "ghcr.io/devcontainers/features/node:1"
+
+// featurePreset maps a `--feature <name>` to the devcontainer feature it adds and
+// the registry domains its toolchain needs (appended to the egress allow-list).
+type featurePreset struct {
+	id      string
+	domains []string
+}
+
+// sandboxFeatures is the closed set of `--feature` presets (R10.2). Language
+// toolchains arrive as features so the base image stays language-agnostic.
+var sandboxFeatures = map[string]featurePreset{
+	"go":     {"ghcr.io/devcontainers/features/go:1", []string{"proxy.golang.org", "sum.golang.org"}},
+	"python": {"ghcr.io/devcontainers/features/python:1", []string{"pypi.org", "files.pythonhosted.org"}},
+	"node":   {nodeFeatureID, nil}, // already in the base scaffold
+	"rust":   {"ghcr.io/devcontainers/features/rust:1", []string{"static.crates.io", "crates.io", "index.crates.io"}},
+	"java":   {"ghcr.io/devcontainers/features/java:1", []string{"repo.maven.apache.org"}},
+}
+
+// SandboxFeatureNames returns the supported --feature names, sorted (for help
+// and error messages).
+func SandboxFeatureNames() []string {
+	out := make([]string, 0, len(sandboxFeatures))
+	for k := range sandboxFeatures {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// SandboxOptions is the headless input for `csdd sandbox init`.
+type SandboxOptions struct {
+	Root         string
+	Features     []string
+	AllowDomains []string
+	Hardened     bool
+	Force        bool
+}
+
+// sandboxFile is one scaffolded devcontainer file with its on-disk mode.
+type sandboxFile struct {
+	name    string
+	content string
+	mode    os.FileMode
+}
+
+// SandboxInit scaffolds .devcontainer/ with the four-file template (R10). It
+// returns the base names actually written (idempotent: an existing file is left
+// untouched unless Force). Every file is LF-normalized by the templater so the
+// firewall script survives a CRLF working tree (R10.3).
+func SandboxInit(templates embed.FS, opts SandboxOptions) ([]string, error) {
+	extraFeatureIDs, extraDomains, err := resolveSandboxFeatures(opts)
+	if err != nil {
+		return nil, err
+	}
+
+	hardened := "false"
+	if opts.Hardened {
+		hardened = "true"
+	}
+	devcontainer, err := templater.Render(templates, "templates/sandbox/devcontainer.json.tmpl", map[string]string{
+		"Hardened":      hardened,
+		"ExtraFeatures": renderExtraFeatures(extraFeatureIDs),
+	})
+	if err != nil {
+		return nil, err
+	}
+	dockerfile, err := templater.Static(templates, "templates/sandbox/Dockerfile.tmpl")
+	if err != nil {
+		return nil, err
+	}
+	firewall, err := templater.Static(templates, "templates/sandbox/init-firewall.sh.tmpl")
+	if err != nil {
+		return nil, err
+	}
+	domains, err := templater.Static(templates, "templates/sandbox/allowed-domains.txt.tmpl")
+	if err != nil {
+		return nil, err
+	}
+	domains = appendAllowDomains(domains, extraDomains)
+
+	files := []sandboxFile{
+		{"devcontainer.json", devcontainer, 0o644},
+		{"Dockerfile", dockerfile, 0o644},
+		{"init-firewall.sh", firewall, 0o755},
+		{"allowed-domains.txt", domains, 0o644},
+	}
+	dir := paths.Devcontainer(opts.Root)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return nil, err
+	}
+	var written []string
+	for _, f := range files {
+		target := filepath.Join(dir, f.name)
+		if _, statErr := os.Stat(target); statErr == nil && !opts.Force {
+			continue // idempotent: never clobber without --force
+		}
+		if err := workspace.AtomicWrite(target, []byte(f.content), f.mode); err != nil {
+			return nil, err
+		}
+		written = append(written, f.name)
+	}
+	return written, nil
+}
+
+// resolveSandboxFeatures validates the requested features and collects the extra
+// feature IDs and allow-list domains they imply, plus any explicit --allow-domain
+// hosts, deduplicated with first-seen order preserved.
+func resolveSandboxFeatures(opts SandboxOptions) (featureIDs, domains []string, err error) {
+	seenFeat := map[string]bool{}
+	seenDom := map[string]bool{}
+	addDomain := func(d string) {
+		if d = strings.TrimSpace(d); d != "" && !seenDom[d] {
+			seenDom[d] = true
+			domains = append(domains, d)
+		}
+	}
+	for _, name := range opts.Features {
+		p, ok := sandboxFeatures[strings.ToLower(strings.TrimSpace(name))]
+		if !ok {
+			return nil, nil, fmt.Errorf("unknown --feature %q; supported: %s", name, strings.Join(SandboxFeatureNames(), ", "))
+		}
+		if p.id != "" && p.id != nodeFeatureID && !seenFeat[p.id] {
+			seenFeat[p.id] = true
+			featureIDs = append(featureIDs, p.id)
+		}
+		for _, d := range p.domains {
+			addDomain(d)
+		}
+	}
+	for _, d := range opts.AllowDomains {
+		addDomain(d)
+	}
+	return featureIDs, domains, nil
+}
+
+// renderExtraFeatures formats additional feature IDs as the JSONC tail that slots
+// after the base node feature: each becomes `,\n    "<id>": {}`. Empty when there
+// are none, keeping the base features object valid.
+func renderExtraFeatures(ids []string) string {
+	var b strings.Builder
+	for _, id := range ids {
+		b.WriteString(",\n    ")
+		b.WriteString(`"` + id + `": {}`)
+	}
+	return b.String()
+}
+
+// appendAllowDomains appends an active-host block to the rendered allow-list. The
+// preset registries in the template stay commented; the flags add live entries.
+func appendAllowDomains(base string, domains []string) string {
+	if len(domains) == 0 {
+		return base
+	}
+	var b strings.Builder
+	b.WriteString(strings.TrimRight(base, "\n"))
+	b.WriteString("\n\n# --- added by `csdd sandbox init` flags ---\n")
+	for _, d := range domains {
+		b.WriteString(d)
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
+
+// --- doctor (R11) ---------------------------------------------------------
+
+// SandboxCheck is one isolation check with its individual verdict (R11.2).
+type SandboxCheck struct {
+	Name   string `json:"name"`
+	OK     bool   `json:"ok"`
+	Detail string `json:"detail"`
+}
+
+// SandboxReport is the whole doctor result; OK is true only when every check is.
+type SandboxReport struct {
+	OK     bool           `json:"ok"`
+	Checks []SandboxCheck `json:"checks"`
+}
+
+// DoctorProbes indirects the three environment queries so tests can drive doctor
+// without a real container or network. Nil fields fall back to the real probes.
+type DoctorProbes struct {
+	Getenv    func(string) string
+	Geteuid   func() int
+	Reachable func(hostPort string) bool
+}
+
+// Control and Anthropic probe targets. The control host is deliberately NOT in
+// the default allow-list, so a working firewall makes it unreachable.
+const (
+	doctorControlHost   = "example.com:443"
+	doctorAnthropicHost = "api.anthropic.com:443"
+)
+
+// Doctor verifies the session is inside the hardened container (R11.1): the
+// devcontainer env marker, a non-root user, and an active firewall (the control
+// host blocked AND api.anthropic.com reachable). It performs no network beyond
+// the two reachability probes.
+func Doctor(p DoctorProbes) SandboxReport {
+	if p.Getenv == nil {
+		p.Getenv = os.Getenv
+	}
+	if p.Geteuid == nil {
+		p.Geteuid = os.Geteuid
+	}
+	if p.Reachable == nil {
+		p.Reachable = tcpReachable
+	}
+
+	var checks []SandboxCheck
+
+	devVal := p.Getenv("DEVCONTAINER")
+	checks = append(checks, SandboxCheck{
+		Name: "devcontainer_env", OK: devVal == "true",
+		Detail: "DEVCONTAINER=" + devVal + " (want true)",
+	})
+
+	euid := p.Geteuid()
+	checks = append(checks, SandboxCheck{
+		Name: "non_root_user", OK: euid != 0,
+		Detail: fmt.Sprintf("euid=%d (want non-zero)", euid),
+	})
+
+	controlUp := p.Reachable(doctorControlHost)
+	anthropicUp := p.Reachable(doctorAnthropicHost)
+	checks = append(checks, SandboxCheck{
+		Name: "firewall_active", OK: !controlUp && anthropicUp,
+		Detail: fmt.Sprintf("control %s reachable=%v (want false); %s reachable=%v (want true)",
+			doctorControlHost, controlUp, doctorAnthropicHost, anthropicUp),
+	})
+
+	ok := true
+	for _, c := range checks {
+		if !c.OK {
+			ok = false
+		}
+	}
+	return SandboxReport{OK: ok, Checks: checks}
+}
+
+// tcpReachable reports whether a TCP connection to hostPort succeeds within a
+// short timeout.
+func tcpReachable(hostPort string) bool {
+	conn, err := net.DialTimeout("tcp", hostPort, 3*time.Second)
+	if err != nil {
+		return false
+	}
+	_ = conn.Close()
+	return true
+}
diff --git a/internal/plan/sandbox_test.go b/internal/plan/sandbox_test.go
new file mode 100644
index 0000000..58ef0eb
--- /dev/null
+++ b/internal/plan/sandbox_test.go
@@ -0,0 +1,150 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/protonspy/csdd/internal/templater"
+)
+
+func readSandboxFile(t *testing.T, root, name string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(root, ".devcontainer", name))
+	if err != nil {
+		t.Fatalf("read %s: %v", name, err)
+	}
+	return string(data)
+}
+
+func TestSandboxInitScaffold(t *testing.T) {
+	root := t.TempDir()
+	written, err := SandboxInit(templater.FS, SandboxOptions{Root: root})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(written) != 4 {
+		t.Fatalf("expected 4 files written, got %v", written)
+	}
+	for _, name := range []string{"devcontainer.json", "Dockerfile", "init-firewall.sh", "allowed-domains.txt"} {
+		content := readSandboxFile(t, root, name)
+		if strings.Contains(content, "\r\n") {
+			t.Errorf("%s contains CRLF; must be LF-normalized", name)
+		}
+	}
+	// The firewall script is executable.
+	fi, err := os.Stat(filepath.Join(root, ".devcontainer", "init-firewall.sh"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Mode().Perm()&0o100 == 0 {
+		t.Errorf("init-firewall.sh should be executable, got %v", fi.Mode())
+	}
+	// Default (non-hardened) build arg.
+	if !strings.Contains(readSandboxFile(t, root, "devcontainer.json"), `"HARDENED": "false"`) {
+		t.Errorf("default devcontainer should set HARDENED=false")
+	}
+}
+
+func TestSandboxInitIdempotentAndForce(t *testing.T) {
+	root := t.TempDir()
+	if _, err := SandboxInit(templater.FS, SandboxOptions{Root: root}); err != nil {
+		t.Fatal(err)
+	}
+	// Hand-edit a file, then re-run without --force: it must be preserved.
+	target := filepath.Join(root, ".devcontainer", "allowed-domains.txt")
+	if err := os.WriteFile(target, []byte("# custom\nmy.host\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	written, err := SandboxInit(templater.FS, SandboxOptions{Root: root})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(written) != 0 {
+		t.Errorf("idempotent re-init should write nothing, wrote %v", written)
+	}
+	if got := readSandboxFile(t, root, "allowed-domains.txt"); !strings.Contains(got, "my.host") {
+		t.Errorf("re-init clobbered a hand-edited file")
+	}
+	// --force regenerates.
+	written, err = SandboxInit(templater.FS, SandboxOptions{Root: root, Force: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(written) != 4 {
+		t.Errorf("--force should rewrite all four files, wrote %v", written)
+	}
+}
+
+func TestSandboxInitFeaturesAndDomains(t *testing.T) {
+	root := t.TempDir()
+	_, err := SandboxInit(templater.FS, SandboxOptions{
+		Root:         root,
+		Features:     []string{"go"},
+		AllowDomains: []string{"internal.registry.example"},
+		Hardened:     true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	dc := readSandboxFile(t, root, "devcontainer.json")
+	if !strings.Contains(dc, "features/go:1") {
+		t.Errorf("--feature go should add the go devcontainer feature: %s", dc)
+	}
+	if !strings.Contains(dc, `"HARDENED": "true"`) {
+		t.Errorf("--hardened should set HARDENED=true")
+	}
+	domains := readSandboxFile(t, root, "allowed-domains.txt")
+	if !strings.Contains(domains, "proxy.golang.org") {
+		t.Errorf("--feature go should add its registry domains")
+	}
+	if !strings.Contains(domains, "internal.registry.example") {
+		t.Errorf("--allow-domain should append the host")
+	}
+}
+
+func TestSandboxInitUnknownFeature(t *testing.T) {
+	root := t.TempDir()
+	_, err := SandboxInit(templater.FS, SandboxOptions{Root: root, Features: []string{"cobol"}})
+	if err == nil || !strings.Contains(err.Error(), "unknown --feature") {
+		t.Errorf("unknown feature should error, got %v", err)
+	}
+}
+
+func TestDoctor(t *testing.T) {
+	cases := []struct {
+		name      string
+		dev       string
+		euid      int
+		control   bool // control host reachable
+		anthropic bool // anthropic reachable
+		wantOK    bool
+	}{
+		{"all good", "true", 1000, false, true, true},
+		{"not in devcontainer", "", 1000, false, true, false},
+		{"root user", "true", 0, false, true, false},
+		{"firewall leaks control", "true", 1000, true, true, false},
+		{"anthropic blocked", "true", 1000, false, false, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			report := Doctor(DoctorProbes{
+				Getenv:  func(string) string { return tc.dev },
+				Geteuid: func() int { return tc.euid },
+				Reachable: func(hp string) bool {
+					if hp == doctorControlHost {
+						return tc.control
+					}
+					return tc.anthropic
+				},
+			})
+			if report.OK != tc.wantOK {
+				t.Errorf("Doctor OK = %v, want %v (checks=%+v)", report.OK, tc.wantOK, report.Checks)
+			}
+			if len(report.Checks) != 3 {
+				t.Errorf("expected 3 individual checks, got %d", len(report.Checks))
+			}
+		})
+	}
+}
diff --git a/internal/plan/seq.go b/internal/plan/seq.go
new file mode 100644
index 0000000..f9dc3ea
--- /dev/null
+++ b/internal/plan/seq.go
@@ -0,0 +1,260 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+	"github.com/protonspy/csdd/internal/validator"
+)
+
+// Step names the next unit of work the runner (or a human) should perform for a
+// feat. The spec-phase steps drive the spec flow; a task step names one leaf task
+// in tasks.md to implement.
+const (
+	StepSpecRequirements = "spec-requirements"
+	StepSpecDesign       = "spec-design"
+	StepSpecTasks        = "spec-tasks"
+	StepTaskPrefix       = "task " // followed by the task id, e.g. "task 1.2"
+)
+
+// Step is the sequencer's answer: which feat, which step, and why. It is a pure
+// function of the parsed plan, the derived statuses, and block markers (§5.5), so
+// the same workspace always yields the same next step.
+type Step struct {
+	Feat   string `json:"feat"`
+	Step   string `json:"step"`
+	Reason string `json:"reason"`
+}
+
+// Sequencer outcomes. These map to distinct CLI exit codes (R6.3) so an agent
+// can branch on $? without parsing.
+const (
+	SeqStep     = iota // 0: a step is available
+	_                  // (1,2 reserved: generic/usage errors)
+	_                  //
+	SeqComplete        // 3: every feat is done
+	SeqNothing         // 4: work remains but nothing is unblocked
+	SeqNotReady        // 5: plan not approved, or drifted
+)
+
+// Next selects the next step to perform (R6.1). It walks feats in milestone order
+// then table order, skips feats that are done or blocked, requires every
+// dependency to be done, and returns the first actionable step within the first
+// eligible feat. The returned int is the sequencer outcome (SeqStep/…); on
+// SeqStep the Step is populated.
+//
+// requireApproved gates autonomy: when true (the runner), an unapproved or
+// drifted plan returns SeqNotReady. A human following `plan next` by hand passes
+// false and sequences a draft freely.
+func Next(root string, doc *PlanDoc, requireApproved bool) (Step, int, error) {
+	if requireApproved {
+		approved, drift, err := IsApproved(root, doc.Slug)
+		if err != nil {
+			return Step{}, SeqNotReady, err
+		}
+		if !approved || drift {
+			return Step{}, SeqNotReady, nil
+		}
+	}
+
+	statuses := map[string]FeatStatus{}
+	for _, f := range doc.Feats {
+		statuses[f.Slug] = deriveFeatStatus(root, doc.Slug, f)
+	}
+
+	allDone := true // vacuously true for an empty plan → SeqComplete
+	for _, f := range orderFeats(doc.Feats) {
+		state := statuses[f.Slug].State
+		if state != StateDone {
+			allDone = false
+		}
+		if state == StateDone || state == StateBlocked {
+			continue
+		}
+		// Dependencies must all be done before this feat is eligible. A feat
+		// waiting on a not-yet-done dep is skipped; the dep itself (if actionable)
+		// is reached earlier or later in the same walk.
+		if _, unmet := firstUnmetDep(f, statuses); unmet {
+			continue
+		}
+		return nextStepForFeat(root, f, statuses[f.Slug]), SeqStep, nil
+	}
+
+	if allDone {
+		return Step{}, SeqComplete, nil
+	}
+	// Work remains but nothing is unblocked: every incomplete feat is blocked or
+	// its dependency chain bottoms out at a blocked feat.
+	return Step{}, SeqNothing, nil
+}
+
+// orderFeats returns feats in milestone order (first-seen) then table order — the
+// total deterministic order the sequencer walks (§5.5).
+func orderFeats(feats []Feat) []Feat {
+	milestoneRank := map[string]int{}
+	next := 0
+	for _, f := range feats {
+		if _, ok := milestoneRank[f.Milestone]; !ok {
+			milestoneRank[f.Milestone] = next
+			next++
+		}
+	}
+	idx := make([]int, len(feats))
+	for i := range idx {
+		idx[i] = i
+	}
+	sort.SliceStable(idx, func(a, b int) bool {
+		fa, fb := feats[idx[a]], feats[idx[b]]
+		if milestoneRank[fa.Milestone] != milestoneRank[fb.Milestone] {
+			return milestoneRank[fa.Milestone] < milestoneRank[fb.Milestone]
+		}
+		return idx[a] < idx[b] // stable table order within a milestone
+	})
+	out := make([]Feat, len(feats))
+	for i, j := range idx {
+		out[i] = feats[j]
+	}
+	return out
+}
+
+// firstUnmetDep returns the first dependency of f that is not yet done, and
+// whether one exists. Unknown deps (not in statuses) are treated as unmet so a
+// misdeclared dependency never lets a feat run ahead of validation.
+func firstUnmetDep(f Feat, statuses map[string]FeatStatus) (string, bool) {
+	for _, dep := range f.Depends {
+		st, ok := statuses[dep]
+		if !ok || st.State != StateDone {
+			return dep, true
+		}
+	}
+	return "", false
+}
+
+// nextStepForFeat returns the actionable step within an eligible feat: advance
+// the spec flow through requirements → design → tasks, then implement the next
+// unchecked leaf task honoring tasks.md order and _Depends:_.
+func nextStepForFeat(root string, f Feat, fs FeatStatus) Step {
+	switch fs.State {
+	case StatePending:
+		return Step{Feat: f.Slug, Step: StepSpecRequirements, Reason: "no spec yet — start the requirements phase"}
+	case StateRequirements:
+		return Step{Feat: f.Slug, Step: StepSpecRequirements, Reason: "requirements not yet approved"}
+	case StateDesign:
+		return Step{Feat: f.Slug, Step: StepSpecDesign, Reason: "requirements approved — draft the design"}
+	case StateTasks:
+		return Step{Feat: f.Slug, Step: StepSpecTasks, Reason: "design approved — draft the tasks"}
+	default:
+		// ready / implementing: the next unchecked leaf task.
+		if id, ok := nextTask(filepath.Join(paths.Specs(root), f.Slug)); ok {
+			return Step{Feat: f.Slug, Step: StepTaskPrefix + id, Reason: "implement task " + id}
+		}
+		// No leaf task found though the feat isn't marked done — fall back to tasks.
+		return Step{Feat: f.Slug, Step: StepSpecTasks, Reason: "no actionable task found; review tasks.md"}
+	}
+}
+
+// taskRow is a minimal tasks.md task line used for sequencing.
+type taskRow struct {
+	id      string
+	done    bool
+	depends []string
+}
+
+// nextTask returns the id of the next task to implement in specs/<feat>/tasks.md:
+// the first unchecked leaf task (no other task has it as a numeric prefix) whose
+// _Depends:_ tasks are all checked, in file order. Returns ok=false when every
+// task is checked or none parse.
+func nextTask(specDir string) (string, bool) {
+	data, err := os.ReadFile(filepath.Join(specDir, "tasks.md"))
+	if err != nil {
+		return "", false
+	}
+	rows := parseTaskRows(string(data))
+	if len(rows) == 0 {
+		return "", false
+	}
+	// Leaf = no other task id has this id as a "<id>." prefix.
+	ids := map[string]bool{}
+	doneByID := map[string]bool{}
+	for _, r := range rows {
+		ids[r.id] = true
+		doneByID[r.id] = r.done
+	}
+	isLeaf := func(id string) bool {
+		for other := range ids {
+			if other != id && strings.HasPrefix(other, id+".") {
+				return false
+			}
+		}
+		return true
+	}
+	for _, r := range rows {
+		if r.done || !isLeaf(r.id) {
+			continue
+		}
+		if depsMet(r.depends, doneByID) {
+			return r.id, true
+		}
+	}
+	return "", false
+}
+
+// depsMet reports whether every listed dependency task is checked. An unknown
+// dependency is treated as unmet (conservative).
+func depsMet(depends []string, done map[string]bool) bool {
+	for _, d := range depends {
+		if !done[d] {
+			return false
+		}
+	}
+	return true
+}
+
+// parseTaskRows extracts task lines and their _Depends:_ from tasks.md, reusing
+// the validator's canonical grammar and fence masking so sequencing agrees with
+// linting and the dashboard on what a task is.
+func parseTaskRows(content string) []taskRow {
+	text := validator.MaskCodeFences(textutil.NormalizeNewlines(content))
+	lines := strings.Split(text, "\n")
+	var out []taskRow
+	var cur *taskRow
+	flush := func() {
+		if cur != nil {
+			out = append(out, *cur)
+			cur = nil
+		}
+	}
+	var block []string
+	commit := func() {
+		if cur == nil {
+			return
+		}
+		joined := strings.Join(block, "\n")
+		if m := validator.DependsAnnotRe.FindStringSubmatch(joined); m != nil {
+			for _, tok := range strings.Split(m[1], ",") {
+				if t := strings.TrimSpace(tok); t != "" {
+					cur.depends = append(cur.depends, t)
+				}
+			}
+		}
+	}
+	for _, line := range lines {
+		if m := validator.TaskLineRe.FindStringSubmatch(line); m != nil {
+			commit()
+			flush()
+			block = []string{line}
+			cur = &taskRow{id: m[3], done: strings.EqualFold(strings.TrimSpace(m[2]), "x")}
+			continue
+		}
+		if cur != nil {
+			block = append(block, line)
+		}
+	}
+	commit()
+	flush()
+	return out
+}
diff --git a/internal/plan/seq_test.go b/internal/plan/seq_test.go
new file mode 100644
index 0000000..8fcff75
--- /dev/null
+++ b/internal/plan/seq_test.go
@@ -0,0 +1,157 @@
+package plan
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+const seqPlan = `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | |
+| 2 | b | B | a | M1 | | |
+| 3 | c | C | — | M2 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+func nextStep(t *testing.T, root, slug string, requireApproved bool) (Step, int) {
+	t.Helper()
+	doc, err := Load(root, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	step, outcome, err := Next(root, doc, requireApproved)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return step, outcome
+}
+
+func TestNextOrderingAndDeps(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	allApproved := map[string]bool{"requirements": true, "design": true, "tasks": true}
+
+	// Nothing done: first M1 feat with no deps → a, at the requirements phase.
+	step, outcome := nextStep(t, root, "p", false)
+	if outcome != SeqStep || step.Feat != "a" || step.Step != StepSpecRequirements {
+		t.Fatalf("expected a/spec-requirements, got %+v outcome=%d", step, outcome)
+	}
+
+	// a done: b's dep is met and b (M1) precedes c (M2).
+	writeSpec(t, root, "a", allApproved, true, "- [x] 1. done\n")
+	step, _ = nextStep(t, root, "p", false)
+	if step.Feat != "b" {
+		t.Errorf("expected b next (M1 before M2), got %s", step.Feat)
+	}
+
+	// a + b done: c (M2) is next.
+	writeSpec(t, root, "b", allApproved, true, "- [x] 1. done\n")
+	step, _ = nextStep(t, root, "p", false)
+	if step.Feat != "c" {
+		t.Errorf("expected c next, got %s", step.Feat)
+	}
+
+	// all done → complete.
+	writeSpec(t, root, "c", allApproved, true, "- [x] 1. done\n")
+	_, outcome = nextStep(t, root, "p", false)
+	if outcome != SeqComplete {
+		t.Errorf("expected SeqComplete, got %d", outcome)
+	}
+}
+
+func TestNextBlockedAndNothing(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	// a is blocked (runner marker); b depends on a, c is independent.
+	writeFile(t, filepath.Join(stateDir(root, "p"), "blocked", "a"), "gate failed\n")
+
+	// c is still reachable.
+	step, outcome := nextStep(t, root, "p", false)
+	if outcome != SeqStep || step.Feat != "c" {
+		t.Fatalf("expected c reachable while a blocked, got %+v/%d", step, outcome)
+	}
+
+	// Now mark c done too; only b remains, but it waits on blocked a → nothing.
+	allApproved := map[string]bool{"requirements": true, "design": true, "tasks": true}
+	writeSpec(t, root, "c", allApproved, true, "- [x] 1. done\n")
+	_, outcome = nextStep(t, root, "p", false)
+	if outcome != SeqNothing {
+		t.Errorf("expected SeqNothing (b waits on blocked a), got %d", outcome)
+	}
+}
+
+func TestNextStepProgression(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	cases := []struct {
+		approvals map[string]bool
+		ready     bool
+		tasks     string
+		wantStep  string
+	}{
+		{map[string]bool{}, false, "", StepSpecRequirements},
+		{map[string]bool{"requirements": true}, false, "", StepSpecDesign},
+		{map[string]bool{"requirements": true, "design": true}, false, "", StepSpecTasks},
+		{map[string]bool{"requirements": true, "design": true, "tasks": true}, true,
+			"- [ ] 1. Parent\n  - [ ] 1.1 First _Requirements: 1.1_\n  - [ ] 1.2 Second _Depends: 1.1_\n", "task 1.1"},
+	}
+	for _, tc := range cases {
+		writeSpec(t, root, "a", tc.approvals, tc.ready, tc.tasks)
+		step, outcome := nextStep(t, root, "p", false)
+		if outcome != SeqStep || step.Feat != "a" || step.Step != tc.wantStep {
+			t.Errorf("approvals=%v → step %q (want %q)", tc.approvals, step.Step, tc.wantStep)
+		}
+	}
+}
+
+func TestNextTaskHonorsDepends(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	allApproved := map[string]bool{"requirements": true, "design": true, "tasks": true}
+	// 1.1 done; 1.2 depends on 1.1 (met) → next is 1.2, not 1.3 (depends on 1.2, unmet).
+	tasks := "- [x] 1.1 First _Requirements: 1.1_\n- [ ] 1.2 Second _Depends: 1.1_\n- [ ] 1.3 Third _Depends: 1.2_\n"
+	writeSpec(t, root, "a", allApproved, true, tasks)
+	step, _ := nextStep(t, root, "p", false)
+	if step.Step != "task 1.2" {
+		t.Errorf("expected task 1.2 (deps met), got %q", step.Step)
+	}
+}
+
+func TestNextRequiresApproval(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	// Unapproved + requireApproved → SeqNotReady.
+	_, outcome := nextStep(t, root, "p", true)
+	if outcome != SeqNotReady {
+		t.Fatalf("expected SeqNotReady for unapproved plan, got %d", outcome)
+	}
+	// Approve, then it sequences.
+	doc, _ := Load(root, "p")
+	if err := ApprovePlan(root, doc, time.Unix(0, 0)); err != nil {
+		t.Fatal(err)
+	}
+	_, outcome = nextStep(t, root, "p", true)
+	if outcome != SeqStep {
+		t.Errorf("expected SeqStep after approval, got %d", outcome)
+	}
+	// Drift (edit plan.md) → SeqNotReady again.
+	writeFile(t, filepath.Join(Dir(root, "p"), "plan.md"), seqPlan+"\n<!-- edit -->\n")
+	_, outcome = nextStep(t, root, "p", true)
+	if outcome != SeqNotReady {
+		t.Errorf("expected SeqNotReady after drift, got %d", outcome)
+	}
+}
+
+func TestNextDeterministic(t *testing.T) {
+	root := setupWorkspace(t, "p", seqPlan)
+	a, o1 := nextStep(t, root, "p", false)
+	b, o2 := nextStep(t, root, "p", false)
+	if a != b || o1 != o2 {
+		t.Errorf("nondeterministic next: %+v/%d vs %+v/%d", a, o1, b, o2)
+	}
+}
diff --git a/internal/plan/status.go b/internal/plan/status.go
new file mode 100644
index 0000000..7ee59b1
--- /dev/null
+++ b/internal/plan/status.go
@@ -0,0 +1,192 @@
+package plan
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+	"github.com/protonspy/csdd/internal/validator"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// Feat states (R5.1). A feat's state is DERIVED from specs/<feat>/ reality on
+// every read — never stored — so there is no second bookkeeping to desync (design
+// principle 4).
+const (
+	StatePending      = "pending"      // no spec directory yet
+	StateRequirements = "requirements" // spec exists; requirements not yet approved
+	StateDesign       = "design"       // requirements approved; design not yet approved
+	StateTasks        = "tasks"        // design approved; tasks not yet approved
+	StateReady        = "ready"        // ready_for_implementation; no task checked yet
+	StateImplementing = "implementing" // some but not all tasks checked
+	StateDone         = "done"         // every task checked
+	StateBlocked      = "blocked"      // a runner block marker exists for the feat
+)
+
+// FeatStatus is one feat's derived state plus the evidence behind it.
+type FeatStatus struct {
+	Slug         string `json:"feat"`
+	Num          string `json:"num,omitempty"`
+	Milestone    string `json:"milestone,omitempty"`
+	State        string `json:"state"`
+	TasksTotal   int    `json:"tasks_total,omitempty"`
+	TasksChecked int    `json:"tasks_checked,omitempty"`
+	BlockReason  string `json:"block_reason,omitempty"`
+}
+
+// PlanStatus is the whole-plan derived view: plan-level flags (approval, drift,
+// unprocessed deviations) plus per-feat states, in table order.
+type PlanStatus struct {
+	Slug       string       `json:"plan"`
+	Name       string       `json:"name,omitempty"`
+	Approved   bool         `json:"approved"`
+	Drift      bool         `json:"drift"`
+	Deviations int          `json:"deviations"`
+	Feats      []FeatStatus `json:"feats"`
+}
+
+// DeriveStatus computes the plan-level flags and every feat's state from disk
+// reality. It performs no writes and is deterministic given the workspace.
+func DeriveStatus(root string, doc *PlanDoc) (PlanStatus, error) {
+	dir := Dir(root, doc.Slug)
+	st := PlanStatus{Slug: doc.Slug, Name: doc.Name}
+
+	approved, drift, err := IsApproved(root, doc.Slug)
+	if err != nil {
+		return st, err
+	}
+	st.Approved = approved
+	st.Drift = drift
+	st.Deviations = countDeviations(dir)
+
+	for _, f := range doc.Feats {
+		st.Feats = append(st.Feats, deriveFeatStatus(root, doc.Slug, f))
+	}
+	return st, nil
+}
+
+// deriveFeatStatus resolves a single feat's state. A block marker always wins
+// (an unblock is a runner/human act); otherwise the state follows spec approvals
+// and, once ready, the tasks.md checkbox progress.
+func deriveFeatStatus(root, slug string, f Feat) FeatStatus {
+	fs := FeatStatus{Slug: f.Slug, Num: f.Num, Milestone: f.Milestone}
+
+	if reason, blocked := blockMarker(root, slug, f.Slug); blocked {
+		fs.State = StateBlocked
+		fs.BlockReason = reason
+		return fs
+	}
+
+	specDir := filepath.Join(paths.Specs(root), f.Slug)
+	if _, err := os.Stat(specDir); err != nil {
+		fs.State = StatePending
+		return fs
+	}
+
+	ap := readSpecApprovals(specDir)
+	switch {
+	case !ap["requirements"]:
+		fs.State = StateRequirements
+	case !ap["design"]:
+		fs.State = StateDesign
+	case !ap["tasks"]:
+		fs.State = StateTasks
+	default:
+		total, checked := taskProgress(specDir)
+		fs.TasksTotal, fs.TasksChecked = total, checked
+		switch {
+		case total > 0 && checked == total:
+			fs.State = StateDone
+		case checked > 0:
+			fs.State = StateImplementing
+		default:
+			fs.State = StateReady
+		}
+	}
+	return fs
+}
+
+// readSpecApprovals returns which of the three phases are approved in spec.json.
+// A missing or malformed spec.json yields no approvals (state "requirements"),
+// never a crash — the spec folder exists, so work has begun but nothing is
+// certified.
+func readSpecApprovals(specDir string) map[string]bool {
+	out := map[string]bool{}
+	data, err := os.ReadFile(filepath.Join(specDir, "spec.json"))
+	if err != nil {
+		return out
+	}
+	var doc struct {
+		Approvals map[string]struct {
+			Approved bool `json:"approved"`
+		} `json:"approvals"`
+	}
+	if json.Unmarshal(data, &doc) != nil {
+		return out
+	}
+	for _, p := range workspace.SpecPhases {
+		out[p] = doc.Approvals[p].Approved
+	}
+	return out
+}
+
+// taskProgress counts task checkboxes in tasks.md, reusing the validator's
+// canonical task grammar (validator.TaskLineRe) and fence masking so a fenced
+// example is never miscounted — the same parse the dashboard and lint use.
+func taskProgress(specDir string) (total, checked int) {
+	data, err := os.ReadFile(filepath.Join(specDir, "tasks.md"))
+	if err != nil {
+		return 0, 0
+	}
+	text := validator.MaskCodeFences(textutil.NormalizeNewlines(string(data)))
+	for _, line := range strings.Split(text, "\n") {
+		m := validator.TaskLineRe.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		total++
+		if s := strings.ToLower(strings.TrimSpace(m[2])); s == "x" {
+			checked++
+		}
+	}
+	return total, checked
+}
+
+// stateDir is the transient runner-state directory .csdd/plan/<slug>/ (§2),
+// regenerable and gitignored.
+func stateDir(root, slug string) string {
+	return filepath.Join(paths.State(root), "plan", slug)
+}
+
+// blockMarker reads .csdd/plan/<slug>/blocked/<feat>, returning its reason text
+// and whether the feat is currently blocked.
+func blockMarker(root, slug, feat string) (string, bool) {
+	data, err := os.ReadFile(filepath.Join(stateDir(root, slug), "blocked", feat))
+	if err != nil {
+		return "", false
+	}
+	return strings.TrimSpace(string(data)), true
+}
+
+var reDeviationEntry = regexp.MustCompile(`^##\s+\[\d{4}-\d{2}-\d{2}\].*\|\s*` + regexp.QuoteMeta(VerdictBlocked) + `\s*$`)
+
+// countDeviations counts blocked entries in the run journal (log.md). A blocked
+// entry is a structured deviation the human must fold into the plan and re-approve
+// (principle 5); its presence is surfaced as a plan-level flag (R5.2).
+func countDeviations(dir string) int {
+	data, err := os.ReadFile(filepath.Join(dir, "log.md"))
+	if err != nil {
+		return 0
+	}
+	n := 0
+	for _, line := range strings.Split(textutil.NormalizeNewlines(string(data)), "\n") {
+		if reDeviationEntry.MatchString(strings.TrimRight(line, " \t")) {
+			n++
+		}
+	}
+	return n
+}
diff --git a/internal/plan/status_test.go b/internal/plan/status_test.go
new file mode 100644
index 0000000..f0728c4
--- /dev/null
+++ b/internal/plan/status_test.go
@@ -0,0 +1,179 @@
+package plan
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"testing"
+)
+
+// writeSpec creates specs/<slug>/spec.json with the given approvals and optional
+// tasks.md content, to drive status derivation.
+func writeSpec(t *testing.T, root, slug string, approvals map[string]bool, ready bool, tasksMD string) {
+	t.Helper()
+	spec := map[string]any{
+		"feature_name":             slug,
+		"ready_for_implementation": ready,
+		"approvals":                map[string]any{},
+	}
+	ap := spec["approvals"].(map[string]any)
+	for _, p := range []string{"requirements", "design", "tasks"} {
+		ap[p] = map[string]any{"generated": true, "approved": approvals[p]}
+	}
+	b, _ := json.MarshalIndent(spec, "", "  ")
+	writeFile(t, filepath.Join(root, "specs", slug, "spec.json"), string(b))
+	if tasksMD != "" {
+		writeFile(t, filepath.Join(root, "specs", slug, "tasks.md"), tasksMD)
+	}
+}
+
+func stateOf(st PlanStatus, slug string) string {
+	for _, f := range st.Feats {
+		if f.Slug == slug {
+			return f.State
+		}
+	}
+	return "<absent>"
+}
+
+func TestDeriveStatusAllStates(t *testing.T) {
+	planMD := `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | pend | none | — | M1 | | |
+| 2 | inreq | req | — | M1 | | |
+| 3 | indesign | des | — | M1 | | |
+| 4 | intasks | tsk | — | M1 | | |
+| 5 | ready | rdy | — | M1 | | |
+| 6 | impl | imp | — | M1 | | |
+| 7 | done | dn | — | M1 | | |
+| 8 | blk | blk | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+	root := setupWorkspace(t, "p", planMD)
+
+	// pend: no spec at all (nothing written).
+	// inreq: spec exists, nothing approved.
+	writeSpec(t, root, "inreq", map[string]bool{}, false, "")
+	// indesign: requirements approved only.
+	writeSpec(t, root, "indesign", map[string]bool{"requirements": true}, false, "")
+	// intasks: requirements + design approved.
+	writeSpec(t, root, "intasks", map[string]bool{"requirements": true, "design": true}, false, "")
+	// ready: all approved, no task checked.
+	allApproved := map[string]bool{"requirements": true, "design": true, "tasks": true}
+	writeSpec(t, root, "ready", allApproved, true, "- [ ] 1. Do a thing\n")
+	// impl: all approved, some tasks checked.
+	writeSpec(t, root, "impl", allApproved, true, "- [x] 1. Done\n- [ ] 2. Not yet\n")
+	// done: all approved, every task checked.
+	writeSpec(t, root, "done", allApproved, true, "- [x] 1. Done\n- [x] 2. Also done\n")
+	// blk: has a runner block marker (spec state is irrelevant).
+	writeSpec(t, root, "blk", allApproved, true, "- [x] 1. Done\n")
+	writeFile(t, filepath.Join(stateDir(root, "p"), "blocked", "blk"), "gate failed twice\n")
+
+	doc, err := Load(root, "p")
+	if err != nil {
+		t.Fatal(err)
+	}
+	st, err := DeriveStatus(root, doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := map[string]string{
+		"pend":     StatePending,
+		"inreq":    StateRequirements,
+		"indesign": StateDesign,
+		"intasks":  StateTasks,
+		"ready":    StateReady,
+		"impl":     StateImplementing,
+		"done":     StateDone,
+		"blk":      StateBlocked,
+	}
+	for slug, wantState := range want {
+		if got := stateOf(st, slug); got != wantState {
+			t.Errorf("feat %s: state = %s, want %s", slug, got, wantState)
+		}
+	}
+}
+
+func TestDeriveStatusApprovalAndDrift(t *testing.T) {
+	planMD := `---
+name: p
+status: approved
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+	root := setupWorkspace(t, "p", planMD)
+	dir := Dir(root, "p")
+
+	// Unapproved.
+	doc, _ := Load(root, "p")
+	st, _ := DeriveStatus(root, doc)
+	if st.Approved {
+		t.Errorf("plan should be unapproved before plan.json exists")
+	}
+
+	// Approve at the current hash → approved, no drift.
+	h, err := HashPlan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := SavePlanJSON(dir, PlanJSON{Name: "p", Approvals: PlanApproval{Approved: true, ContentHash: h}}); err != nil {
+		t.Fatal(err)
+	}
+	st, _ = DeriveStatus(root, doc)
+	if !st.Approved || st.Drift {
+		t.Errorf("expected approved & no drift, got approved=%v drift=%v", st.Approved, st.Drift)
+	}
+
+	// Edit plan.md → drift.
+	writeFile(t, filepath.Join(dir, "plan.md"), planMD+"\n<!-- edit -->\n")
+	st, _ = DeriveStatus(root, doc)
+	if !st.Drift {
+		t.Errorf("expected drift after editing plan.md")
+	}
+}
+
+func TestDeriveStatusDeviations(t *testing.T) {
+	planMD := `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+	root := setupWorkspace(t, "p", planMD)
+	writeFile(t, filepath.Join(Dir(root, "p"), "log.md"), `# Run journal
+
+## [2026-07-07] spec-requirements | a | done
+## [2026-07-07] task 1.1 | a | blocked
+## [2026-07-07] task 1.2 | a | blocked
+`)
+	doc, _ := Load(root, "p")
+	st, _ := DeriveStatus(root, doc)
+	if st.Deviations != 2 {
+		t.Errorf("Deviations = %d, want 2", st.Deviations)
+	}
+}
diff --git a/internal/plan/validate.go b/internal/plan/validate.go
new file mode 100644
index 0000000..b5f0a3a
--- /dev/null
+++ b/internal/plan/validate.go
@@ -0,0 +1,436 @@
+package plan
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/glossary"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/textutil"
+	"github.com/protonspy/csdd/internal/validator"
+)
+
+// reFeatSlug is the spec-directory-name grammar a feat slug must satisfy
+// (kebab-case), identical to workspace.KebabCheck's rule but kept local so the
+// finding message is plan-specific.
+var reFeatSlug = regexp.MustCompile(`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`)
+
+// reDependRange matches a numeric range ("1-3") used as dependency shorthand.
+// Feat slugs are kebab-case and start with a letter, so a numeric range or a
+// "a..b" span is never a valid slug — it is the shorthand R2.1 forbids.
+var reDependRange = regexp.MustCompile(`\d+\s*[-–—]\s*\d+`)
+
+// ValidatePlan runs every mechanical check R3 mandates over a parsed plan, plus
+// the grammar issues Parse recorded. root is used to resolve stack:/[[wiki]] refs
+// and to EARS-lint seeds. The returned issues are deterministically ordered so a
+// double run is byte-stable (the approve gate and CI act on a stable list).
+func ValidatePlan(doc *PlanDoc, root string) []validator.Issue {
+	var issues []validator.Issue
+
+	// Grammar issues carried from Parse (table shape, missing columns).
+	for _, g := range doc.grammar {
+		issues = append(issues, validator.Issue{File: "plan.md", Line: g.line, Msg: g.msg})
+	}
+
+	if len(doc.Feats) == 0 {
+		issues = append(issues, validator.Issue{
+			File: "plan.md",
+			Msg:  "plan defines no feats (the '## Feats' table is empty or missing)",
+		})
+	}
+
+	// Feat slugs: validity + uniqueness. Build the set of known slugs for the
+	// dependency-resolution pass below.
+	known := map[string]bool{}
+	seen := map[string]int{}
+	for _, f := range doc.Feats {
+		if !reFeatSlug.MatchString(f.Slug) {
+			issues = append(issues, validator.Issue{
+				File: "plan.md", Line: f.Line,
+				Msg: "invalid feat slug '" + f.Slug + "': must be kebab-case (a valid spec directory name)",
+			})
+		} else {
+			known[f.Slug] = true
+		}
+		if prev, ok := seen[f.Slug]; ok {
+			issues = append(issues, validator.Issue{
+				File: "plan.md", Line: f.Line,
+				Msg: "duplicate feat slug '" + f.Slug + "' (first seen on line " + itoa(prev) + ")",
+			})
+		} else {
+			seen[f.Slug] = f.Line
+		}
+	}
+
+	// Dependencies: range shorthand, then resolution against known feats.
+	for _, f := range doc.Feats {
+		for _, dep := range f.Depends {
+			if reDependRange.MatchString(dep) || strings.Contains(dep, "..") {
+				issues = append(issues, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' Depends uses range shorthand '" + dep + "'; list feat slugs explicitly",
+				})
+				continue
+			}
+			if dep == f.Slug {
+				issues = append(issues, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' depends on itself",
+				})
+				continue
+			}
+			if !known[dep] {
+				issues = append(issues, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' depends on unknown feat '" + dep + "'",
+				})
+			}
+		}
+	}
+
+	// Dependency cycles among feats.
+	for _, cyc := range featCycles(doc) {
+		issues = append(issues, validator.Issue{
+			File: "plan.md",
+			Msg:  "feat dependency cycle: " + strings.Join(cyc, " → "),
+		})
+	}
+
+	// Ref resolution: stack:<name> against docs/stack.md, [[page]] against pages,
+	// adr:<slug> against docs/adr/.
+	decided := decidedTech(root)
+	wikiPages := wikiPageSlugs(root)
+	adrs := ScanADRs(root)
+	for _, f := range doc.Feats {
+		for _, name := range f.StackRefs {
+			if !decided[normalizeTechName(name)] {
+				issues = append(issues, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' references undeclared tech 'stack:" + name + "' (no matching row in docs/stack.md Decided table)",
+				})
+			}
+		}
+		for _, page := range f.WikiRefs {
+			if !wikiPages[normalizeWikiSlug(page)] {
+				issues = append(issues, validator.Issue{
+					File: "plan.md", Line: f.Line,
+					Msg: "feat '" + f.Slug + "' has a broken plan ref '[[" + page + "]]' (no matching page under docs/wiki/pages/)",
+				})
+			}
+		}
+		issues = append(issues, adrRefIssues(f, adrs)...)
+	}
+
+	// docs/adr well-formedness (R3.2), surfaced only WHERE the directory exists.
+	for _, ai := range adrs.issuesResolved() {
+		issues = append(issues, validator.Issue{File: ai.file, Msg: ai.msg})
+	}
+
+	// Glossary: avoided terms in the plan/feat slugs + glossary well-formedness,
+	// surfaced only WHERE docs/glossary.md exists (absent is silent).
+	issues = append(issues, glossaryIssues(root, doc)...)
+
+	// Quality gates presence (R3.3).
+	if len(doc.Gates) == 0 {
+		issues = append(issues, validator.Issue{
+			File: "plan.md",
+			Msg:  "no quality gates declared (the '## Quality Gates' section is empty or missing)",
+		})
+	}
+
+	// EARS lint over each present seed requirements.md (R3.4).
+	issues = append(issues, seedRequirementIssues(root, doc)...)
+
+	sortIssues(issues)
+	return issues
+}
+
+// glossaryIssues lints identifiers against docs/glossary.md (R2): a feat slug or
+// the plan slug carrying an avoided alias as whole token(s) is a finding naming
+// the canonical term, and the glossary's own well-formedness problems (R1.3) are
+// surfaced in the same pass. An absent glossary yields nothing (Load reports
+// not-present).
+func glossaryIssues(root string, doc *PlanDoc) []validator.Issue {
+	gl := glossary.Load(root)
+	if !gl.Present {
+		return nil
+	}
+	var out []validator.Issue
+	avoided := func(slug string, line int) {
+		for _, m := range gl.Match(slug) {
+			if m.Alias == "" {
+				continue // canonical use is correct, not a finding
+			}
+			out = append(out, validator.Issue{
+				File: "plan.md", Line: line,
+				Msg: "avoided term '" + m.Alias + "' in '" + slug + "' — canonical is '" + m.Canonical + "'",
+			})
+		}
+	}
+	avoided(doc.Slug, 0)
+	for _, f := range doc.Feats {
+		avoided(f.Slug, f.Line)
+	}
+	for _, gi := range gl.Issues() {
+		out = append(out, validator.Issue{File: "docs/glossary.md", Line: gi.Line, Msg: gi.Msg})
+	}
+	return out
+}
+
+// featCycles returns the dependency cycles among feats as slug lists, using
+// Tarjan SCC so each cycle is reported once, deterministically.
+func featCycles(doc *PlanDoc) [][]string {
+	adj := map[string][]string{}
+	nodes := map[string]bool{}
+	selfLoop := map[string]bool{}
+	known := map[string]bool{}
+	for _, f := range doc.Feats {
+		known[f.Slug] = true
+	}
+	for _, f := range doc.Feats {
+		for _, dep := range f.Depends {
+			if !known[dep] { // unresolved deps are a separate finding
+				continue
+			}
+			if dep == f.Slug {
+				selfLoop[f.Slug] = true
+			}
+			adj[f.Slug] = append(adj[f.Slug], dep)
+			nodes[f.Slug] = true
+			nodes[dep] = true
+		}
+	}
+	for k := range adj {
+		sort.Strings(adj[k])
+	}
+	var cycles [][]string
+	for _, comp := range tarjanSCC(nodes, adj) {
+		if len(comp) > 1 || (len(comp) == 1 && selfLoop[comp[0]]) {
+			cycles = append(cycles, comp)
+		}
+	}
+	sort.Slice(cycles, func(i, j int) bool {
+		return strings.Join(cycles[i], "\x00") < strings.Join(cycles[j], "\x00")
+	})
+	return cycles
+}
+
+// tarjanSCC returns the strongly-connected components of the dependency graph,
+// each internally sorted, so cycle reporting is deterministic.
+func tarjanSCC(nodes map[string]bool, adj map[string][]string) [][]string {
+	ids := make([]string, 0, len(nodes))
+	for n := range nodes {
+		ids = append(ids, n)
+	}
+	sort.Strings(ids)
+
+	index := 0
+	indices := map[string]int{}
+	low := map[string]int{}
+	onStack := map[string]bool{}
+	var stack []string
+	var out [][]string
+
+	var strongconnect func(v string)
+	strongconnect = func(v string) {
+		indices[v] = index
+		low[v] = index
+		index++
+		stack = append(stack, v)
+		onStack[v] = true
+		for _, w := range adj[v] {
+			if _, ok := indices[w]; !ok {
+				strongconnect(w)
+				if low[w] < low[v] {
+					low[v] = low[w]
+				}
+			} else if onStack[w] && indices[w] < low[v] {
+				low[v] = indices[w]
+			}
+		}
+		if low[v] == indices[v] {
+			var comp []string
+			for {
+				w := stack[len(stack)-1]
+				stack = stack[:len(stack)-1]
+				onStack[w] = false
+				comp = append(comp, w)
+				if w == v {
+					break
+				}
+			}
+			sort.Strings(comp)
+			out = append(out, comp)
+		}
+	}
+	for _, v := range ids {
+		if _, ok := indices[v]; !ok {
+			strongconnect(v)
+		}
+	}
+	return out
+}
+
+// seedRequirementIssues EARS-lints every present seeds/<feat>/requirements.md,
+// reusing the spec validator. Issue paths are rewritten to the seed's workspace
+// path so a finding points at the exact file.
+func seedRequirementIssues(root string, doc *PlanDoc) []validator.Issue {
+	var out []validator.Issue
+	dir := Dir(root, doc.Slug)
+	for _, f := range doc.Feats {
+		seedDir := filepath.Join(seedsDir(dir), f.Slug)
+		if _, err := os.Stat(filepath.Join(seedDir, "requirements.md")); err != nil {
+			continue // seeds are optional; only lint what exists
+		}
+		rel := filepath.ToSlash(filepath.Join("docs", "plans", doc.Slug, "seeds", f.Slug))
+		for _, iss := range validator.ValidateSpec(seedDir, validator.PhaseRequirements) {
+			iss.File = rel + "/" + iss.File
+			out = append(out, iss)
+		}
+	}
+	return out
+}
+
+// StackRow is one row of the docs/stack.md Decided table (a one-line technology
+// contract). The brief inlines it in full (R7.2).
+type StackRow struct {
+	Domain  string
+	Choice  string
+	Version string
+	Why     string
+	Refs    string
+}
+
+// decidedRows parses the Decided table of docs/stack.md into full rows, keyed by
+// the normalized Choice name. A missing contract yields an empty map.
+func decidedRows(root string) map[string]StackRow {
+	out := map[string]StackRow{}
+	data, err := os.ReadFile(paths.Stack(root))
+	if err != nil {
+		return out
+	}
+	lines := strings.Split(textutil.NormalizeNewlines(string(data)), "\n")
+	inDecided := false
+	headerSeen := false
+	for _, raw := range lines {
+		trimmed := strings.TrimSpace(raw)
+		if strings.HasPrefix(trimmed, "## ") {
+			title := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(trimmed, "## ")))
+			inDecided = strings.HasPrefix(title, "decided")
+			headerSeen = false
+			continue
+		}
+		if !inDecided || !strings.HasPrefix(trimmed, "|") {
+			continue
+		}
+		cells := splitCells(trimmed)
+		if isTableSeparator(cells) {
+			continue
+		}
+		if !headerSeen {
+			headerSeen = true // the first row is the column header
+			continue
+		}
+		if len(cells) < 2 {
+			continue
+		}
+		cell := func(i int) string {
+			if i < len(cells) {
+				return strings.TrimSpace(cells[i])
+			}
+			return ""
+		}
+		choice := cell(1)
+		if choice == "" || choice == "—" || choice == "-" {
+			continue
+		}
+		out[normalizeTechName(choice)] = StackRow{
+			Domain: cell(0), Choice: choice, Version: cell(2), Why: cell(3), Refs: cell(4),
+		}
+	}
+	return out
+}
+
+// decidedTech returns the set of normalized Decided choice names (for resolving
+// feat stack: refs during validate).
+func decidedTech(root string) map[string]bool {
+	rows := decidedRows(root)
+	out := make(map[string]bool, len(rows))
+	for k := range rows {
+		out[k] = true
+	}
+	return out
+}
+
+// wikiPageSlugs returns the normalized base names of every page under
+// docs/wiki/pages/, for resolving feat [[wiki-page]] refs.
+func wikiPageSlugs(root string) map[string]bool {
+	out := map[string]bool{}
+	dir := filepath.Join(paths.DocsWiki(root), "pages")
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return out
+	}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+			continue
+		}
+		base := strings.TrimSuffix(e.Name(), ".md")
+		out[normalizeWikiSlug(base)] = true
+	}
+	return out
+}
+
+var reNonAlnum = regexp.MustCompile(`[^a-z0-9]+`)
+var reMajorVersionSeg = regexp.MustCompile(`^v[0-9]+$`)
+
+// normalizeTechName reduces a tech name (a stack: ref or a Decided choice) to a
+// comparable key: the last path segment of a module path (skipping a Go-style
+// vN suffix), the first whitespace/operator-delimited word (dropping a version
+// like "Go 1.22"), lowercased with punctuation stripped. Both sides of the
+// stack-ref check pass through it, so the match is symmetric.
+func normalizeTechName(s string) string {
+	s = strings.ToLower(strings.TrimSpace(s))
+	if strings.Contains(s, "/") {
+		segs := strings.Split(strings.TrimRight(s, "/"), "/")
+		last := segs[len(segs)-1]
+		if reMajorVersionSeg.MatchString(last) && len(segs) > 1 {
+			last = segs[len(segs)-2]
+		}
+		s = last
+	}
+	if f := strings.FieldsFunc(s, func(r rune) bool {
+		return r == ' ' || r == '\t' || r == '@' || r == '=' || r == '>' || r == '<' || r == '~' || r == '^' || r == '!'
+	}); len(f) > 0 {
+		s = f[0]
+	}
+	return reNonAlnum.ReplaceAllString(s, "")
+}
+
+// normalizeWikiSlug reduces a [[wiki-page]] target or a page filename to a
+// comparable slug (lowercased, non-alphanumeric runs to single hyphens).
+func normalizeWikiSlug(s string) string {
+	s = strings.ToLower(strings.TrimSpace(s))
+	if i := strings.LastIndexByte(s, '/'); i >= 0 {
+		s = s[i+1:]
+	}
+	s = strings.TrimSuffix(s, ".md")
+	return strings.Trim(reNonAlnum.ReplaceAllString(s, "-"), "-")
+}
+
+// sortIssues imposes a deterministic order (file, line, message) so validate
+// output is byte-stable across runs.
+func sortIssues(in []validator.Issue) {
+	sort.SliceStable(in, func(i, j int) bool {
+		if in[i].File != in[j].File {
+			return in[i].File < in[j].File
+		}
+		if in[i].Line != in[j].Line {
+			return in[i].Line < in[j].Line
+		}
+		return in[i].Msg < in[j].Msg
+	})
+}
diff --git a/internal/plan/validate_test.go b/internal/plan/validate_test.go
new file mode 100644
index 0000000..35b1ad8
--- /dev/null
+++ b/internal/plan/validate_test.go
@@ -0,0 +1,201 @@
+package plan
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// setupWorkspace lays down a workspace with a stack contract and one wiki page,
+// then writes the given plan.md under docs/plans/<slug>/. It returns the root.
+func setupWorkspace(t *testing.T, slug, planMD string) string {
+	t.Helper()
+	root := t.TempDir()
+	writeFile(t, filepath.Join(root, "docs", "stack.md"), `# Tech contract
+
+## Decided
+
+| Domain | Choice | Version | Why | Refs |
+|---|---|---|---|---|
+| Language | Go | 1.22 | speed | — |
+| HTTP router | chi | v5 | small | — |
+
+## Rules
+`)
+	writeFile(t, filepath.Join(root, "docs", "wiki", "pages", "storage-design.md"), "# Storage Design\n")
+	writeFile(t, filepath.Join(root, "docs", "plans", slug, "plan.md"), planMD)
+	return root
+}
+
+func msgsContain(issues []issueStrings, sub string) bool {
+	for _, i := range issues {
+		if strings.Contains(i.s, sub) {
+			return true
+		}
+	}
+	return false
+}
+
+type issueStrings struct{ s string }
+
+func validateStrings(t *testing.T, root, slug string) []issueStrings {
+	t.Helper()
+	doc, err := Load(root, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out []issueStrings
+	for _, i := range ValidatePlan(doc, root) {
+		out = append(out, issueStrings{i.String()})
+	}
+	return out
+}
+
+func TestValidateClean(t *testing.T) {
+	root := setupWorkspace(t, "photos", `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | stack:go [[storage-design]] |
+| 2 | thumbs | Thumbnails | upload | M1 | P | stack:chi |
+
+## Quality Gates
+
+- verify: make check
+`)
+	issues := validateStrings(t, root, "photos")
+	if len(issues) != 0 {
+		t.Fatalf("expected clean plan, got issues: %v", issues)
+	}
+}
+
+func TestValidateUnknownDepAndCycle(t *testing.T) {
+	root := setupWorkspace(t, "p", `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | b | M1 | | |
+| 2 | b | B | a | M1 | | |
+| 3 | c | C | ghost | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`)
+	issues := validateStrings(t, root, "p")
+	if !msgsContain(issues, "depends on unknown feat 'ghost'") {
+		t.Errorf("missing unknown-dep finding: %v", issues)
+	}
+	if !msgsContain(issues, "feat dependency cycle") {
+		t.Errorf("missing cycle finding: %v", issues)
+	}
+}
+
+func TestValidateRefsAndGates(t *testing.T) {
+	root := setupWorkspace(t, "p", `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | stack:redis [[missing-page]] |
+`)
+	issues := validateStrings(t, root, "p")
+	if !msgsContain(issues, "undeclared tech 'stack:redis'") {
+		t.Errorf("missing undeclared-tech finding: %v", issues)
+	}
+	if !msgsContain(issues, "broken plan ref '[[missing-page]]'") {
+		t.Errorf("missing broken-ref finding: %v", issues)
+	}
+	if !msgsContain(issues, "no quality gates declared") {
+		t.Errorf("missing empty-gates finding: %v", issues)
+	}
+}
+
+func TestValidateDupAndInvalidSlugAndRange(t *testing.T) {
+	root := setupWorkspace(t, "p", `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | good | A | — | M1 | | |
+| 2 | good | dup | — | M1 | | |
+| 3 | Bad_Slug | invalid | — | M1 | | |
+| 4 | ranged | R | 1-3 | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`)
+	issues := validateStrings(t, root, "p")
+	if !msgsContain(issues, "duplicate feat slug 'good'") {
+		t.Errorf("missing duplicate finding: %v", issues)
+	}
+	if !msgsContain(issues, "invalid feat slug 'Bad_Slug'") {
+		t.Errorf("missing invalid-slug finding: %v", issues)
+	}
+	if !msgsContain(issues, "range shorthand '1-3'") {
+		t.Errorf("missing range finding: %v", issues)
+	}
+}
+
+func TestValidateSeedEARS(t *testing.T) {
+	root := setupWorkspace(t, "p", `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | — | M1 | | |
+
+## Quality Gates
+
+- verify: make check
+`)
+	// A seed requirements.md with a numbered criterion that lacks EARS structure.
+	writeFile(t, filepath.Join(root, "docs", "plans", "p", "seeds", "a", "requirements.md"),
+		"### Requirement 1: Thing\n\n**Acceptance Criteria**\n\n1. The user clicks the button and it should work.\n")
+	issues := validateStrings(t, root, "p")
+	if !msgsContain(issues, "docs/plans/p/seeds/a/requirements.md") {
+		t.Errorf("seed EARS finding should be path-qualified: %v", issues)
+	}
+}
+
+func TestValidateDeterministic(t *testing.T) {
+	root := setupWorkspace(t, "p", `---
+name: p
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | a | A | ghost | M1 | | stack:redis |
+| 2 | b | B | zzz | M1 | | [[nope]] |
+`)
+	a := validateStrings(t, root, "p")
+	b := validateStrings(t, root, "p")
+	if len(a) != len(b) {
+		t.Fatalf("nondeterministic count %d vs %d", len(a), len(b))
+	}
+	for i := range a {
+		if a[i].s != b[i].s {
+			t.Errorf("nondeterministic order at %d: %q vs %q", i, a[i].s, b[i].s)
+		}
+	}
+}
diff --git a/internal/templater/templates/commands/csdd-plan-run.md.tmpl b/internal/templater/templates/commands/csdd-plan-run.md.tmpl
new file mode 100644
index 0000000..7cf9f47
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-plan-run.md.tmpl
@@ -0,0 +1,23 @@
+---
+description: Drive a csdd plan's autonomous loop — fresh sessions per step, gated and committed by the runner. Requires an approved, drift-free plan.
+argument-hint: <plan-slug> [--autonomous]
+allowed-tools: Bash(csdd plan run:*), Bash(csdd plan status:*), Bash(npx @protonspy/csdd plan:*)
+---
+
+## Task
+
+Drive the plan in `$ARGUMENTS` through `csdd plan run`.
+
+Preflight first: `csdd plan status <slug>` must show the plan **approved** and
+**drift-free** (no unprocessed deviations you haven't reviewed). Then:
+
+- **Supervised (default):** `csdd plan run <slug>` — the runner spawns a session
+  per step with `--permission-mode acceptEdits`, runs the gates, and approves/
+  commits only on green.
+- **Autonomous:** `csdd plan run <slug> --autonomous` — ONLY inside the hardened
+  sandbox. `csdd sandbox doctor` must pass first; the runner refuses to pass
+  `--dangerously-skip-permissions` otherwise.
+
+The runner owns approvals and commits. If it records a `blocked` deviation, do not
+patch the plan mid-run — take it to the `prd` skill's Revise workflow and
+re-approve.
diff --git a/internal/templater/templates/commands/csdd-plan-status.md.tmpl b/internal/templater/templates/commands/csdd-plan-status.md.tmpl
new file mode 100644
index 0000000..9ab394d
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-plan-status.md.tmpl
@@ -0,0 +1,13 @@
+---
+description: Show a csdd plan's derived status — per-feat state (pending/…/done/blocked), approval, drift, and unprocessed deviations.
+argument-hint: <plan-slug>
+allowed-tools: Bash(csdd plan status:*), Bash(npx @protonspy/csdd plan status:*)
+---
+
+## Task
+
+Run `csdd plan status $ARGUMENTS` and summarize: which feats are done, in
+progress, pending, or blocked; whether the plan is approved and drift-free; and
+whether `log.md` holds unprocessed deviations (which route to the `prd` skill's
+Revise workflow). State is derived from `specs/` reality — there is nothing to
+edit here.
diff --git a/internal/templater/templates/commands/csdd-plan-validate.md.tmpl b/internal/templater/templates/commands/csdd-plan-validate.md.tmpl
new file mode 100644
index 0000000..e45065c
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-plan-validate.md.tmpl
@@ -0,0 +1,11 @@
+---
+description: Lint a csdd plan — feat-table grammar, dependency cycles, undeclared tech, broken refs, missing quality gates, and EARS over seeds.
+argument-hint: <plan-slug>
+allowed-tools: Bash(csdd plan validate:*), Bash(npx @protonspy/csdd plan validate:*)
+---
+
+## Task
+
+Run `csdd plan validate $ARGUMENTS` and report the findings. Exit non-zero means
+the plan is not ready to approve — walk each finding and fix `plan.md` (or the
+seeds), then re-run. Do not approve a plan with open findings.
diff --git a/internal/templater/templates/commands/glossary.md.tmpl b/internal/templater/templates/commands/glossary.md.tmpl
new file mode 100644
index 0000000..4605dce
--- /dev/null
+++ b/internal/templater/templates/commands/glossary.md.tmpl
@@ -0,0 +1,22 @@
+---
+description: Own the project's ubiquitous language — challenge, sharpen, and record canonical domain terms (and their banned synonyms) in docs/glossary.md, so identifiers and prose speak one language.
+argument-hint: <the term or terminology question, e.g. "is it customer or client?">
+allowed-tools: Read, Edit, Write, Bash(csdd graph:*), Bash(csdd plan:*), Bash(csdd wiki:*), Bash(npx @protonspy/csdd:*)
+---
+
+## Task
+
+Use the **glossary** skill to resolve the terminology in `$ARGUMENTS` into the
+project's ubiquitous-language contract at `docs/glossary.md`.
+
+Apply its four moves — **challenge** a term that conflicts with an existing entry,
+**sharpen** a vague or overloaded term to one canonical form (recommend, the human
+decides), **stress-test** the boundary with concrete scenarios, and
+**cross-reference** via `csdd graph query` before asking. Record each resolved term
+**inline the moment it resolves** (creating `docs/glossary.md` lazily on the first
+entry) with a tight what-it-IS definition and an `_Avoid_` list; on a rename,
+append the old term to the successor's `_Avoid_` (the tombstone rule).
+
+Keep it a contract, not documentation: project-specific terms only, zero
+implementation detail. When a naming choice is itself a gate-positive decision,
+hand it to the decision grill (`/prd` or `quick-prd`) and let the ADR cite the term.
diff --git a/internal/templater/templates/commands/prd.md.tmpl b/internal/templater/templates/commands/prd.md.tmpl
new file mode 100644
index 0000000..4b70728
--- /dev/null
+++ b/internal/templater/templates/commands/prd.md.tmpl
@@ -0,0 +1,29 @@
+---
+description: Author a csdd plan for a multi-feature initiative — runs the PRD skill (Draft → Research → Stack → Decompose → validate) and ends at a lint-clean plan for you to approve.
+argument-hint: <the initiative, e.g. "photo albums with sharing and search">
+allowed-tools: Read, Edit, Write, Bash(csdd plan:*), Bash(csdd graph:*), Bash(csdd wiki:*), Bash(npx @protonspy/csdd:*)
+---
+
+## Task
+
+Use the **prd** skill to turn the initiative in `$ARGUMENTS` into an approved csdd
+plan under `docs/plans/<slug>/`.
+
+Run its five passes in order — **Draft** (a **two-tier** interview: batched
+multiple-choice for scope facts, then a one-at-a-time **Decision grill** for every
+load-bearing decision that passes the triple gate — hard to reverse + surprising +
+real trade-off — each recorded the moment it resolves as `docs/adr/NNNN-<slug>.md`),
+**Research** (current docs → wiki pages, cited in Refs), **Stack consult** (the
+`stack` skill's Propose for any new tech — the human decides), **Decompose** (the
+`## Feats` table, one feat = one spec, citing decisions as `adr:<slug>`), and
+**Present** (sweep every gate-positive `[ASSUMPTION]` into an ADR or
+`[DEFERRED-BY-HUMAN]`) — scaffolding with `csdd plan init` and running
+`csdd plan validate` after every authoring pass.
+
+Author only. Do **not** run `csdd plan approve`, `csdd plan generate`, or
+`csdd plan run`, and do not write `plan.json`, `docs/graph/`, or `.csdd/`. End by
+showing the validated feat table and telling the user to run
+`csdd plan approve <slug>` themselves.
+
+For a single feature, use `/quick-prd` instead — its PRD is an input to Draft, not
+a plan.
diff --git a/internal/templater/templates/plan/plan.md.tmpl b/internal/templater/templates/plan/plan.md.tmpl
new file mode 100644
index 0000000..f9c9abd
--- /dev/null
+++ b/internal/templater/templates/plan/plan.md.tmpl
@@ -0,0 +1,64 @@
+---
+name: {{.Name}}
+status: draft
+---
+
+# {{.Name}} — Plan
+
+<!--
+This is a csdd PLAN: the structured document ABOVE specs. It decomposes an
+initiative into FEATS, where each feat becomes exactly one spec in specs/.
+Author the prose freely; the three sections below (## Feats, ## Quality Gates,
+## Executor Notes) are machine-parsed and linted by `csdd plan validate`. Two
+human gates bracket the whole flow — `csdd plan approve` before autonomous work,
+the pull request after — and everything between is contract-checked machine work.
+Do not fill in choices you have not made; the structure is provided, the
+decisions are yours.
+-->
+
+## Context and vision
+
+<!-- What are we building, and why now? Free prose; the parser ignores it. -->
+
+## Feats
+
+<!--
+One row per feat. A feat = one spec = a short session chain of work. Keep each
+feat small enough that a fresh session can carry it through requirements →
+design → tasks → implementation. Columns (all required, matched by header name):
+
+  #          display order
+  Feat       kebab-case slug — becomes the spec directory name
+  Objective  one line: the outcome this feat delivers
+  Depends    comma-separated feat slugs that must be `done` first (— for none;
+             range shorthand like `1-3` is a validation error — list slugs)
+  Milestone  grouping label (e.g. M1); feats run in milestone then table order
+  (P)        `P` if this feat MAY run in parallel with its milestone siblings
+             (v1 honors the marker for ordering only)
+  Refs       whitespace-separated [[wiki-page]], stack:<name>, and adr:<slug>
+             tokens; each stack:<name> must match a docs/stack.md Decided row,
+             each [[wiki-page]] a page under docs/wiki/pages/, and each
+             adr:<slug> a decision record docs/adr/NNNN-<slug>.md (the why this
+             feat depends on — inlined in full into its run brief)
+-->
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+<!-- | 1 | example-feat | Deliver the thing | — | M1 | | stack:go [[design-notes]] adr:pick-store | -->
+
+## Quality Gates
+
+<!--
+The plan's own verification contract: `- <label>: <command>` lines. The runner
+executes every gate after each implementation step; a red gate blocks advance.
+At least one gate is required for the plan to validate.
+-->
+
+<!-- - verify: make check -->
+
+## Executor Notes
+
+<!--
+Opaque guidance passed verbatim into every session brief: repo conventions,
+workstation quirks, commit rules. Keep it short and imperative.
+-->
diff --git a/internal/templater/templates/root/knowledge-section.md.tmpl b/internal/templater/templates/root/knowledge-section.md.tmpl
index 4312a8c..47d6d42 100644
--- a/internal/templater/templates/root/knowledge-section.md.tmpl
+++ b/internal/templater/templates/root/knowledge-section.md.tmpl
@@ -30,3 +30,43 @@ this.
 enter the project; `csdd graph analyze` reports a tech finding
 (`undeclared`/`phantom`/`unrefined`); or the user mentions adopting or changing
 technology.
+
+**Decision records (`docs/adr/`) capture the why.** A decision that passes the
+**triple gate** — **hard to reverse**, **surprising without context**, **the result
+of a real trade-off** — becomes an ADR at `docs/adr/NNNN-<slug>.md` (append-only,
+project-scoped; a `# <title>` heading then 1–3 sentences). Feats cite it as
+`adr:<slug>` in their `Refs`, `csdd plan validate` breaks on a broken/ambiguous/
+superseded citation, and the record is inlined into every run brief for the feats
+that cite it. **Never decide silently** — a gate-positive decision with no ADR is an
+open decision, not an improvisation. **Never edit a superseded record** — mark it
+`status: superseded` / `superseded-by: <NNNN>` and write its successor. A decision
+that fails the gate is prose, never an ADR (that is what stops ADR spam). The
+`/prd` and `quick-prd` skills own recording the decision the moment it resolves.
+
+**The glossary (`docs/glossary.md`) is the ubiquitous language.** Each domain
+concept has one **canonical term** with a tight definition and an `_Avoid_` list of
+banned synonyms. Identifiers — feat slugs, spec directories, wiki page names — are
+minted from canonical terms; `csdd plan validate`, `csdd graph analyze`, and
+`csdd wiki lint` report an avoided term used as a whole token. **When a domain term
+is contested or fuzzy, invoke the `glossary` skill** — challenge it, sharpen it to
+one canonical form, and record it inline (the file is created lazily on the first
+term). **Never rename a term without its tombstone**: append the old term to the
+successor's `_Avoid_` list in the same edit so the old name stays banned forever.
+
+**Plan mode — the layer above specs.** A **plan** (`docs/plans/<slug>/`) decomposes
+an initiative into **feats**, each becoming exactly one spec.
+
+- **Run `/prd` before multi-feature work.** Anything that spans more than one spec
+  starts as a plan: `/prd` (the PRD skill) interviews, researches, consults the
+  stack, decomposes into feats, and lints with `csdd plan validate` — ending at a
+  validated plan for you to `csdd plan approve`. A single feature stays on the
+  lighter `quick-prd` on-ramp.
+- **Never edit an approved plan, and never execute approvals, during a run.**
+  `csdd plan run` is csdd-controlled: the runner owns `csdd spec approve`, commits,
+  and every write to `plan.md`/`plan.json`/`docs/graph/`/`.csdd/`. A session that
+  touches those is a hard failure. Approval is bound to a content hash — any edit
+  is drift and pauses autonomy until re-approval.
+- **Deviations go through Revise, not improvisation.** When a step hits an
+  unforeseen problem, return a `blocked` verdict with a revision proposal; folding
+  it into the plan and re-approving is the PRD skill's **Revise** workflow — a
+  human act, never a silent workaround.
diff --git a/internal/templater/templates/sandbox/Dockerfile.tmpl b/internal/templater/templates/sandbox/Dockerfile.tmpl
new file mode 100644
index 0000000..29cd65c
--- /dev/null
+++ b/internal/templater/templates/sandbox/Dockerfile.tmpl
@@ -0,0 +1,36 @@
+# csdd sandbox — hardened, language-agnostic devcontainer image.
+#
+# Base is the official devcontainers Ubuntu image (ships a non-root `vscode`
+# user). NO language runtime is installed here: Node (for Claude Code), Go,
+# Python, etc. arrive as devcontainer features so the image stays neutral and
+# every project pins its own toolchain via `csdd sandbox init --feature <name>`.
+FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04
+
+# HARDENED restricts the vscode user's sudo to ONLY the firewall script (no
+# general root). It is the recommended build for unattended
+# `csdd plan run --autonomous`; the default keeps broad sudo for interactive use.
+ARG HARDENED=false
+
+# Firewall + resolver tooling. iptables/ipset enforce the default-deny egress;
+# dnsutils/curl/jq resolve and verify the allow-list.
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+ && apt-get install -y --no-install-recommends \
+      iptables ipset dnsutils curl jq ca-certificates \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Install the default-deny firewall and its allow-list.
+COPY init-firewall.sh /usr/local/bin/init-firewall.sh
+COPY allowed-domains.txt /etc/csdd/allowed-domains.txt
+RUN chmod +x /usr/local/bin/init-firewall.sh
+
+# Sudo policy. The firewall must run as root at container start; HARDENED limits
+# sudo to exactly that command so a bypass-mode session cannot escalate to a
+# general root shell and reprogram egress.
+RUN if [ "$HARDENED" = "true" ]; then \
+      echo 'vscode ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh' > /etc/sudoers.d/csdd-firewall ; \
+    else \
+      echo 'vscode ALL=(root) NOPASSWD: ALL' > /etc/sudoers.d/csdd-firewall ; \
+    fi \
+ && chmod 0440 /etc/sudoers.d/csdd-firewall
+
+USER vscode
diff --git a/internal/templater/templates/sandbox/allowed-domains.txt.tmpl b/internal/templater/templates/sandbox/allowed-domains.txt.tmpl
new file mode 100644
index 0000000..cfb240d
--- /dev/null
+++ b/internal/templater/templates/sandbox/allowed-domains.txt.tmpl
@@ -0,0 +1,36 @@
+# csdd sandbox — egress allow-list.
+# One host per line; blank lines and #-comments are ignored. init-firewall.sh
+# resolves each host to its current IPv4 addresses and permits ONLY those.
+# Keep this list minimal: every entry widens what a bypass-mode session can reach.
+
+# --- Anthropic / Claude Code ---
+api.anthropic.com
+statsig.anthropic.com
+sentry.io
+
+# --- GitHub ---
+github.com
+api.github.com
+codeload.github.com
+objects.githubusercontent.com
+ghcr.io
+
+# --- npm (Claude Code runtime + tooling) ---
+registry.npmjs.org
+
+# --- VS Code / devcontainers ---
+update.code.visualstudio.com
+marketplace.visualstudio.com
+
+# --- Ubuntu apt ---
+archive.ubuntu.com
+security.ubuntu.com
+ports.ubuntu.com
+
+# --- Language registry presets ---
+# `csdd sandbox init --feature <name>` un-comments the matching registries below
+# (or add hosts with --allow-domain). Left commented, they stay blocked.
+# [go]     proxy.golang.org sum.golang.org
+# [python] pypi.org files.pythonhosted.org
+# [rust]   static.crates.io crates.io index.crates.io
+# [java]   repo.maven.apache.org
diff --git a/internal/templater/templates/sandbox/devcontainer.json.tmpl b/internal/templater/templates/sandbox/devcontainer.json.tmpl
new file mode 100644
index 0000000..3272095
--- /dev/null
+++ b/internal/templater/templates/sandbox/devcontainer.json.tmpl
@@ -0,0 +1,25 @@
+// csdd sandbox — devcontainer definition (JSONC; comments are allowed).
+// Open with your IDE's "Reopen in Container", or `devcontainer up`. Inside,
+// bypass-mode Claude is safe: `csdd sandbox doctor` proves isolation and
+// `csdd plan run --autonomous` refuses to pass --dangerously-skip-permissions
+// unless it does.
+{
+  "name": "csdd-sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    // HARDENED=true limits the vscode user's sudo to the firewall script only.
+    "args": { "HARDENED": "{{.Hardened}}" }
+  },
+  // NET_ADMIN/NET_RAW let init-firewall.sh program iptables/ipset at start.
+  "runArgs": ["--cap-add=NET_ADMIN", "--cap-add=NET_RAW"],
+  "remoteUser": "vscode",
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/node:1": {}{{.ExtraFeatures}}
+  },
+  // Install Claude Code (Node feature provides the runtime).
+  "postCreateCommand": "npm install -g @anthropic-ai/claude-code",
+  // Bring up the default-deny egress firewall on every start; it self-verifies
+  // and exits non-zero if isolation is not enforced.
+  "postStartCommand": "sudo /usr/local/bin/init-firewall.sh"
+}
diff --git a/internal/templater/templates/sandbox/init-firewall.sh.tmpl b/internal/templater/templates/sandbox/init-firewall.sh.tmpl
new file mode 100644
index 0000000..2c2558b
--- /dev/null
+++ b/internal/templater/templates/sandbox/init-firewall.sh.tmpl
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# csdd sandbox — default-deny egress firewall with self-verification.
+#
+# Resolves every host in the allow-list to its current IPv4 addresses and permits
+# ONLY those (plus loopback, DNS, and established return traffic); all other
+# outbound traffic is dropped. It then PROVES isolation: a control host must be
+# unreachable and api.anthropic.com reachable, or it exits non-zero so
+# `csdd sandbox doctor` (and `plan run --autonomous`) refuse to proceed.
+set -euo pipefail
+
+ALLOWLIST="${1:-/etc/csdd/allowed-domains.txt}"
+CONTROL_HOST="${CSDD_FIREWALL_CONTROL_HOST:-example.com}"  # not allow-listed → must be blocked
+
+log() { echo "[csdd-firewall] $*"; }
+
+if [ ! -r "$ALLOWLIST" ]; then
+  echo "[csdd-firewall] FAIL: allow-list not found: $ALLOWLIST" >&2
+  exit 1
+fi
+
+log "flushing existing rules"
+iptables -F
+iptables -X 2>/dev/null || true
+ipset destroy csdd-allow 2>/dev/null || true
+ipset create csdd-allow hash:ip
+
+# Loopback and DNS first — DNS is needed to resolve the allow-list itself.
+iptables -A OUTPUT -o lo -j ACCEPT
+iptables -A INPUT  -i lo -j ACCEPT
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
+# Established/related return traffic.
+iptables -A INPUT  -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+log "resolving allow-list -> ipset"
+while IFS= read -r raw; do
+  host="${raw%%#*}"                       # strip inline comments
+  host="$(echo "$host" | tr -d '[:space:]')"
+  [ -z "$host" ] && continue
+  for ip in $(getent ahostsv4 "$host" | awk '{print $1}' | sort -u); do
+    ipset add csdd-allow "$ip" 2>/dev/null || true
+  done
+done < "$ALLOWLIST"
+
+iptables -A OUTPUT -m set --match-set csdd-allow dst -j ACCEPT
+
+# Default-deny everything else.
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+log "verifying isolation"
+if curl -sS --max-time 5 "https://${CONTROL_HOST}" >/dev/null 2>&1; then
+  echo "[csdd-firewall] FAIL: control host ${CONTROL_HOST} reachable — egress not enforced" >&2
+  exit 1
+fi
+if ! curl -sS --max-time 5 https://api.anthropic.com >/dev/null 2>&1; then
+  echo "[csdd-firewall] FAIL: api.anthropic.com unreachable — allow-list too strict" >&2
+  exit 1
+fi
+log "OK: egress restricted to the allow-list"
diff --git a/internal/templater/templates/skills/glossary/SKILL.md.tmpl b/internal/templater/templates/skills/glossary/SKILL.md.tmpl
new file mode 100644
index 0000000..2b2b291
--- /dev/null
+++ b/internal/templater/templates/skills/glossary/SKILL.md.tmpl
@@ -0,0 +1,109 @@
+---
+name: glossary
+description: Own the project's ubiquitous language — the canonical terms and their banned synonyms in docs/glossary.md. Use when a domain term is coined, contested, fuzzy, or renamed; when naming a feat/spec/wiki identifier; or when another skill (prd, quick-prd, wiki) surfaces a terminology conflict. You author the contract; the CLI parses, lints identifiers, and graphs it. Invoked by /glossary.
+---
+
+# Glossary — the ubiquitous-language contract
+
+## Goal
+
+Keep the project speaking **one language**: every domain concept has exactly one
+**canonical term** with a tight definition and an `_Avoid_` list of the synonyms it
+bans, recorded in `docs/glossary.md`. Terminology drift is the quietest project
+rot — the plan says "customer", a spec says "client", a wiki page says "account",
+and the graph (which links by name) sees three unrelated things. You author the
+contract; the **CLI parses and lints** it (`csdd plan validate` on feat/plan
+slugs, `csdd graph analyze` / `csdd wiki lint` on spec dirs and wiki pages) and
+graphs terms as `term` nodes — it never writes prose.
+
+## The Iron Law
+
+> **The glossary is a contract, not documentation.** One canonical term per
+> concept, a one-or-two-sentence definition of what it **IS** (never what it does),
+> project-specific terms only, **zero implementation details**. Identifiers are
+> minted from canonical terms; a renamed term always leaves a tombstone. Record
+> the term the moment it resolves — never batch, never guess.
+
+## When to Use
+
+- A domain term is **coined, contested, or fuzzy** — challenge and sharpen it here.
+- You are **naming** a feat slug, spec directory, or wiki page — mint it from a
+  canonical term (validate/analyze enforce this).
+- Another skill (`prd`, `quick-prd`, `wiki`) surfaces a terminology conflict and
+  routes it here.
+- A canonical term is being **renamed** — apply the tombstone rule.
+
+## Execution Workflow
+
+The four moves. Judgment is yours; the CLI supplies the structure and the lint.
+
+1. **Challenge.** The moment a term appears that conflicts with an existing entry
+   (a synonym for a canonical term, or a second meaning for one word), stop and
+   name the conflict. Do not let two words for one concept coexist.
+2. **Sharpen.** For a vague or overloaded term, propose a single canonical form
+   with a **recommended answer** (the decision-grill interaction form: one term, a
+   recommendation, the human decides) and a one-or-two-sentence definition of what
+   it IS. Push synonyms onto its `_Avoid_` list.
+3. **Stress-test.** Probe the boundary with concrete edge-case scenarios ("is a
+   cancelled order still an Order?") until the definition holds or splits into two
+   canonical terms.
+4. **Cross-reference before asking.** Run `csdd graph query "<term>"` (the graph
+   already indexes the workspace) to see where a concept is used before asking the
+   user — source facts, grill only the genuine ambiguity.
+
+**Record inline, create lazily.** When a term resolves, update `docs/glossary.md`
+**immediately** (never batched), creating the file on the first entry — `csdd`
+scaffolds nothing. An entry is:
+
+```
+## Language
+
+**<Canonical Term>**: One or two sentences — what it IS, not what it does.
+_Avoid_: synonym-one, synonym-two
+```
+
+Use `###` subheadings to cluster entries when natural groups emerge.
+
+**The tombstone rule (the term lifecycle).** When a canonical term is renamed,
+append the **old** term to the **successor's** `_Avoid_` list in the **same edit**.
+The lint then patrols the old name forever — the rename is mechanically permanent,
+no state machine required.
+
+**Hand off gate-positive naming.** When a naming choice is itself a decision that
+passes the triple gate — a deliberate concept split, or diverging from industry
+vocabulary on purpose (hard to reverse + surprising + a real trade-off) — hand it
+to the **decision grill** (`prd`/`quick-prd`) and let the ADR **cite the term**.
+The two contracts compose: *what we call it* → glossary; *why we chose it* → ADR.
+
+## Gotchas
+
+- **Not documentation.** General programming concepts and how-things-work prose do
+  not belong — only terms unique to this project's domain, defined as what they are.
+- **Whole-token lint, identifiers only.** The linter bites on feat/spec/wiki
+  identifiers where matching is deterministic; prose drift is **your** job
+  (challenge/sharpen), never the linter's. An alias too generic to ban (it would
+  cry wolf) should be deleted, not tolerated.
+- **Never rename without a tombstone.** A rename that skips the `_Avoid_` append
+  lets the old name creep back in silently.
+- **Never batch.** A glossary written at the end of a session is a glossary of
+  guesses; record each term the moment it resolves.
+- **The CLI owns `docs/graph/`.** Rebuild with `csdd graph build` after editing the
+  glossary so term nodes reflect the change.
+
+## Verification Before Reporting
+
+- `csdd plan validate <slug>` (if a plan is in play) and `csdd graph analyze` are
+  clean of avoided-term and glossary well-formedness findings, or every finding is
+  explicitly acknowledged to the human.
+- Every new/renamed term has a one-or-two-sentence definition of what it IS, an
+  `_Avoid_` list where synonyms exist, and — for a rename — the old term
+  tombstoned onto the successor.
+- No entry carries implementation detail or restates a general programming concept.
+
+## Completion Criteria
+
+- [ ] Every contested/fuzzy term was challenged and sharpened to one canonical form; conflicts were resolved, not left coexisting.
+- [ ] `docs/glossary.md` was updated inline the moment each term resolved (created lazily on the first entry), with tight what-it-IS definitions and `_Avoid_` lists.
+- [ ] Every rename left a tombstone (old term appended to the successor's `_Avoid_`).
+- [ ] `csdd graph query` was consulted before asking the user; gate-positive naming was handed to the decision grill with the ADR citing the term.
+- [ ] `csdd plan validate` / `csdd graph analyze` / `csdd wiki lint` are clean of avoided-term and glossary findings (or acknowledged).
diff --git a/internal/templater/templates/skills/prd/SKILL.md.tmpl b/internal/templater/templates/skills/prd/SKILL.md.tmpl
new file mode 100644
index 0000000..633e234
--- /dev/null
+++ b/internal/templater/templates/skills/prd/SKILL.md.tmpl
@@ -0,0 +1,177 @@
+---
+name: prd
+description: Turn an initiative that spans MULTIPLE features into an approved csdd plan (docs/plans/<slug>/) — a feat table where each feat becomes exactly one spec. Runs the whole authoring pipeline through the CLI (Draft → Research → Stack consult → Decompose → lint), scaffolding with `csdd plan init` and linting with `csdd plan validate` after every pass, and ends by presenting a validated plan for the human `csdd plan approve`. Use for big work that decomposes into many specs; use quick-prd for a single feature.
+---
+
+# PRD — author a csdd plan
+
+## Goal
+
+Turn a multi-feature initiative into a **validated plan** at
+`docs/plans/<slug>/plan.md`: a `## Feats` table where each feat becomes exactly
+one spec, with explicit dependencies, milestones, quality gates, and per-feat
+seeds. You author the prose and the feat table; the **CLI owns every mechanical
+step** (`csdd plan init` / `validate`, or `npx @protonspy/csdd plan …`). You never
+write `plan.json`, `docs/graph/`, or `.csdd/`, and you never approve — the skill
+ends by handing a lint-clean plan to the human for `csdd plan approve`.
+
+## The Iron Law
+
+> **The plan is a contract. Every feat is one spec-sized chunk, every dependency
+> is explicit, every technology is a `docs/stack.md` Decided row, and the plan
+> lints clean before you present it. Author only — never approve, never run the
+> loop, never write plan.json/graph/state.**
+
+## When to Use
+
+- **Use** for an initiative that decomposes into **multiple specs** (a subsystem,
+  a milestone-sized effort, anything a single `requirements.md` can't hold).
+- **Not** for one feature — use `quick-prd` (its `docs/product/prd-<feature>.md`
+  is an accepted *input* to this skill's Draft step).
+- **Not** to execute the plan — that is `csdd plan run` (supervised or, inside a
+  sandbox, `--autonomous`), which this skill never triggers.
+
+## Collect Inputs First
+
+- The initiative in the user's words, plus any `quick-prd` PRD under
+  `docs/product/` that seeds it.
+- Steering (`product.md`, `tech.md`, `structure.md`), `docs/stack.md`, and the
+  existing `specs/` — source facts; do not re-ask what is recorded.
+- The workspace marker: run inside a `csdd init`-ed project (`.csdd/` present).
+
+## Execution Workflow
+
+Run the five passes in order. **After every pass that edits `plan.md` or seeds,
+run `csdd plan validate <slug>` and fix findings before continuing.**
+
+### 1) Draft — interview in two tiers, then frame
+Scaffold first: `csdd plan init <slug>` (kebab-case). Draft runs in **two tiers**:
+first batch the scope facts, then grill the load-bearing decisions.
+
+**Tier 1 — scope facts (batched).** Interview the user with **batched, lettered
+multiple-choice questions** (via the harness question tool) so they answer fast
+("1B, 2A, 3C"). Cover: the outcome (problem, not solution), primary users and
+non-users, the core capabilities v1 must deliver, scope boundaries, and success
+criteria. Write the plan's **Context and vision** prose and the goals/non-goals
+from the *recorded answers* — mark every gap `[ASSUMPTION]`.
+
+**Tier 2 — the Decision grill (one at a time).** Some choices are not scope facts
+but **decisions**. Put every candidate through the **triple gate** — record it as
+an ADR only when **all three** hold:
+
+> 1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+> 2. **Surprising without context** — a future reader will ask "why this way?".
+> 3. **The result of a real trade-off** — there were genuine alternatives.
+>
+> If any one is missing it is prose or a cheap `[ASSUMPTION]`, never an ADR.
+> (Contrapositive: if it's easy to reverse you'll just reverse it; if it's not
+> surprising nobody will wonder; if there was no alternative there's nothing to
+> record.) This gate is what designs out ADR spam.
+
+For every gate-positive candidate, run the **grill**:
+- **One decision per exchange.** Never bundle decisions into the batch — scope
+  facts are batched, decisions are grilled.
+- **Recommendation first.** State your recommended answer and the trade-off, then
+  let the **human decide** (grilling's form; facts come from the repo, decisions
+  from the user).
+- **Dependency order.** Order the grill so a decision that unblocks other
+  decisions is asked first.
+- **Write the ADR the moment it resolves.** Scan `docs/adr/` for the highest
+  number, add 1, and write `docs/adr/NNNN-<slug>.md` immediately — a `# <title>`
+  heading then 1–3 sentences (context, decision, why). Never batch the writes;
+  never renumber an existing record.
+- **Look up, don't ask.** Anything recoverable from steering, `docs/stack.md`,
+  `specs/`, or code is a fact you source — never a grill question.
+
+The citation is wired in Decompose (each affected feat's `Refs` gets `adr:<slug>`).
+
+**Terminology hook.** When the interview surfaces a **contested or fuzzy domain
+term** (two words for one concept, or one word for two), route it through the
+**glossary skill** — it owns challenge/sharpen/record. Do not settle terminology
+inline here; a canonical term recorded in `docs/glossary.md` is what Decompose
+mints slugs from.
+
+### 2) Research — verify against current docs
+For each unfamiliar library, API, or pattern the initiative leans on, check
+**current documentation** (Context7 MCP when configured, else web search — never
+training data for API/config/version details). File findings as wiki pages under
+`docs/wiki/pages/` (use the `wiki` skill's Ingest workflow) and reference them
+from the relevant feat's `Refs` as `[[page-name]]`.
+
+### 3) Stack consult — decide the tech
+For any technology **not** already a `docs/stack.md` Decided row, invoke the
+`stack` skill's **Propose** workflow: present 2–3 options with trade-offs and let
+the **human decide**. Only after a decision, add it (via the stack skill) and cite
+it from the feat's `Refs` as `stack:<name>`. Never adopt tech silently.
+
+### 4) Decompose — the feat table
+Fill the `## Feats` table applying the **right-sizing rule**:
+- **One feat = one spec = a short session chain.** If a feat wouldn't fit a
+  requirements→design→tasks→implement pass, split it.
+- **Mint feat slugs from canonical terms** (per `docs/glossary.md`, via the
+  glossary skill) — never an avoided synonym; `csdd plan validate` reports an
+  avoided term in a slug.
+- **Dependencies are explicit** feat slugs in `Depends` (never a range like
+  `1-3`); order feats by `Milestone` then table order.
+- **Refs** carry the `stack:<name>`, `[[wiki-page]]`, and `adr:<slug>` tokens from
+  steps 1–3 — cite every decision record on the feat(s) it governs so the why is
+  inlined into that feat's run brief.
+- **Seeds (optional):** pre-author `docs/plans/<slug>/seeds/<feat>/requirements.md`
+  (etc.) to hand the eventual spec a head start.
+Also fill **## Quality Gates** (`- <label>: <command>` — at least one) and
+**## Executor Notes** (repo conventions passed verbatim into every run brief).
+
+### 5) Present — sweep assumptions, then hand off for approval
+**First, the assumption sweep.** Walk every remaining `[ASSUMPTION]` in `plan.md`.
+Put each through the triple gate: a gate-positive assumption is an unowned
+decision, so **grill it into an ADR** (§1 tier 2) or have the **human explicitly
+defer it** — re-mark it `[DEFERRED-BY-HUMAN]` in `plan.md`. **Never present a plan
+for approval while a gate-positive `[ASSUMPTION]` survives unmarked** — that is a
+decision made by nobody.
+
+Then run `csdd plan validate <slug>` one last time; it must be clean. Show the
+user the feat table and its `csdd plan status <slug>`, and tell them to review and
+run **`csdd plan approve <slug>`** themselves. Do not approve, generate specs, or
+start the runner.
+
+### Revise (later) — fold deviations back in
+When a run records `blocked` deviations in `docs/plans/<slug>/log.md`
+(surfaced by `csdd plan status`), re-open this skill: read each deviation's
+revision proposal. **If the proposal embodies a gate-positive decision, grill it
+and write a new ADR — or, when it overturns a recorded one, mark the superseded
+record (`status: superseded`, `superseded-by: <NNNN>`) and write its successor —
+BEFORE amending `plan.md`.** Then amend `plan.md`, re-`validate`, and hand back to
+the human for a fresh `csdd plan approve` (re-approval clears the drift). Editing
+an approved plan and its decisions is always a human-gated act, never done mid-run.
+
+## Gotchas
+
+- **Author only.** Never run `csdd plan approve`, `csdd plan generate`, or
+  `csdd plan run`; never write `plan.json`, `docs/graph/`, or `.csdd/`. The plan
+  is presented for the human to approve.
+- **Range shorthand in Depends is a lint error** — list feat slugs explicitly.
+- **Undeclared tech and broken `[[refs]]` fail `plan validate`** — do steps 2–3
+  before wiring them into the table.
+- **Feats too big are the common failure.** If a feat's objective needs "and" to
+  describe, it is probably two feats.
+- **quick-prd is the single-feature on-ramp**, not a replacement: its PRD feeds
+  Draft; it does not produce a plan.
+
+## Verification Before Reporting
+
+- Run: `csdd plan validate <slug>` — it must exit clean (no findings).
+- Check: every feat is one spec-sized chunk with an explicit objective; every
+  `Depends` names a real feat; every `stack:`/`[[…]]` ref resolves; `## Quality
+  Gates` is non-empty; `## Executor Notes` states the repo's verify command and
+  conventions.
+- If blocked: if the user cannot name the milestone-level outcome, stop and say
+  so — do not invent a feat table over an undefined initiative.
+
+## Completion Criteria
+- [ ] `csdd plan init <slug>` scaffolded the plan; prose came from recorded answers.
+- [ ] Unfamiliar tech/APIs were researched against current docs and filed as wiki pages, cited in `Refs`.
+- [ ] Every new technology went through the `stack` skill's Propose (human-decided) and is a `docs/stack.md` Decided row.
+- [ ] Every gate-positive decision (triple gate: hard to reverse + surprising + real trade-off) was grilled one-at-a-time, recorded as a `docs/adr/NNNN-<slug>.md` the moment it resolved, and cited from its feat(s) as `adr:<slug>`. No gate-negative record was written (ADR spam is a review finding).
+- [ ] The Present sweep resolved every gate-positive `[ASSUMPTION]` — grilled into an ADR or `[DEFERRED-BY-HUMAN]`; none survive unmarked.
+- [ ] The `## Feats` table right-sizes each feat to one spec, with explicit deps, milestones, and refs; `## Quality Gates` and `## Executor Notes` are filled.
+- [ ] `csdd plan validate <slug>` is clean and the plan was presented for the human `csdd plan approve` — nothing approved, generated, or run here.
diff --git a/internal/templater/templates/skills/quick-prd/SKILL.md.tmpl b/internal/templater/templates/skills/quick-prd/SKILL.md.tmpl
index cdea503..c4717f8 100644
--- a/internal/templater/templates/skills/quick-prd/SKILL.md.tmpl
+++ b/internal/templater/templates/skills/quick-prd/SKILL.md.tmpl
@@ -69,11 +69,33 @@ at minimum:
 When an option set can't capture an answer, fall back to a focused free-text
 question. Apply **YAGNI** — drop speculative capability rather than spec it.
 
+**Terminology hook.** If a domain term is contested or fuzzy, route it through the
+**glossary skill** (challenge + record the canonical term in `docs/glossary.md`) —
+no ceremony; the feature's names should use canonical terms.
+
 ### 3) Draft the PRD from the answers
 Load `assets/prd-template.md` and fill it top to bottom, from the recorded
 answers. Follow the section rules in **PRD Structure** below. Mark every gap
 `[ASSUMPTION]`.
 
+### 3b) Record load-bearing decisions (ADRs)
+A single feature still makes decisions worth keeping. Put each through the
+**triple gate** — record it only when **all three** hold:
+
+> 1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+> 2. **Surprising without context** — a future reader will ask "why this way?".
+> 3. **The result of a real trade-off** — there were genuine alternatives.
+>
+> If any one is missing it is prose or a cheap `[ASSUMPTION]`, never an ADR.
+
+For every gate-positive decision, write `docs/adr/NNNN-<slug>.md` in the **same
+format** as `/prd` — scan `docs/adr/` for the highest number, add 1, a `# <title>`
+heading then 1–3 sentences (context, decision, why); never renumber. At
+single-feature scale these surface **organically** as you draft — there is no
+sequential grill tier. Reference each from the PRD (a "Decisions (ADRs)" note
+citing `docs/adr/NNNN-<slug>.md`) so a later `/prd` inherits them as
+**recorded decisions**, not re-asked questions.
+
 ### 4) Write the file
 Write `docs/product/prd-<feature>.md` (kebab-case). One PRD per feature; never
 clobber the canonical `docs/product/prd.md`.
@@ -101,6 +123,8 @@ implementing agent.
 - **Non-Goals** — what this feature explicitly will not do. Mandatory and non-empty.
 - **Design Considerations** *(optional)* — UI/UX notes, component reuse, mockup links.
 - **Technical Considerations** *(optional)* — constraints, dependencies, performance targets.
+- **Decisions (ADRs)** *(when any gate-positive decision was made)* — a short list
+  citing each `docs/adr/NNNN-<slug>.md` recorded per step 3b.
 - **Success Metrics** — quantified targets; each references the `FR-N`(s) it measures.
 - **Open Questions** — unresolved clarifications and every `[ASSUMPTION]`.
 
@@ -135,6 +159,7 @@ before deleting" is acceptable; "works correctly" is not.
 - [ ] `docs/product/prd-<feature>.md` was written from the recorded answers, not guesses.
 - [ ] Every functional requirement is numbered and EARS-shaped; every user story has verifiable acceptance criteria.
 - [ ] Non-Goals, Success Metrics, and Open Questions (with every `[ASSUMPTION]`) are present.
+- [ ] Every gate-positive decision (triple gate) was recorded as `docs/adr/NNNN-<slug>.md` and cited from the PRD, so `/prd` inherits it as a recorded decision.
 - [ ] The user is pointed to `spec-brainstorm` or `discovery-handoff` as next — no spec/design/tasks/code started here.
 
 ## References
diff --git a/internal/templater/templates/skills/wiki/SKILL.md.tmpl b/internal/templater/templates/skills/wiki/SKILL.md.tmpl
index b2cc7cd..5703ddb 100644
--- a/internal/templater/templates/skills/wiki/SKILL.md.tmpl
+++ b/internal/templater/templates/skills/wiki/SKILL.md.tmpl
@@ -41,6 +41,9 @@ Three workflows. Deterministic structure comes from the CLI; judgment is yours.
      provenance edge that clears the "unprocessed source" lint).
    - Add `[[wikilinks]]` to related pages; add the new page to `index.md` under
      the right category.
+   - **Name pages in canonical terms.** When naming a page, consult
+     `docs/glossary.md` (via the **glossary** skill) — a page name carrying an
+     avoided synonym is a `csdd wiki lint` finding.
    - Append a `log.md` entry: `## [YYYY-MM-DD] ingest | <title>`.
 2. **Query** (answer from accumulated knowledge):
    - Read `index.md`, drill into the relevant pages, and — for structural
diff --git a/internal/web/frontend/src/App.tsx b/internal/web/frontend/src/App.tsx
index c5fbd92..a940e81 100644
--- a/internal/web/frontend/src/App.tsx
+++ b/internal/web/frontend/src/App.tsx
@@ -9,15 +9,17 @@ import { FileViewer } from './components/FileViewer'
 import { TestsView } from './components/TestsView'
 import { ResourceView } from './components/ResourceView'
 import { GraphView } from './components/GraphView'
+import { PlansView } from './components/PlansView'
 import { AuthScreen } from './components/AuthScreen'
 import { resourceKindsHint } from './resources'
 import type { ResourceKind } from './resources'
 
 // View is the top-level workspace area chosen from the header tabs. Specs and
 // Tests are full-width pages; Resources and Files use the contextual sidebar.
-export type View = 'specs' | 'resources' | 'files' | 'tests' | 'graph'
+export type View = 'specs' | 'plans' | 'resources' | 'files' | 'tests' | 'graph'
 const VIEWS: { id: View; label: string }[] = [
   { id: 'specs', label: 'Specs' },
+  { id: 'plans', label: 'Plans' },
   { id: 'resources', label: 'Resources' },
   { id: 'files', label: 'Files' },
   { id: 'tests', label: 'Tests' },
@@ -159,6 +161,8 @@ export function App() {
               <EmptyPrompt title="Files" hint="Pick a file on the left to view it." />
             ))}
 
+          {view === 'plans' && <PlansView version={version} />}
+
           {view === 'tests' && <TestsView version={version} />}
 
           {view === 'graph' && <GraphView version={version} />}
diff --git a/internal/web/frontend/src/api.ts b/internal/web/frontend/src/api.ts
index 6f439ea..d5facdc 100644
--- a/internal/web/frontend/src/api.ts
+++ b/internal/web/frontend/src/api.ts
@@ -1,4 +1,12 @@
-import type { Overview, SpecDetail, WorkspaceTree, FileContent, TestReport } from './types'
+import type {
+  Overview,
+  SpecDetail,
+  WorkspaceTree,
+  FileContent,
+  TestReport,
+  PlanSummary,
+  PlanDetail,
+} from './types'
 import { authHeader, requireAuth } from './auth'
 
 async function get<T>(url: string): Promise<T> {
@@ -19,4 +27,6 @@ export const api = {
   tree: () => get<WorkspaceTree>('/api/tree'),
   file: (path: string) => get<FileContent>(`/api/file?path=${encodeURIComponent(path)}`),
   tests: () => get<TestReport>('/api/tests'),
+  plans: () => get<PlanSummary[]>('/api/plans'),
+  plan: (slug: string) => get<PlanDetail>(`/api/plan/${encodeURIComponent(slug)}`),
 }
diff --git a/internal/web/frontend/src/components/PlansView.tsx b/internal/web/frontend/src/components/PlansView.tsx
new file mode 100644
index 0000000..80a18d6
--- /dev/null
+++ b/internal/web/frontend/src/components/PlansView.tsx
@@ -0,0 +1,181 @@
+import { useEffect, useState } from 'react'
+import { api } from '../api'
+import type { PlanSummary, PlanDetail, PlanFeat, MilestoneProgress } from '../types'
+import { ProgressBar } from './bits'
+
+// PlansView is the read-only Plans tab: a list of plans with approval/drift
+// badges, and a per-plan view rendering the feat table with derived status,
+// milestone progress, blocked flags, and the run journal (log.md).
+export function PlansView({ version }: { version: number }) {
+  const [plans, setPlans] = useState<PlanSummary[] | null>(null)
+  const [err, setErr] = useState<string | null>(null)
+  const [open, setOpen] = useState<string | null>(null)
+
+  useEffect(() => {
+    setErr(null)
+    api.plans().then(setPlans).catch((e) => setErr(String(e)))
+  }, [version])
+
+  if (err) return <div className="banner error">{err}</div>
+  if (!plans) return <div className="empty">Loading…</div>
+  if (open) return <PlanDetailView slug={open} version={version} onBack={() => setOpen(null)} />
+  if (plans.length === 0) return <NoPlans />
+
+  return (
+    <div className="plans-view">
+      <div className="spec-header">
+        <h1>Plans</h1>
+      </div>
+      <div className="cards">
+        {plans.map((p) => (
+          <button key={p.slug} className="card plan-card" onClick={() => setOpen(p.slug)}>
+            <div className="card-title">
+              {p.name || p.slug} <ApprovalBadge approved={p.approved} drift={p.drift} />
+            </div>
+            <div className="muted small">{p.slug}</div>
+            <div className="stat-grid">
+              <Stat label="feats" value={p.feats} />
+              <Stat label="done" value={p.done} tone="ok" />
+              <Stat label="blocked" value={p.blocked} tone={p.blocked > 0 ? 'bad' : undefined} />
+            </div>
+            <ProgressBar pct={p.feats > 0 ? Math.round((p.done * 100) / p.feats) : 0} />
+            {p.deviations > 0 && <div className="badge warn">{p.deviations} deviation(s)</div>}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function PlanDetailView({ slug, version, onBack }: { slug: string; version: number; onBack: () => void }) {
+  const [d, setD] = useState<PlanDetail | null>(null)
+  const [journal, setJournal] = useState<string>('')
+  const [err, setErr] = useState<string | null>(null)
+
+  useEffect(() => {
+    setErr(null)
+    api.plan(slug).then(setD).catch((e) => setErr(String(e)))
+    // The run journal is fetched through the hardened /api/file route so it
+    // inherits the host guard and secret redaction.
+    api
+      .file(`docs/plans/${slug}/log.md`)
+      .then((f) => setJournal(f.text ?? ''))
+      .catch(() => setJournal(''))
+  }, [slug, version])
+
+  if (err) return <div className="banner error">{err}</div>
+  if (!d) return <div className="empty">Loading…</div>
+
+  return (
+    <div className="plan-detail">
+      <div className="spec-header">
+        <button className="link-btn" onClick={onBack}>
+          ← Plans
+        </button>
+        <h1>
+          {d.name || d.slug} <ApprovalBadge approved={d.approved} drift={d.drift} />
+        </h1>
+      </div>
+
+      {d.milestones.length > 0 && (
+        <div className="card">
+          <div className="card-title">Milestones</div>
+          {d.milestones.map((m) => (
+            <MilestoneRow key={m.name || '—'} m={m} />
+          ))}
+        </div>
+      )}
+
+      <div className="card">
+        <div className="card-title">Feats ({d.feats.length})</div>
+        <div className="feat-table">
+          {d.feats.map((f) => (
+            <FeatRow key={f.slug} f={f} />
+          ))}
+        </div>
+      </div>
+
+      {journal.trim() !== '' && (
+        <div className="card">
+          <div className="card-title">Run journal (log.md)</div>
+          <pre className="codeblock">
+            <code>{journal}</code>
+          </pre>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function FeatRow({ f }: { f: PlanFeat }) {
+  return (
+    <div className="feat-row" title={f.objective}>
+      <span className="feat-num muted">{f.num}</span>
+      <span className="feat-slug">
+        {f.slug}
+        {f.parallel && <span className="badge muted" title="may run in parallel with milestone siblings">P</span>}
+      </span>
+      <span className="feat-objective muted">{f.objective}</span>
+      <StateBadge state={f.state} />
+      <span className="feat-progress muted small">
+        {f.tasks_total > 0 ? `${f.tasks_checked}/${f.tasks_total} tasks` : ''}
+        {f.block_reason ? f.block_reason : ''}
+      </span>
+    </div>
+  )
+}
+
+function MilestoneRow({ m }: { m: MilestoneProgress }) {
+  const pct = m.total > 0 ? Math.round((m.done * 100) / m.total) : 0
+  return (
+    <div className="cov-bar-row">
+      <span className="feat-slug">{m.name || '—'}</span>
+      <ProgressBar pct={pct} />
+      <span className="muted small">
+        {m.done}/{m.total}
+      </span>
+    </div>
+  )
+}
+
+function ApprovalBadge({ approved, drift }: { approved: boolean; drift: boolean }) {
+  if (drift) return <span className="badge warn">drift</span>
+  if (approved) return <span className="badge ready">approved</span>
+  return <span className="badge muted">draft</span>
+}
+
+function StateBadge({ state }: { state: string }) {
+  const tone =
+    state === 'done' ? 'ready' : state === 'blocked' ? 'warn' : state === 'implementing' || state === 'ready' ? 'info' : 'muted'
+  return <span className={`badge ${tone}`}>{state}</span>
+}
+
+function Stat({ label, value, tone }: { label: string; value: number; tone?: 'ok' | 'bad' }) {
+  const color = tone === 'ok' ? 'var(--ok)' : tone === 'bad' ? 'var(--bad)' : undefined
+  return (
+    <div className="stat">
+      <div className="stat-val" style={color ? { color } : undefined}>
+        {value}
+      </div>
+      <div className="stat-label">{label}</div>
+    </div>
+  )
+}
+
+function NoPlans() {
+  return (
+    <div className="empty">
+      <h2>No plans yet</h2>
+      <p className="muted">
+        A plan decomposes an initiative into feats (each becomes one spec). Author one with the
+        <code> /prd </code> skill, or scaffold directly:
+      </p>
+      <pre className="codeblock" style={{ textAlign: 'left', maxWidth: 480, margin: '12px auto' }}>
+        <code>{`npx @protonspy/csdd plan init <slug>
+# author the feat table, then:
+npx @protonspy/csdd plan validate <slug>
+npx @protonspy/csdd plan approve <slug>`}</code>
+      </pre>
+    </div>
+  )
+}
diff --git a/internal/web/frontend/src/styles.css b/internal/web/frontend/src/styles.css
index c74d19c..8cd0654 100644
--- a/internal/web/frontend/src/styles.css
+++ b/internal/web/frontend/src/styles.css
@@ -506,6 +506,55 @@ code {
   background: rgba(84, 192, 138, 0.16);
   color: var(--ok);
 }
+.badge.info {
+  background: rgba(90, 166, 230, 0.16);
+  color: var(--info);
+}
+
+/* ---- Plans tab ------------------------------------------------------- */
+.plan-card {
+  text-align: left;
+  cursor: pointer;
+}
+.link-btn {
+  background: none;
+  border: none;
+  color: var(--info);
+  cursor: pointer;
+  padding: 0;
+  font: inherit;
+  margin-bottom: 4px;
+}
+.feat-table {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.feat-row {
+  display: grid;
+  grid-template-columns: 2.2em minmax(9em, 1.4fr) 2.2fr auto minmax(6em, 0.9fr);
+  align-items: center;
+  gap: 10px;
+  padding: 4px 2px;
+  border-top: 1px solid var(--bg-3);
+}
+.feat-row:first-child {
+  border-top: none;
+}
+.feat-slug {
+  font-weight: 600;
+}
+.feat-slug .badge {
+  margin-left: 6px;
+}
+.feat-objective {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.feat-progress {
+  text-align: right;
+}
 
 /* ---- Top tabs (header) ----------------------------------------------- */
 .top-tabs {
diff --git a/internal/web/frontend/src/types.ts b/internal/web/frontend/src/types.ts
index e366829..77442b7 100644
--- a/internal/web/frontend/src/types.ts
+++ b/internal/web/frontend/src/types.ts
@@ -211,3 +211,45 @@ export interface TestReport {
   tests: TestSummary | null
   sources: string[]
 }
+
+// Plans — the layer above specs. A plan (docs/plans/<slug>/) decomposes an
+// initiative into feats, each becoming one spec; all state is derived read-only.
+export interface PlanSummary {
+  slug: string
+  name: string
+  approved: boolean
+  drift: boolean
+  deviations: number
+  feats: number
+  done: number
+  blocked: number
+}
+
+export interface PlanFeat {
+  slug: string
+  num: string
+  objective: string
+  milestone: string
+  depends: string[]
+  parallel: boolean
+  state: string
+  tasks_total: number
+  tasks_checked: number
+  block_reason?: string
+}
+
+export interface MilestoneProgress {
+  name: string
+  total: number
+  done: number
+}
+
+export interface PlanDetail {
+  slug: string
+  name: string
+  approved: boolean
+  drift: boolean
+  deviations: number
+  feats: PlanFeat[]
+  milestones: MilestoneProgress[]
+}
diff --git a/internal/web/handlers.go b/internal/web/handlers.go
index 3d90df1..58e854d 100644
--- a/internal/web/handlers.go
+++ b/internal/web/handlers.go
@@ -89,6 +89,22 @@ func newMux(root string, h *hub, a *auth, allowedHosts ...string) http.Handler {
 		writeJSON(w, http.StatusOK, session.LoadTestReport(root))
 	}))
 
+	mux.HandleFunc("GET /api/plans", a.protect(func(w http.ResponseWriter, _ *http.Request) {
+		setWriteDeadline(w)
+		writeJSON(w, http.StatusOK, loadPlansList(root))
+	}))
+
+	mux.HandleFunc("GET /api/plan/{slug}", a.protect(func(w http.ResponseWriter, r *http.Request) {
+		slug := r.PathValue("slug")
+		d, err := loadPlanDetail(root, slug)
+		if err != nil {
+			// Opaque: the raw error may embed a filesystem path.
+			writeError(w, http.StatusNotFound, planNotFound(slug))
+			return
+		}
+		writeJSON(w, http.StatusOK, d)
+	}))
+
 	mux.HandleFunc("GET /api/events", a.protect(h.sseHandler))
 
 	// Everything else is the embedded SPA (with index.html fallback). Public so
diff --git a/internal/web/plans.go b/internal/web/plans.go
new file mode 100644
index 0000000..5bcf915
--- /dev/null
+++ b/internal/web/plans.go
@@ -0,0 +1,142 @@
+package web
+
+import (
+	"fmt"
+
+	"github.com/protonspy/csdd/internal/plan"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// planSummary is one row of GET /api/plans: enough to render the Plans list with
+// approval/drift badges and milestone-agnostic progress counts.
+type planSummary struct {
+	Slug       string `json:"slug"`
+	Name       string `json:"name"`
+	Approved   bool   `json:"approved"`
+	Drift      bool   `json:"drift"`
+	Deviations int    `json:"deviations"`
+	Feats      int    `json:"feats"`
+	Done       int    `json:"done"`
+	Blocked    int    `json:"blocked"`
+}
+
+// webFeat is one feat row in the per-plan view, merging the plan's static feat
+// metadata with its derived status.
+type webFeat struct {
+	Slug         string   `json:"slug"`
+	Num          string   `json:"num"`
+	Objective    string   `json:"objective"`
+	Milestone    string   `json:"milestone"`
+	Depends      []string `json:"depends"`
+	Parallel     bool     `json:"parallel"`
+	State        string   `json:"state"`
+	TasksTotal   int      `json:"tasks_total"`
+	TasksChecked int      `json:"tasks_checked"`
+	BlockReason  string   `json:"block_reason,omitempty"`
+}
+
+// milestoneProgress is per-milestone completion, in first-seen order.
+type milestoneProgress struct {
+	Name  string `json:"name"`
+	Total int    `json:"total"`
+	Done  int    `json:"done"`
+}
+
+// planDetail is GET /api/plan/{slug}: the whole read-only per-plan view. The run
+// journal (log.md) is intentionally NOT inlined here — the UI loads it through
+// the existing hardened /api/file route so it inherits host-guard + redaction.
+type planDetail struct {
+	Slug       string              `json:"slug"`
+	Name       string              `json:"name"`
+	Approved   bool                `json:"approved"`
+	Drift      bool                `json:"drift"`
+	Deviations int                 `json:"deviations"`
+	Feats      []webFeat           `json:"feats"`
+	Milestones []milestoneProgress `json:"milestones"`
+}
+
+// loadPlansList derives a summary for every plan under docs/plans/. A plan that
+// fails to load is skipped (the list stays useful) rather than failing the whole
+// request.
+func loadPlansList(root string) []planSummary {
+	slugs, err := plan.List(root)
+	if err != nil {
+		return []planSummary{}
+	}
+	out := make([]planSummary, 0, len(slugs))
+	for _, slug := range slugs {
+		doc, err := plan.Load(root, slug)
+		if err != nil {
+			continue
+		}
+		st, err := plan.DeriveStatus(root, doc)
+		if err != nil {
+			continue
+		}
+		s := planSummary{
+			Slug: slug, Name: st.Name, Approved: st.Approved,
+			Drift: st.Drift, Deviations: st.Deviations, Feats: len(st.Feats),
+		}
+		for _, f := range st.Feats {
+			switch f.State {
+			case plan.StateDone:
+				s.Done++
+			case plan.StateBlocked:
+				s.Blocked++
+			}
+		}
+		out = append(out, s)
+	}
+	return out
+}
+
+// loadPlanDetail assembles the per-plan view. The slug is validated as a single
+// path segment first (defense-in-depth against traversal through the read-model).
+func loadPlanDetail(root, slug string) (planDetail, error) {
+	if err := workspace.SafeName(slug, "plan"); err != nil {
+		return planDetail{}, err
+	}
+	doc, err := plan.Load(root, slug)
+	if err != nil {
+		return planDetail{}, err
+	}
+	st, err := plan.DeriveStatus(root, doc)
+	if err != nil {
+		return planDetail{}, err
+	}
+
+	byState := map[string]plan.FeatStatus{}
+	for _, f := range st.Feats {
+		byState[f.Slug] = f
+	}
+	d := planDetail{
+		Slug: slug, Name: st.Name, Approved: st.Approved,
+		Drift: st.Drift, Deviations: st.Deviations,
+	}
+	milestoneIndex := map[string]int{}
+	for _, f := range doc.Feats {
+		s := byState[f.Slug]
+		d.Feats = append(d.Feats, webFeat{
+			Slug: f.Slug, Num: f.Num, Objective: f.Objective, Milestone: f.Milestone,
+			Depends: f.Depends, Parallel: f.Parallel, State: s.State,
+			TasksTotal: s.TasksTotal, TasksChecked: s.TasksChecked, BlockReason: s.BlockReason,
+		})
+		mi, ok := milestoneIndex[f.Milestone]
+		if !ok {
+			mi = len(d.Milestones)
+			milestoneIndex[f.Milestone] = mi
+			d.Milestones = append(d.Milestones, milestoneProgress{Name: f.Milestone})
+		}
+		d.Milestones[mi].Total++
+		if s.State == plan.StateDone {
+			d.Milestones[mi].Done++
+		}
+	}
+	return d, nil
+}
+
+// planNotFound is the opaque error returned when a plan can't be loaded, so the
+// underlying filesystem path never leaks into the response.
+func planNotFound(slug string) error {
+	return fmt.Errorf("plan not found: %s", slug)
+}
diff --git a/internal/web/plans_test.go b/internal/web/plans_test.go
new file mode 100644
index 0000000..6040800
--- /dev/null
+++ b/internal/web/plans_test.go
@@ -0,0 +1,105 @@
+package web
+
+import (
+	"net/http"
+	"testing"
+)
+
+const webPlanMD = `---
+name: photos
+status: draft
+---
+## Feats
+
+| # | Feat | Objective | Depends | Milestone | (P) | Refs |
+|---|------|-----------|---------|-----------|-----|------|
+| 1 | upload | Ingest photos | — | M1 | | |
+| 2 | thumbs | Thumbnails | upload | M1 | P | |
+| 3 | search | Full-text search | — | M2 | | |
+
+## Quality Gates
+
+- verify: make check
+`
+
+func planWorkspace(t *testing.T) string {
+	return tempWorkspace(t, map[string]string{
+		"docs/plans/photos/plan.md": webPlanMD,
+		// upload is done, thumbs is blocked, search is pending.
+		"specs/upload/spec.json":           `{"feature_name":"upload","ready_for_implementation":true,"approvals":{"requirements":{"approved":true},"design":{"approved":true},"tasks":{"approved":true}}}`,
+		"specs/upload/tasks.md":            "- [x] 1. done\n",
+		".csdd/plan/photos/blocked/thumbs": "gate failed\n",
+		"docs/plans/photos/log.md":         "# Journal\n## [2026-07-07] task 1 | upload | done\n",
+	})
+}
+
+func TestAPIPlansList(t *testing.T) {
+	srv := testServer(t, planWorkspace(t))
+	var plans []planSummary
+	if code := getJSON(t, srv.URL+"/api/plans", &plans); code != http.StatusOK {
+		t.Fatalf("GET /api/plans = %d", code)
+	}
+	if len(plans) != 1 {
+		t.Fatalf("expected 1 plan, got %d", len(plans))
+	}
+	p := plans[0]
+	if p.Slug != "photos" || p.Feats != 3 {
+		t.Errorf("unexpected summary: %+v", p)
+	}
+	if p.Done != 1 {
+		t.Errorf("expected 1 done feat (upload), got %d", p.Done)
+	}
+	if p.Blocked != 1 {
+		t.Errorf("expected 1 blocked feat (thumbs), got %d", p.Blocked)
+	}
+	if p.Approved {
+		t.Errorf("plan is unapproved; summary should reflect that")
+	}
+}
+
+func TestAPIPlanDetail(t *testing.T) {
+	srv := testServer(t, planWorkspace(t))
+	var d planDetail
+	if code := getJSON(t, srv.URL+"/api/plan/photos", &d); code != http.StatusOK {
+		t.Fatalf("GET /api/plan/photos = %d", code)
+	}
+	if len(d.Feats) != 3 {
+		t.Fatalf("expected 3 feats, got %d", len(d.Feats))
+	}
+	states := map[string]string{}
+	for _, f := range d.Feats {
+		states[f.Slug] = f.State
+	}
+	if states["upload"] != "done" || states["thumbs"] != "blocked" || states["search"] != "pending" {
+		t.Errorf("derived feat states wrong: %v", states)
+	}
+	// Milestone progress: M1 has upload(done)+thumbs(blocked)=1/2, M2 search 0/1.
+	var m1 milestoneProgress
+	for _, m := range d.Milestones {
+		if m.Name == "M1" {
+			m1 = m
+		}
+	}
+	if m1.Total != 2 || m1.Done != 1 {
+		t.Errorf("M1 progress = %+v, want 1/2", m1)
+	}
+	// Feat metadata is merged in (objective + depends).
+	for _, f := range d.Feats {
+		if f.Slug == "thumbs" {
+			if f.Objective != "Thumbnails" || len(f.Depends) != 1 || f.Depends[0] != "upload" {
+				t.Errorf("thumbs metadata not merged: %+v", f)
+			}
+			if f.BlockReason == "" {
+				t.Errorf("blocked feat should carry its reason")
+			}
+		}
+	}
+}
+
+func TestAPIPlanDetailTraversalGuard(t *testing.T) {
+	srv := testServer(t, planWorkspace(t))
+	// A traversal slug must be rejected (404), never resolve outside docs/plans/.
+	if code := getJSON(t, srv.URL+"/api/plan/..%2f..%2fetc", nil); code == http.StatusOK {
+		t.Errorf("traversal slug should not succeed, got %d", code)
+	}
+}

From 67e8b00e44387723e454124958323caf8425288a Mon Sep 17 00:00:00 2001
From: Mateus Andrade <133387879+protonspy@users.noreply.github.com>
Date: Tue, 7 Jul 2026 05:39:52 -0300
Subject: [PATCH 2/2] fix(plan): satisfy golangci-lint and the Windows test
 runner

- runner.go: check the fmt.Fprintf return in the log closures and summarize
  (errcheck).
- sandbox_test.go: skip the POSIX exec-bit assertion on Windows, which has no
  exec bit (matches the web_test.go token-perm guard).
- glossary_cli_test.go: drop the ineffectual code assignment in the analyze step.
---
 internal/cli/glossary_cli_test.go | 2 +-
 internal/plan/runner.go           | 6 +++---
 internal/plan/sandbox_test.go     | 6 ++++--
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/internal/cli/glossary_cli_test.go b/internal/cli/glossary_cli_test.go
index 0e54e03..a461134 100644
--- a/internal/cli/glossary_cli_test.go
+++ b/internal/cli/glossary_cli_test.go
@@ -121,7 +121,7 @@ func TestGlossaryLintE2E(t *testing.T) {
 	}
 
 	// 4. The orphan-term informational fires (Feat is unused here).
-	code, out, _ = run(t, "graph", "analyze", "--root", dir)
+	_, out, _ = run(t, "graph", "analyze", "--root", dir)
 	if !strings.Contains(out, "orphan term") {
 		t.Errorf("expected an orphan_term finding in analyze; out=%s", out)
 	}
diff --git a/internal/plan/runner.go b/internal/plan/runner.go
index 1af3f2a..2b807c4 100644
--- a/internal/plan/runner.go
+++ b/internal/plan/runner.go
@@ -96,7 +96,7 @@ func Run(opts RunOptions) (RunSummary, error) {
 	fillRunDefaults(&opts)
 	h := opts.Hooks
 	out := opts.Out
-	logf := func(format string, a ...any) { fmt.Fprintf(out, format+"\n", a...) }
+	logf := func(format string, a ...any) { _, _ = fmt.Fprintf(out, format+"\n", a...) }
 
 	doc, err := Load(opts.Root, opts.Slug)
 	if err != nil {
@@ -181,7 +181,7 @@ func Run(opts RunOptions) (RunSummary, error) {
 func executeStep(opts RunOptions, doc *PlanDoc, step Step, mode SessionMode, sum *RunSummary) bool {
 	h := opts.Hooks
 	out := opts.Out
-	logf := func(format string, a ...any) { fmt.Fprintf(out, format+"\n", a...) }
+	logf := func(format string, a ...any) { _, _ = fmt.Fprintf(out, format+"\n", a...) }
 
 	baseBrief, err := Brief(opts.Root, doc, step)
 	if err != nil {
@@ -399,7 +399,7 @@ func fillRunDefaults(opts *RunOptions) {
 }
 
 func summarize(out io.Writer, sum RunSummary) RunSummary {
-	fmt.Fprintf(out, "totals: %d steps, %d retries, %d blocks\n", sum.Steps, sum.Retries, sum.Blocks)
+	_, _ = fmt.Fprintf(out, "totals: %d steps, %d retries, %d blocks\n", sum.Steps, sum.Retries, sum.Blocks)
 	return sum
 }
 
diff --git a/internal/plan/sandbox_test.go b/internal/plan/sandbox_test.go
index 58ef0eb..cbebfc3 100644
--- a/internal/plan/sandbox_test.go
+++ b/internal/plan/sandbox_test.go
@@ -3,6 +3,7 @@ package plan
 import (
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -33,12 +34,13 @@ func TestSandboxInitScaffold(t *testing.T) {
 			t.Errorf("%s contains CRLF; must be LF-normalized", name)
 		}
 	}
-	// The firewall script is executable.
+	// The firewall script is executable. Windows has no POSIX exec bit, so the
+	// mode check only applies on Unix.
 	fi, err := os.Stat(filepath.Join(root, ".devcontainer", "init-firewall.sh"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if fi.Mode().Perm()&0o100 == 0 {
+	if runtime.GOOS != "windows" && fi.Mode().Perm()&0o100 == 0 {
 		t.Errorf("init-firewall.sh should be executable, got %v", fi.Mode())
 	}
 	// Default (non-hardened) build arg.