mandrel 1.87.0 → 1.89.0

package/.agents/workflows/helpers/code-review.md

@@ -64,7 +64,7 @@ envelope via
 
 It is an **input-only** signal: it changes *how thorough* the review is, never
 the findings envelope (`{ status, severity, posted, report, halted,
-blockerReason }`) nor the posted `code-review` structured-comment body. An
+blockerReason }`) nor the posted `verification-results` structured-comment body. An
 absent or malformed `depth` is treated as `standard`, so an Epic that skipped
 `/plan` still gets a passing review with no new failure mode.
 
@@ -117,13 +117,82 @@ The pipeline will:
 - Run a focused lint check on the change set.
 - Post a structured summary report to the `[TICKET_ID]` issue.
 
+### Step 1a — Story-scope local-lens pass (`scope: story` only, Epic #4405)
+
+When `scope === 'story'`, the shared review spine
+[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/code-review.js)
+runs a **shift-left local-lens pass** in the same close subprocess, *before*
+returning the review envelope. It:
+
+1. Enumerates the actual Story diff (`baseRef...headRef` via
+   `git diff --name-only`).
+2. Selects the **local-tier** lenses that own a concern decidable from a single
+   Story's diff — `resolveLensTier(lens) === 'local'` **plus** the pure
+   `matchesAnyFilePattern` matcher against the diff (the audit-suite SDK's
+   [`selectLocalLenses`](../../scripts/lib/audit-suite/selector.js)). This is
+   deliberately **not** `selectAudits`: `selectAudits` unions in keyword and
+   gate matches and has no per-tier gate, so it would widen the roster past the
+   footprint-matched local set this tier owns.
+3. Materializes the matched roster at **`light`** depth
+   (`STORY_SCOPE_LENS_DEPTH`) via `runAuditSuite`, surfacing the outcome on the
+   review envelope's `localLensReview` field.
+
+A diff that matches no local lens adds **no** lens work (the roster is empty and
+`runAuditSuite` is never invoked). The pass is advisory and best-effort: a git
+or materialization failure degrades to a skipped envelope and never blocks the
+close.
+
+Both close entry points —
+[`runStoryCodeReview`](../../scripts/lib/orchestration/story-close/phases/code-review.js)
+(Epic-attached) and
+[`runStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
+(standalone) — reach this pass through the single `runStoryReviewCore` spine, so
+standalone Stories gain local-lens coverage for the first time. Because the pass
+lives inside the close subprocess (invoked after the delivering child exits), it
+honors the maker-blind invariant above: a maker never runs its own local-lens
+review. This step does not apply to `scope: epic`, whose lens roster is the
+cumulative + global + risk-routed set resolved at Epic close (Step 1b).
+
+### Step 1b — Epic-close lens roster (`scope: epic` only, Epic #4405)
+
+When `scope === 'epic'`, the cumulative Epic diff is walked **once** at close:
+the Epic-close lens roster is executed as **dimensions of this same review
+pass**, not as a separate Phase 4 walk (Story #4412 folded the standalone
+epic-audit lens walk into this pass). Resolve and walk the roster inline:
+
+1. Resolve the roster via [`helpers/epic-audit.md`](epic-audit.md) Step 1 —
+   run `epic-audit-prepare.js --gate gate3` and take its **`epicCloseLenses`**
+   field: the slim roster of cumulative + global + risk-routed lenses, with
+   every local-tier change-set lens excluded (routed off `resolveLensTier` in
+   [`selectEpicCloseLenses`](../../scripts/lib/orchestration/code-review.js)).
+   Local-tier concerns are already verified shift-left (write-time checklists +
+   the Story-scope local-lens pass), so they are **not** re-run here.
+2. Materialize each rostered lens via
+   [`runAuditSuite`](../../scripts/lib/audit-suite/index.js) at the envelope's
+   `depth`, applying the `{{changedFiles}}` substitution, and walk each lens's
+   `.agents/workflows/audit-<lens>.md` procedure over the cumulative
+   `main..epic/<epicId>` diff. Global lenses (`globalLenses`, e.g.
+   `audit-navigability`) run against the WHOLE route tree, exempt from the
+   change-set narrowing.
+3. Fold the lens findings into this pass's severity aggregate **alongside** the
+   Step 2 review pillars — one walk of the cumulative diff, one aggregate, one
+   `verification-results` comment (Step 4). An empty `epicCloseLenses` roster
+   (docs-only, or every selected lens already covered shift-left, and no
+   risk-routed lens) adds no lens dimension — the pillars still run.
+
+This step does not apply to `scope: story` (its roster is the local-tier set of
+Step 1a) and is skipped when `epic-audit-prepare.js` returns `degraded: true`
+(propagate the reason and STOP, per `epic-audit.md`).
+
 ## Step 2 — Review Pillars
 
 For each changed file, execute a strict review against four pillars. The
 second pillar (**Integration Review**) deliberately defers the security /
-performance / quality / coverage sweeps to the change-set-scoped audits
-that already ran upstream — re-walking them here is duplication, not
-defense-in-depth.
+performance / quality / coverage sweeps to the change-set-scoped lenses — at
+`scope: story` those ran shift-left in the Story-scope local-lens pass (Step
+1a); at `scope: epic` they run inline in this same pass as the Epic-close lens
+roster (Step 1b). Re-walking those sweeps a second time in this pillar is
+duplication, not defense-in-depth.
 
 **Apply the `depth` lever** (see **Review depth** above) to how hard you walk
 these pillars: at `light`, focus on Pillar 1 and reduce Pillars 2–3 to a quick
@@ -151,11 +220,11 @@ The integration view depends on `scope`. The diff under review is always
 against differs:
 
 - **`scope: story`** — the diff is `epic/<epicId>..story-<storyId>` (i.e.
-  one Story's contribution to the Epic). There is typically no
-  `audit-results` comment on the Story; Phase 4 epic-level audits have not
-  yet run for this change set. The integration view here focuses on
-  cross-Task ripple within the Story and contract drift against the Epic
-  branch tip. Look for:
+  one Story's contribution to the Epic). The Story-scope local-lens pass
+  (Step 1a) has already covered the local-tier concerns; the Epic-close lens
+  roster has not run for this change set (it runs once at Epic close). The
+  integration view here focuses on cross-Task ripple within the Story and
+  contract drift against the Epic branch tip. Look for:
   - Cross-Task contract drift inside the Story (one Task's API change vs.
     another Task's caller in the same branch).
   - Shared-module ripple effects from this Story onto siblings already
@@ -163,30 +232,31 @@ against differs:
   - Spec deviations that the per-Task commits papered over.
 
 - **`scope: epic`** — the diff is `main..epic/<epicId>` (the cumulative
-  Epic change set). Read the **`audit-results` structured comment** posted
-  on the Epic ticket by the [`epic-audit.md`](epic-audit.md) helper in
-  Phase 4. That comment is the authoritative source of security, privacy,
-  performance, code-quality, and test-coverage findings for this change
-  set — they were produced by the change-set-aware lens selector and
-  per-lens audit workflows under `.agents/workflows/audit-*.md`. Do **not**
-  re-derive those findings inline here.
+  Epic change set). The Epic-close lens roster (`epicCloseLenses`) is walked
+  **inline as part of this pass** (Step 1b) — the cumulative diff is read once,
+  and the security, privacy, performance, code-quality, and test-coverage
+  findings the rostered lenses produce feed this pass's aggregate directly.
+  There is no separate `audit-results` comment to read (Story #4412 retired it);
+  the lens findings and the pillar findings share the single
+  `verification-results` comment this pass posts.
 
   The integration view at epic scope is what the per-lens audits cannot
   produce because each lens runs in isolation:
 
-  - Cross-reference 🔴 / 🟠 audit findings against the spec deviations
+  - Cross-reference 🔴 / 🟠 lens findings against the spec deviations
     flagged in Pillar 1 — a finding that traces back to a deliberate
     Tech-Spec decision is different from one that traces back to an
     oversight.
   - Look for cross-cutting concerns no single lens owns: contract drift
     between Stories, shared-module ripple effects, boundary changes that
     thread security and performance implications together.
-  - Note any audit finding that the operator's remediation flow should
+  - Note any lens finding that the operator's remediation flow should
     bundle (e.g. one refactor closes findings from multiple lenses).
 
-  If the Epic has no `audit-results` comment (docs-only Epic, or Phase 4
-  was skipped via `--skip-epic-audit`), record that explicitly in the
-  findings report and proceed — there is nothing to integrate.
+  If the Epic-close roster is empty (docs-only Epic, every selected lens
+  already covered shift-left, or the pass was skipped via
+  `--skip-epic-audit` / `--skip-code-review`), record that explicitly in the
+  findings report and proceed — there is no lens dimension to integrate.
 
 ### Pillar 3: Documentation Integrity
 
@@ -261,9 +331,11 @@ prior baseline before merging.
 
 ## Step 4 — Produce Findings Report
 
-Findings are **persisted as a `code-review` structured comment on the
-`[TICKET_ID]` issue** by `runCodeReview`. The target ticket is the Story
-when `scope === 'story'` and the Epic when `scope === 'epic'`. The comment
+Findings are **persisted as a `verification-results` structured comment on
+the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract of
+Story #4411; at `scope: epic` this single comment also carries the Step 1b
+Epic-close lens findings). The target ticket is the Story when
+`scope === 'story'` and the Epic when `scope === 'epic'`. The comment
 is idempotent — re-runs replace the prior one — and its body includes
 severity-tier counts plus the full findings list so downstream workflows
 (notably the retro helper) can summarise blockers/high findings without
@@ -293,12 +365,64 @@ For every finding, provide:
   fix worked. Keep it tight (≤ 5 sentences); the sub-agent will read the
   surrounding code itself.
 
+### The `## Fixed on-branch` section (Story #4399)
+
+Findings that Step 4.5 remediated on `[HEAD_REF]` MUST be rendered under a
+dedicated **`## Fixed on-branch`** heading, **not** in the severity groups
+above. This is the contract seam that keeps remediated findings from
+spawning ghost follow-up issues: the
+[audit-results graduator](../../scripts/lib/feedback-loop/audit-results-graduator.js)
+(the sole canonical reader of the unified comment)
+skips every entry inside this section (both because a fixed entry is
+rendered with a **✅ prefix** — so it carries no leading severity emoji the
+parser would match — and because the parser has an explicit
+Fixed-on-branch section guard).
+
+Render each fixed finding as a `✅`-prefixed line naming its original
+severity, the file path in backticks, and the remediating commit SHA, e.g.:
+
+```markdown
+## Fixed on-branch
+
+- ✅ 🟡 Medium: `src/lib/foo.js` — missing edge-case guard added (a1b2c3d)
+- ✅ 🟠 High: `src/api/users.js` — ownership check added (d4e5f6a)
+```
+
+Open (escalated / unfixed) findings stay in their severity group with
+their leading severity emoji so the graduator still files them.
+
 ## Step 4.5 — Focused-fix Routing (host LLM, no automated loop)
 
 There is **no runtime auto-fix function** at this phase. The host LLM is
-the executor: for each 🔴 / 🟠 finding from Step 4, decide between two
-paths and keep the `code-review` structured comment authoritative for
-anything not fixed in-place.
+the executor: it decides, per finding, between a focused fix on
+`[HEAD_REF]` and leaving the finding on the `verification-results`
+structured comment for the operator.
+
+### Resolve the remediation threshold (Story #4399)
+
+Read `delivery.codeReview.autoFixSeverity` from the resolved `.agentrc.json`
+(default **`medium`**; the resolver in
+[`config/runners.js`](../../scripts/lib/config/runners.js) supplies the
+default when the key is absent). The threshold governs **which severities
+route into on-branch remediation** — it never changes the halting rule (a
+surviving 🔴 still stops) or the escalation classes:
+
+- **`medium`** (default) — route 🔴 Critical, 🟠 High, **and 🟡 Medium**
+  findings into remediation. 🟢 Suggestions stay on the comment (never
+  auto-fixed).
+- **`high`** — route only 🔴 Critical and 🟠 High findings, reproducing
+  the pre-4399 behavior exactly. 🟡 Medium and 🟢 Suggestion findings stay
+  on the comment.
+
+Hard cutover per
+[`rules/git-conventions.md`](../../rules/git-conventions.md) § Contract
+Cutovers — no back-compat flag; `high` is opt-in to the old routing.
+
+### 🔴 / 🟠 findings — per-finding ceremony (unchanged)
+
+For each 🔴 / 🟠 finding from Step 4, decide between two paths and keep the
+`verification-results` structured comment authoritative for anything not fixed
+in-place.
 
 1. **Apply a focused fix on `[HEAD_REF]`.** Permitted only when the
    finding is unambiguously *fixable* (clean remediation, no scope
@@ -328,27 +452,52 @@ anything not fixed in-place.
      attempt (the equivalent of the prior loop's
      `validation-regression` / `thrash-detected` exits).
 
+### 🟡 Medium findings — batched per-lens ceremony (only when `autoFixSeverity: medium`)
+
+When the threshold is `medium`, remediate the fixable 🟡 Medium findings in
+a **batch keyed by owning review lens/pillar** rather than the per-finding
+ceremony above:
+
+1. Group the fixable Mediums by owning lens (the pillar or audit family
+   that produced them). A Medium is fixable on the same terms as a 🟠; a
+   Medium in any escalation class stays on the comment exactly like a 🟠.
+2. For each lens, call `assert-branch.js --expected [HEAD_REF]`, stage
+   explicit paths only, and make **one focused conventional commit per
+   lens** (`fix(<scope>): <description> (review findings batch)`).
+3. Bounded-attempt semantics extend to the batch: each finding gets **at
+   most one** attempt, and a lens's batch commit that would exceed
+   `delivery.codeReview.maxFixScopeFiles` routes that lens's findings to
+   escalation (`scope-exceeded`) instead of committing.
+4. After **all** lens batches are committed, run a **single** validation
+   pass (`npm run lint` plus the relevant `npm test` slice) and a
+   **single** targeted rescan over the touched files. Surviving batched
+   findings stay on the comment for Step 5.
+
+Record every remediated finding (🟠 or 🟡) in the **"Fixed on-branch"**
+section of the `verification-results` comment (Step 4) so it does not graduate
+to a follow-up issue.
+
 Do not invent a programmatic retry budget. The host LLM applies *at most
-one* focused-fix attempt per finding before escalating to the operator.
-Escalated findings remain on the `code-review` structured comment with
-their reason recorded, so Step 5 (and downstream consumers) see exactly
-why each one was not auto-remediated.
+one* focused-fix attempt per finding (or per batched finding) before
+escalating to the operator. Escalated findings remain on the `code-review`
+structured comment with their reason recorded, so Step 5 (and downstream
+consumers) see exactly why each one was not auto-remediated.
 
 ## Step 4.6 — Cross-phase re-check trigger
 
 After the focused-fix routing in Step 4.5 completes, any host-LLM-applied
-fix commits have modified files on `[HEAD_REF]` that the Phase 4 audit
-lenses already walked. Some of those edits may overlap the `filePatterns`
-of one or more lenses (e.g. a fix landing in `**/auth/*.js` overlaps the
-`audit-security` lens). When that happens, the prior `audit-results`
-structured comment is **stale for the overlapping lenses only** — the
-non-overlapping findings remain authoritative and MUST NOT be
+fix commits have modified files on `[HEAD_REF]` that the Epic-close lens
+roster already walked (Step 1b). Some of those edits may overlap the
+`filePatterns` of one or more lenses (e.g. a fix landing in `**/auth/*.js`
+overlaps the `audit-security` lens). When that happens, the lens findings in
+the `verification-results` comment are **stale for the overlapping lenses
+only** — the non-overlapping findings remain authoritative and MUST NOT be
 re-derived.
 
 > **Scope note.** This cross-phase re-check applies only when
-> `scope === 'epic'`. Story-scope reviews run before Phase 4 epic audits
-> exist, so there is no `audit-results` comment to invalidate; skip this
-> step entirely for `scope === 'story'`.
+> `scope === 'epic'`. Story-scope reviews carry no Epic-close lens roster,
+> so there is nothing to invalidate; skip this step entirely for
+> `scope === 'story'`.
 
 Invoke the re-check selector with the cumulative set of paths touched by
 the focused-fix commits:
@@ -369,11 +518,11 @@ no-op.
 When `selectedAudits` is non-empty:
 
 1. Re-invoke each listed lens prompt under
-   [`../audit-*.md`](../) the same way Phase 4's `epic-audit.md` does —
+   [`../audit-*.md`](../) the same way the Step 1b Epic-close walk does —
    one lens at a time, against the current `[HEAD_REF]` tip.
 2. **Append** a `## Cross-phase re-check` section to the **existing**
-   `audit-results` structured comment on the Epic ticket. Do **not** post
-   a new comment; the comment is idempotent and downstream consumers
+   `verification-results` structured comment on the Epic ticket. Do **not**
+   post a new comment; the comment is idempotent and downstream consumers
    (the code-review trim, `/deliver` Pillar 2, the retro helper)
    read it once. The append carries the re-checked lens names, the new
    findings (if any), and the focused-fix commit SHAs that triggered the
@@ -383,7 +532,7 @@ When `selectedAudits` is non-empty:
    through Step 4.5's focused-fix routing. Findings that already
    received a focused-fix attempt in the first pass do not get a fresh
    attempt when the cross-phase re-check resurfaces an adjacent one —
-   leave them on the `code-review` comment for the operator.
+   leave them on the `verification-results` comment for the operator.
 
 If `selectedAudits` is empty, skip silently and proceed to Step 5. The
 re-check trigger is **read-only signal** — it never mutates the Epic

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

@@ -1,8 +1,10 @@
 ---
 description: >-
   Drive an Epic from `agent::ready` to a merged pull request against `main`.
-  The ten-phase flow runs the wave loop, close-validation, epic-audit,
-  code-review, retro, finalize, watch-and-iterate, conditional auto-merge,
+  The ten-phase flow runs the wave loop, close-validation, the Epic-close
+  lens-roster resolve, the code-review pass (which walks the cumulative diff
+  once with the lens roster folded in), retro, finalize, watch-and-iterate,
+  conditional auto-merge,
   and local branch cleanup. When the run is end-to-end clean (zero manual
   interventions, zero 🔴/🟠 review findings, compact retro) the PR
   auto-merges via `gh pr merge --squash --delete-branch`; otherwise the
@@ -36,8 +38,8 @@ back to the operator-merges-button path.
   → Phase 1 — prepare              (epic-deliver-prepare.js)
   → Phase 2 — ready-set loop       (wave-tick.js → dispatch ready set → observe → re-tick)
   → Phase 3 — close-validation     (lint + test + ratchets on epic/<id>)
-  → Phase 4 — epic-audit           (helpers/epic-audit.md — change-set audits via selectAudits)
-  → Phase 5 — code-review          (helpers/code-review.md with scope: epic)
+  → Phase 4 — epic-close lens roster (helpers/epic-audit.md — resolve the slim cumulative+global+risk-routed roster)
+  → Phase 5 — code-review          (helpers/code-review.md scope: epic — walks the cumulative diff once, lens roster folded in)
   → Phase 6 — retro                (.agents/scripts/lib/orchestration/retro-runner.js)
   → Phase 6.5 — integration gate   (whole-product navigability + journey suite; @pending ≠ green for surface-adding Epics — blocks finalize)
   → Phase 7 — finalize             (lifecycle-emit → epic.close.end → open PR to main)
@@ -81,6 +83,19 @@ spawned.
 Every other runtime modifier is sourced from the Epic's labels or from
 `delivery.deliverRunner` in `.agentrc.json`.
 
+- `--yes` — the top-level `/deliver` unattended flag (suppresses the
+  operator confirmation gate; see [`deliver.md`](../deliver.md)). This
+  helper reads it as the **headless signal** for Phase 8.5's must-land
+  terminal step (Story #4427): when `/deliver` was invoked with `--yes`,
+  thread `--headless true` into the Phase 8.5
+  `epic.automerge.start` `lifecycle-emit.js` call (omit the flag, or
+  pass `--headless false`, for an attended run). The runtime reads this
+  as an explicit `headless` input threaded through
+  `runLifecycleEmit` → `buildDefaultListenerChain` →
+  `MergeWatcher({ headless })` — never an ambient/undefined global.
+  Attended-mode behavior (no `--headless` flag) is byte-for-byte
+  unchanged: `MergeWatcher` defaults `headless` to `false`.
+
 ---
 
 ## Contract
@@ -178,9 +193,14 @@ Validates `type::epic`, enumerates `type::story` descendants, parses
 checkpoint in the per-Story-status shape (a flat `stories` map seeded at
 `pending`, plus the global `concurrencyCap`). Treat the printed JSON as
 `state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt, docsDigestPath }`.
-`stories` is the flat dispatch hint (`{ storyId, worktree, title }` per open
-Story); the ready-set `tick` (Phase 2) decides which to dispatch on each
-beat. `docsDigestPath` is the repo-relative path to the per-Epic docs digest
+`stories` is the flat dispatch hint (`{ storyId, worktree, title,
+checklistPath }` per open Story); the ready-set `tick` (Phase 2) decides
+which to dispatch on each beat. `checklistPath` is the repo-relative path to
+that Story's footprint-matched local-lens authoring checklist
+(`temp/epic-<epicId>/checklists/story-<storyId>.md`, Story #4410) — thread it
+into that child's prompt (§ 2b, item 7); it is `null` when the Story's
+predicted footprint matched no local lens. `docsDigestPath` is the
+repo-relative path to the per-Epic docs digest
 (`temp/epic-<epicId>/docs-digest.md`) that prepare writes from
 `project.docsContextFiles` — thread it into every child prompt (§ 2b, item 6).
 It is `null` when the project configured no `docsContextFiles` (no digest is
@@ -369,7 +389,14 @@ digest instead of re-reading the full `project.docsContextFiles` set,
 and to pull individual docs files on demand (per
 [`.agents/instructions.md` § 3](../../instructions.md)). When
 `docsDigestPath` is null (the project configured no `docsContextFiles`),
-say so — the child then has no per-Story docs mandate. The pairing of
+say so — the child then has no per-Story docs mandate. (7) pass the
+**checklist path** — the `checklistPath` field from that Story's entry in
+the `stories` dispatch hint (Story #4410), which points at
+`temp/epic-<epicId>/checklists/story-<storyId>.md`. Instruct the child to
+read that file (footprint-matched local-lens authoring checklists) and
+self-check its change against those concerns while writing. When
+`checklistPath` is null (the Story's predicted footprint matched no local
+lens), there is nothing to read. The pairing of
 `story.heartbeat` and `agent::blocked` is what lets the § 2d Idle
 Watchdog distinguish a working child from a dead one; a silent child
 with no recent heartbeat and no blocker label is the failure mode the
@@ -473,51 +500,61 @@ the Epic branch; if any drifts, refresh and commit
 
 ---
 
-## Phase 4 — Epic audit (change-set lenses)
+## Phase 4 — Epic-close lens roster
 
 Skip when `--skip-epic-audit`. Otherwise auto-invoke
-[`helpers/epic-audit.md`](epic-audit.md) inline. The helper runs
+[`helpers/epic-audit.md`](epic-audit.md) inline to **resolve** (not walk) the
+slim Epic-close lens roster. The helper runs
 [`epic-audit-prepare.js`](../../scripts/epic-audit-prepare.js) to ask the
 [`selectAudits`](../../scripts/lib/audit-suite/index.js) SDK which lenses fire
 at the `gate3` close gate, **unions in the model-judged risk-routed lenses**
 (Story #3889 — `epic-audit-prepare.js` reads the Epic's `planningRisk`
 envelope off the `epic-plan-state` checkpoint and maps each high-risk axis to
-its lens via `resolveAuditLenses`), then dispatches each selected lens through
-[`runAuditSuite`](../../scripts/lib/audit-suite/index.js). A high-risk Epic
-therefore auto-runs its mapped lenses (e.g. a `security`-axis Epic runs
-`audit-security`) even when the change set alone did not select them; a
-low-risk Epic adds nothing. Findings are persisted as an `audit-results`
-structured comment on the Epic.
-
-The helper walks the selected roster **serially in-context by default**; when
-the roster carries more than one lens it **may delegate the walk to a single
-audit-orchestrator sub-agent** that fans the already-selected lenses out as
-parallel level-2 agents and returns only the aggregated `audit-results` (see
-[`epic-audit.md` § "Optional: delegate the roster walk to an audit-orchestrator
-sub-agent"](epic-audit.md), within the sub-agent depth budget noted under
-"Flat Story dispatch by design" above). The roster stays fixed upstream, every
-per-lens cost gate is preserved, and the seven sequential-only lenses are **not**
-batch-converted — the fan-out parallelizes across lenses only and never changes
-how any single lens runs internally.
-
-- **Any 🔴 Critical Blocker** — STOP. Relay to the operator.
-- **Only 🟠/🟡/🟢** — log as non-blocking and continue.
+its lens via `resolveAuditLenses`), then restricts that union to the tiers the
+Epic-close tier owns via
+[`selectEpicCloseLenses`](../../scripts/lib/orchestration/code-review.js): the
+envelope's **`epicCloseLenses`** field is the slim roster of **cumulative +
+global + risk-routed** lenses, with every **local-tier** change-set lens
+excluded (its concern is already verified shift-left at the write-time and
+Story-scope tiers). A high-risk Epic still auto-runs its risk-routed lenses
+even when the change set alone did not select them; a docs-only or
+already-shift-left-covered change set yields an empty roster.
+
+**The lens roster is not walked here.** Story #4412 folded the standalone
+Phase 4 lens walk into the Phase 5 code-review pass so the cumulative Epic diff
+is walked **once**. Phase 4 resolves `epicCloseLenses` (plus `depth`,
+`globalLenses`, `substitutionsPayload`) and hands it to Phase 5; there is no
+separate `audit-results` comment. Remediation of the lens findings happens in
+Phase 5 and is **tier-aware** (Story #4412): the Epic-close tier reads
+`delivery.epicAudit.autoFixSeverity` (default **`high`**) and routes only
+🔴 Critical + 🟠 High lens findings into on-branch remediation while 🟡 Medium
+and 🟢 Suggestion findings graduate (🟡 Medium concerns are already remediated
+shift-left); setting `medium` opts back into routing 🔴/🟠/🟡.
+
 - **Selector reports `degraded: true`** — STOP. Propagate the
   `reason`/`detail`, post a friction comment, do not fall back to a
   full-roster audit.
-- **`selectedAudits` is empty** (docs-only change set) — log the
-  short-circuit and continue to Phase 5.
+- **`epicCloseLenses` is empty** (docs-only change set, or every selected lens
+  already covered shift-left, and no risk-routed lens) — there is no lens
+  dimension for Phase 5 to walk; continue to Phase 5, which still runs its
+  review pillars.
 
 ---
 
-## Phase 5 — Code review
+## Phase 5 — Code review (cumulative diff walked once)
 
 Skip when `--skip-code-review`. Otherwise resolve the **risk-derived review
 depth** for this Epic, then auto-invoke
 [`helpers/code-review.md`](code-review.md) inline (read-only audit)
 with the argument envelope `{ scope: 'epic', ticketId: <epicId>, baseRef:
-'main', headRef: 'epic/<epicId>', depth: <reviewDepth> }`. The helper
-persists findings as a `code-review` structured comment on the Epic.
+'main', headRef: 'epic/<epicId>', depth: <reviewDepth> }`, threading the
+Phase 4 `epicCloseLenses` roster through. The pass walks the cumulative
+`main..epic/<epicId>` diff **once**: it executes the Epic-close lens roster as
+review dimensions (helper Step 1b) **and** the review pillars, folding both
+into a single aggregate. Findings persist as the unified `verification-results`
+structured comment on the Epic (the single findings surface — Story #4411
+unified the former `code-review` and `audit-results` contracts, and Story #4412
+folded the lens walk into this pass).
 
 The `depth` is the live epic-scope producer for Story #3876's review-depth
 lever (Story #3937). Resolve it from the Epic's judged risk envelope the same
@@ -533,8 +570,20 @@ emit so a high-risk Epic gets a deeper adversarial pass and a low-risk one a
 lighter one. Depth is **input-only** — it never changes the findings envelope
 or the posted comment shape.
 
-- **Any 🔴 Critical Blocker** — STOP. Relay to the operator.
-- **Only 🟠/🟡/🟢** — log as non-blocking and continue.
+Remediation in this pass is **tier-aware and split by finding class**
+(Story #4412). The **review-pillar** findings (Pillars 1–4) route off
+`delivery.codeReview.autoFixSeverity` (default **`medium`** — 🔴/🟠/🟡
+on-branch, Mediums batched per lens, 🟢 stays on the comment). The **Epic-close
+lens** findings (Step 1b) route off `delivery.epicAudit.autoFixSeverity`
+(default **`high`** — only 🔴/🟠 on-branch; 🟡 Medium + 🟢 graduate, because
+🟡 Medium concerns were already remediated shift-left). Setting either key to
+its other value re-widens or narrows that class. Remediated findings are
+rendered under the single `verification-results` comment's `## Fixed on-branch`
+section so they never graduate to follow-up issues. The severity gate below is
+**unchanged** — it keys off the surviving (unfixed) findings.
+
+- **Any surviving 🔴 Critical Blocker** — STOP. Relay to the operator.
+- **Only 🟠/🟡/🟢 surviving** — log as non-blocking and continue.
 
 ---
 
@@ -565,6 +614,23 @@ the GitHub upsert succeeds, the retro body is also **mirrored locally** to
 `epicRetroMirrorPath`). GitHub remains the source of truth — a
 mirror-write failure only logs a warn and never fails the phase.
 
+**Auto-file routed proposals (Story #4418).** Between gathering the retro
+signals and composing the body, the runner files the retro's **actionable
+routed proposals** (the `framework` / `consumer` friction categories that
+recurred ≥ 2× or were force-flagged by an unresolved `agent::blocked`) as
+GitHub follow-up issues via the graduator pre-parsed-findings seam
+([`retro-proposals-graduator.js`](../../scripts/lib/feedback-loop/retro-proposals-graduator.js)).
+Each filed issue carries `meta::<framework-gap|consumer-improvement>` +
+`friction::<category>` labels — the join key `/plan` Phase 0's
+prior-feedback fetcher reads back — and the rendered retro sections then
+list the **real filed issue numbers** instead of paste-ready `gh issue
+create` command stanzas. Filing is idempotent (a content-hash marker probe
+skips already-filed categories) and respects the graduator per-run filing
+cap. The beat runs behind `delivery.feedbackLoop.retroProposals` (default
+**ON**); set it to `false` to suppress auto-filing and fall back to the
+command stanzas. Filing never fails the phase — a filing error degrades to
+the command stanzas.
+
 ---
 
 ## Phase 6.5 — Post-wave integration gate (Epic #4131, F1/F4)
@@ -720,13 +786,36 @@ run. Passing `--epic <epicId>` scopes the red-path failure digest to
 ## Phase 8.5 — Auto-merge gate
 
 After Phase 8 exits 0, evaluate the auto-merge predicate by emitting
-`epic.automerge.start`:
+`epic.automerge.start`. When this `/deliver` run was invoked with `--yes`,
+add `--headless true` so the downstream `MergeWatcher` engages the
+must-land terminal step (Story #4427, § Arguments above); omit the flag
+(or pass `--headless false`) for an attended run:
 
 ```bash
 node .agents/scripts/lifecycle-emit.js --epic <epicId> \
-  --event epic.automerge.start --pr-url <prUrl>
+  --event epic.automerge.start --pr-url <prUrl> [--headless true]
 ```
 
+**Must-land terminal step (headless only).** `MergeWatcher` polls
+`epic.merge.armed` to confirmation as usual. If its poll budget is
+exhausted, a headless (`--headless true`) run does not exit silently —
+it classifies the block (`classifyMergeBlock`, the shared classifier
+from Story #4426) and applies one bounded retry before giving up:
+
+- `checks-pending-timeout` (required checks still progressing) — extend
+  the watch budget once and keep polling.
+- `api-race-other` (no definitive block signal) — re-arm once by
+  re-emitting `epic.merge.ready` on the bus (never a direct `gh pr merge`
+  call — `AutomergeArmer` remains the sole authorized call site).
+- `branch-protection-human-required`, or both bounded retries already
+  spent — terminal: emit `merge.unlanded` (`scope: "epic"`, carrying the
+  block class) and fall through to the existing single `epic.blocked`
+  emit — one blocked path, never a duplicate `agent::blocked` transition.
+
+Attended runs (no `--headless` flag) keep today's exact behavior: budget
+exhaustion emits `epic.blocked` immediately, with no classification, no
+retry, and no `merge.unlanded`.
+
 `AutomergePredicate` first runs a **live `gh pr checks --required` probe**
 (Story #4361): green required CI is the arming signal, so if any required
 check is red, pending, or the probe is unreadable it emits

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

@@ -336,6 +336,32 @@ auto-merge. Report its one-line result in the summary. Merged Story branches
 themselves are reaped by the boot sweep at the next `/plan` / `/deliver` boot —
 see [`.agents/rules/git-conventions.md` § Local checkout hygiene](../../rules/git-conventions.md).
 
+### Feedback rollup
+
+Then run the **end-of-run feedback rollup** over the delivered Story set so
+the write-only standalone signals tree finally has a consumer. Each per-Story
+sub-agent appends `friction` records to its standalone stream
+(`temp/standalone/stories/story-<sid>/signals.ndjson`); the rollup scans those
+streams and aggregates friction by category:
+
+```bash
+node .agents/scripts/standalone-feedback-rollup.js --stories <all delivered story ids, comma-separated>
+```
+
+The CLI prints one JSON object
+(`{ kind, stories, totalFriction, byCategory, perStory }`) and **always exits
+0** — missing or empty streams degrade to an empty summary, so this beat never
+fails the run. Surface `totalFriction` and the `byCategory` totals in the run
+summary so the operator sees where friction clustered across the delivery:
+
+```text
+Feedback rollup — 4 friction signals across 3 Stories
+  Execution Error: 2, Tool Limitation: 1, Missing Skill: 1
+```
+
+When `totalFriction` is 0 (or every stream was missing), report a single
+"no friction signals recorded" line and move on — it is not an error.
+
 When some Stories are blocked or failed, list them explicitly with the
 `blockerCommentId` or failure detail so the operator knows where to look.