mandrel 2.13.0 → 2.15.0

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -23,7 +23,7 @@ caller: helpers/deliver-story.md
 
 ## Step 0 — Lease preflight and merged-sweep
 
-### Lease preflight (Story #3483)
+### Lease preflight
 
 Before any git mutation, init takes an exclusive, time-bounded **lease** on
 the Story ticket via the assignee-as-lease primitive
@@ -33,7 +33,7 @@ Epic-scoped dispatch manifest to serialise two operators driving the same
 Story, so this lease is the only guard against a concurrent
 `single-story-init` clobbering an in-flight run.
 
-**Fail-closed (audit #3513).** Unlike `/deliver`, the standalone path
+**Fail-closed.** Unlike `/deliver`, the standalone path
 has **no Epic-scoped lifecycle ledger** to read a per-owner
 `story.heartbeat` from, so there is no live-heartbeat source to decide
 whether a foreign claim is stale. Rather than silently reclaim every
@@ -49,7 +49,7 @@ foreign assignee (which would leave the guard inert), the standalone lease
 `--dry-run` skips the lease (no assignee mutation). The matching release
 runs in `single-story-close.js` (Step 3).
 
-### Branch reuse (Story #3483)
+### Branch reuse
 
 When a `story-<id>` branch already exists locally, init **reuses** it rather
 than re-creating it (re-running `git branch` on an existing ref throws
@@ -69,7 +69,7 @@ matching `origin/` ref, and stale tracking refs for any merged sibling
 stories are reaped in one pass. The sweep never blocks init — failures
 are logged and the new story is initialized regardless.
 
-The sweep applies two hardening layers (Story #2011):
+The sweep applies two hardening layers:
 
 - **Per-candidate protection.** Each merged-PR candidate is filtered
   through three guards before reaching `executeCleanup`:
@@ -105,7 +105,7 @@ checkout** if it resolves a main-checkout absolute path. To stay in the
 worktree you MUST prefix **every Edit/Write/Read path with the absolute
 worktree root** (the `workCwd` value from Step 0), not merely `cd` into it.
 Never edit files under the bare main-checkout root. `single-story-close.js`
-runs a **wrong-tree guard** (Story #3364) that aborts close and posts a
+runs a **wrong-tree guard** that aborts close and posts a
 `friction` comment if it finds uncommitted tracked-path edits in the main
 checkout while the worktree is the active work tree — but that is a backstop,
 not a substitute for prefixing paths correctly.
@@ -121,11 +121,11 @@ The v2 engine's trait table:
 | Ticket type | `type::story` only |
 | Branch | `story-<id>` seeded from `project.baseBranch` (`main`) |
 | Merge target | `main` via PR (squash + required checks) |
-| Epic integration branch | **None** — no `epic/<id>`, no `--no-ff` wave merge |
 | Spec / slices | Folded `## Spec` + optional `## Slicing` checkpoints in-session |
 | Ceremony | Per-Story, routed off the derived change level via `ceremony-routing.js` |
 
-**Ceremony-lite Stories still land through this engine unchanged (Story #4683).** A lite-routed Story collapses only the *advisory* plan/deliver
+**Ceremony-lite Stories still land through this engine unchanged.** A
+lite-routed Story collapses only the *advisory* plan/deliver
 ceremony — the fresh-critic / Tech-Spec authoring a one-artifact scope does
 not earn. It does **not** get a cheaper landing: the close-validation gates
 (lint / test / format / coverage / CRAP / maintainability), the PR to `main`,
@@ -133,7 +133,7 @@ and the `rules/security-baseline.md` MUSTs all run exactly as for a
 full-ceremony Story. The lite route's `preserves` field is the machine-readable
 record of those non-negotiables; there is no lite-specific gate bypass.
 
-**Deliver derives the route from the Story body's shape (Story #4722).**
+**Deliver derives the route from the Story body's shape.**
 Persist stamps a lite cohort's Stories with the `route::lite` label as a
 *human-visible hint only* (and ledgers the authored verdict — recorded
 reason plus per-Story shape evidence — on the `story-plan-state`
@@ -167,7 +167,7 @@ demand. See [`.agents/instructions.md` § 3](../../instructions.md).
 write and self-check as you author. When absent, lens-aware coverage still
 runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
-before it spawns the worker (Story #4627) — see [`/deliver`](../deliver.md).
+before it spawns the worker — see [`/deliver`](../deliver.md).
 
 **Pre-eval full-suite discipline (spine step 5).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
@@ -181,7 +181,7 @@ directly.
 
 ### Step 1a — self-eval mechanics
 
-**One verdict-owner per cluster (Story #4723).** The ceremony routing's
+**One verdict-owner per cluster.** The ceremony routing's
 resolved decision names each cluster's single verdict owner
 (`verdictOwner: 'fresh-critic' | 'inline-self-eval'` from
 `resolveCeremonyForRisk`): the fresh maker-blind critic when sensitivity
@@ -195,7 +195,7 @@ round cap, proceed / redraft / block — not an independent additional pass
 over the criteria. The M4-B floor holds: one verdict per cluster, the
 cluster count owned by `acceptance-clusters.js` alone.
 
-**Critic evidence-share (Story #4250).** When the critic runs a `verify[]`
+**Critic evidence-share.** When the critic runs a `verify[]`
 command that is byte-identical to a close gate (`lint` / `typecheck`), it
 records the pass into the Story evidence keyspace via `--standalone` so
 close short-circuits the gate at unchanged HEAD. Run it in the **Story
@@ -220,7 +220,7 @@ node .agents/scripts/update-ticket-state.js --ticket <storyId> --state agent::bl
 
 ## Step 2 — Ceremony detail
 
-**Compute the change set once** (Story #4593) with the shared enumerator —
+**Compute the change set once** with the shared enumerator —
 the same module close uses — and reuse that one list downstream:
 
 ```bash
@@ -247,7 +247,7 @@ Resolve fresh-vs-inline acceptance critics per AC-cluster with
 floor forces `fresh`). Review depth reads the same derived level via
 `review-depth.js` inside close, so the two decisions cannot disagree.
 
-**Lite-route override (Story #4722).** When the Story's body derives the
+**Lite-route override.** When the Story's body derives the
 lite shape (`resolveStoryDispatchMode` → `inline`), run every
 acceptance critic **inline** — do not spawn fresh-context critic sub-agents
 regardless of what the profile would otherwise resolve. The self-eval rigor
@@ -261,7 +261,7 @@ removed. Hard gates are untouched.
 
 **What close does internally.** The script runs the close-validation gates
 against `baseBranch`, syncs the Story branch from `origin/<baseBranch>`
-(Story #2580 — the parallel-race defence), pushes `story-<id>`, opens (or
+(the parallel-race defence), pushes `story-<id>`, opens (or
 reuses) a PR against `baseBranch` with a `Closes #<storyId>` footer, enables
 GitHub native auto-merge (`--auto --squash --delete-branch`) **when
 `delivery.ci.autoMerge` is `"trust-ci"` (the default)**, flips the Story to
@@ -284,7 +284,8 @@ The wait probes the checks every poll: a red required check fails fast as
 `checks-failed` instead of burning the budget, and a PR that falls behind its
 base is brought up to date within `updateAttempts` tries.
 
-**Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`, Story #4698).** Under the default `"sync"` the merge wait runs in the foreground as
+**Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`).** Under
+the default `"sync"` the merge wait runs in the foreground as
 described above. When a consumer's CI routinely takes longer than the host
 tool ceiling (~10 min) can hold a single close invocation, the foreground
 wait almost always expires `pending` after burning ~5 minutes of the slot —
@@ -309,29 +310,25 @@ checks pass. Under `"strict"`, the close **does not arm auto-merge** — the
 PR opens and waits for an **operator merge**, exactly as `--no-auto-merge`
 does per-run.
 
-**Close flags:**
-
-- `--skip-validation` — bypass the gates. Use only when re-running close
-  after a fixed gate failure that's already known to pass.
-- `--skip-sync` — bypass the base-sync (Story #2580). Use only after a
-  hand-resolved sync, or in tests.
-- `--no-auto-merge` — disable auto-merge. Use when the PR materially changes
-  behaviour and warrants a pre-merge eyeball; the operator then merges via
-  the GitHub UI.
-- `--wait-merge` — **close-and-land** (Story #4428). Forces close to poll
-  the armed PR to merge confirmation and flip `agent::done` itself. When
-  neither land flag is passed, close defaults from
-  `delivery.routing.closeAndLand` (**true**): attended and headless delivers
-  share the land-in-one-close happy path.
-- `--no-wait-merge` — explicit opt-out that always wins. Use when the
-  operator wants the PR left at `agent::closing` for a human land (or a
-  wrapper that will invoke `single-story-confirm-merge.js` itself). Reports
-  `pending` — the work is not done, nothing is broken, and one named command
-  finishes it.
-- `--max-wait-seconds <n>` — raise the merge wait's per-invocation bound for
-  this run (Story #4543). Use from a headless caller with no host
-  tool-invocation ceiling to keep single-block semantics without editing the
-  consumer's config.
+**When to reach for a close flag.** What each one *does* is in
+`node .agents/scripts/single-story-close.js --help`; below is only the
+judgment that help text cannot carry.
+
+- `--skip-validation` — only when re-running close after a fixed gate
+  failure that's already known to pass.
+- `--skip-sync` — only after a hand-resolved sync, or in tests.
+- `--no-auto-merge` — when the PR materially changes behaviour and warrants a
+  pre-merge eyeball; the operator then merges via the GitHub UI.
+- `--wait-merge` — **close-and-land**. When neither land flag
+  is passed, close defaults from `delivery.routing.closeAndLand` (**true**):
+  attended and headless delivers share the land-in-one-close happy path.
+- `--no-wait-merge` — the explicit opt-out always wins. Use when the operator
+  wants the PR left at `agent::closing` for a human land (or a wrapper that
+  will invoke `single-story-confirm-merge.js` itself). Reports `pending` —
+  the work is not done, nothing is broken, and one named command finishes it.
+- `--max-wait-seconds <n>` — from a headless caller with no host
+  tool-invocation ceiling, to keep single-block semantics
+  without editing the consumer's config.
 
 ---
 
@@ -341,14 +338,14 @@ The `single-story-close.js` script, in order:
 
 1. Runs the close-validation gates against `baseBranch` as the baseline.
    On any gate failure it throws — the operator fixes and re-runs close.
-   **Gate output is captured, not streamed (Story #4736).** Every gate line
+   **Gate output is captured, not streamed.** Every gate line
    goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
    one digest line naming that artifact, and a **failed** gate replays its
    captured tail inline so the evidence is in front of you without opening a
    file. Read the artifact when you need the full text — or re-run under
    `AGENT_LOG_LEVEL=verbose` for live streaming.
-1a. **Syncs the Story branch from `origin/<baseBranch>`** before push
-   (Story #2580). Runs `git fetch origin <baseBranch>` followed by
+1a. **Syncs the Story branch from `origin/<baseBranch>`** before push.
+   Runs `git fetch origin <baseBranch>` followed by
    `git merge --no-edit origin/<baseBranch>` inside the worktree. This
    defends against the parallel-`/deliver-story` race: when
    multiple sessions run in parallel, the Story that auto-merges first
@@ -385,7 +382,7 @@ The `single-story-close.js` script, in order:
    GitHub UI. Pass `--no-auto-merge` to opt out when the PR needs a
    pre-merge eyeball.
 4. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
-   the GitHub issue **OPEN** (Story #3385). Auto-merge completes
+   the GitHub issue **OPEN**. Auto-merge completes
    asynchronously *after* this script exits, so closing the issue here
    would strand a CLOSED issue with no merged work if the PR later failed
    CI, went `BEHIND` base, or was closed without merging. The Story rests
@@ -397,7 +394,7 @@ The `single-story-close.js` script, in order:
    only reaches `agent::done` once its PR to `main` is confirmed merged.
 5. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
    is enabled.
-6. **Releases the Story lease** (Story #3483). Clears the Story assignment
+6. **Releases the Story lease.** Clears the Story assignment
    that init claimed so the next `/deliver-story` run sees an
    unclaimed ticket. The release is a no-op when the operator no longer
    holds the claim (a later run took over via reclaim/steal), so a late
@@ -436,7 +433,7 @@ armed across retries, so you do not re-arm — then resume the land with the
 envelope's `nextCommand`.
 
 To watch the checks on the red path, drive `pr-watch-with-update.js` — the
-**single CI-watch mechanism** (Story #4358). It polls the required checks to a
+**single CI-watch mechanism**. It polls the required checks to a
 terminal state and auto-recovers from `mergeStateStatus: BEHIND`; do **not**
 fall back to a bare `gh pr checks` watch invocation:
 
@@ -485,7 +482,7 @@ where a worker most often misbehaves: it delivers up to arming auto-merge,
 then ends its turn with **free-form prose** — e.g. "I'll wait for the
 background watch task to complete" or "the next event will be its completion
 notification" — leaving the merge unconfirmed and the Story stranded at
-`agent::closing` (observed on Story #1553 / PR #1554). **Do not do this.**
+`agent::closing`. **Do not do this.**
 `pr-watch-with-update.js --pr <prNumber>` *blocks the current turn* until CI
 resolves — that is the mechanism by which you wait. You MUST keep your turn alive
 across the wait: watch → (fix + push + re-watch on red) → confirm the merge
@@ -593,14 +590,13 @@ when `--pr` is omitted) and:
 - **Story already `agent::done` / issue already closed** → idempotent
   `{ action: 'noop', reason: 'already-done' }`.
 
-The issue closes exactly when the work has merged, never at PR-open
-(#2155).
+The issue closes exactly when the work has merged, never at PR-open.
 
 ---
 
 ## Step 5.5 — Re-assert Status column detail
 
-> **The land tail already ran this** (Story #4543) — it is `tail.statusResync`
+> **The land tail already ran this** — it is `tail.statusResync`
 > in the terminal envelope. Run it by hand only when that step reported
 > `false`, or after a manual merge on a `--no-wait-merge` run.
 
@@ -609,7 +605,7 @@ node .agents/scripts/resync-status-column.js --story <storyId>
 ```
 
 The helper re-fires the `ColumnSync` mutation and **polls for ~15 s** to win the
-race against the bot's late write (Story #2876). It is idempotent and
+race against the bot's late write. It is idempotent and
 no-op-safe (`no-project` / `not-on-project` exit 0).
 
 The GitHub Projects v2 built-in workflows `Pull request merged` and
@@ -617,9 +613,9 @@ The GitHub Projects v2 built-in workflows `Pull request merged` and
 and fire ~minutes *after* auto-merge lands. They overwrite the Status
 field as a side-effect, clobbering the `Done` value
 `single-story-confirm-merge.js` set at the `agent::done` flip in Step 5
-and leaving closed Stories stuck at `In Progress` on the board
-(reproduced on Story #2813). The confirmation step has already exited by
-then, so the bot gets the last write.
+and leaving closed Stories stuck at `In Progress` on the board. The
+confirmation step has already exited by then, so the bot gets the last
+write.
 
 `resync-status-column.js`:
 
@@ -627,21 +623,17 @@ then, so the bot gets the last write.
 - Re-fires the same `ColumnSync` mutation `transitionTicketState` used
   at close, overwriting the bot's late write.
 - **Polls the live Status for ~15 s after the initial write** and
-  re-fires on drift (Story #2876). Without this loop, a one-shot
+  re-fires on drift. Without this loop, a one-shot
   mutation routinely lost the race against the bot's asynchronous
-  fire (reproduced on Story #2871 / PR #2872).
+  fire.
 - Prints a single-line JSON envelope:
   `{ ticketId, status, column?, reason?, attempts? }`. `attempts > 1`
   means the helper had to fight a bot overwrite; `status: 'drifted'`
   means the bot won every attempt in the poll budget (rare; usually
   signals operator should reap the conflicting workflows).
 
-Tuning flags (rarely needed):
-
-- `--poll-attempts <n>` — total mutation attempts including the
-  initial sync. Default `4`. Pass `1` to disable the poll loop
-  (fastest, matches pre-#2876 behaviour).
-- `--poll-delay-ms <ms>` — delay between drift checks. Default `5000`.
+Tuning flags are rarely needed; the script enumerates them itself
+(`node .agents/scripts/resync-status-column.js --help`).
 
 Idempotent: re-running on a ticket whose Status already matches the
 target returns the same envelope. No-op skips (`no-project`,
@@ -658,7 +650,7 @@ defense-in-depth against re-enabled or future workflows.
 
 ## Step 6 — Local branch cleanup detail
 
-> **The land tail already ran this** (Story #4543) — it is `tail.refCleanup` and
+> **The land tail already ran this** — it is `tail.refCleanup` and
 > `tail.baseFastForward` in the terminal envelope, done in-process against the
 > same planners this command drives. Run it by hand only when either step
 > reported `false` (a dirty shared checkout is the common, benign cause), or
@@ -727,7 +719,7 @@ up").
 
 The field-level contract is the shipped schema
 [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
-(Story #4543) — not this file, and not
+— not this file, and not
 [`agents/story-worker.md`](../../agents/story-worker.md). All three used to
 carry their own prose version; the schema is now the only definition. What
 follows is the *judgement* around it, which a schema cannot express.
@@ -744,7 +736,7 @@ tool-invocation ceiling, which would otherwise park the Story at
   budget is anchored at the PR's `createdAt`, so resuming does not restart the
   clock and the give-up bound still means something.
 - It is **not** a park. Returning `pending` because you would rather not wait
-  is the Story #1553 / PR #1554 failure mode wearing a schema. Return it only
+  is the no-park failure mode wearing a schema. Return it only
   when the bound genuinely expired, or a human owns the merge.
 
 The no-park rule holds: a turn that ends with prose ("I'll wait for the watch

package/.agents/workflows/helpers/deliver-story.md

@@ -3,6 +3,7 @@ description:
   Execute one Story end-to-end. Creates story-<id> from main, implements in a
   worktree (optional ## Slicing checkpoints), runs derived-level ceremony,
   opens a PR against main, and lands.
+mandatoryReads: [deliver-digest.md]
 ---
 
 # /deliver-story #[Story ID]
@@ -16,14 +17,13 @@ description:
 > one bundled read of what every delivery needs — dispatch decision, engine
 > invariants, the change-set/ceremony incantation, the acceptance-eval gate,
 > and the terminal-envelope contract — replacing the per-session re-reads of
-> the helper set and `story-deliver-terminal.schema.json` (Story #4736). The
-> steps below cite it as "digest § N" rather than restating it.
+> the helper set and `story-deliver-terminal.schema.json`. The steps below
+> cite it as "digest § N" rather than restating it.
 
 ## Overview
 
 The **one** delivery engine in v2 — every Story (a lite-**shaped** Story
-runs inline with inline critics, #4722; engine, gates, envelope
-byte-identical):
+runs inline with inline critics; engine, gates, envelope byte-identical):
 
 ```text
 single-story-init.js → implement + commits → derived-level ceremony
@@ -31,10 +31,10 @@ single-story-init.js → implement + commits → derived-level ceremony
   → CI watch + merge → single-story-confirm-merge.js (agent::done)
 ```
 
-An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan.
-There is no `epic/<id>` branch, no `--no-ff` wave merge (trait table:
-reference § Engine invariants). Prerequisites: a `type::story` issue,
-clean `gh auth status`, and `project.baseBranch` on local and `origin`.
+An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. The
+engine's trait table is reference § Engine invariants. Prerequisites: a
+`type::story` issue, clean `gh auth status`, and `project.baseBranch` on
+local and `origin`.
 
 ## Step 0 — Initialize (`single-story-init.js`)
 
@@ -45,14 +45,14 @@ timeout — the per-tree install can take minutes; never `run_in_background`:
 node .agents/scripts/single-story-init.js --story <storyId>
 ```
 
-Flags: `--dry-run` (no mutations; skips lease + sweep), `--steal` (transfer
-a foreign lease). It validates `type::story`, **acquires the Story lease**
+Every script below documents its own flags — run it with `--help`.
+It validates `type::story`, **acquires the Story lease**
 (fails closed on a foreign assignee), fetches `origin`, seeds `story-<id>`
 from `baseBranch` (idempotent reuse), materializes a worktree, runs a
 guarded merged-`story-*` sweep, and flips `agent::executing` (reference
 § Step 0). Capture `workCwd` from the result envelope.
 
-**Land or block (issue #4483).** `remoteVerified: false` → flip
+**Land or block.** `remoteVerified: false` → flip
 `agent::blocked` quoting `remoteProbe.detail` and stop. Implementing outside
 the worktree/branch/PR path or committing to local `main` is forbidden —
 close's push is the only sanctioned landing.
@@ -94,9 +94,9 @@ mechanics live in the single-homed include
 ## Step 2 — Ceremony (profile + derived level)
 
 Ceremony is `delivery.routing.ceremonyProfile` × the **derived change
-level** — never a planner-authored verdict (Story #4542). **Digest § 3** is
-the incantation: compute the change set once (Story #4593), derive the level,
-resolve fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
+level** — never a planner-authored verdict. **Digest § 3** is the
+incantation: compute the change set once, derive the level, resolve
+fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
 inline regardless (routing edge cases: reference § Step 2). Hard gates always
 run in Step 3 — the derived level never disables them; do **not** pre-run the
 close chain here.
@@ -113,12 +113,12 @@ post-land tail in one process. Run it and **branch on the terminal envelope's
 `nextCommand`; `blocked`/`checks-failed` → Step 4; `failed` → diagnose and
 re-run). Gate output is captured to
 `temp/orchestration/close-gates-<storyId>.log` — a clean run prints a digest
-line, a red gate replays its tail inline (Story #4736).
+line, a red gate replays its tail inline.
 
 Internals (gate order, base-sync, auto-merge arming), the merge-wait
-budgets, the slow-CI **async** confirm mode (Story #4698 — launch the
-`pending` envelope's `nextCommand` as **background** Bash, never a
-foreground poll), the `autoMerge` policy, and every close flag: reference
+budgets, the slow-CI **async** confirm mode (launch the `pending`
+envelope's `nextCommand` as **background** Bash, never a foreground
+poll), the `autoMerge` policy, and every close flag: reference
 § Step 3 — Merge wait, async mode, and flags.
 
 ## Steps 4–6 — Recovery router (**recovery-only**)
@@ -130,7 +130,7 @@ recovery path **only** when the envelope routes you there:
   armed), resume via `nextCommand`; triage per
   [`rules/ci-remediation.md`](../../rules/ci-remediation.md). The watch is
   internally blocking — never end a turn with prose and an unconfirmed
-  merge (Story #1553). Reference § Step 4.
+  merge. Reference § Step 4.
 - **`pending`** → run `nextCommand` (`single-story-confirm-merge.js`) until
   resolved. Reference § Step 5.
 - **`tail.statusResync: false`** → reference § Step 5.5;
@@ -142,9 +142,9 @@ End your turn by relaying the validated envelope close emits between its
 `--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
 hand-composed object. Statuses, exits, and required fields: **digest § 5**
 (whose SSOT is the shipped
-[schema](../../schemas/story-deliver-terminal.schema.json), Story #4543).
+[schema](../../schemas/story-deliver-terminal.schema.json)).
 `pending` is the only sanctioned no-merge ending, returned only when your own
-budget is exhausted (Story #1553). Reference § Step 7.
+budget is exhausted. Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
@@ -162,7 +162,7 @@ reuses an open PR).
 - **Never** push the Story branch directly to `main` — the PR is the only
   merge surface.
 - **Always** prefix path-based tools with the absolute `workCwd` root
-  (Step 0.5); close's wrong-tree guard (Story #3364) is a backstop.
+  (Step 0.5); close's wrong-tree guard is a backstop.
 - **Report state, not process** — mirror the close envelope's fields; no
   step narration.
 - Drive every `agent::*` transition through

package/.agents/workflows/helpers/mandrel-sync-config.md

@@ -24,8 +24,8 @@ description: >-
 
 ## Overview
 
-Story #1995 replaced the previous template-merge behaviour with a
-**default-aware** reconciliation: the helper never adds optional keys to the
+The helper performs a **default-aware** reconciliation rather than a
+template merge: it never adds optional keys to the
 project config, because the runtime already layers framework defaults
 underneath the project's values at read time. The only thing the helper
 writes today is a structured report. The mechanical work is delegated to

package/.agents/workflows/helpers/parallel-tooling.md

@@ -77,8 +77,7 @@ prefer the higher-numbered rule — the parallelism gain compounds the
 background-shell gain. Concretely: dispatch the `Agent` calls in one turn
 (Rule 3), and **inside** each sub-agent let it apply Rule 2 to its own
 long-running shells — and, within the supported nesting depth budget
-(verified depth 2, announced max depth 5; see
-[#2870](https://github.com/dsj1984/mandrel/issues/2870)), let it apply
+(verified depth 2, announced max depth 5), let it apply
 **Rule 3** to its own independent sub-units as well, not only Rule 2
 background shells. A sub-agent is a full orchestrator at its own level:
 recursive `Agent` fan-out is available to it, so the host does not need to

package/.agents/workflows/helpers/plan-reference.md

@@ -1,15 +1,73 @@
 # /plan — on-demand reference appendix
 
 > **Applies when:** you are executing [`/plan`](../plan.md) and hit one of the
-> situations below — shape-derived complexity routing, `--tickets` supersede
-> authoring, critic dispatch detail, a failed persist, or source-id
-> resolution. The spine stays resident; this file is read on demand.
+> situations below — input-mode derivation, the Gate #1 light handoff,
+> shape-derived complexity routing, tickets-mode supersede authoring, critic
+> dispatch detail, a failed persist, or source-id resolution. The spine stays
+> resident; this file is read on demand.
+
+## Deriving the input mode
+
+`/plan` has no operator-facing flags; the CLIs below still take every flag they
+always did. Read the invocation, **announce what you derived**, then fill in
+the flag — the same derive-then-announce contract `/git-deliver` uses for its
+terminal level.
+
+| What was typed | Mode | You pass |
+| --- | --- | --- |
+| nothing | ask | — (ask what to plan) |
+| prose | seed | `--seed "<text>"` |
+| an argument resolving to an existing file | seed-file | `--seed-file <path>` |
+| ids, none of them a delivered Story | tickets | `--tickets <ids>` |
+| one id that is an `agent::done` Story | amends | `--amends '#<id>'` |
+| "…but let me review before you file" | (any) | `--force-review` |
+
+**Order matters.** Test *file exists* before *looks like prose*, or a bare
+`notes.md` becomes a one-word seed. Test *all args are `^#?\d+$`* before
+either, or a ticket list becomes prose.
+
+**The one genuinely ambiguous case** is a bare id, between `amends` and
+`tickets`. Resolve it from live state — `agent::done` can only be amended, an
+open unplanned issue can only be planned — and ask only when the id is an open
+Story already at `agent::ready`, where both readings are live. Do not ask in
+the cases state already answers; an unnecessary question is the friction this
+whole surface exists to remove.
+
+Mixed ids and prose in one invocation is a **hard error**: refuse and ask which
+was meant, rather than guessing a mode and doing the wrong work.
+
+## Gate #1 → the light path (in-session handoff)
+
+On a confirmed `deliverLightSuggestion`, `/plan` routes into
+[`deliver-light.md`](deliver-light.md) **without ending the session**. Two
+things make that safe, and both are worth understanding before changing it:
+
+1. **The handoff carries the envelope, not the seed.** Gate #1 already holds a
+   codebase snapshot and `complexitySignals`; fill the light gate's `--creates`
+   / `--refactors` / `--acceptance` / `--reason` from those. Re-deriving from
+   raw seed text throws away the better signal and can disagree with the
+   suggestion that routed you.
+2. **The gate still runs.** The suggestion is read against seed-time ceilings
+   (`DELIVER_LIGHT_SUGGESTION_CEILINGS` — artifacts, risk hits, sensitive-path
+   classes); the light gate is read against a predicted shape
+   (`STORY_SHAPE_CEILINGS` — `maxChanges`, `maxAcceptance`). Two different
+   checks on purpose, so a confirm is not a bypass.
+
+**When the light gate answers `ask-operator`**, the two ceiling sets disagreed.
+Resume `/plan` at step 2 (Author) **in this same session** — the interrogation
+is still valid and re-paying for it buys nothing. This bounce-back is not an
+escalation.
+
+Escalation in the *other* direction — an over-scope prompt on the light path —
+is terminal and requires a fresh session. The rule that separates the two, and
+why it must not be flattened into symmetry:
+[`deliver-light.md` § Why the two directions differ](deliver-light.md).
 
 ## Shape-derived complexity routing (`complexitySignals`)
 
 Complexity routes on the **objective shape of the authored work**, never on
-seed word count (Story #4722 — a detailed prompt can describe trivial work, a
-terse one complex work; `maxSeedWords` is removed). The pipeline stages the
+seed word count — a detailed prompt can describe trivial work, a terse one
+complex work. The pipeline stages the
 decision:
 
 - **Signals, not routing.** The envelope's `complexitySignals` field is
@@ -37,7 +95,7 @@ decision:
   and the security baseline. Those gates run in `single-story-close.js`
   regardless of route.
 
-**The label is a hint; deliver re-derives (Story #4722).** Persist labels a
+**The label is a hint; deliver re-derives.** Persist labels a
 lite cohort's Stories with **`route::lite`** as a *human-visible hint only* —
 `/deliver` computes the route from each fetched Story body via the same shape
 function at dispatch, so neither a lost label nor an unread marker can
@@ -53,7 +111,7 @@ in [`.agents/docs/configuration.md`](../../docs/configuration.md) under
 ceilings on `STORY_SHAPE_CEILINGS` in
 [`lib/orchestration/complexity-gate.js`](../../scripts/lib/orchestration/complexity-gate.js).
 
-## Correct-by-construction authoring template (Story #4723)
+## Correct-by-construction authoring template
 
 `plan-context.js --out` writes `stories.template.json` as a
 **correct-by-construction** skeleton, built from the same repo snapshot the
@@ -73,7 +131,7 @@ ceilings on `STORY_SHAPE_CEILINGS` in
   authoritative: they probe the base branch ref, not the working tree.
 - **Keep `## Spec` near contract-level prose.** Persist emits an
   **advisory** warning past ~250 words (`SPEC_SOFT_WORD_BUDGET`) — it never
-  fails the persist, but it is the nudge toward the #4707 contract-level
+  fails the persist, but it is the nudge toward a contract-level
   Spec (interfaces, invariants, load-bearing constraints; no per-file
   behavior narration). The hard fail-closed ceiling (~1500 tokens,
   `spec-spill.js`) is unchanged.
@@ -112,7 +170,7 @@ Story (mirroring `assertAcceptancePartition`): every id passed to
 `--tickets` must be claimed by **exactly one** Story, and no Story may
 claim an id that was not a source ticket. With N>1 the mapping is not
 total by default — an authored map is the only thing that can say
-`#4525-#4528 → #4530` while `#4529 → #4531`, which a blanket "superseded by
+`#11-#14 → #20` while `#15 → #21`, which a blanket "superseded by
 this plan-run" reference could not.
 
 ## Critic dispatch detail
@@ -120,7 +178,7 @@ this plan-run" reference could not.
 The **pre-mortem** critic fires on any of three deterministic triggers: the
 draft ticket count reaching half the reviewability budget, a
 `planning.riskHeuristics` phrase matching the plan text, or the
-**external-dependency** probe (Story #4700) finding an out-of-repo marker — a
+**external-dependency** probe finding an out-of-repo marker — a
 scoped package the plan names that no repo manifest declares, a cross-repo
 `github.com/<owner>/<repo>` reference, or an endpoint named as a service
 prerequisite. That third trigger is what gives the default N=1 plan a cheap
@@ -136,7 +194,7 @@ markers only, so a plan naming no such artifact dispatches exactly as before.
 }
 ```
 
-The verdict's third entry, `textHygiene`, is advisory-only (Story #4599): it
+The verdict's third entry, `textHygiene`, is advisory-only: it
 carries deterministic body lints (`dangling-citation` / `open-question` /
 `slicing-mass`) with no dispatch semantics — it spawns nothing and never
 gates the run. Fold `textHygiene.findings[]` into the re-author round the
@@ -161,8 +219,8 @@ critic that reads the maker's case grades the case, not the draft.
 
 ## Ready means fully persisted
 
-`agent::ready` is the **terminal** step, not part of the creating POST
-(Story #4541). The order is: create unlabelled → upsert `story-plan-state` on
+`agent::ready` is the **terminal** step, not part of the creating POST.
+The order is: create unlabelled → upsert `story-plan-state` on
 every Story → upsert `plan-summary` on the primary → flip every Story to
 `agent::ready`.
 
@@ -196,7 +254,7 @@ gates, and abandoned authoring sessions do not accumulate under `temp/`.
 ## How the source ids reach persist
 
 In `--tickets` mode persist needs to know which ids were fetched. It resolves
-them **envelope-first** (Story #4554):
+them **envelope-first**:
 
 | Channel | When it wins |
 | --- | --- |

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -108,10 +108,7 @@ PowerShell `Get-CimInstance Win32_Process`, terminating them with
 
 > **Not a slash command (decision overturned).** The drain is **not** a
 > `/drain-pending-cleanup` slash command — it was demoted to a
-> directly-runnable script (Story #3706, overturning the
-> `docs/decisions.md` matrix row that originally kept it as a command).
-> The wave-era automatic callers were deleted with the epic-runner in
-> the v2 cutover, so the drain is now operator-driven:
+> directly-runnable script. The drain is operator-driven:
 > `node .agents/scripts/drain-pending-cleanup.js`.
 
 ### When to run it manually