@sabaiway/agent-workflow-engine 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 3.0.0 — the plan canon becomes a capped index: a module ledger whose rows ARE the steps (AD-104)
+
+A plan is an **index plus constraints**, never a transcript. The executor reads the repository; the
+plan says which files to open, what each may become, and how the result is checked. The canon used
+to say what a plan CONTAINS and never what it may COST — the last plan written to the old shape ran
+690 lines, most of it free prose under `## Approach`, a section with a budget of nothing and no
+check on its content.
+
+> ### ⚠ BREAKING — a plan written to any 2.x canon is invalid, and a shipped tool now refuses it
+>
+> The skeleton is LITERAL and tooling extracts by exact match: the title line `# Plan: <title>`,
+> then five `## ` headings — `Goal and boundary`, `Module ledger`, `Verification`, `Phase: Cleanup`,
+> `Next steps`. `## Approach` and `## Decisions (locked)` are gone, and the
+> Plan → Phase → Step → Substep vocabulary with them. Kit **6.0.0**'s `grounding --plan` requires the
+> three canon sections and refuses a MISSING one by name — a plan that exited 0 under every 2.x
+> canon now exits 1. That refusal IS the migration signal, and it is why this is a MAJOR: the same
+> class as **2.0.0**, where deleting a vocabulary from the canon was already called BREAKING.
+> A leftover `## Approach` is not itself the trigger: a section the canon does not name is simply
+> never sliced. A settled decision is no longer a section either — it becomes a boundary or non-goal
+> in *Goal and boundary*, or a check in *Verification*.
+>
+> **Migration.** Rewrite the plan to the skeleton above: the old `## Approach` prose becomes a
+> `## Goal and boundary` (observable outcome, preserved behaviour, explicit non-goals) plus a
+> `## Module ledger` (one row per path, ending in the `total: <before> → <after> lines` budget); its
+> Steps become ledger rows. Nothing in a deployed project's `docs/ai/` moves — the deployment-lineage
+> stamp is unchanged and no migration file is needed.
+
+- **`planning.md` 152 → 114 lines.** The whole plan file is capped at **100 lines AND 8000 bytes** —
+  both, because a line cap alone is paid off with longer lines. Reserves: Goal and boundary 10,
+  Module ledger 60, Verification 20, Cleanup plus Next steps 10. A plan that does not fit is not
+  under-described: either the TASK splits along independently verifiable boundaries, or it is a sweep.
+- **The ledger rows ARE the steps**, so the Plan → Phase → Step → Substep numbering is DELETED. One
+  row per path, at most 200 bytes, six fields: `<check-id> | create|modify|delete | <path> |
+  <responsibility> | <max lines | n/a> | <anchor>`. Rows execute top to bottom, each is one logical
+  commit, and a row may anchor only on a path above it or on existing code. The only surviving phases
+  are session boundaries and Cleanup. A `create` row's responsibility names the **exported surface**
+  — the one interface contract a plan owes its executor, because it is not in the checkout to derive.
+- **A wide mechanical change is ONE row** — a glob path, the invariant every site must satisfy, an
+  asserted count. Splitting a sweep into per-file rows costs more prose than the sweep and breaks
+  the intermediate states.
+- **The budget that decides is the TOTAL.** The ledger ends with `total: <before> → <after> lines`.
+  Five files under a 400-line cap can each be legal while the change doubles the codebase. Growth
+  takes a stated reason on that line; a refactor that claims to reduce anything and grows is refused
+  at plan time.
+- **Review asks what to cut, not what is missing.** *What gets cut* deletes any line for which both
+  answers are yes — can a zero-context executor still pick the right files without it, and can
+  verification still catch a wrong result without it. A line may be ADDED only by naming the specific
+  wrong execution it prevents AND deleting at least as many lower-value lines.
+- **`procedures.md` 137 → 87 lines, 10427 → 5768 bytes** — back under `planning.md` (5977), as its
+  own long-standing assertion requires. Every restated planning rule became a pointer, and the
+  pointers name planning sections **by heading**: `planning.md` has no numbered sections, so the old
+  `§4/§6/§7/§8/§9` references pointed at moved or deleted text. `procedures-canon.test.mjs` now
+  checks that every named anchor is a live `## ` heading and that no `planning.md §N` pointer
+  survives.
+- `orchestration.md`'s convergence-bar pointer, the agent-rules **lens fragment** (its two per-Step
+  clauses are now per-row, the outgoing body appended verbatim to `agent-rules-lens-priors.md` per
+  the AD-041 append-only contract), the methodology **slot** blurb, and the SKILL/README/`package.json`
+  descriptions all drop the retired vocabulary.
+- Unchanged and still binding: right altitude and fold-by-code (AD-027/AD-029), checked-vs-unchecked
+  syntax — *Un-run syntax never ships in prose* (AD-036), heavy review at the diff, and the mandatory
+  `## Phase: Cleanup`.
+
+## 2.1.0 — the plan names the layout it is about to create (AD-091)
+
+The authoring canon now asks for the layout while the plan is still text: every Step that creates a
+file names that file and the single responsibility it carries — and where the project declares a
+source-size cap, the planned layout fits it.
+
+- **`procedures.md` plan-authoring, Draft (step 2)** — every Step that CREATES a file names that file
+  and the single responsibility it carries, and **where the project declares a source-size cap**, the
+  planned layout fits it. The conditional is canon, not decoration: a project that declares no
+  practice must never be handed an invented limit.
+- **`planning.md` §8 self-review checklist** — the matching line, so the draft is re-checked against
+  it before the plan is finalized. The line carries the canon's own rationale for asking at plan
+  time: "a gate that refuses an oversized file after it is written only pays for a rewrite".
+- The rung lives in **plan-authoring only** — plan-execution grows no rival copy of it. Both canon
+  pins are enforced by the existing canon suites, including the conditional form.
+
 ## 2.0.0 — strip-the-kit: the planning canon teaches the computed loop (AD-059)
 
 > ### ⚠ BREAKING — the §9 "Computed instrument" canon is rewritten

package/README.md

@@ -1,7 +1,7 @@
 # @sabaiway/agent-workflow-engine
 
 **The canonical home of the `agent-workflow` planning methodology.** It owns the
-methodology *text* — the Plan → Phase → Step vocabulary, the plan-file lifecycle
+methodology *text* — the capped plan shape (goal and boundary, module ledger, verification), the plan-file lifecycle
 (`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
 final **Phase: Cleanup**, the **orchestration-recipe** vocabulary (Solo / Reviewed / Council /
 Delegated), the bounded slot fragments the family kit injects into a deployed project's
@@ -39,9 +39,9 @@ you install and use the **kit** (`@sabaiway/agent-workflow-kit`), which injects
 methodology slot into your project's `AGENTS.md`. Install the engine standalone when you want
 the canonical methodology reference on disk:
 
-- [`references/planning.md`](references/planning.md) — the **full methodology**: the
-  Plan → Phase → Step vocabulary, the plan-file lifecycle, the `queue.md` series index, the
-  mandatory final **Phase: Cleanup**, and the plan-then-execute split.
+- [`references/planning.md`](references/planning.md) — the **plan canon**: the capped plan shape
+  (Goal and boundary · Module ledger · Verification), the subtraction rubric, the plan-file
+  lifecycle, the `queue.md` series index, and the mandatory final **Phase: Cleanup**.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
   methodology fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
   pointer, kept under the entry point's line cap).

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-engine
-description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
+description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '2.0.0'
+  version: '3.0.0'
 ---
 
 # agent-workflow-engine
@@ -18,10 +18,10 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
 
 ## What it provides (`provides: ["plan"]`)
 
-- [`references/planning.md`](references/planning.md) — the **full methodology**: the
-  Plan→Phase→Step→Substep vocabulary, plan-file lifecycle (`docs/plans/*.md`, gitignored, never
-  committed), the `queue.md` series index, the mandatory final **Phase: Cleanup**, the
-  plan-then-execute split, and the session-continuity heuristic.
+- [`references/planning.md`](references/planning.md) — the **plan canon**: the capped plan shape
+  (Goal and boundary · Module ledger · Verification — literal headings), the subtraction rubric for
+  review, the plan-file lifecycle (`docs/plans/*.md`, gitignored, never committed), the `queue.md`
+  series index and the mandatory final **Phase: Cleanup**.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded** fragment the
   composition root injects into a deployed project's `AGENTS.md`, between the
   `<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short

package/capability.json

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

package/package.json

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

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

@@ -127,3 +127,19 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 - **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch into ONE invocation — the review-ledger triad rides one batched write, other stage writers combine via one launcher per stage; never one writer call at a time (each write is its own prompt).
+
+<!-- prior: 2026-08-21 (planning canon rewrite) — the two per-Step clauses become per-row -->
+### 2.x. Planning, review & process-fidelity invariants
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
+- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
+- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
+- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
+- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
+- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
+- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).

package/references/agent-rules-lens.md

@@ -2,11 +2,11 @@
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
+- **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
-- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
 - **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
 - **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.

package/references/methodology-slot.md

@@ -1 +1 @@
-> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).
+> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).

package/references/orchestration.md

@@ -75,9 +75,9 @@ reviewers are `ready`, EVERY review round runs BOTH — skipping a ready backend
 or "the other one already shipped" is a **SILENT downgrade of Council → Reviewed, and is forbidden**.
 The distinction is strict: an *unavailable* backend is a LOUD, stated degrade (the lattice above); a
 *ready* backend you quietly drop is a fidelity breach, not a degrade. The same holds for any recipe
-that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`planning.md`](planning.md)
-§9) re-runs **every named backend each round** — convergence is reached only when one round comes back
-clean from all of them.
+that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`procedures.md`](procedures.md)
+*Fold + loop*) re-runs **every named backend each round** — convergence is reached only when one round
+comes back clean from all of them.
 
 **Backend divergence is the crossover stop — it bounds the ROUNDS, never the backends.** Running every
 named backend every round CONVERGES when one round returns **0 blockers + 0 majors** from all of them.

package/references/planning.md

@@ -1,151 +1,114 @@
 # Planning Workflow
 
-Source of truth for **how plans are written, stored, executed, and torn down**. Overrides the generic `writing-plans` skill — if both trigger, this one wins. Runtime series status (which plan is Current / Pending) lives in `docs/plans/queue.md`.
+How plans are written, executed and torn down. Overrides the generic `writing-plans` skill — if both
+trigger, this one wins.
 
----
+A plan is an **index plus constraints**, never a transcript. The executor reads the repository; the
+plan tells it which files to open, what each one may become, and how the result is checked.
 
-## 1. Plan vocabulary
+## Shape
 
-Strict four-level hierarchy, used in plan files (`docs/plans/*.md`) and in verbal summaries:
+The whole file is capped at **100 lines and 8000 bytes** — both, because a line cap alone is paid off
+with longer lines. The headings are LITERAL, copied bare: tooling extracts sections by exact match.
 
-- **Plan** — top-level container = the plan file itself. One file = one Plan. A series of related plans is not grouped under any wrapper noun; refer to them as "Plan 1 of N", "the next plan". Series order lives in `queue.md` (§3).
-- **Phase** — a large block inside the Plan. Exactly one execution session. Ends with its own verification block. `## Phase 1: …`, `## Phase 2: …`.
-- **Step** — an atomic change inside a Phase. Numbered `<phase>.<step>`: `### 1.1. …`. One Step → one logical commit.
-- **Substep** — optional split of a complex Step. Lettered: `**1.2.a**`, `**1.2.b**`. Use only when a Step cannot be one command.
-
-Reserve the word "task" for the todo list and `active_plan.md` — not for plan structure.
-
-## 2. Plan directory & lifecycle
-
-Plan files are **ephemeral, machine-local scratch space**, gitignored (`.gitignore` contains `docs/plans/`).
-
-**Lifecycle:** Creation (untracked file) → Execution (Phases 1..N-1) → mandatory **Phase N: Cleanup** (§4) → Post-deletion (only `changelog.md` + ADRs remain). Plans are **NEVER committed** — full stop. Even if a plan looks load-bearing (referenced by an ADR), inline the load-bearing content into a persistent doc and delete the plan file.
-
-**Forbidden:** `git add` of any plan file; plan-file paths in committed docs; leaving plan files on disk after Cleanup. If the user says "commit the plan" — ask back: "the plan is ephemeral — what exactly should I inline into `decisions.md` / `changelog.md`?".
-
-## 3. Series & queue.md
-
-A **series** = 2+ related plans that share a roadmap. The index lives at `docs/plans/queue.md` (gitignored, machine-local):
-
-```markdown
-## Series: <name>
-
-### Current
-- **Plan N / M** — <slug> — <one-line description>
-
-### Pending
-- **Plan N+1 / M** — <slug or TBD> — <description>
-
-### Done
-- **Plan K / M** — <slug> — done YYYY-MM-DD. Outputs: <pointers>.
+```
+# Plan: <title>
+## Goal and boundary
+## Module ledger
+## Verification
+## Phase: Cleanup
+## Next steps
 ```
 
-`queue.md` is initialised when the **first** plan of a series is written, not during its Cleanup — without an upfront index the execution agent has no map of the series. Each plan's Cleanup then marks itself Done (with outputs) and promotes the next plan to Current. A single, unrelated plan does not need a series entry.
-
-## 4. Required Cleanup phase
-
-Every Plan MUST end with a final **Phase N: Cleanup** — the last numbered Phase. Without it the Plan is not done.
-
-Minimum content:
-
-- **Migrate outputs** → `docs/ai/decisions.md` (AD-XXX), `changelog.md`, `known_issues.md` (Issue-XXX), `current_state.md`, `pages/<page>.md`.
-- **Inline cross-references** — `grep -rn "<plan-slug>" docs/` must be empty. Every pointer is rewritten inline or removed.
-- **Update `queue.md`** — if part of a series, mark Done + promote next.
-- **Delete the plan file** — `rm docs/plans/<slug>.md`.
-- **Verification** — `grep -rn "<slug>" .` empty; `ls docs/plans/<slug>.md` → No such file; docs cap-validator green.
-
-If a Plan is aborted mid-flight, Cleanup still runs — partial outputs land in `known_issues.md`, then the file is deleted.
-
-## 5. All work in plans
-
-Anything required for the task is a **Step inside the Plan**. Nothing "before the plan", "between plans", or "don't forget" — those evaporate at execution time because the execution agent reads only the plan file, not chat scrollback. Every dependency, check, and install is its own Step or Substep. The final "Next steps" section contains **only user-actionable** items.
-
-## 6. Plan-then-execute split
-
-Default workflow for non-trivial features (multi-file change, new service + hook + UI, architectural choices): write a **self-contained Plan** and stop. Implementation runs in a fresh session via the `executing-plans` skill.
-
-- Triggers: any feature, refactor, or change touching more than ~1 file, or non-obvious architectural choices.
-- Does NOT apply to typos, one-line fixes, doc-only edits, or pure "where is X" research — those run inline.
-- The Plan must be readable cold by a fresh agent: file paths, contracts, execution order, verification, gotchas — all inside the file.
+A plan that does not fit is not under-described. Either the TASK is too big — split it along
+independently verifiable boundaries, never by document size — or it is a SWEEP (below).
 
-This split is a token-efficiency strategy: exploration context stays out of the execution window.
+- **Goal and boundary** (10 lines) — the observable outcome, what behaviour is preserved, explicit
+  non-goals.
+- **Module ledger** (60 lines) — the single list of paths, and the plan's execution order.
+- **Verification** (20 lines) — the acceptance check, plus one command that validates the whole ledger.
+- **Phase: Cleanup** and **Next steps** (human-actionable only) share the 10 reserved lines.
 
-### Session-continuity heuristic (split vs continue)
+## Module ledger
 
-The volume trigger above (files / LoC / tokens) is necessary but not sufficient. The deeper question is whether the planning context is the execution **payload** or **noise**:
+One row per path, ≤200 bytes per row, six fields:
 
-- **Split** (fresh session) when planning exploration was *broad fan-out* — many files skimmed, sub-agent dumps, wide searches to *locate* things. That context is noise for execution; discard it.
-- **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
-- When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
+```
+<check-id> | create|modify|delete | <path> | <responsibility, one sentence> | <max lines | n/a> | <anchor>
+```
 
-### ExitPlanMode authorizes the plan, not execution
+**The rows ARE the steps.** They execute top to bottom, each row is one logical commit, and a row may
+only anchor on a path above it or on existing code. There is no separate step/phase numbering — the
+only phases are session boundaries in a multi-session plan, and Cleanup.
 
-A harness "approved — you can now start coding" prompt (e.g. Claude Code's **ExitPlanMode**) authorizes the **PLAN only** — this methodology overrides that generic prompt. A planning session is not done until the plan is landed in `docs/plans/` **and** the cold-start execution prompt is emitted (the plan-authoring Definition of Done). So **"Continue in-session" above is a DELIBERATE transition into `plan-execution`, taken *after* both of those exist** — never an implicit slide from plan-approval straight into editing tracked files. Plan-approval is not a licence to execute the plan in the same breath; the boundary holds whether you split or continue.
+A `create` row's responsibility names the **exported surface** the module must provide — the names
+other rows import. That surface does not exist in the checkout yet, so it cannot be derived from it;
+this is the one interface contract a plan owes its executor.
 
-## 7. Plan-document structure
+Budgets come from the project's declared source-size cap. No declared cap → `n/a`, never an invented
+number. On `modify` the budget is the file's TOTAL size after the change, not a delta. A `delete` row
+carries `—` for budget and anchor.
 
-```
-# Plan: <human-readable title>
-
-## Context              ← why this Plan exists, current state, why now (reads cold)
-## Approach             ← chosen design + an explicit "What we are NOT doing"
-## Decisions (locked)   ← optional: settled, binding decisions the executor must not re-litigate
-## Phase 1: <name>
-   ### 1.1. <step>      ← exact paths + commands
-## Phase 2: <name>
-   ...
-## Phase N: Cleanup     ← mandatory (§4)
-## Critical files       ← table: file → change kind (new / modify / delete / move)
-## Reuse                ← pointers to existing patterns/snippets to copy, not re-derive
-## Verification         ← full check sequence (mechanical + behavioural)
-## Next steps           ← user-actionable only (§5)
-```
+**Total, not per-file.** The ledger ends with one line:
+`total: <before> → <after> lines`. Five files under a 400 cap can each be legal while the change
+doubles the codebase — the per-file budget cannot see that. Growth is allowed only with a stated
+reason on that line; a refactor that claims to reduce anything and grows is refused here, at plan
+time.
 
-## 8. Self-review checklist (before finalizing a Plan)
+**A SWEEP is one row.** A wide mechanical change — one edit repeated across N files — is a single row
+whose path is a glob, whose responsibility states the invariant every site must satisfy, and whose
+count is asserted. Splitting a sweep into per-file rows or into several plans costs more prose than
+the sweep, and breaks the intermediate states.
 
-- Every Step has exact file paths and exact commands.
-- Every recommendation that used to live outside the Plan is now a Step (§5).
-- Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
-- If part of a series: `queue.md` is initialised / updated (§3).
-- No `git add <plan>` and no "commit the plan" wording in the final report.
-- Every code-touching decision cites the `file:line` it is grounded in; the plan stays at intent / invariant / acceptance altitude, leaving fine code-mechanics to Execute (§9).
-- Decisions the review loop SETTLED (fixtures, contracts, boundary clauses) live under the optional `## Decisions (locked)` heading (§7) — binding for the executor, never re-litigated at Execute.
+## Verification
 
-## 9. Right-altitude & code-grounded folds
+Exact existing commands plus the acceptance check for the goal. The ledger is validated by ONE
+command over its `check-id`s — existence and budget for create/modify, absence for delete, the count
+for a sweep, and the total line. Per-row assertions in prose are the repetition this section exists
+to avoid.
 
-These disciplines keep a plan converging instead of churning, and keep a fold or edit from shipping a new bug. They govern authoring, every review round, and execution. The honest premise: prose has no checker, so the only guarantee that a fold/edit ships no regression is a deterministic, non-vacuous, auto-run gate — hence test-as-spec + characterize-first below.
+## What gets cut
 
-**Right altitude.** A plan pins *intent + architecture + invariants + acceptance criteria* — the named tests that must stay green and the new tests that must pass. It does NOT spell out fine code-mechanics in prose: those are resolved in code at Execute (against the real files + the per-Step review + the gates), where prose cannot diverge from reality. Most "blockers" that resurface across review rounds are code-level details that never belonged in a prose plan.
+Delete any line for which both answers are yes: *can a zero-context executor still pick the right
+files without it?* and *can verification still catch a wrong result without it?* Specifically, cut:
 
-**No code-mechanics in the plan.** A Step still carries its exact paths + commands (§7, §8) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate, and merely running without asserting checks nothing; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL, anything that transforms data or evaluates a condition — never lives in plan prose, however plausible or shell-verified it looks ("I ran it in my shell" is not a checker): a fold or draft that wants one is the trigger to write the red→green test-as-spec at Execute instead.
+- prose that restates code reachable from a named anchor — keep the anchor, drop the retelling
+- anything already binding from `AGENTS.md`, package scripts or repo convention
+- rejected alternatives, discussion history, past incidents that do not change the file map
+- edge cases, failure paths, rollback narratives that change neither a boundary nor a check
+- implementation walkthroughs and pseudocode — except a `create` row's exported surface, above
+- any requirement stated twice, and any dependency or install that is not its own ledger row
 
-**Fold by code, not prose.** Before folding any code-touching finding into the plan, READ the cited `file:line`; the fold cites it. A fold grounded in prose alone drifts from the code and seeds the next bug.
+**A decision settled during review is not a section.** It becomes a boundary or non-goal in Goal, or a
+check in Verification. A settlement expressible as neither is code-level detail for Execute.
 
-**Test-as-spec.** Fold a code-touching review finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker, and a paragraph cannot self-check. A bug may still be written, but the test catches a fold-/edit-induced regression before it ships.
+**Review asks what to cut, not what is missing.** A line may be ADDED only by naming the specific
+wrong execution it prevents AND deleting at least as many lower-value lines. A review comment asking
+for "more completeness" is refused by this rule.
 
-**Characterize-first.** Before editing UNCOVERED code, first write a test pinning its current behavior (green), then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible (one logical change = one gated commit), and prefer SUBTRACTIVE folds.
+## Un-run syntax never ships in prose
 
-**Fold minimally — a prose plan has no checker.** An ephemeral, gitignored plan is PROSE with no executable checker, so a single fold that silently drifts one of several prose spots seeds the next churn round (this is what turns a 2-round review into a 6-round one). Fold **minimally, in ONE place**, run a **self-consistency** read across the whole plan before every re-review, and keep the plan SHORT. The only runtime firing an ephemeral plan can carry is the point-of-use advisor's printed review-loop checkpoint — there is no other checker.
+A plan carries exact commands its own Verification RUNS against a stated expected outcome, plus
+literal fixtures a named test validates. Control flow, regexes, grammars, algorithm bodies — anything
+that transforms data or evaluates a condition — never live in plan prose: prose has no checker. A
+finding that wants one is the trigger to write a red→green test at Execute instead.
 
-**Heavy review at the diff, not the plan.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** — one backend grounded-ships while another keeps revising line-by-line mechanics — IS that crossover: resolve at altitude (raise the surviving major to an acceptance invariant, or hand the mechanics to Execute), do not exhaust the strictest backend. Route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**, where the runner and gates settle it, not another prose round. The plan is the wrong place for an exhaustive line-by-line review.
+## Cleanup, and the plan's own life
 
-**Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY named backend the recipe runs (nits / non-blocking + a ship verdict is the stop). FOLDING a finding is NOT convergence — re-review after folding. This §9 governs the ALTITUDE at which you reach clean (fix the major, or raise it to an explicit acceptance invariant Execute must meet) — it NEVER lowers the bar to "majors folded".
+Plan files are **ephemeral, gitignored, never committed**. If something in a plan is load-bearing,
+inline it into a durable doc — `decisions.md`, `changelog.md` — and delete the plan. `git add` of a
+plan file, and plan paths inside committed docs, are forbidden.
 
-**Convergence heuristic.** When a review round keeps finding code-mechanism issues on a stable architecture, STOP refining prose — either raise the spec to invariant + acceptance altitude, or hand the mechanics to Execute. Do not re-litigate code mechanics in the plan.
+**Every plan ends with `## Phase: Cleanup`.** It migrates outputs to the durable docs, updates
+`docs/plans/queue.md` for a series, deletes the plan file, and verifies `grep -rn "<slug>" .` is empty
+and the docs cap-validator is green. An aborted plan still runs Cleanup — partial outputs land in
+`known_issues.md`.
 
-**Computed instrument (plan-execution).** The plan-execution (code) loop's stop is READ from the four deterministic checks + the ship receipts, never remembered: declare each bugfix red BEFORE the fix (`core-evidence red-proof` — an observed N/N red with content custody); an unavailable review backend gets an explicit `core-evidence degrade` record, never a silent skip; then stage everything, run the configured reviews on the STAGED tree, and mint the ONE receipt with `run-gates --final` (coverage of every changed executable line + red-proof verification ride the final run); `commit-guard --check` gates the commit against that receipt — any later edit re-stales it (the exit contracts live in each tool's own header — point, don't restate); `core-evidence summary` renders the loop state statelessly. The per-round finding-origin tally + triage classification discipline — **fixable-bug** (a fold pinned by a red→green test) / **inherent-layer-residual** (raised to an acceptance criterion) / **escalate** (a maintainer decision) — stays the dialogue-level discipline for BOTH activities; no ledger records it.
+## The plan must read cold
 
-## 10. Autonomy at the plan checkpoints
+The executing session sees the plan file and the repository, never the authoring conversation.
 
-The plan lifecycle's human checkpoints — plan **approval** (plan-authoring ends there), each
-**gated commit** (plan-execution commits per Step), and any push/publish ask — are **fixed points
-the autonomy policy never moves** (`orchestration.md` §7). What the per-activity level changes is
-the texture *between* them: under `sandbox` autonomy the executor runs a whole working stretch —
-edits, tests, gates, review dispatches — to the next checkpoint without per-command prompts (the
-OS sandbox confines the blast radius); under `prompt` it asks along the way. **Read the policy at
-session start** (`docs/ai/autonomy.json`; absent → the computed defaults ARE the policy; malformed
-→ STOP loudly) alongside the standing recipe preference, and state the effective level in the
-session's opening summary so the human knows which texture to expect. A plan itself never needs to
-restate the policy — it is per-project configuration, not plan content; a plan names an autonomy
-requirement only when a Step genuinely departs from the declared level (e.g. a consent-gated
-privileged install), and that departure is always an explicit ask, never a silent widening.
+Heavy review belongs at the diff, not the plan: plan review settles boundaries, budgets and the
+total; the per-row review runs against real code where a gate fails immediately. An all-mechanics
+artifact — a sweep, CI wiring, prose-only edits — takes a thin plan plus a diff review rather than
+another prose round.

package/references/procedures.md

@@ -1,44 +1,29 @@
 # Activity Procedures
 
-Canonical, on-demand reference for **how an orchestrating agent performs a named activity** — the
-ordered steps of a workflow activity with **typed recipe slots** that bind to the
-[orchestration recipes](orchestration.md) (Solo / Reviewed / Council / Delegated). This is the
-*how to perform* source of truth; it composes with — and never restates — the plan structure and
-lifecycle in [`planning.md`](planning.md). The composition root (`agent-workflow-kit`) reads this
-canon LIVE and renders the requested activity's steps + the resolved effective recipe per slot via
-the read-only `/agent-workflow-kit procedures <activity>`; it parses ONLY each section's `Slots:`
-line (drift-guarded against its activity table), never the steps.
-
-A **recipe slot** is a point in an activity where a recipe applies: `review` accepts
-`solo | reviewed | council`; `execute` accepts `solo | delegated`. The per-project default lives in
-`docs/ai/orchestration.json` and is resolved against backend readiness by the kit — never decided in
-this canon. Each activity section below begins with a machine-parseable `Slots:` line (the only line
-the kit parses) and then its ordered steps. Terse by design: it points at the canon it binds to, it
-does not restate it.
-
-The commit rule holds across every activity: **when an activity has a commit boundary, the
-orchestrator owns that commit; a backend is advisory or delegated, never autonomous, and never
-commits** (see [`orchestration.md`](orchestration.md) §6). Not every activity commits —
-`plan-authoring` ends at **approval** and produces **no** commit (plans are ephemeral, never
-committed); `plan-execution` commits **per Step**. Any project-declared release/publishing or extra
-stages are honored per the project's `workflow:methodology` slot — this generic canon bakes in no
-single project's stages.
-
-**Read your preference at session start.** At the start of a planning or execution session, read the
-project's standing recipe preference in `docs/ai/orchestration.json` (set it in plain language with
-`/agent-workflow-kit set-recipe` — it previews then writes; hand-editing the file stays supported); the
-kit resolves it against backend readiness. Do not re-ask each session what is already configured there.
-Read the **autonomy policy** the same way and at the same moment: `docs/ai/autonomy.json` declares the
-red-lines and the per-activity autonomy level (absent → the computed defaults ARE the policy; malformed
-→ STOP loudly, never guess; set it with `/agent-workflow-kit set-autonomy`) — the per-activity
-procedures below run UNDER that policy (`orchestration.md` §7), and the kit's `procedures` advisor
-prints the resolved level beside each activity's recipes.
-
-**Communication contract.** Every user-facing message delivers the artifact **inline** — the plan, the
-next-session prompt, the diff, the value asked for — never a bare pointer ("see §X / open the file") as a
-*substitute* for showing it; lead with the result, show exactly what was asked, and never read as
-mockery. For a genuinely large artifact, deliver a real summary or the key excerpt inline **and** link
-the file — never flood, never hide.
+The ordered steps of each named activity, with **typed recipe slots** bound to the
+[orchestration recipes](orchestration.md). It composes with — never restates —
+[`planning.md`](planning.md), naming that canon's sections by *heading*. The kit reads this file
+LIVE and parses ONLY each section's `Slots:` line, never the steps.
+
+A **recipe slot**: `review` accepts `solo | reviewed | council`; `execute` accepts
+`solo | delegated`. The per-project default lives in `docs/ai/orchestration.json`, resolved against
+backend readiness by the kit.
+
+**When an activity has a commit boundary, the orchestrator owns that commit; a backend is advisory
+or delegated, never autonomous, and never commits** (`orchestration.md` §6). `plan-authoring` ends
+at **approval** with no commit (plans are ephemeral, never committed); `plan-execution` commits per
+ledger row.
+
+**Read your preference at session start.** At the start of a planning or execution session, read
+`docs/ai/orchestration.json` (`/agent-workflow-kit set-recipe` writes it; hand-editing stays
+supported) and never re-ask it. Read the **autonomy policy** the same way and at the same moment:
+`docs/ai/autonomy.json` (absent → the computed defaults ARE the policy; malformed → STOP loudly,
+never guess; `/agent-workflow-kit set-autonomy` writes it) — every procedure below runs UNDER it
+(`orchestration.md` §7).
+
+**Communication contract.** Every user-facing message delivers the artifact **inline** — never a
+bare pointer ("see §X") as a substitute; lead with the result; a large artifact gets a real summary
+inline plus the link.
 
 ---
 
@@ -46,85 +31,57 @@ the file — never flood, never hide.
 
 Slots: review
 
-Produce a self-contained, cold-readable plan, reviewed to the configured depth before approval.
-
-1. **Research** — gather the exact files, contracts, and constraints the plan will touch.
-2. **Draft** — write the plan to the document structure defined in [`planning.md`](planning.md) §7,
-   with exact paths and commands per Step. Bind to that structure; do not restate it here.
-3. **Self-review** — run the [`planning.md`](planning.md) §8 checklist (exact paths/commands, strict
-   vocabulary, every out-of-plan recommendation folded into a Step, `queue.md` updated for a series).
-   Apply the [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and
-   hold the right altitude.
-4. **review {recipe}** — review the draft at the depth the resolved `review` recipe selects: Solo
-   (self-review only), Reviewed (one backend reviews), or Council (both backends review, you
-   synthesize). The kit resolves the effective recipe from `docs/ai/orchestration.json` + readiness.
-5. **Fold + loop** — fold every finding back into the draft and re-review. A loop is CLEAN only at
-   **0 blockers + 0 majors** from every backend the recipe names (the convergence bar,
-   [`planning.md`](planning.md) §9); folding ≠ convergence — re-review after folding. Fold a
-   code-touching finding **test-as-spec** (a named acceptance test, not a prose paragraph); a fold must
-   add **no code-mechanics** to the plan — a Step still carries its own exact paths + commands
-   (checked syntax: its Verification asserts an expected outcome), but un-run, logic-bearing syntax
-   (control-flow, a regex, a glob, a mini-DSL) never enters plan prose — a fold needing one is the
-   trigger to name the test instead. Council runs every named backend
-   **every round** (recipe fidelity,
-   [`orchestration.md`](orchestration.md) §4) — never quietly drop a ready backend. Cap architecture
-   plan-review at **≤2 rounds**, stopping at the **crossover** where **backend divergence** (one backend
-   grounded-ships while another keeps revising mechanics) IS the stop — the bar is still met by RESOLVING
-   the surviving major at altitude (raise it to an acceptance invariant, or hand it to Execute), never by
-   exhausting the strictest backend. Run a **self-consistency** read before every re-review and route an
-   all-mechanics/CI or prose-only artifact to a **thin plan + diff-review** ([`planning.md`](planning.md)
-   §9). Each round MUST emit **{round N · finding-origin tally (first-draft / fold-induced / mechanics) ·
-   per-backend verdict}** so the crossover is a computed signal, not a remembered rule. At the cap,
-   classify every surviving blocking finding — **fixable-bug** (fold ONCE as a red→green test, re-review)
-   / **inherent-layer-residual** (document + raise to an acceptance criterion) / **escalate** (the
-   maintainer decides); a minor never forces triage.
-6. **Present for approval** — surface the finished plan to the user; do not begin execution here. A
-   harness "approved — start coding" prompt (**ExitPlanMode**) authorizes the PLAN only
-   ([`planning.md`](planning.md) §6); continuing into `plan-execution` is a deliberate transition taken
-   after the plan + its cold-start prompt exist, never an implicit slide.
-
-**Required output (Definition of Done):** a planning session produces a self-contained plan in
-`docs/plans/` **and** a cold-start execution prompt to begin the next session — **both produced without
-the user asking**. A planning session that ends without both is not done.
-
-The plan MUST end with the mandatory **Phase: Cleanup** ([`planning.md`](planning.md) §4) — a plan
-without it is not done.
+1. **Research** — the exact files, contracts and constraints touched.
+2. **Draft** — write to the shape [`planning.md`](planning.md) fixes; its *Module ledger* decides
+   the layout and every budget before any file exists — a size gate is only the backstop.
+3. **Self-review** — apply *What gets cut*; fold by code (read and cite the `file:line`); update
+   `queue.md` for a series.
+4. **review {recipe}** — Solo (self-review only) / Reviewed (one backend) / Council (both; you
+   synthesize), as the resolved `review` recipe selects.
+5. **Fold + loop** — fold every finding and re-review; CLEAN is **0 blockers + 0 majors** from every
+   backend the recipe names — folding ≠ convergence. Fold a code-touching finding **test-as-spec**,
+   with **no code-mechanics** in the plan: only **checked syntax** its Verification runs; un-run,
+   **logic-bearing** syntax never enters prose (*Un-run syntax never ships in prose*). Council runs
+   every named backend **every round** (recipe fidelity, `orchestration.md` §4). Cap architecture
+   review at **≤2 rounds**; **backend divergence** (one ships, one keeps revising mechanics) IS the
+   **crossover** — resolve the surviving major at altitude, never by exhausting the strictest
+   backend; a **self-consistency** read precedes each re-review; an all-mechanics or prose-only
+   artifact takes a thin plan + **diff-review** (*The plan must read cold*). Each round MUST emit
+   **{round N · finding-origin tally · per-backend verdict}**. At the cap, classify each surviving
+   blocker or major: **fixable-bug** (fold ONCE as a red→green test, re-review) /
+   **inherent-layer-residual** (raise to an acceptance criterion) / **escalate**.
+6. **Present for approval** — never execute here: a harness "approved — start coding" prompt
+   (**ExitPlanMode**) authorizes the PLAN only; `plan-execution` is a deliberate transition once
+   the plan and its cold-start prompt exist.
+
+**Definition of Done:** a plan in `docs/plans/` ending with **Phase: Cleanup** **and** a cold-start
+execution prompt to begin the next session — both produced without the user asking.
 
 ## plan-execution
 
 Slots: execute, review
 
-Execute an approved plan Step by Step; each Step is one logical commit.
-
-1. **Per Step, resolve the recipe** — the kit resolves `execute` and `review` for this run from
-   `docs/ai/orchestration.json` + readiness (a per-run `--override <slot>=<recipe>` is allowed).
-2. **If `execute` resolved to Delegated, dispatch execution FIRST** — hand the bounded sub-task to the
-   backend (codex-exec → a diff) *before* integrating; otherwise the orchestrator implements the Step
-   directly.
-3. **Implement / integrate** — apply the change (your own edits, or the reviewed delegated diff),
-   following the project's reuse + clean-code rules.
-4. **Self-review** — run the [`planning.md`](planning.md) §8 self-review on the change, applying the
-   [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and hold the
-   right altitude. Edit-time corollary: **characterize-first** — before editing uncovered code, pin its
-   current behavior in a green test, then edit (any unintended change goes red); fold each finding
-   **test-as-spec** (red→green), and keep edits atomic/reversible.
-5. **review {recipe}** — review the result at the resolved `review` depth (Solo / Reviewed / Council),
-   exactly as in plan-authoring. This is the **heavy review at the diff** — real compiling code + the
-   full suite, where a regression fails a gate immediately ([`planning.md`](planning.md) §9). Council
-   runs every named backend **every round** (recipe fidelity, [`orchestration.md`](orchestration.md) §4);
-   loop to **0 blockers + 0 majors** from every backend before the gate. Each round MUST emit
-   **{round N · finding-origin tally · per-backend verdict}**; when backends diverge, that is the
-   crossover — resolve at altitude, not by exhausting the strictest backend. Classify survivors at the
-   cap the same way (**fixable-bug / inherent-layer-residual / escalate**). This loop's computed
-   instruments: `core-evidence red-proof` declares each bugfix red BEFORE the fix; `core-evidence
-   degrade` records an unavailable backend explicitly; the reviews run on the STAGED tree and
-   `run-gates --final` mints the ONE receipt `commit-guard --check` gates the commit against — the
-   exit contracts live in each tool's own header, never restated here.
-6. **Gates** — run the project's verification gate (tests + checks) to green before committing.
-7. **Commit boundary** — the orchestrator makes the single commit for the Step; a backend never
-   commits. The project's commit-approval policy (e.g. ask first) lives in the project's own rules.
-
-**Output:** each Step lands as one logical commit with its gates green; the orchestrator owns the commit.
-
-Honor any project-declared release/publishing or extra stages (per the `workflow:methodology` slot)
-before the plan's Cleanup — this generic canon does not enumerate them.
+Each ledger row is one logical commit.
+
+1. **Resolve the recipe per row** — `execute` and `review` from `docs/ai/orchestration.json` +
+   readiness (`--override <slot>=<recipe>` per run).
+2. **If `execute` resolved to Delegated, dispatch execution FIRST** — the backend returns a diff
+   (codex-exec) *before* you integrate; otherwise implement directly.
+3. **Implement / integrate** — your own edits or the reviewed delegated diff.
+4. **Self-review** — the change against its [`planning.md`](planning.md) ledger row and the plan's
+   Verification, under the project's reuse and clean-code rules; fold by code (cite the
+   `file:line`); **characterize-first**: pin uncovered code's behaviour in a green test before
+   editing it; fold each finding test-as-spec (red→green); atomic, reversible edits.
+5. **review {recipe}** — the **heavy review at the diff** (*The plan must read cold*): real code and
+   the full suite. The plan-authoring loop applies unchanged — every named backend every round,
+   **0 blockers + 0 majors**, the **{round N · finding-origin tally · per-backend verdict}**
+   emission, **fixable-bug / inherent-layer-residual / escalate** at the cap. Its instruments:
+   `core-evidence red-proof` declares each bugfix red BEFORE the fix; `core-evidence
+   degrade` records an unavailable backend; reviews run on the STAGED tree; `run-gates --final`
+   mints the ONE receipt `commit-guard --check` gates the commit against.
+6. **Gates** — the project's verification gate to green.
+7. **Commit boundary** — the orchestrator makes the single commit; a backend never commits; the
+   commit-approval policy lives in the project's own rules.
+8. **After the last row** — the project-declared release or extra stages (the `workflow:methodology`
+   slot; this canon bakes in none) and then `## Phase: Cleanup` (*Cleanup, and the plan's own
+   life*) run as rows of their own, each through steps 1–7.