mandrel 1.94.0 → 2.1.0

package/.agents/workflows/deliver.md

@@ -1,200 +1,201 @@
 ---
 description:
-  Unified delivery entry point. Inspects the ticket type(s) and
-  Epic-reference state of the supplied IDs, composes a sequential segment
-  plan over any mix of Epics and standalone Stories, then delegates each
-  segment to the Epic wave loop or the standalone multi-Story fan-out —
-  preserving every flag and the parallel-delivery contract of the retired
-  commands.
+  Unified delivery entry point. Takes a list of Story ids, resolves their
+  dependency graph from live state, and delivers each via the single
+  deliver-story engine — story-<id> → PR → main.
 ---
 
-# /deliver [Epic IDs...] | [Story IDs...]
+# /deliver <storyId...>
 
 ## Role
 
-Router. `/deliver` owns input classification, segment-plan composition, and
-path selection only — all phase content lives in the two path helpers:
+Single delivery path with a single input shape: **a list of Story ids**.
+`/deliver` owns input resolution and sequencing only — every Story runs
+through [`helpers/deliver-story.md`](helpers/deliver-story.md). There is no
+Epic wave loop, no `epic/<id>` integration branch, and no `--no-ff` wave
+merges.
 
-- [`helpers/deliver-epic.md`](helpers/deliver-epic.md) — the full Epic
-  delivery loop (preflight, wave loop fanning out
-  [`helpers/epic-deliver-story`](helpers/epic-deliver-story.md),
-  close-validation, epic-audit, code-review, retro, finalize, watch,
-  auto-merge gate, cleanup).
-- [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the
-  standalone multi-Story path (`stories-wave-tick.js` continuous ready-set
-  loop, operator confirmation, parallel fan-out to
-  [`helpers/single-story-deliver`](helpers/single-story-deliver.md)).
+The dependency graph is **discovered, not declared**: `resolve-stories.js`
+reads it from live state (body edges ∪ native GitHub `blocked_by` edges,
+with every blocker resolved against its real issue state). You never hand it
+a graph, and there is no batch label — which is what lets you deliver
+Stories **across plan runs and over time**: a Story whose blocker landed
+weeks ago in a different run is simply ready.
 
-## Input matrix (authoritative)
+## Inputs
 
-Fetch each supplied ID's labels and body (`type::*` label, `Epic: #N`
-reference) before routing:
-
-| Input | Route |
-| --- | --- |
-| Exactly one `type::epic` ID | **Epic path** — resolve the Epic's delivery route (see [Epic delivery-route resolution](#epic-delivery-route-resolution) below), then run the selected helper's phases unchanged (single-segment plan; no confirmation prompt). |
-| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3 (single-segment plan; no confirmation prompt). |
-| Any combination of ≥1 `type::epic` IDs and ≥0 standalone `type::story` IDs | **Segment plan** — compose and execute the sequential segment plan below. |
-| Any Story carrying an `Epic: #N` reference (alone or mixed into an otherwise-valid set) | **Error**, naming every affected ID and the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
-
-Per-ID classification is unchanged: fetch the `type::*` label and probe the
-body for an `Epic: #N` reference before routing. Never guess a route.
-
-## Epic delivery-route resolution
-
-Every `type::epic` segment resolves to one of two delivery shapes before its
-helper runs. The routing is a pure function of the Epic's labels, its
-`epic-plan-state` checkpoint, and the config kill-switch — implemented in
-[`lib/orchestration/deliver-route.js`](../scripts/lib/orchestration/deliver-route.js)
-(`resolveEpicDeliveryRoute(epic, checkpoint, config)`), mirroring how the
-code-review depth resolver reads `planningRisk`/`decompose` off the same
-checkpoint. Fetch the Epic's labels and read its `epic-plan-state` structured
-comment, then apply the precedence (highest wins):
-
-1. **Kill-switch — overrides all.** `delivery.routing.singleDelivery === false`
-   (default `true`, read via `getDeliveryRouting`) forces **fan-out** for
-   *every* Epic, even a single-marked one. This is the instant, per-consumer
-   global revert that ships before the default flips — no code rollback, no
-   re-plan.
-2. **Single marker → single route.** The `delivery::single` label (primary)
-   **or** `decompose.shape === "single"` on the checkpoint (secondary). A
-   spec-only plan authored no Story tree; its `## Delivery Slicing` table is
-   the audit trail.
-3. **No marker → fan-out.** A legacy Epic (no marker, an authored Story tree)
-   or a genuinely-wide DAG. Deliver-time width only *advises* — it never
-   reroutes a single-marked Epic (that would orphan a tree that does not
-   exist; re-route = re-plan).
-
-**Route dispatch.**
-
-- **`fan-out`** → run [`helpers/deliver-epic.md`](helpers/deliver-epic.md)
-  Phases 1–9 unchanged (the wave loop fanning out per-Story sub-agents).
-- **`single`** → run
-  [`helpers/deliver-epic-single.md`](helpers/deliver-epic-single.md) (the
-  live flip, M4-B): a one-worktree in-session slice walk (prepare `--single` →
-  ordered `## Delivery Slicing` walk on `epic/<id>` → per-AC-cluster
-  acceptance critics) that **reuses `helpers/deliver-epic.md` Phases 3–9
-  byte-for-byte** for the merge tail. This is now the **default** shape for a
-  single-marked Epic. The kill-switch (`delivery.routing.singleDelivery=false`)
-  still forces this verdict back to `fan-out` — an instant global revert with
-  no code rollback.
-
-## Segment plan (mixed / multi-Epic input)
-
-When the supplied IDs span more than one Epic, or mix Epics with standalone
-Stories, the router composes a **segment plan** and executes the segments
-**strictly sequentially**:
-
-1. **Standalone segment first** (when any standalone Story IDs are
-   present): the full standalone-Story set forms **one** segment,
-   delivered via [`helpers/deliver-stories.md`](helpers/deliver-stories.md)
-   Phases 0–3 unchanged. It runs first because it is fast, each Story
-   merges to `main` independently, and each subsequent Epic segment's
-   Phase 7.0 base-sync then integrates those merges naturally instead of
-   the Epic PR opening behind base.
-2. **Epic segments in input order**: each `type::epic` ID forms its own
-   segment. Resolve its delivery route (see [Epic delivery-route
-   resolution](#epic-delivery-route-resolution)) and run the selected helper
-   unchanged — the `fan-out` route dispatches
-   [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9, the
-   `single` route dispatches
-   [`helpers/deliver-epic-single.md`](helpers/deliver-epic-single.md) (which
-   reuses that helper's Phases 3–9 for the merge tail).
-
-Sequential execution is a deliberate design decision: the Epic path assumes
-a single main checkout (prepare's checkout guard, Phase 7.0
-`git checkout epic/<id>`), holds a per-Epic lease, serializes same-machine
-sessions via `epic-merge-lock.js`, and constrains dispatch to one wave at a
-time. Segments are never interleaved or parallelized; running them one at a
-time keeps both helpers' machinery untouched.
-
-**Confirmation gate.** When the composed plan has more than one segment,
-present it to the operator before dispatching — the segments, the IDs in
-each, and the execution order — and wait for confirmation. `--yes`
-suppresses this prompt. Single-segment plans route directly with today's
-behavior (no new prompt; the standalone path's own Phase 1 confirmation
-still applies as before).
-
-**Failure policy.** A segment that ends non-complete (blocked, failed, or
-halted at a gate) **stops the run** — no subsequent segment dispatches.
-Report the terminal state: which segments completed, which segment halted
-(and why), and which segments never started. Name the resume command:
-re-running `/deliver` with the same IDs — both path helpers short-circuit
-already-done work (the Epic path resumes idempotently from its checkpoint;
-merged standalone Stories no-op).
-
-## Flags (scoped per segment)
-
-| Path | Flags |
+| Invocation | Behavior |
 | --- | --- |
-| Epic | `--skip-epic-audit`, `--skip-code-review`, `--skip-retro`, `--full-retro`, `--steal`, `--as <handle>` |
-| Story | `--dep <from>:<to>`, `--yes`, `--concurrency <n>` |
+| `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story.md`. |
+| `/deliver <storyId> <storyId> ...` | Resolve the set with `resolve-stories.js`, then sequence by the discovered graph via `stories-wave-tick.js`. Default concurrency is **3**. |
 
-In a segment plan, Epic-path flags apply to **every** Epic segment;
-Story-path flags apply to the standalone segment. `--yes` additionally
-suppresses the router's segment-plan confirmation gate above. A flag with
-no applicable segment in the plan is reported once as a no-op warning and
-ignored — never an error (the existing convention, restated for segment
-plans).
+Any named ticket that is not `type::story`, or that still carries an
+`Epic: #N` footer, is a hard error naming the id and the fix (close or
+re-plan as a v2 Story). Resolution refuses the whole set rather than
+silently dropping the offending id and under-delivering.
 
-**Multi-Story parallel contract (preserved verbatim).**
+> **Retired (Story #4540).** `--run <planRunId>` and the `plan-run::<id>`
+> label are gone, along with `--dep`. Batch identity was the wrong axis:
+> it could not express an edge to a Story planned in another run, while
+> ordering already lives in the dependency edges themselves. Deliver the
+> ids; the graph resolves itself.
 
-```text
-/deliver <id> <id> … --dep <from>:<to> --concurrency <n> --yes
-```
+## Flags
 
-preserves the retired multi-Story command's full surface — the same flags,
-the same operator confirmation gate (suppressed by `--yes`), and the same
-parallel fan-out to
-[`helpers/single-story-deliver`](helpers/single-story-deliver.md) — but
-schedules through `stories-wave-tick.js`'s **continuous ready-set loop**
-(the shared `selectReadySet` core) rather than a static wave plan: each
-Story dispatches the instant its own dependencies are done, capped by the
-resolved global `concurrencyCap` and guarded against file-overlap
-co-dispatch, exactly as the Epic path is. The parallelism lives **inside**
-the standalone segment; segments themselves remain strictly sequential.
+| Flag | Meaning |
+| --- | --- |
+| `--concurrency <n>` | Ready-set fan-out cap (default **3** from `delivery.deliverRunner.concurrencyCap`; set `1` for sequential). |
+| `--yes` | Suppress the multi-Story confirmation gate. |
+| `--steal` | Forwarded to `single-story-init.js` / lease steal. |
+| `--wait-merge` | Force close-and-land (the default; `delivery.routing.closeAndLand`, default `true`). |
+| `--no-wait-merge` | Opt out of close-and-land; stop at `agent::closing` for a human land. |
+
+**Operator-merge implies no-wait.** `--no-auto-merge` and
+`delivery.ci.autoMerge: "strict"` deliberately leave the PR un-armed, so
+there is nothing for close to land: the Story rests at `agent::closing` for
+the human merge, and is **not** flipped to `agent::blocked`. An explicit
+`--wait-merge` does not override this — close cannot land a PR that was
+never armed. A genuine *arm failure* is different: it still waits and still
+blocks, because that is a fault to report rather than an operator decision
+to respect.
 
 ## Procedure
 
-1. **Parse args.** At least one positive-integer ID is required.
-2. **Classify.** Fetch each ticket's labels + body and apply the input
-   matrix above. Any Epic-attached Story ID is a hard error naming the
-   affected IDs and the fix — never guess a route.
-3. **Compose the segment plan.** Standalone-Story set (when present) as
-   one segment, then one segment per Epic ID in input order. For a
-   multi-segment plan, present it and wait for operator confirmation
-   (`--yes` suppresses).
-4. **Execute segments sequentially.** For each segment in order, read the
-   selected path helper **in full** and execute it from its entry phase,
-   forwarding the segment's scoped flags. The helper's phase numbering,
-   watchdogs, gates, and scripts are unchanged — this router adds no phase
-   content. Stop on the first non-complete segment per the failure policy.
-5. **Report.** On completion (or halt), summarize per-segment outcomes and,
-   when halted, the resume command.
+1. **Resolve the set.** One command, for one Story or many:
+
+   ```bash
+   node .agents/scripts/resolve-stories.js --ids <id,id,...>
+   ```
+
+   Capture `stories[]`, `dag[]`, and `done[]` from the envelope. Do **not**
+   rebuild the graph by hand — it is discovered from live state, including
+   edges a body does not spell out and blockers outside the delivered set.
+
+   Resolution hard-errors (exit 1) on a named id that is not a Story, still
+   carries an `Epic: #N` footer, or whose native dependency edges cannot be
+   read. A failed edge read is fatal by design: a missing gate would
+   co-dispatch a Story against an unlanded blocker.
+
+2. **Confirm (N>1).** Present the order and wait unless `--yes`.
+
+3. **Sequence.** Loop until every Story is done:
+
+   ```bash
+   node .agents/scripts/stories-wave-tick.js \
+     --dag '<dag from step 1>' --done <csv> --in-flight <n> --concurrency <n>
+   ```
+
+   **Seed the first beat's `--done` from the resolver's `done[]`** — not from
+   an empty string. That array carries the blockers that have already landed,
+   including foreign ones outside the delivered set. Seeding it empty
+   discards exactly the cross-run resolution this step exists for, and the
+   run wedges on a blocker that finished weeks ago. On later beats, `--done`
+   is `done[]` plus every Story that has since closed.
+
+   Branch on the exit code:
+   - **0** — dispatch each `ready` id. An empty `ready` with work in flight
+     means "waiting"; keep looping.
+   - **2** — `cycleError`: the graph is self-referential. Fix the
+     `depends_on` declarations; do not retry.
+   - **3** — `wedged`: nothing is dispatchable, nothing is in flight, and
+     undone Stories are waiting on blockers that are not done. The envelope
+     names the stuck ids and their unmet blockers. Either land the blocker
+     first or include it in `--ids`. Do not retry unchanged — the state
+     cannot improve on its own.
+
+   For each `ready` Story id, read
+   [`helpers/deliver-story.md`](helpers/deliver-story.md) **in full** and
+   execute it (init → implement → ceremony → close-and-land). Under
+   `--yes` / injected helper content, execute directly without a re-read
+   turn.
+
+4. **Per-run epilogue (N>1).** After the last Story lands, keyed on the
+   delivered id set:
+
+   ```bash
+   node .agents/scripts/plan-run-epilogue.js --stories 101,102
+   ```
+
+   This executes, in order:
+   - `audit-roster` — selects cross-Story audit lenses over the combined
+     landed tip and posts `plan-run-audit-roster` on the primary Story;
+     the host MUST walk each listed lens against the combined diff
+   - `follow-up-rollup` — friction follow-ups across every Story in the
+     run (files issues when auto-file is on; posts `follow-ups`)
+   - `sibling-coherence` — Spec/Acceptance coherence check across sibling
+     bodies (`plan-run-sibling-coherence`)
+
+   A single-Story run skips the epilogue — follow-ups are captured on
+   merge confirm instead (`captureStoryFollowUps`).
+
+## Branch model (authoritative)
+
+Every Story:
+
+```text
+story-<id>  →  PR  →  main (squash + required checks)
+```
+
+There is no `epic/<id>` integration branch and no `--no-ff` wave merge.
+Dependent Stories land sequentially so each builds on the previous merge
+to `main`.
+
+## Ceremony (profiles + two scopes)
+
+Ceremony depth is selected by `delivery.routing.ceremonyProfile`
+(`minimal` | `standard` | `strict`, default `standard`) and the **change
+level derived from the Story's own diff** — the changed files' intersection
+with the sensitive-path classes in `audit-rules.json`
+(`review-depth.js#deriveChangeLevel`), not a planner-authored verdict
+(Story #4542):
+
+| Profile | Acceptance critic | When to use |
+| --- | --- | --- |
+| `minimal` | Always inline | Tiny trusted N=1 Stories |
+| `standard` | Derived-level routed (+ sampling floor) | Default |
+| `strict` | Always fresh-context | High-assurance / regulated surfaces |
+
+| Scope | What runs | Mechanism |
+| --- | --- | --- |
+| **Per-Story (always)** | Gates, branch discipline, close-and-land | `deliver-story` / `single-story-close` |
+| **Per-Story (profile + derived level)** | Acceptance critic mode; review depth | `ceremony-routing.js` + `review-depth.js` + `code-review.js` |
+| **Per-run (N>1)** | Audit roster · follow-up roll-up · sibling coherence | `plan-run-epilogue.js` once at run end |
+| **Per-Story land tail** | Follow-up capture · status resync · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
+
+## Reading a Story's outcome
+
+Each Story's delivery ends in exactly one schema-validated terminal envelope
+([`story-deliver-terminal.schema.json`](../schemas/story-deliver-terminal.schema.json),
+Story #4543) — `landed` | `pending` | `blocked` | `failed`. That schema is the
+SSOT for the shape; this workflow does not restate its fields.
+
+`pending` is **not** a failure: the bounded merge wait expired with the PR
+healthy and in flight (or a human owns the merge), nothing was mutated, and
+the envelope's `nextCommand` names what resumes it. Run that command rather
+than re-dispatching the Story.
+
+For a Story in an unclear state — including the merged-but-label-stale one a
+`/deliver` re-run refuses outright — probe it read-only:
+
+```bash
+node .agents/scripts/deliver-recover.js --story <storyId>
+```
 
 ## Constraints
 
-- **Land or block — never a silent local build (issue #4483).** The
-  helpers' orchestration path (worktrees, `story-<id>`/`epic/<id>` branches,
-  close-validation, PR) is the ONLY sanctioned delivery mechanism.
-  Executing story slices inline in this session and/or committing the
-  delivery to local `main` is expressly forbidden, regardless of how the
-  environment looks. Each path surfaces verified remote evidence
-  (`remoteVerified`) at entry; on `false`, transition the ticket to
-  `agent::blocked` quoting `remoteProbe.detail` and halt.
-- `/deliver` requires planned tickets: Epics at `agent::ready` (the
-  Epic helper's preflight enforces this, per segment) or well-formed
-  standalone Stories. Planning happens in [`/plan`](plan.md); the
-  plan-review gate between the two commands is a hard boundary.
-- The router performs no git or label mutations itself; the path helpers
-  own every script invocation.
-- Segments execute strictly sequentially — never interleave a standalone
-  Story fan-out with an Epic wave loop, and never run two Epic segments
-  concurrently.
+- **Land or block — never a silent local build.** Worktrees, `story-<id>`
+  branches, close-validation, and PR-to-`main` are the only sanctioned
+  delivery mechanism. Attended delivers default to close-and-land
+  (`delivery.routing.closeAndLand: true`); use `--no-wait-merge` only when
+  a human will land the PR.
+- `/deliver` never plans — tickets come from [`/plan`](plan.md).
+- The router performs no git/label mutations; `deliver-story` owns every
+  script invocation per Story.
 
 ## See also
 
-- [`/plan`](plan.md) — the unified planning entry point.
-- [`helpers/deliver-epic.md`](helpers/deliver-epic.md) /
-  [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the path
-  helpers, delegated to per segment.
+- [`/plan`](plan.md) — unified planning entry point.
+- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one Story
+  delivery engine.
+- Placeholder design Story for a fully deterministic deliver-run
+  orchestrator: [#4521](https://github.com/dsj1984/mandrel/issues/4521).

package/.agents/workflows/git-cleanup.md

@@ -24,7 +24,7 @@ confirmation:
    already gone (or never existed) but whose `origin/<branch>` still
    points at a merged PR — even without `--remote`; `--remote` is still
    required to *delete* them. A third branch, whose content already
-   landed in `<base>` by another route (a squash-merged Epic PR, a
+   landed in `<base>` by another route (a squash-merged PR, a
    cherry-pick, a manual `merge --squash`), is caught by a
    **content-equivalence probe** (`git merge-tree --write-tree`,
    git ≥ 2.38) even when it has no merged PR of its own and is not a
@@ -40,7 +40,7 @@ passed, **all four phases run** sequentially. Pass any of
 narrow the run.
 
 > **When to run**: After a session that landed several PRs, or before
-> starting a new Epic / Story, to put the local checkout into a known
+> starting a new Story, to put the local checkout into a known
 > tidy state.
 >
 > **Persona**: `devops-engineer` · **Skills**:
@@ -226,10 +226,9 @@ The merged-branch sweep recognizes three detection signals, in order:
    `git merge-tree --write-tree <base> <branch>` (git ≥ 2.38) produces a
    tree identical to `<base>`'s own tree — i.e. applying the branch's
    changes on top of `<base>` is a content no-op. This catches
-   `story-<id>` branches merged into `epic/<id>` whose Epic PR
-   **squash-merged** to `main` (the story commits are not ancestors of
-   `main` and the story branch usually has no PR of its own), and any
-   other branch whose content landed via a different route (a renamed
+   `story-<id>` branches whose PR **squash-merged** to `main` (the story
+   commits are not ancestors of `main`), and any other branch whose content
+   landed via a different route (a renamed
    head, a cherry-pick, a manual `merge --squash`). When git rejects
    `--write-tree` (git < 2.38) or the simulated merge conflicts, the
    probe is inconclusive and the branch keeps its existing `not-merged`

package/.agents/workflows/git-deliver.md

@@ -10,7 +10,7 @@ description: >-
 # /git-deliver [Message] [--no-push] [--pr] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
 
 The **single source of truth** for getting outstanding working-tree changes
-out the door when they do not belong to a planned Epic (typo fixes, doc
+out the door when they do not belong to a planned Story (typo fixes, doc
 tweaks, dependency bumps, operator housekeeping, benchmark result commits
 from mandrel-bench's `/benchmark` Step 4). It is the ad-hoc counterpart to
 the heavyweight `/deliver` pipeline: one command that **detects the git

package/.agents/workflows/helpers/_merge-conflict-template.md

@@ -1,7 +1,7 @@
 # Merge Conflict Resolution — Shared Procedure
 
 Canonical, workflow-agnostic procedure for resolving merge / rebase conflicts.
-Referenced by `deliver-stories.md` and `deliver-epic.md`.
+Referenced by `deliver.md` and `helpers/deliver-story.md`.
 
 ## Procedure
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -1,19 +1,16 @@
 ---
 description: >-
   Shared include for the bounded acceptance self-eval loop run during Story
-  delivery (both Epic-attached `epic-deliver-story` and standalone
-  `single-story-deliver`). Defines the per-round critic mechanic; each caller
-  supplies its own gate-decision wrapper (snapshot vs. label transitions).
+  delivery (`helpers/deliver-story`). Defines the per-round critic mechanic;
+  the caller supplies its gate-decision wrapper (label transitions).
 ---
 
 # Bounded acceptance self-eval loop (shared include)
 
 > **Include module.** Not a slash command. Referenced from
-> [`epic-deliver-story.md`](epic-deliver-story.md) and
-> [`single-story-deliver.md`](single-story-deliver.md) at their respective
-> Step 1a. This file is the **single prose home** for the per-round critic
-> mechanic; each caller layers only its own wrapper (snapshot transitions vs.
-> standalone label transitions, and whether to pass `--epic`).
+> [`deliver-story.md`](deliver-story.md) at Step 1a. This file is the
+> **single prose home** for the per-round critic mechanic; the caller layers
+> only its wrapper (Story label transitions).
 
 After the implementation commits land and **before** the Story proceeds to
 close, run an explicit, **independent** eval pass that scores the working diff
@@ -25,10 +22,9 @@ satisfies *this Story's* acceptance criteria.
 The loop is **always on** (a hard cutover — there is no flag to disable it) and
 **bounded** by `delivery.acceptanceEval.maxRounds` (default 2), which the
 resolver clamps into `[1, hard ceiling]` so the cap can never be switched off or
-run unbounded. It is **distinct from** the Epic-level acceptance-spec
-reconciliation in `/deliver` Phase 7.1 (which fires once at finalize and
-only checks `@ac-*` Gherkin tag presence): this loop is per-Story,
-per-criterion, mid-delivery, and evaluates the actual work product.
+run unbounded. It is **distinct from** the per-run `sibling-coherence` epilogue
+step (`planRunEpilogue` for N>1): this loop is per-Story, per-criterion,
+mid-delivery, and evaluates the actual work product.
 
 ## Per round
 
@@ -37,7 +33,7 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    continuation of your implementing turn — so the evaluator does not grade its
    own homework.
 
-   > **Sub-agent type + risk-routed ceremony (Epic #4478, M7-B).** When
+   > **Sub-agent type + derived-level ceremony (Epic #4478, M7-B).** When
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), dispatch
    > the critic with `subagent_type: acceptance-critic` — it boots on the
    > role-scoped [`acceptance-critic`](../../agents/acceptance-critic.md) context
@@ -46,20 +42,28 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > kill-switch is **off** (`roleScopedAgents: false`), fall back to
    > `subagent_type: general-purpose`.
    >
-   > **Whether to spawn fresh at all is risk-routed** (mirrors the risk →
-   > review-depth and risk → audit-lens routers). Resolve it per cluster with
-   > `resolveCeremonyForRisk` from
+   > **Whether to spawn fresh at all is routed off the derived change level**
+   > — the same signal `review-depth.js` resolves depth from, so the two
+   > decisions cannot disagree. Derive it with `deriveChangeLevel` from
+   > [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) over
+   > the Story's changed files (`git diff --name-only main...story-<id>`), then
+   > resolve the ceremony per cluster with `resolveCeremonyForRisk` from
    > [`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)
-   > using the Epic's `planningRisk.overallLevel` and
-   > `delivery.routing.freshCriticSampleRate`:
-   > **`high`/`medium` risk → `fresh`** (spawn the critic); **`low` risk →
-   > `inline`** (the contract-identical inline fallback below), **except** the
-   > `freshCriticSampleRate` fraction of low-risk clusters the sampling floor
-   > forces `fresh` so low risk never means zero independent checking; **missing
-   > / unknown risk → `fresh` + full ceremony** (fail-safe). This chooses
-   > fresh-vs-inline **per cluster only — it never changes the cluster count**.
+   > using that `derivedLevel` and `delivery.routing.freshCriticSampleRate`:
+   > **`high` (the diff touches a sensitive path registered in
+   > `audit-rules.json`) → `fresh`** (spawn the critic); **`low` (it touches
+   > none) → `inline`** (the contract-identical inline fallback below),
+   > **except** the `freshCriticSampleRate` fraction of low-level clusters the
+   > sampling floor forces `fresh` so a low level never means zero independent
+   > checking; **`null` / unknown (the diff could not be enumerated) → `fresh` +
+   > full ceremony** (fail-safe). This chooses fresh-vs-inline **per cluster
+   > only — it never changes the cluster count**.
    >
-   > **Inline-critic path (low-risk-routed OR nesting-absent harness).** The
+   > Story #4542 re-based this off the planner-authored risk verdict: a level
+   > the plan asserted about itself was exactly the signal that could *reduce*
+   > independent checking, and nothing verified it against the diff.
+   >
+   > **Inline-critic path (low-level-routed OR nesting-absent harness).** The
    > verdict is authored **inline** whenever the risk router above resolves to
    > `inline` (a low-risk cluster not caught by the sampling floor), and also as
    > a **fallback** on any harness that cannot spawn the fresh critic.
@@ -100,15 +104,9 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      HEAD-sha key enforces "unchanged HEAD") and pass the exact gate name:
 
      ```bash
-     # Epic-attached Story:
      node <main-repo>/.agents/scripts/evidence-gate.js \
-       --epic-id <epicId> --scope-id <storyId> --gate lint \
+       --standalone --scope-id <storyId> --gate lint \
        --worktree <worktree> -- npm run lint
-
-     # Standalone Story (no parent Epic) — use --standalone, omit --epic-id:
-     node <main-repo>/.agents/scripts/evidence-gate.js \
-       --standalone --scope-id <storyId> --gate typecheck \
-       --worktree <worktree> -- <resolved typecheck command>
      ```
 
      Close's `shouldSkip` then short-circuits that gate when HEAD is
@@ -122,13 +120,11 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
      verifyEvidence[] }` record per acceptance item.
 2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
-   exact invocation — standalone omits `--epic`; the Epic-attached path passes
-   `--epic <epicId>` so the per-criterion signal lands on the Epic-scoped
-   stream):
+   exact invocation — omit `--epic`):
 
    ```bash
    node <main-repo>/.agents/scripts/acceptance-eval.js \
-     --story <storyId> [--epic <epicId>] --verdict <verdict-path>
+     --story <storyId> --verdict <verdict-path>
    ```
 
    The gate validates the verdict against the schema, applies the round cap,
@@ -138,11 +134,10 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      close.
    - **`decision: "redraft"`** (some `partial`/`unmet`, rounds remaining) →
      exit 0. Redraft the flagged criteria (named in `unmetCriteria[]`), commit
-     the fix, and re-run the eval pass for the next round.
+     the fix, and start another round.
    - **`decision: "block"`** (round cap reached, criteria still unmet) → exit
      non-zero. **Do not proceed to close.** Take the caller's blocked path
-     (transition to `agent::blocked` / flip the snapshot to `blocked`) and post
-     a `friction` comment naming the unmet criteria and their evidence. Never
-     silently proceed to close.
+     (transition to `agent::blocked`) and post a `friction` comment naming the
+     unmet criteria and their evidence. Never silently proceed to close.
 
 Write the verdict files under `temp/` only — they are scratch artifacts.

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -58,13 +58,13 @@ review-time prose rule.
 
 Per-file Maintainability Index (MI) is tracked in
 [`baselines/maintainability.json`](../../../baselines/maintainability.json).
-A commit that drops a file's MI by more than
-`delivery.quality.codingGuardrails.miDropMustRefactor` points (default
-`1.5`) requires a refactor in the same Story — not a baseline bump. The MI
-ratchet's per-file `tolerance` (default `0.5`) is a noise filter, **not**
-permission to spend the budget; the 1.5-point ceiling is the upper bound
-above which the change is treated as a regression that must be undone or
-offset, not absorbed.
+A commit that drops a file's MI by more than the configured
+`delivery.quality.gates.maintainability.tolerance` (default `0.5` points)
+requires a refactor in the same Story — not a baseline bump. `tolerance` is
+the single MI-drop control: it is not a noise filter beneath a separate
+must-refactor ceiling — any drop past it is treated as a regression that
+must be undone or offset, not absorbed. Set `tolerance` higher only when the
+project deliberately wants a looser MI-drop budget.
 
 `quality:preview --changed-since HEAD` shows the per-file MI delta in the
 working tree before the commit lands.