mandrel 1.88.0 → 1.90.0

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -34,6 +34,7 @@ allowed_tools:
 
 - Run only during `/plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
 - Write exactly three artifacts and only inside `temp/epic-<Epic_ID>/`: `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All three MUST exist on disk before returning.
+- **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the Phase 7 persist call rejecting an artifact (e.g. a missing `## Delivery Slicing` heading, a schema-invalid risk verdict) — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/` artifact that fix only what the rejection named; do NOT rewrite an artifact wholesale from a blank draft. `helpers/plan-epic.md` bounds this to **one refinement pass** per invocation (the same shape as the Epic Clarity Gate's own "one refinement pass per invocation" contract) — do not loop.
 - Start each markdown artifact at the correct `##` heading (Tech Spec → `## Delivery Slicing`, Acceptance Spec → `## Acceptance Table` — never the Epic's own `## Acceptance Criteria` heading, which stays the ideation bullets) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
 - The Tech Spec MUST open with `## Delivery Slicing` and MUST NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is duplication and a drift risk. A `## Technical Overview` section is optional and, when present, is a 2–3 sentence orientation of the *technical approach* only (which subsystems are touched and reused), never a re-narration of the problem statement, goals, or scope.
 - Judge risk from what the change *does* (the Epic body / Tech Spec you just wrote), never from keyword presence — "out of scope: billing" is not a billing change; "rotate the credential vault" is high-risk even without a security keyword.
@@ -75,15 +76,24 @@ reads:
   Fields:
   - `epic.id`, `epic.title`, `epic.body` (or `epic.bodySummary` when the
     planning-context budget downgrades the body to a summary)
-  - `docsContext.items[]` — bounded project docs scraped from the configured
-    `docsRoot` (start with these for "how does the codebase do X today?"
-    context; the validator already capped their size)
+  - `docsContext` — digest-first (Story #4433, hard cutover of the § 3.1
+    planning read contract): `{ mode: 'digest', digestPath }` pointing at
+    the per-Epic docs digest (`<tempRoot>/epic-<Epic_ID>/docs-digest.md` —
+    the same file the `/deliver` story sub-agents already consume, Story
+    #4338 / #4324), or `null` when `project.docsContextFiles` is unset. Read
+    the digest at `digestPath` for "how does the codebase do X today?"
+    orientation (path, byte size, heading outline with line numbers, first
+    paragraph per `##` section), then pull the full file on demand with your
+    own Read tool — jump straight to the line the digest names — only when a
+    section bears on the spec. There is no full-content `items[]` field;
+    embedding whole/summarized doc bodies in this envelope was retired in
+    the same cutover that made the `/deliver` children digest-first.
   - `codebaseSnapshot` — Story #2634 structural view of the consumer repo
     (file tree, `package.json` exports + scripts, recently-touched
     directories, detected test runner + BDD feature roots, and — at the
     `medium` tier — per-file export signatures). Prefer module / file
     names that appear in this snapshot over names that appear only in
-    `docsContext.items[]`; the docs may be stale relative to the actual
+    the docs digest; the docs may be stale relative to the actual
     source tree. When the spec needs to cite a file that is **not** in
     `codebaseSnapshot.files`, surface that as a `<!-- DRIFT -->` callout
     in the Tech Spec body naming the cited path, so the freshness gate
@@ -151,13 +161,16 @@ or (for the verdict) schema-invalid.
 
 Read `temp/epic-<Epic_ID>/planner-context.json` with the `Read` tool. Pull
 the Epic title, body (or body summary, including the Epic's `## User Stories`
-section), the `docsContext` items, and (for reference) the two system prompts.
+section), and the `docsContext` digest pointer (`digestPath`, or `null`).
+When non-null, read the digest file at `digestPath` next — that outline,
+not the planner-context envelope, is where the actual doc orientation
+lives; pull a full doc on demand only when a section looks relevant.
 
 ### Step 2 — Author the Tech Spec (Engineering Architect persona)
 
 Apply the Tech Spec system prompt below to the Epic body (Context / Goal /
-Scope / User Stories), the
-`docsContext` items, and the `codebaseSnapshot` envelope (so the spec is
+Scope / User Stories), the docs digest (plus any full file pulled on
+demand), and the `codebaseSnapshot` envelope (so the spec is
 grounded in the actual codebase, not hallucinated patterns). Cite module
 and file names from `codebaseSnapshot.files` / `codebaseSnapshot.signatures`
 before reaching for names that appear only in the documentation. Write to

package/.agents/skills/core/scope-triage/SKILL.md

@@ -86,6 +86,67 @@ or a small Epic, and neither call is clearly right. **Present the choice rather
 than deciding for the operator.** Do not force a verdict to avoid the third
 option; a borderline scope surfaced as borderline is the correct output.
 
+## Change-Request Triage Rubric
+
+A **change request** — "fix this", "tweak that", "extend the existing X" —
+is the common case this rubric routes cheaply: a delta against a surface the
+project already shipped, not a from-scratch capability. Route it to `story`
+by default when all three delta signals hold; treat any one signal's absence
+as a prompt to re-check, not an automatic `epic` bump.
+
+### Delta signals
+
+- **Delta to an already-delivered surface.** The request references a
+  concrete existing capability (a module, workflow, script, or shipped
+  feature) rather than proposing a new one. "Fix the flaky retry in
+  `evidence-gate.js`" is a delta; "add a retry framework" is not.
+- **Existing corpus covers the touched area.** The project's docs digest
+  and/or an already-closed or in-flight Epic's Tech Spec section already
+  describe the surface being changed — the standalone-Story path can draft
+  against that inherited context (`corpusContext` in the `/plan --idea`
+  envelope) instead of re-deriving architecture from a blank slate. When no
+  corpus hit exists for the touched area, that is a signal the request may
+  be reaching into genuinely new territory — re-check the `epic` signals
+  below before defaulting to `story`.
+- **Footprint fits Story sizing.** The plausible file footprint and
+  acceptance-criteria count still fit the Story width in
+  `DEFAULT_TASK_SIZING` (per the `story` verdict signals above) — a change
+  request that fans out across independent subsystems is sized like an Epic
+  regardless of how small the originating request sounded.
+
+### Story-verdict rationale template
+
+Use this template to record the verdict — it names which delta signal
+carried the call, so a reviewer can sanity-check the routing decision without
+re-deriving it:
+
+```text
+Verdict: story
+Delta: <the existing surface this change targets>
+Corpus hit: <docs digest section / Epic # and Tech Spec excerpt that covers
+  this area, or "none — re-checked epic signals, still story-sized">
+Footprint: <rough file/AC count vs DEFAULT_TASK_SIZING>
+```
+
+### Worked example
+
+> Request: "The `/plan` standalone-Story path always drafts from a blank
+> slate even when a change request is a small delta against something we
+> already shipped — thread the existing docs digest and matching Epic
+> Tech Spec sections into the draft context."
+>
+> ```text
+> Verdict: story
+> Delta: story-plan.js's --emit-context envelope and the plan-story.md
+>   Phase 2 drafting instructions — both already exist and ship today.
+> Corpus hit: Epic #4429's own Tech Spec section (this rubric's parent
+>   Epic) already describes the docs-digest reuse pattern from
+>   orchestration/docs-digest.js.
+> Footprint: one new lib module (planning-corpus.js), one envelope field,
+>   one helper-doc instruction — comfortably inside DEFAULT_TASK_SIZING's
+>   softFiles/softAcceptanceCount band.
+> ```
+
 ## Handoff & no-re-triage rule
 
 A workflow entered via a scope-triage **handoff** MUST NOT re-triage. A handoff

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-08T12:24:41.101Z",
+  "generatedAt": "2026-07-11T11:32:48.235Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -138,7 +138,7 @@
       "category": "core",
       "path": ".agents/skills/core/epic-plan-decompose-author/SKILL.md",
       "description": "Author the Story ticket JSON for an Epic from the decomposer authoring context emitted by `epic-plan-decompose.js --emit-context`. Use during Phase 8 of `/plan` when the host LLM needs to write the ticket array before `epic-plan-decompose.js` validates and persists it.",
-      "policyCapsuleBullets": 14,
+      "policyCapsuleBullets": 15,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
@@ -158,7 +158,7 @@
       "category": "core",
       "path": ".agents/skills/core/epic-plan-spec-author/SKILL.md",
       "description": "Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON for an Epic from the planner authoring context emitted by `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when the host LLM needs to write the three artifacts before `epic-plan-spec.js` folds them into the Epic body's managed sections.",
-      "policyCapsuleBullets": 13,
+      "policyCapsuleBullets": 14,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },

package/.agents/workflows/audit-documentation.md

@@ -135,6 +135,7 @@ node .agents/scripts/check-lifecycle-doc-drift.js
 node .agents/scripts/generate-config-docs.js --check
 node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
+node .agents/scripts/resolve-doc-tiers.js --json
 ```
 
 Fold the results in as findings:
@@ -148,6 +149,13 @@ Fold the results in as findings:
   remediation is "rerun `npm run docs:gen` / `npm run sync:commands` and
   commit the regenerated output".
 
+The **read-tier map** — `resolve-doc-tiers.js --json` — is not itself a
+finding. It emits `{ tiers: { alwaysLoaded, mandatoryRead, digestVisible,
+onDemand } }`, each a `[{ path, bytes }]` list classifying every doc by how
+often it is loaded into agent context. Hold that map for the Context Economy
+severity-weighting rule (Step 2.5) — it decides how much a Context-Economy
+finding's location amplifies its cost.
+
 This lens orchestrates the existing checkers only; it does not add new
 deterministic checker scripts.
 
@@ -182,6 +190,56 @@ works (wrong command, deleted script, contract mismatch); **Medium** =
 materially outdated description or missing coverage of a major surface;
 **Low** = cosmetic drift, stale examples, tone/format inconsistencies.
 
+## Step 2.5: Context Economy
+
+Steps 1–2 verify the docs are **accurate**. This step verifies they are
+**economical** — that a doc still earns the context every reader (human or
+agent) pays to load it. A doc can be entirely accurate and still cost far
+more than it returns: it accretes finished-work history, states the same fact
+two incompatible ways, or claims an authority the code has outgrown. Flag
+these under the three Context Economy categories below. Each carries a
+recognition heuristic — a shape you can spot from the prose itself.
+
+- **History Bloat:** the doc carries verbatim finished-work history that
+  crowds out its live guidance — fully-checked (all-`[x]`) checklists,
+  step-by-step phase / rollout logs, and past-tense "shipped" / "completed"
+  narratives no reader acts on anymore. Recognition: a section whose every
+  checkbox is ticked, or a changelog / decision run whose historical rows
+  dwarf the live ones. **Remediation:** apply the documentation-and-adrs
+  [Pruning & Archiving](../skills/core/documentation-and-adrs/SKILL.md#pruning--archiving)
+  convention — lift any still-live gotcha into the live doc **first**, then
+  **archive, don't delete**: relocate the verbatim history to a dated
+  `docs/archive/<name>-<YYYY-MM>.md`, collapse each completed checklist to a
+  one-line outcome, and leave a one-line pointer behind. Never prune ADRs by
+  archiving — supersede them in place.
+- **Contradiction:** the doc states the same fact two incompatible ways, so a
+  reader cannot tell which is current. Recognition: a footnote- or
+  parenthetical-corrected table cell (a value carrying an inline `(now X)` /
+  `~~old~~` correction), or two prose statements that assert different values
+  for the same command, path, count, or contract. **Remediation:** collapse
+  to the single verified-current statement and delete the stale twin.
+- **Authority Drift:** the doc is crowned the source of truth for a surface
+  the verified code has since outgrown — the prose still presents itself as
+  canonical, but the implementation is now the real authority. Recognition: a
+  doc that declares itself SSOT / "canonical" / "single source of truth" for
+  a contract whose current shape you had to read the code to confirm, because
+  the doc no longer matches it. **Remediation:** either re-sync the doc to the
+  code and keep the SSOT claim, or demote the claim and point at the code as
+  the authority.
+
+### Read-tier severity weighting
+
+A Context-Economy finding's cost scales with how often the doc is actually
+read. Step 1 ran `resolve-doc-tiers.js --json`, which classifies every
+target-set doc into a read tier (`alwaysLoaded`, `mandatoryRead`,
+`digestVisible`, `onDemand`). **A finding whose doc falls in the
+`alwaysLoaded` or `mandatoryRead` tier escalates one severity band**
+(Low→Medium, Medium→High): bloat, contradiction, or drift in a doc every task
+loads costs far more than the same defect in an on-demand reference. Apply the
+escalation **after** assigning the base severity from the Step 2 guidance, and
+name the doc's tier in the finding's Current State so the escalation is
+auditable.
+
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
@@ -208,8 +266,8 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
 
 ### [Short Title of the Issue]
 
-- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity]
-- **Impact:** [High | Medium | Low]
+- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity | History Bloat | Contradiction | Authority Drift]
+- **Impact:** [High | Medium | Low] — for a Context Economy finding, this is the base severity **after** any read-tier escalation (Step 2.5); state the doc's tier in Current State.
 - **Current State:** [The doc, the exact claim, and what the code actually
   does — cite file paths and lines on both sides]
 - **Recommendation & Rationale:** [The specific doc edit (or generator
@@ -218,6 +276,28 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
   `[A copy-pasteable, highly specific prompt to execute this doc fix independently]`
 ```
 
+## Periodic full-scope sweep
+
+Context Economy findings accrete slowly — a doc that is lean today grows a
+bloated tail over many Epics, and no single change-set-scoped `/deliver`
+Phase 4 run sees the whole picture. Run this lens **full-scope** on a
+recurring cadence so the drift is caught before it compounds:
+
+- **Cron loop** — [`loops:nightly-audit`](loops/nightly-audit.md)
+  runs the audit sweep unattended each night; the host (`/schedule` or a
+  cron-driven `/loop`) owns the cadence. Point it at this lens full-scope
+  (no `--paths`, no change-set filter — the `{{changedFiles}}` block renders
+  the literal token, so the whole target-set union is audited).
+- **Scheduled invocation** — `/schedule` running `/audit-documentation`
+  full-scope on a daily/weekly cron is the equivalent one-shot form when a
+  standing loop is not wired up.
+
+Route the resulting `audit-documentation-results.md` through
+[`/audit-to-stories`](audit-to-stories.md), which groups the findings,
+deduplicates them against existing Issues by fingerprint, and opens
+remediation Stories (or chains into `/plan --idea`) so the Context-Economy
+findings land as actionable, tracked work rather than a report nobody reads.
+
 ## Constraint
 
 This workflow is **read-only** with respect to the repository: run the

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
@@ -299,7 +371,8 @@ 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
-[`code-review` graduator](../../scripts/lib/feedback-loop/code-review-graduator.js)
+[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
@@ -322,8 +395,8 @@ their leading severity emoji so the graduator still files them.
 
 There is **no runtime auto-fix function** at this phase. The host LLM is
 the executor: it decides, per finding, between a focused fix on
-`[HEAD_REF]` and leaving the finding on the `code-review` structured
-comment for the operator.
+`[HEAD_REF]` and leaving the finding on the `verification-results`
+structured comment for the operator.
 
 ### Resolve the remediation threshold (Story #4399)
 
@@ -348,7 +421,7 @@ 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
-`code-review` structured comment authoritative for anything not fixed
+`verification-results` structured comment authoritative for anything not fixed
 in-place.
 
 1. **Apply a focused fix on `[HEAD_REF]`.** Permitted only when the
@@ -401,8 +474,8 @@ ceremony above:
    findings stay on the comment for Step 5.
 
 Record every remediated finding (🟠 or 🟡) in the **"Fixed on-branch"**
-section of the `code-review` comment (Step 4) so it does not graduate to a
-follow-up issue.
+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 (or per batched finding) before
@@ -413,18 +486,18 @@ 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:
@@ -445,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
@@ -459,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