mandrel 2.0.0 → 2.2.0

package/.agents/docs/SDLC.md

@@ -2,7 +2,7 @@
 
 Mandrel uses **Story-centric GitHub orchestration** — GitHub Issues,
 Labels, and Projects V2 are the Single Source of Truth. Plans persist as
-`type::story` tickets (optionally grouped by a `plan-run::<id>` label);
+`type::story` tickets ordered by `depends_on` edges;
 each Story is delivered on its own `story-<id>` branch and reaches `main`
 through its own PR.
 
@@ -40,8 +40,9 @@ From zero to shipped:
 
    `/plan` is a **single path** — there is no Epic/Story router, no
    scope-triage `epic|story` verdict, and no `deliveryShape`. All GitHub
-   reads happen in `plan-context.js`, all writes in `plan-persist.js`, and
-   two HITL gates bracket the authoring middle. Duplicate search targets
+   reads happen in `plan-context.js`, the issue-creating writes in
+   `plan-persist.js`, and two HITL gates bracket the authoring middle.
+   Duplicate search targets
    open **Stories** (`type::story`), never Epics.
 
    1. **Interrogate** — `plan-context.js` emits the single authoring
@@ -49,19 +50,29 @@ From zero to shipped:
       probe, risk heuristics, `systemPrompts.story`). Duplicate review
       folds into **gate #1**.
    2. **Author** — write `stories.json` (**one Story by default**) with a
-      folded Tech Spec in `## Spec` / `## Slicing`, plus
-      `risk-verdict.json` (axes + summary only — no `deliveryShape`).
+      folded Tech Spec in `## Spec` / `## Slicing`. There is no risk artifact
+      to author (Story #4542).
       Binding criteria live in top-level `acceptance[]` / `verify[]`;
       changes/references are `{ path, assumption }` objects. Split into
       N>1 only under the default-single split policy.
-   3. **Persist** — **gate #2** (risk-routed; typically skipped for N=1
-      low-risk) then `plan-persist.js` runs every deterministic gate and
-      creates Story issue(s) with `type::story` + `agent::ready` (plus a
-      shared `plan-run::<id>` label when N>1).
+   2.5. **Critics** — `plan-critics.js` evaluates the consolidation +
+      pre-mortem dispatch conditions against the authored draft and ledgers
+      every skip. This is the **only** critic gate (#4592 moved it out of
+      `plan-persist.js` into workflow prose), so skipping it silently skips
+      both critics: run it before Persist, per
+      [`/plan`](../workflows/plan.md) step 2.5.
+   3. **Persist** — **gate #2** (raised only by an explicit `--force-review`)
+      then `plan-persist.js` runs every deterministic gate and
+      creates Story issue(s) with `type::story` + `agent::ready`, writing
+      each authored `depends_on` edge into the sibling body as a
+      `blocked by #<id>` footer when N>1.
 
 2. **Deliver the Story.** Run [`/deliver <storyId>`](../workflows/deliver.md)
-   (or `/deliver <a> <b> …`, or `/deliver --run <planRunId>` for a
-   multi-Story plan-run) in your IDE. `/deliver` owns input resolution and
+   (or `/deliver <a> <b> …` for several) in your IDE. `/deliver` takes
+   only Story ids and resolves their dependency graph from live state —
+   body edges union native GitHub `blocked_by` edges, with every blocker
+   checked against its real issue state, so a Story whose blocker landed in
+   an earlier plan run is simply ready. `/deliver` owns input resolution and
    `depends_on` sequencing only — every Story runs through
    [`helpers/deliver-story`](../workflows/helpers/deliver-story.md), the
    single v2 delivery engine. Per-Story it:
@@ -72,11 +83,12 @@ From zero to shipped:
    2. **Implement** — the agent delivers the Story in one guarded session
       against its inline `acceptance[]` / `verify[]` contract (optional
       `## Slicing` intra-session checkpoints).
-   3. **Acceptance self-eval** — a bounded, risk-routed critic loop scores
-      the working diff against each acceptance item before close (see
+   3. **Acceptance self-eval** — a bounded critic loop scores the
+      caller-injected change set against each acceptance item before close (see
       [`helpers/acceptance-self-eval`](../workflows/helpers/acceptance-self-eval.md)).
-   4. **Ceremony** — risk-routed acceptance critics, review depth, and
-      audit lenses (`ceremony-routing.js`).
+   4. **Ceremony** — acceptance critic mode and review depth, both routed off
+      the change level derived from the Story's own diff
+      (`review-depth.js#deriveChangeLevel` → `ceremony-routing.js`).
    5. **Close** (`single-story-close.js`) — runs close-validation gates,
       the maker-blind Story-scope code review, pushes `story-<id>`, opens
       a PR to `main`, and (under the default `delivery.ci.autoMerge:
@@ -88,7 +100,7 @@ From zero to shipped:
       `MERGED` PR the Story flips to `agent::done`; local branch cleanup
       and Projects-v2 Status re-assert run out-of-band.
 
-   For a multi-Story plan-run, `/deliver` sequences ready Stories by
+   For a multi-Story run, `/deliver` sequences ready Stories by
    `depends_on` and runs the per-run epilogue (audit roster · follow-up
    roll-up · sibling coherence) once after the last Story lands.
 
@@ -105,8 +117,8 @@ rather than re-documenting the ceremony they own.
 - **Layered state stores with explicit precedence.** Ticket status lives
   in GitHub Issues and Labels; the lifecycle bus
   (`temp/run-<id>/lifecycle.ndjson`) is the canonical resume target for
-  in-flight runs; structured comments (`story-run-progress`,
-  `verification-results`, retro) are the operator-visible rollup. The
+  in-flight runs; structured comments (`verification-results`, retro) are
+  the operator-visible rollup. The
   stores, their owners, and their conflict-resolution rules are listed in
   [§ State stores](#state-stores) — that matrix is the single source of
   truth for "who owns which write."
@@ -149,9 +161,8 @@ on-disk layout resolved by
 | State Store | Owner (canonical writer) | Mutation API | Idempotency key | Conflict resolution |
 | --- | --- | --- | --- | --- |
 | GitHub labels | `transitionTicketState` via `ticketing.js` | `gh issue edit --add-label / --remove-label`, wrapped in `update-ticket-state.js` | `(ticketId, label-set)` — set-equality before write | Authoritative for current ticket lifecycle state; if a label disagrees with the lifecycle ledger, the **ledger wins on resume** and the label is re-derived. |
-| `story-run-progress` comment | `story-phase.js` (per Story, per phase transition) | `post-structured-comment.js` (upsert by `kind`) | `(storyId, kind='story-run-progress')` | Authoritative for Story-level phase progress. |
 | `verification-results` comment | `lib/orchestration/code-review.js` | `post-structured-comment.js` (upsert by `kind`) | `(storyId, kind='verification-results')` | Authoritative for the Story-scope review + lens findings; critical findings block close. |
-| Lifecycle ledger NDJSON | `lifecycle-emit.js` (single append-only writer per run) | Append-only line write to `temp/run-<id>/lifecycle.ndjson` | `(runId, eventId)` — `eventId` is a content hash of `{type, ts, payload}` | **Canonical resume target.** When labels / comments disagree with the ledger, the ledger wins and the others are re-derived. |
+| Lifecycle ledger NDJSON | `LedgerWriter` (`lib/orchestration/lifecycle/ledger-writer.js`, registered as the first listener on every bus event — single append-only writer per run) | Append-only line write to `temp/run-<id>/lifecycle.ndjson` | `(runId, eventId)` — `eventId` is a content hash of `{type, ts, payload}` | **Canonical resume target.** When labels / comments disagree with the ledger, the ledger wins and the others are re-derived. |
 | Validation evidence cache | `evidence-gate.js` | JSON cache file under the run temp tree, keyed by HEAD SHA | `(gate, git rev-parse HEAD)` | Pure cache: a missing entry triggers a re-run; presence is a fast-path skip. Cache eviction is safe. |
 | PR / auto-merge state | `single-story-close.js` (sole authorized caller of `gh pr merge`) | `gh pr merge --auto --squash --delete-branch`; PR open via the close pipeline's `gh pr create` | `(prNumber, head-branch SHA)` — `gh pr list --head` probes before create | GitHub is authoritative for PR + auto-merge arming state; the ledger records the *intent* to arm, GitHub records the outcome. |
 | Worktree cleanup state | `WorktreeManager.reap` (via `single-story-close.js` / `git-cleanup.js`) | `git worktree remove` + on-disk pending-cleanup JSON under the run temp tree | `(storyId, worktree-path)` | Filesystem is authoritative for "is the worktree gone?"; the pending-cleanup JSON only tracks stale-registry entries needing a follow-up sweep. |
@@ -180,12 +191,12 @@ graph LR
         A["👤 /plan --seed | --seed-file | --tickets"]:::manual
         B["🤖 interrogate → author → persist"]:::agentic
         A --> B
-        B -.-> B_Art["📄 type::story issue(s)<br/>(+ optional plan-run::&lt;id&gt;)"]:::artifact
+        B -.-> B_Art["📄 type::story issue(s)<br/>(+ depends_on edges)"]:::artifact
     end
 
     subgraph Phase2 ["Phase 2: Deliver"]
         direction TB
-        E["👤 /deliver &lt;storyId&gt;<br/>(or --run &lt;planRunId&gt;)"]:::manual
+        E["👤 /deliver &lt;storyId&gt; [&lt;storyId&gt;…]"]:::manual
         F["🤖 deliver-story: story-&lt;id&gt; from main<br/>implement → self-eval → ceremony → close"]:::agentic
         G["🤖 close-validation → code-review → open PR"]:::agentic
         E --> F --> G
@@ -267,7 +278,7 @@ the SDLC depends on:
 - **One Story by default.** `/plan` authors a single `type::story` issue
   whose body carries a folded `## Spec` (inline only — never spilled to
   `docs/`) plus top-level `acceptance[]` / `verify[]`. It splits into N>1
-  siblings (sharing a `plan-run::<id>` label + `depends_on` edges) **only**
+  siblings (ordered by `depends_on` edges) **only**
   under the default-single split policy: near-zero overlap or a genuine
   architectural seam. Coupled work stays one Story and is decomposed inside
   `## Slicing` as intra-session checkpoints, not sibling tickets.
@@ -278,8 +289,7 @@ the SDLC depends on:
   `assertAcceptancePartition` so every acceptance criterion belongs to
   exactly one Story.
 - **Handoff.** Persist creates the Story issue(s) at `agent::ready` and
-  names the delivery command: `/deliver <storyId>` (or `/deliver --run
-  <planRunId>`).
+  names the delivery command: `/deliver <storyId> [<storyId> ...]`.
 
 Optional split advisory notes come from
 [`core/scope-triage`](../skills/core/scope-triage/SKILL.md); there is no
@@ -308,8 +318,7 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 | Mode | Entry point | When to use |
 | --- | --- | --- |
 | **Single Story** | `/deliver <storyId>` | Deliver one Story end-to-end; ends with a PR open to `main`. |
-| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**); each lands through its own PR. |
-| **Plan-run** | `/deliver --run <planRunId>` | Resolve Stories labeled `plan-run::<id>`, sequence them, and run the per-run epilogue after the set lands. |
+| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; each lands through its own PR, and the per-run epilogue runs after the set lands. |
 | **Story worker (internal)** | *helper* `helpers/deliver-story <storyId>` | Per-Story engine invoked internally by `/deliver`; not an operator slash command. |
 
 The single operator-facing entry point is `/deliver`. It performs no
@@ -374,14 +383,14 @@ Concurrent runs are serialised by **two distinct layers**:
   assignee; `--steal` is the only override. See
   [`README.md` § Multi-developer coordination](../README.md#multi-developer-coordination).
 
-### Concurrent close — push retry
+### Concurrent close
 
 `single-story-close.js` syncs the Story branch from `origin/main` before
-pushing and opening/locating the PR. Bounded retry constants live in
-`.agents/scripts/lib/config/runners.js` (`DEFAULT_STORY_MERGE_RETRY`:
-3 attempts, `[250, 500, 1000]` ms backoff). A real content conflict aborts
-the loop with a clear error, leaves the tree clean, and exits non-zero for
-manual resolution.
+pushing and opening/locating the PR, so concurrent closes serialize through
+their own worktrees rather than racing one shared branch. The push does not
+retry: a rejected push, or a real content conflict at base-sync, aborts with
+a clear error, leaves the tree clean, and exits non-zero for manual
+resolution.
 
 ---
 
@@ -486,14 +495,18 @@ pass — the tiers below *are* the audit machinery.
 | --- | --- | --- | --- |
 | Tier 1 — write-time | During Story implementation | Footprint-matched **local**-lens authoring checklists threaded into the Story prompt (`checklistPath`) | advisory |
 | Tier 2 — Story-scope | `single-story-close.js` (maker-blind subprocess) | Local-tier lens roster over the Story diff (`selectLocalLenses`) + review pillars, posted as `verification-results` | blocking on 🔴 |
-| Tier 3 — run closeout | `/deliver` per-run epilogue (`plan-run-epilogue.js`, N>1 only) | Cumulative + global + risk-routed lenses (`selectAudits` / `resolveAuditLenses`) over the combined landed tip | blocking |
+| Tier 3 — run closeout | `/deliver` per-run epilogue (`plan-run-epilogue.js`, N>1 only) | Cumulative + global lenses (`selectAudits`) over the combined landed tip | blocking |
 
 - **`local`** lenses (decidable from a single Story's diff) are verified at
   Tiers 1–2 and are **not** re-run at run closeout.
-- **`cumulative`** lenses (only decidable across a plan-run's combined diff)
+- **`cumulative`** lenses (only decidable across a run's combined diff)
   and **`global`** lenses (whole-product properties) are verified at Tier 3.
-- **Risk-routed** lenses run regardless of tier when a high-risk axis (or a
-  route-adding change set) demands them.
+
+There is no risk-routed lens tier. Story #4542 deleted the risk→lens router:
+it had zero callers while this document claimed it ran inside close. Lens
+selection is change-set-matched (`selectAudits` / `selectLocalLenses`); the
+`sensitivePaths` classes in `audit-rules.json` route review **depth**, not
+lenses.
 
 The run-closeout roster is deliberately **slim**: it excludes every
 local-tier change-set lens so the outermost tier — where a fix is most
@@ -504,8 +517,8 @@ expensive — does not re-verify a concern already covered shift-left.
 The Story-scope code review runs **outside the maker's context**, inside
 the `single-story-close.js` close subprocess, over `main...story-<id>`
 (see [`helpers/code-review.md`](../workflows/helpers/code-review.md)). It
-walks the Story diff once, executing the risk-routed lens roster as review
-dimensions alongside the review pillars, and posts the unified
+walks the Story diff once, executing the change-set-matched local lens roster
+as review dimensions alongside the review pillars, and posts the unified
 `verification-results` comment. Remediation is tier-aware and split by
 finding class off `delivery.codeReview.autoFixSeverity` (default `medium`);
 surviving 🔴 Critical findings halt the run. The legacy `scope: epic`
@@ -513,12 +526,14 @@ Epic-branch review path was removed with the v2 cutover.
 
 ### Quality ratchets
 
-- **Maintainability ratchet** (`check-maintainability.js`) — fails if the
+- **Maintainability ratchet** (`check-baselines.js` via
+  `lib/baselines/kinds/maintainability.js`) — fails if the
   composite score drops below the established baseline.
-- **CRAP gate** (`check-crap.js`) — per-method complexity × coverage risk
+- **CRAP gate** (`check-baselines.js` via `lib/baselines/kinds/crap.js`) —
+  per-method complexity × coverage risk
   against `baselines/crap.json`, wired into close-validation, `ci.yml`, and
-  `.husky/pre-push`. The `baseline-refresh:`-tagged commit convention is the
-  project standard for baseline edits (see
+  `.husky/pre-push`. The `baseline-refresh: true` commit-trailer convention
+  is the project standard for baseline edits (see
   [`core/gates-and-baselines`](../skills/core/gates-and-baselines/SKILL.md)).
 
 ### Audits → Stories
@@ -552,7 +567,7 @@ Severity vocabulary (`eventSeverity()` derives it for state transitions):
 
 | Severity | Used for | Webhook prefix |
 | --- | --- | --- |
-| `low` | `story-run-progress` upserts, intermediate transitions, audit reports. | `[low]` |
+| `low` | Intermediate transitions, audit reports. | `[low]` |
 | `medium` | Operator-visible milestones: Story state transitions, story merged, run complete. | `[medium]` |
 | `high` | Operator must act (HITL gates, Story blockers, autonomous-chain failures); body leads with `🚨 Action Required:`. | `[Action Required]` |
 
@@ -650,8 +665,7 @@ the ticket or re-plan the work as a v2 Story via `/plan --tickets <id>`.
 | `/plan --seed-file <path>` | Plan from on-disk notes / a plan seed (the `/audit-to-stories` handoff). |
 | `/plan --tickets <ids>` | Analyze existing issue(s) into proper Stories (prefer an N=1 rewrite). |
 | `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story` — `story-<id>` → PR → `main`. |
-| `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order; each lands through its own PR. |
-| `/deliver --run <planRunId>` | Resolve Stories labeled `plan-run::<id>`, sequence them, and run the per-run epilogue. |
+| `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (resolved from live state), then run the per-run epilogue. |
 | *helper* `helpers/deliver-story` | Per-Story engine invoked by `/deliver`; not an operator slash command. See [`deliver-story.md`](../workflows/helpers/deliver-story.md). |
 | `/audit-to-stories` | Convert audit findings into a plan seed / Stories → `/plan --seed-file`. |
 | `/qa-explore` · `/qa-assist` · `/qa-run` | Agent-led / human-led exploratory QA and the automated Gherkin harness. |

package/.agents/docs/agentrc-reference.json

@@ -56,19 +56,17 @@
       "mentionOperator": false,
       "commentEvents": ["state-transition", "story-merged", "operator-message"],
       "webhookEvents": [
-        "epic-started",
-        "epic-progress",
-        "epic-blocked",
-        "epic-unblocked",
-        "epic-complete"
+        "state-transition",
+        "story-merged",
+        "story-closing",
+        "operator-message",
+        "merge.unlanded",
+        "merge.flip-failed",
+        "loop.tick"
       ]
     }
   },
   "planning": {
-    "context": {
-      "maxBytes": 50000,
-      "summaryMode": "auto"
-    },
     "codebaseSnapshot": {
       "tier": "skinny",
       "include": [
@@ -131,8 +129,7 @@
       "paths": ["README.md"]
     },
     "deliverRunner": {
-      "concurrencyCap": 3,
-      "verifyConcurrencyCap": 4
+      "concurrencyCap": 3
     },
     "worktreeIsolation": {
       "enabled": true,
@@ -336,12 +333,10 @@
       "codingGuardrails": {
         "cyclomaticFlag": 8,
         "cyclomaticMustFix": 12,
-        "miDropMustRefactor": 1.5,
         "requireSiblingTest": false
       },
       "autoRefresh": {
         "enabled": true,
-        "miDropCap": 1.5,
         "crapJumpCap": 5,
         "scope": "diff"
       },

package/.agents/docs/configuration.md

@@ -97,9 +97,6 @@ top-level keys are validation errors.
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | — | — |
-| `context` | No | `object` | — | Nested configuration block. |
-| `context.maxBytes` | No | `integer` | — | — |
-| `context.summaryMode` | No | `"auto"` \| `"always"` \| `"never"` | — | — |
 | `codebaseSnapshot` | No | `object` | — | Nested configuration block. |
 | `codebaseSnapshot.tier` | No | `"skinny"` \| `"medium"` | — | — |
 | `codebaseSnapshot.include` | No | `array<string>` | — | — |
@@ -121,13 +118,12 @@ top-level keys are validation errors.
 | --- | --- | --- | --- | --- |
 | `execution` | No | `object` | — | Nested configuration block. |
 | `execution.timeoutMs` | No | `integer` | — | — |
-| `lease` | No | `object` | — | Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner has not emitted a story.heartbeat within this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js. |
+| `lease` | No | `object` | — | Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner's last heartbeat is older than this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js. Note the shipped guards fail closed (there is no live heartbeat source), so a stranded claim is cleared with --steal rather than by TTL expiry. |
 | `lease.ttlMs` | No | `integer` | — | — |
 | `docsFreshness` | No | `object` | — | Nested configuration block. |
 | `docsFreshness.paths` | No | `array` | — | — |
 | `deliverRunner` | No | `object` | — | Nested configuration block. |
 | `deliverRunner.concurrencyCap` | No | `integer` | — | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
-| `deliverRunner.verifyConcurrencyCap` | No | `integer` | — | Bounded-concurrency cap for the per-wave verifyWaveResults loop (Epic #3019 Tech Spec §1.4). Separate from the wave-execution `concurrencyCap` so operators can tune ticket-verification parallelism independently of Story dispatch parallelism. Default 4. |
 | `worktreeIsolation` | No | `object` | — | Nested configuration block. |
 | `worktreeIsolation.enabled` | No | `boolean` | — | — |
 | `worktreeIsolation.root` | No | `string` | — | — |
@@ -235,11 +231,9 @@ top-level keys are validation errors.
 | `quality.codingGuardrails` | No | `object` | — | Nested configuration block. |
 | `quality.codingGuardrails.cyclomaticFlag` | No | `integer` | — | — |
 | `quality.codingGuardrails.cyclomaticMustFix` | No | `integer` | — | — |
-| `quality.codingGuardrails.miDropMustRefactor` | No | `number` | — | — |
 | `quality.codingGuardrails.requireSiblingTest` | No | `boolean` | — | — |
 | `quality.autoRefresh` | No | `object` | — | Nested configuration block. |
 | `quality.autoRefresh.enabled` | No | `boolean` | — | — |
-| `quality.autoRefresh.miDropCap` | No | `number` | — | — |
 | `quality.autoRefresh.crapJumpCap` | No | `number` | — | — |
 | `quality.autoRefresh.scope` | No | `"diff"` \| `"full"` | — | — |
 | `quality.baselineEpsilon` | No | `object` | — | Per-kind epsilon for s-stability-epsilon (Story #1964). Sub-epsilon row deltas resolve to prior bytes so env variance does not rewrite the on-disk baseline. |
@@ -252,13 +246,15 @@ top-level keys are validation errors.
 | `quality.baselineEpsilon.bundle-size` | No | `number` | — | — |
 | `quality.baselineEpsilon.duplication` | No | `number` | — | — |
 | `quality.requireBaselines` | No | `boolean` | — | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
-| `quality.navigability` | No | `object` | — | Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's risk-routed ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
+| `quality.navigability` | No | `object` | — | Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
 | `quality.navigability.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against. |
 | `quality.navigability.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against. |
-| `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite /deliver's risk-routed ceremony runs. |
-| `mergeWatch` | No | `object` | — | Knobs consumed by the MergeWatcher lifecycle listener (Story #2896, Epic #2880). `intervalSeconds` is the poll cadence between `gh pr view --json mergeCommit,mergedAt` probes after epic.merge.armed; `maxBudgetSeconds` is the total wall-clock budget before the watcher surfaces `agent::blocked` with reason `budget-exceeded`. |
-| `mergeWatch.intervalSeconds` | No | `integer` | `30` | Seconds between MergeWatcher polls. Default 30. |
-| `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Total wall-clock budget (seconds) for the MergeWatcher poll loop. Default 3600 (60 minutes). |
+| `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite /deliver's per-Story ceremony runs. |
+| `mergeWatch` | No | `object` | — | Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR. |
+| `mergeWatch.intervalSeconds` | No | `integer` | `30` | Seconds between merge-wait polls. Default 30. |
+| `mergeWatch.maxWaitSeconds` | No | `integer` | `300` | Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block. |
+| `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the PR's createdAt. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked. |
+| `mergeWatch.updateAttempts` | No | `integer` | `3` | Maximum times the merge wait will bring a behind-the-base PR up to date before giving up on the branch. Default 3. Set 0 to disable the update. |
 | `codeReview` | No | `object` | — | Nested configuration block. |
 | `codeReview.providers[]` | No | `array<object>` | — | Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
@@ -267,7 +263,7 @@ top-level keys are validation errors.
 | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
 | `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
 | `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
-| `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the working diff against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on). |
+| `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on). |
 | `acceptanceEval.maxRounds` | No | `integer` | — | Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1). |
 | `acceptanceEval.clusterCeiling` | No | `integer` | — | Epic #4475 (M4-B). Max acceptance criteria one single-delivery acceptance critic scores in a single fresh-context pass. Single delivery clusters the Epic ## Acceptance Table ACs into ceil(totalACs / clusterCeiling) groups and spawns one maker-blind critic per cluster, restoring the distributed acceptance coverage the per-Story critic fan-out gave for free. Default 4; clamped into [1, 8] by lib/config/acceptance-eval.js so a large value cannot collapse the fan-out to a single diluted critic. Ignored on the fan-out route. |
 | `ci` | No | `object` | — | Nested configuration block. |
@@ -278,11 +274,11 @@ top-level keys are validation errors.
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | — | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
 | `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
 | `routing.roleScopedAgents` | No | `boolean` | — | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure (≈50KB → ≈8KB per spawn — the payoff of the context diet). When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
-| `routing.freshCriticSampleRate` | No | `number` | — | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Risk-routed ceremony sends a low-risk acceptance cluster down the contract-identical inline critic path, but this fraction of low-risk clusters is still forced through a fresh-context critic so low risk never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
-| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | — | Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = risk-routed with the maker-checker sampling floor. |
+| `routing.freshCriticSampleRate` | No | `number` | — | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
+| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | — | Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor. |
 | `routing.closeAndLand` | No | `boolean` | — | When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge. |
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
-| `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the Epic finalize listener auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Epic. |
+| `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
 
 <!-- END GENERATED:agentrc -->
@@ -405,15 +401,13 @@ Repository-level merge-method allowlist applied by bootstrap.
 | ----------------- | -------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `mentionOperator` | No       | `false`                                                                                | When `true`, friction comments @-mention `operatorHandle` for `medium`-severity dispatches (high always @mentions).                          |
 | `commentEvents`   | No       | `["state-transition", "story-merged", "operator-message"]`                             | Allowlist of event names that reach the GitHub ticket comment channel.                                                                       |
-| `webhookEvents`   | No       | `["epic-started", "epic-progress", "epic-blocked", "epic-unblocked", "epic-complete"]` | Allowlist of event names that reach `NOTIFICATION_WEBHOOK_URL`. The webhook channel is curated for the epic narrative; story-level events are excluded. |
+| `webhookEvents`   | No       | `["state-transition", "story-merged", "story-closing", "operator-message", "merge.unlanded", "merge.flip-failed", "loop.tick"]` | Allowlist of event names that reach `NOTIFICATION_WEBHOOK_URL`. The vocabulary mirrors the events the v2 runtime actually emits through `notify()`. |
 
 Both fields' enums are pinned in the schema and rejected if extended. To
 suppress a channel entirely, set its array to `[]`.
 
-> **Severity assignment.** Task transitions and `story-run-progress` upserts
-> fire `low` (frequency-driven). Story state transitions, `wave-run-progress`,
-> `epic-run-progress`, and epic-completion fire `medium`. Epic blockers and
-> HITL gates fire `high` (webhook prefix `[Action Required]` when an
+> **Severity assignment.** Story state transitions fire `medium`. Blockers
+> and HITL gates fire `high` (webhook prefix `[Action Required]` when an
 > allowlisted blocker event reaches the webhook).
 
 ---
@@ -456,17 +450,6 @@ is `soft` (visible to the planner, does not trip re-decompose). Set a
    explicit `--allow-large-fan-out` operator flag for very large delete blasts;
    that is separate from Story sizing.
 
-### `planning.context`
-
-Caps the size of `--emit-context` JSON payloads emitted during `/plan`
-so a runaway Epic body (with its folded Tech Spec sections) can't blow the
-planning agent's context budget.
-
-| Field         | Required | Default  | Purpose                                                                                       |
-| ------------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
-| `maxBytes`    | No       | `50000`  | Hard ceiling on the JSON payload size (bytes). Truncation is summary-mode-aware.              |
-| `summaryMode` | No       | `'auto'` | `'auto'` truncates intelligently; `'never'` errors over the cap; `'always'` always summarizes. |
-
 ### `planning.codebaseSnapshot`
 
 Controls the codebase-snapshot fetcher that grounds Tech Spec / Story authoring.
@@ -536,8 +519,7 @@ fall back to documented defaults (or are no-ops when omitted).
 
 | Field                       | Required | Default | Purpose                                          |
 | --------------------------- | -------- | ------- | ------------------------------------------------ |
-| `concurrencyCap`            | No       | `3`     | Max parallel Story sub-agents per wave.          |
-| `verifyConcurrencyCap`      | No       | `4`     | Max parallel verify steps per wave.              |
+| `concurrencyCap`            | No       | `3`     | Max ready Stories dispatched by `/deliver` at once. |
 
 ### `delivery.worktreeIsolation`
 
@@ -666,7 +648,6 @@ for `BUNDLE_SIZE_REFRESH=1` usage.
 | ---------------------- | -------- | ------- | ------------------------------------------------------------------ |
 | `cyclomaticFlag`       | No       | (none)  | Cyclomatic-complexity value at which the engineer should refactor.  |
 | `cyclomaticMustFix`    | No       | (none)  | Cyclomatic-complexity value that hard-fails the gate.               |
-| `miDropMustRefactor`   | No       | (none)  | MI drop that mandates a refactor.                                   |
 | `requireSiblingTest`   | No       | (none)  | When `true`, a new function requires a sibling test file.           |
 
 #### `delivery.quality.autoRefresh`
@@ -676,7 +657,6 @@ Controls Story-close auto-baseline-refresh for gated metrics.
 | Field         | Required | Default | Purpose                                                  |
 | ------------- | -------- | ------- | -------------------------------------------------------- |
 | `enabled`     | No       | (none)  | Master switch.                                           |
-| `miDropCap`   | No       | (none)  | Max MI drop the auto-refresher will absorb before failing. |
 | `crapJumpCap` | No       | (none)  | Max CRAP jump the auto-refresher will absorb before failing. |
 | `scope`       | No       | (none)  | One of `'diff'` or `'full'`.                              |
 
@@ -791,22 +771,6 @@ Paths are configured in `delivery.quality.gates.<tier>.baselinePath`. The
 default values match the canonical layout above; override only when a
 project genuinely stores baselines elsewhere.
 
-### Per-wave drift snapshots — `.agents/state/`
-
-The Epic runner's progress reporter writes wave-start snapshots so that a
-resumed run can detect intra-wave drift without re-reading the canonical
-baseline (which may have been refreshed mid-Epic).
-
-| File                                    | Owner                                                | Lifecycle                                       |
-| --------------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
-| `.agents/state/wave-mi-snapshot.json`   | `progress-signals/maintainability-drift.js`          | Captured at wave-start; overwritten next wave.   |
-| `.agents/state/wave-crap-snapshot.json` | `progress-signals/crap-drift.js`                     | Captured at wave-start; overwritten next wave.   |
-
-These are **not** ratchet baselines and must not be committed as such. The
-filenames intentionally differ from the canonical files so a repo-wide grep
-for `baselines/maintainability.json` or `baselines/crap.json` only ever hits
-the canonical paths.
-
 The `.agents/state/` directory itself is created on demand by the progress
 reporter; the framework does not require it to exist ahead of time and does
 not commit its contents.
@@ -867,7 +831,7 @@ git.
 per-contributor value with two jobs: the `@`-handle the framework @mentions on
 friction comments, **and** the lease owner the workflow guards
 ([`ticket-lease.js`](../scripts/lib/orchestration/ticket-lease.js))
-assign to a ticket so two contributors cannot drive the same Epic/Story
+assign to a ticket so two contributors cannot drive the same Story
 concurrently. Because the lease must distinguish *your* run from *another
 person's*, a shared committed handle would defeat it — everyone would coordinate
 under one identity. So each contributor sets their own in `.agentrc.local.json`:
@@ -1063,15 +1027,27 @@ mandrel explain --json   # JSON report for scripting
 
 ### `mandrel sync-commands`
 
-Regenerates the flat `.claude/commands/` tree from `.agents/workflows/`. The
-bootstrap wires a `UserPromptSubmit` hook so this runs automatically on every
-Claude Code prompt; manual invocations are only needed when the hook is absent
-or the commands/ tree is manually deleted.
+Regenerates the flat `.claude/commands/` tree from `.agents/workflows/`. Runs
+automatically at install time (via `prepare`) and as part of `mandrel
+sync`/`update`; manual invocations are only needed when the commands/ tree is
+manually deleted or edited by hand. Refuses to project when the materialized
+`.agents/` tree doesn't match the running CLI's own version.
 
 ```bash
 mandrel sync-commands
 ```
 
+### `mandrel sync-agents`
+
+Regenerates the flat `.claude/agents/` tree from `.agents/agents/` — the
+role-scoped boot contexts `delivery.routing.roleScopedAgents` (default
+`true`) dispatches spawns against. Same wiring and version-match refusal as
+`mandrel sync-commands` above.
+
+```bash
+mandrel sync-agents
+```
+
 ### `mandrel uninstall`
 
 Reverses a recorded install using the install ledger

package/.agents/docs/execution-reference.md

@@ -19,12 +19,13 @@ validated.
 
 - **Canonical record + schema validation**: `diagnose-friction.js` appends one
   `kind: friction` record, validated write-time against
-  `signal-event.schema.json`, to the per-Epic/per-Story `signals.ndjson`
-  stream on local disk. The retro roll-up reads that stream back to aggregate
+  `signal-event.schema.json`, to the per-run/per-Story `signals.ndjson`
+  stream on local disk (under `temp/run-<id>/`). The retro roll-up reads that
+  stream back to aggregate
   friction into routed proposals; nothing is posted to the GitHub ticket at
   capture time.
-- **No-Epic context**: Outside an Epic/Story loop there is no per-Epic stream
-  to anchor to, so the record lands on the **standalone signal stream**
+- **Standalone context**: Outside a delivery run there is no `temp/run-<id>/`
+  stream to anchor to, so the record lands on the **standalone signal stream**
   (`temp/standalone/stories/story-<sid>/signals.ndjson`) under the same
   canonical schema.
 - **Never silently dropped**: The signal is never silently dropped — a
@@ -57,12 +58,40 @@ schema mechanics are in [§ Friction telemetry](#friction-telemetry) above.
 
 ## FinOps & token budgeting (economic guardrails)
 
-Mandrel does **not** enforce live LLM spend from response metadata. The
-framework limits **hydrated prompt size** via section-aware elision
-(`elideEnvelope`) and optional **pre-dispatch estimates**; your host
-runtime (editor / CLI) owns session quota and hard stops. Consult this
-section when reasoning about why a task prompt was elided or why `/deliver`
-refused a fan-out on budget grounds.
+Mandrel does **not** enforce live LLM spend from response metadata. It bounds
+two things, both **fixed framework constants** rather than operator knobs, and
+both **fail closed**: the assembled `/plan` context envelope, and plan-time
+Story sizing. Your host runtime (editor / CLI) owns session quota and hard
+stops. Consult this section when reasoning about why `/plan` refused an
+over-ceiling envelope or an over-budget Story count.
+
+> **There is no configurable context budget.** `planning.context.maxBytes` /
+> `summaryMode` were removed outright in Story #4541, along with the
+> `applyBudget` pass they fed: that pass lost its last caller in the v2
+> cutover, and it was already bounding a field the envelope builders discarded
+> before shipping the raw seed anyway. The schema now **rejects**
+> `planning.context`, so a config carrying it fails loudly rather than silently
+> capping nothing. The ceiling below is the replacement and the only live bound
+> on planner-context size. Separately, `elideEnvelope` in
+> `lib/orchestration/context-envelope.js` — which this section used to credit
+> with limiting hydrated prompt size — has no production caller either (it is
+> carried in `baselines/dead-exports-production.json`). Only `estimateTokens`
+> from that module is live.
+
+### Planner-context envelope (`/plan`)
+
+- **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
+  256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
+  envelope `buildPlanContext` assembles, checked at the single choke point
+  every mode returns through. Measured envelopes on this repo land at ~42 KB,
+  so the ceiling is >2× headroom over a worst-case seed plus a medium-tier
+  codebase snapshot.
+- **On refusal**, the error names the envelope's largest fields. Trim the seed,
+  plan fewer `--tickets` source issues in one run, or narrow
+  `planning.codebaseSnapshot`. The seed is carried **verbatim** by design — it
+  is the operator's request, and summarizing it silently would degrade planning
+  quality precisely when the input is richest — so there is no elision path to
+  fall back on. Raising the ceiling needs a measured justification.
 
 ### Session-mass capacity (plan-time sizing)