mandrel 1.87.0 → 1.89.0

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

@@ -1,44 +1,53 @@
 ---
 description: >-
-  Run smart change-set audits at Epic finalize. Consumes the epic-audit-prepare
-  envelope, dispatches each selected lens (inline, or via a single
-  audit-orchestrator sub-agent that fans the lenses out as parallel level-2
-  agents) through runAuditSuite, and posts an audit-results structured comment
-  back onto the Epic ticket.
+  Resolve the slim Epic-close (gate3) lens roster for /deliver. Consumes the
+  epic-audit-prepare envelope, restricts it to the cumulative + global +
+  risk-routed lenses the Epic-close tier owns, and hands that roster to the
+  Phase 5 code-review pass — which walks the cumulative Epic diff once and folds
+  the lens findings into its single verification-results comment.
 ---
 
-# Epic Audit (helper)
+# Epic-close lens roster (helper)
 
 > **Helper module.** Not a slash command. Invoked automatically from
 > `/deliver` Phase 4 once the wave loop completes (all Stories at
-> `agent::done`). To run an audit directly, use `/deliver [Epic_ID]` — it
-> delegates here (or pass `--skip-epic-audit` to bypass).
+> `agent::done`) to resolve the Epic-close lens roster that the Phase 5
+> code-review pass walks. To run delivery, use `/deliver [Epic_ID]` (or pass
+> `--skip-epic-audit` to bypass the Epic-close lens tier).
+
+This helper resolves the **change-set-aware Epic-close lens roster** for an
+Epic branch. Under the three-tier verification model (Epic #4405) it does
+**not** run a standalone lens walk of its own and does **not** post its own
+structured comment. It selects the slim roster and hands it to the Phase 5
+[`code-review.md`](code-review.md) pass, which walks the cumulative Epic diff
+**once** — executing these lenses as review dimensions — and folds their
+findings into the single `verification-results` comment it posts on the Epic.
+
+> **Three-tier model — where each lens concern is verified.** A lens's `scope`
+> field in [`audit-rules.json`](../../schemas/audit-rules.json) (resolved by
+> [`resolveLensTier`](../../scripts/lib/audit-suite/selector.js)) decides the
+> **one** tier that owns its concern:
+>
+> - **`local`** — decidable from a single Story's diff. Verified **write-time**
+>   (the distilled checklist threaded into the Story implementation prompt,
+>   Story #4410) and at **Story-scope** (the maker-blind local-lens pass in
+>   `story-close`, Story #4409). **Not** re-run at Epic close.
+> - **`cumulative`** — only decidable across the Epic's combined diff. Verified
+>   at **Epic close** only.
+> - **`global`** — evaluates a whole-product property regardless of the diff
+>   (exempt from the cross-epic-leak change-set narrowing). Verified at **Epic
+>   close** only.
+>
+> No lens concern is verified at more than one tier: the Epic-close roster
+> below deliberately **excludes every local-tier change-set lens** and keeps
+> only cumulative + global + risk-routed lenses.
 
-This helper runs the **change-set-aware audit pass** on an Epic branch
-before the code-review helper opens its review. Unlike code-review (which
-walks the full diff against `main` through six fixed pillars), epic-audit
-asks the [`selectAudits`](../../scripts/lib/audit-suite/index.js) SDK which
-lenses are actually relevant to **this** Epic's change set, then dispatches
-only the matching audit workflows. Docs-only Epics select zero lenses and
-exit cleanly.
+**When to run**: After Phase 3 close-validation passes, to resolve the roster
+the Phase 5 code-review pass consumes. `/deliver` invokes this automatically
+once the wave loop completes and all Stories reach `agent::done`.
 
-In addition to the change-set selection, `epic-audit-prepare.js` unions in
-the **risk-routed lenses** (Story #3889): it reads the Epic's model-judged
-`planningRisk` envelope off the `epic-plan-state` checkpoint and routes each
-high-risk axis to its mapped lens via
-[`resolveAuditLenses`](../../scripts/lib/orchestration/code-review.js)
-(`security` → `audit-security`, `public-api` → `audit-architecture`). A
-high-risk Epic therefore auto-runs its mapped lenses even when the change
-set alone did not select them; a low-risk Epic adds nothing beyond the
-change-set selection. Both lens sources fire through the **same**
-`runAuditSuite` dispatch below — no new audit machinery.
-
-> **When to run**: After Phase 3 close-validation passes and before Phase 5
-> code-review. `/deliver` invokes this automatically once the wave loop
-> completes and all Stories reach `agent::done`.
->
-> **Persona**: `architect` · **Skills**: `core/code-review-and-quality`,
-> `core/security-and-hardening`
+**Persona**: `architect` · **Skills**: `core/code-review-and-quality`,
+`core/security-and-hardening`
 
 ## Step 0 — Resolve Context
 
@@ -53,14 +62,13 @@ change-set selection. Both lens sources fire through the **same**
    - **Tech Spec** — the folded Tech Spec sections (opening with
      `## Delivery Slicing`) inside the body's managed region.
 5. Read the Epic body fully (including its Tech Spec sections) to
-   understand the intended
-   scope, selected lenses, and acceptance criteria.
+   understand the intended scope, selected lenses, and acceptance criteria.
 
 ## Step 1 — Prepare (`epic-audit-prepare.js`)
 
 Run the prepare CLI to compute the change-set, ask `selectAudits` which
-lenses fire at `gate3` (the Epic close gate), and emit the helper-consumable
-JSON envelope on stdout:
+lenses fire at `gate3` (the Epic close gate), union in the model-judged
+risk-routed lenses, and emit the helper-consumable JSON envelope on stdout:
 
 ```bash
 node .agents/scripts/epic-audit-prepare.js \
@@ -76,55 +84,54 @@ envelope:
   "epicId": 2586,
   "epicBranch": "epic/2586",
   "depth": "deep",
-  "selectedAudits": ["audit-security", "audit-privacy"],
-  "changeSetAudits": ["audit-privacy"],
+  "selectedAudits": ["audit-security", "audit-architecture", "audit-privacy"],
+  "epicCloseLenses": ["audit-architecture", "audit-security"],
+  "changeSetAudits": ["audit-architecture", "audit-privacy"],
   "riskRoutedAudits": ["audit-security"],
+  "globalLenses": [],
   "changedFiles": ["src/api/admin/users.ts", "..."],
   "changedFilesCount": 47,
   "substitutionsPayload": "src/api/admin/users.ts\n..."
 }
 ```
 
-`selectedAudits` is the de-duplicated **union** of `changeSetAudits` (the
-change-set selection) and `riskRoutedAudits` (the model-judged risk-routed
-lenses). The two source arrays are surfaced for observability so the
-operator can see why each lens fired. Dispatch the `selectedAudits` union
-in Step 2.
+- **`epicCloseLenses` is the roster you hand to Phase 5.** It is the slim
+  Epic-close roster — `selectedAudits` restricted to the tiers the Epic-close
+  tier owns via
+  [`selectEpicCloseLenses`](../../scripts/lib/orchestration/code-review.js):
+  every **cumulative** and **global** change-set lens, plus every **risk-routed**
+  lens, with every **local-tier** change-set lens dropped (its concern is
+  already verified shift-left). In the example above `audit-privacy` (local) is
+  excluded from `epicCloseLenses` while `audit-architecture` (cumulative) is
+  kept and `audit-security` (risk-routed) is kept.
+- **`selectedAudits` / `changeSetAudits` / `riskRoutedAudits`** are surfaced for
+  observability so the operator can see the pre-slim union and why each lens
+  fired. Do **not** walk `selectedAudits` — walk `epicCloseLenses`.
+- **`globalLenses`** is the subset of the roster on the global-lens allowlist
+  (e.g. `audit-navigability`) that the Phase 5 walk runs against the WHOLE
+  route tree, exempt from the cross-epic-leak guard's change-set narrowing
+  (Epic #4131, F2).
 
 ### The `depth` field (Story #3939)
 
 `depth` is `light`, `standard`, or `deep` — an **orthogonal** signal that
-tells you how thorough each **selected** lens should be on this Epic. It is
-resolved by the shared `resolveDepth` resolver from the Epic's model-judged
-risk envelope (`overallLevel` off the `epic-plan-state` checkpoint) folded
-with `changedFilesCount`: a high-risk **or** wide-footprint Epic resolves to
-`deep`, a low-risk small one to `light`, and everything else — including an
-Epic that skipped `/plan` and has no checkpoint — to `standard`.
-
-Depth changes **how deeply** each lens runs, never **which** lenses fire:
-
-- **`light`** — run each selected lens against the **changed surface only**
-  and report **only Critical/High** findings. Skip the Medium/Suggestion
-  sweep. Light **never skips a selected lens** — including the alwaysRun
-  floor (`audit-clean-code`, `audit-architecture`) — it only **shrinks the
-  selected lens's sweep**. An easy, low-risk Epic still runs its audits;
-  they just run lighter.
-- **`standard`** — today's behavior: walk each selected lens's full
-  procedure over the changed surface at every severity.
-- **`deep`** — run the full lens procedure over the changed surface **plus
-  the modules it directly touches**, at every severity.
-
-Depth never changes the severity taxonomy, the findings-report shape, or the
-Phase 4 halting rule below (a 🔴 Critical Blocker halts at every depth;
-everything else logs). Thread the resolved `depth` into each lens walk in
-Step 2 — it scopes the sweep, it does not gate the roster.
+tells the Phase 5 pass how thorough each **rostered** lens should be on this
+Epic. It is resolved by the shared `resolveDepth` resolver from the Epic's
+model-judged risk envelope (`overallLevel` off the `epic-plan-state`
+checkpoint) folded with `changedFilesCount`: a high-risk **or** wide-footprint
+Epic resolves to `deep`, a low-risk small one to `light`, and everything else
+— including an Epic that skipped `/plan` and has no checkpoint — to `standard`.
+Depth changes **how deeply** each lens runs, never **which** lenses fire.
 
 ### Outcomes
 
-- **`selectedAudits` is non-empty** — continue to Step 2.
-- **`selectedAudits` is empty** (docs-only or no-lens change set, and no
-  high-risk axis routed a lens) — skip Step 2 and write the docs-only
-  marker described in Step 4.
+- **`epicCloseLenses` is non-empty** — pass the roster (and `depth`,
+  `globalLenses`, `substitutionsPayload`) to the Phase 5 code-review pass.
+- **`epicCloseLenses` is empty** (docs-only change set, or every selected lens
+  was a local-tier change-set lens already covered shift-left, and no high-risk
+  axis routed a lens) — there is no Epic-close lens dimension to walk; the
+  Phase 5 pass still runs its review pillars and posts the
+  `verification-results` comment.
 - **`degraded: true`** — the selector aborted. Possible `reason` codes:
   `GIT_DIFF_TIMEOUT` (git-diff timed out), `HEAD_REF_UNRESOLVED` (the
   Epic's branch `refs/heads/epic/<id>` is not present in this checkout),
@@ -135,222 +142,48 @@ Step 2 — it scopes the sweep, it does not gate the roster.
   roster — that defeats the change-set scoping, and an unresolved/mismatched
   ref means the change set would belong to the wrong Epic.
 
-## Step 2 — Walk Selected Lenses (`runAuditSuite`)
-
-> **Execution model — the host LLM is the executor, not the CLI.**
-> `run-audit-suite.js` is a **prompt-assembly runner**, not a findings
-> generator. It resolves each lens to its workflow markdown, applies
-> the `{{ticketId}}` / `{{baseBranch}}` / `{{changedFiles}}` (and any
-> per-audit) substitutions, and returns one *workflow descriptor* per
-> lens. Its return envelope intentionally carries `findings: []` and
-> `summary: { critical:0, high:0, medium:0, low:0 }` because no lens
-> has been *executed* yet — the host LLM walks each workflow's
-> procedure inline against the substitution payload, severity-rates
-> what it finds, and assembles the aggregate report in Step 4. If you
-> expected `findings[]` to be populated by the CLI, the rest of this
-> helper will surprise you; stop and re-read this paragraph.
-
-For each lens name in `selectedAudits`, invoke
-[`runAuditSuite`](../../scripts/lib/audit-suite/index.js) (or its CLI
-wrapper) with the prepare envelope as the substitution source. The
-runner loads the matching `.agents/workflows/audit-<lens>.md` file,
-applies the substitutions, and — when `--run-id` is supplied — writes
-the substituted body to a per-lens artifact at
-`<auditOutputDir>/audit-<run-id>-<lens>.md` (default `auditOutputDir`
-is `temp/audits/`):
-
-```bash
-node .agents/scripts/run-audit-suite.js \
-  --audits audit-security,audit-privacy \
-  --ticket [EPIC_ID] \
-  --base-branch [BASE_BRANCH] \
-  --substitution changedFiles="[substitutionsPayload]" \
-  --run-id epic-[EPIC_ID]
-```
-
-CLI shape notes:
-
-- `--audits` is **comma-separated**, not space-separated. Passing each
-  lens as a separate positional arg only captures the first one.
-- `--substitution` is **repeatable** (`key=value` per occurrence); the
-  legacy `--substitutions '<json>'` flag is not supported.
-- `--run-id` is the per-lens artifact prefix (the legacy
-  `--artifact-prefix` flag is not supported). When omitted, no
-  artifact is written and the host LLM must walk the workflow body in
-  memory.
-
-After the runner returns:
-
-1. **Read the descriptor stream** — confirm every requested lens
-   appears in `metadata.auditsRun`, then walk each entry in
-   `workflows[]` (or each on-disk artifact when `--run-id` was set).
-2. **Execute the lens inline at the run's `depth`.** Open the lens
-   workflow at `path` (or the per-lens artifact file when `--run-id`
-   produced one) and follow its procedure verbatim against the
-   substituted change set, scoping the sweep to the envelope's `depth`
-   (see "The `depth` field" above): `light` walks the changed surface and
-   reports only 🔴/🟠 findings, `standard` walks the full procedure at
-   every severity, and `deep` extends the sweep to the directly-touched
-   modules. Depth scopes the sweep only — never skip a selected lens.
-   Each lens declares its own pillars, severity rubric, and remediation
-   prose; treat its body as the canonical execution contract for that
-   pass.
-3. **Aggregate** by severity (🔴 Critical Blocker / 🟠 High /
-   🟡 Medium / 🟢 Suggestion). Hold the aggregate for Step 3
-   (auto-fix) and Step 4 (the `audit-results` structured comment).
-
-### Optional: delegate the roster walk to an audit-orchestrator sub-agent
-
-The Step 2 loop above walks the `selectedAudits` roster **serially in the
-host's own context**. When the roster carries more than one lens, `/deliver`
-Phase 4 MAY instead delegate the whole walk to a **single audit-orchestrator
-sub-agent** — one level-1 `Agent` call (`subagent_type: general-purpose`) — that:
-
-1. Receives the **already-selected** `selectedAudits` roster, the run's
-   `depth`, and the prepare envelope's substitution payload. It does **not**
-   re-run `selectAudits` and does **not** widen the roster — the roster is
-   fixed upstream by Step 1 (see the Constraints below).
-2. Fans the roster out as **parallel level-2 agents, one per lens** (nested
-   `Agent` dispatch — verified depth 2, announced max depth 5, per
-   [#2870](https://github.com/dsj1984/mandrel/issues/2870) and the
-   "Flat Story dispatch by design" note in
-   [`deliver-epic.md`](deliver-epic.md)). Each level-2 agent executes exactly
-   one lens's workflow procedure at the run's `depth`, isolated from the main
-   context.
-3. Collects the per-lens findings, **aggregates them by severity** (🔴 / 🟠 /
-   🟡 / 🟢), and returns **only the aggregated audit-results** to the host —
-   the per-lens reasoning transcripts stay in the level-2 leaves and never
-   enter the main context. The host resumes at Step 3 (remediation routing)
-   with the aggregate exactly as if it had walked the roster itself, and Step 4
-   posts the identical `audit-results` comment.
-
-This delegation is a **cross-lens parallelization of the roster walk only**. It
-is orthogonal to — and MUST NOT be conflated with — the *per-lens execution
-strategy*:
-
-- **The per-lens cost/precision gate is preserved.** Each level-2 lens agent
-  still runs its own lens at whatever strategy that lens's cost/precision gate
-  dictates (`docs/roadmap.md` § "The per-lens cost / precision gate"): an
-  orchestrated lens fans its own analysis dimensions out under
-  `runAuditOrchestration`, a sequential-only lens runs turn-by-turn. Fanning
-  the *roster* out in parallel changes **which context** runs a lens, never
-  **how** that lens runs internally, so no per-lens cost gate is bypassed or
-  altered.
-- **The "do not batch-convert the sequential-only lenses" rule is preserved.**
-  The seven sequential-only lenses (`audit-dependencies`, `audit-devops`,
-  `audit-sre`, `audit-privacy`, `audit-seo`, `audit-ux-ui`,
-  `audit-lighthouse`) stay sequential **inside** their level-2 agent.
-  Dispatching them as parallel level-2 agents is **not** a batch-conversion of
-  their internal execution — a sequential-only lens remains sequential-only
-  (`docs/roadmap.md` § "Remaining orchestration surface"). Generalizing any of
-  those lenses to orchestrated is still a separate, gated, lens-by-lens
-  decision that this roster fan-out neither performs nor pre-empts.
-
-Weigh the whole subtree's token cost before delegating
-([`.agents/instructions.md` § 4](../../instructions.md) — cost compounds with
-nesting depth): the level-1 orchestrator plus one level-2 agent per lens
-re-pays the always-loaded context at each level. For a single-lens roster the
-serial host walk is cheaper; the delegation pays off when several lenses fan
-out at once. Either path produces the identical Step 4 `audit-results` comment,
-so the delegation is a performance/context-isolation choice, never a change to
-what gets audited or reported.
-
-If a future Story lifts per-lens execution out of the host-LLM walk
-into the CLI itself, the runner will populate `findings[]` and this
-section will collapse to a "read the structured findings off the
-envelope" bullet. Until then, the host LLM is the gate.
-
-## Step 3 — Remediation Routing (host LLM, no automated loop)
-
-There is **no runtime auto-fix function** at this phase. The host LLM is
-the executor: it inspects the aggregated 🔴 / 🟠 findings from Step 2 and
-either applies a focused fix on the Epic branch or escalates the finding
-to the operator via the `audit-results` comment in Step 4.
-
-For each 🔴 / 🟠 finding, the host LLM MUST decide between two paths:
-
-1. **Apply a focused fix on `[EPIC_BRANCH]`.** Permitted only when the
-   finding is unambiguously *fixable* (clean remediation, no scope creep,
-   no spec deviation, no secret exposure):
-   - Call [`assert-branch.js`](../../scripts/assert-branch.js) with
-     `--expected [EPIC_BRANCH]` before touching the working tree.
-   - Stage explicit paths only (never `git add .`).
-   - Make one focused conventional commit per finding
-     (`fix(<scope>): <description> (audit finding)`).
-   - Re-run the owning lens (re-invoke `run-audit-suite.js` for that
-     single lens) and confirm the finding is gone before moving on.
-   - Run the lens-appropriate validation subset (`npm run lint` plus the
-     relevant `npm test` slice) to confirm the fix did not regress
-     anything.
-   - If the rescan still surfaces the same finding, or validation
-     regresses, **stop fixing** — route the finding to escalation
-     (path 2) and record the attempt context in Step 4.
-2. **Escalate to the operator via Step 4.** Required when the finding
-   falls into any of the following classes:
-   - `spec-deviation` — the change diverges from the Epic/Tech Spec.
-   - `secrets` — credentials, tokens, or PII surfaced in the diff.
-   - `test-deletion` — coverage was removed without an explicit
-     decision in the spec.
-   - `scope-exceeded` — the remediation would touch more files than the
-     change set warrants.
-   - Any finding the host LLM cannot remediate after one focused
-     attempt (the equivalent of the prior loop's
-     `validation-regression` / `thrash-detected` exits).
-
-Do not invent a programmatic retry budget. The host LLM applies *at most
-one* focused-fix attempt per finding before escalating; any further
-remediation is the operator's call after reading the `audit-results`
-comment.
-
-Escalated findings flow through to Step 4 unchanged with their
-escalation reason recorded — the audit pass does not delete them, it
-just stops trying to fix them automatically. Surface the escalation
-reason for each in the `audit-results` comment so the operator sees
-exactly why the finding was not auto-remediated.
-
-## Step 4 — Post `audit-results` Structured Comment
-
-Persist the findings as an `audit-results` structured comment on the Epic
-issue. The comment is idempotent — re-runs replace the prior one. Build the
-body in a temp file under `[TEMP_ROOT]/epic-[EPIC_ID]/audit-results.md`,
-then upsert via [`post-structured-comment.js`](../../scripts/post-structured-comment.js):
-
-```bash
-node .agents/scripts/post-structured-comment.js \
-  --ticket [EPIC_ID] \
-  --marker audit-results \
-  --body-file [TEMP_ROOT]/epic-[EPIC_ID]/audit-results.md
-```
-
-The body MUST include:
-
-- the `selectedAudits` roster (or `Lenses applied: none (docs-only)` when
-  the prepare envelope returned an empty list),
-- the per-severity counts (🔴 critical / 🟠 high / 🟡 medium / 🟢 suggestion),
-- the per-lens findings grouped under the lens name, each carrying file
-  path + line range + pillar + recommended fix,
-- a link to the per-lens artifact files under `<auditOutputDir>` so the
-  operator (and downstream retro) can re-read the full prompt body.
-
-### Severity gating
-
-- **Any 🔴 Critical Blocker** → STOP. Relay to the operator and let
-  `/deliver` Phase 4 record a manual intervention.
-- **Only 🟠/🟡/🟢** → log as non-blocking and return to `/deliver`
-  Phase 5 (code-review).
+## Step 2 — Hand the roster to the Phase 5 code-review pass
+
+The cumulative Epic diff is walked **once** at Epic close. The
+`epicCloseLenses` roster is executed as **dimensions of the Phase 5
+code-review pass** ([`code-review.md`](code-review.md) with `scope: epic`),
+not as a standalone walk here. The Phase 5 pass:
+
+1. Loads each rostered lens's `.agents/workflows/audit-<lens>.md` via
+   [`runAuditSuite`](../../scripts/lib/audit-suite/index.js) (the
+   prompt-assembly runner), applying the `{{changedFiles}}` / `{{ticketId}}` /
+   `{{baseBranch}}` substitutions from this envelope.
+2. Executes each lens inline at the run's `depth` over the cumulative diff,
+   folding its findings into the pass's severity aggregate alongside the review
+   pillars — one walk of `main..epic/<id>`, one aggregate.
+3. Posts the single `verification-results` structured comment (there is **no**
+   separate `audit-results` comment; that producer was retired in Story #4412).
+
+Remediation of the aggregate is **tier-aware** (Story #4412): the Epic-close
+tier reads `delivery.epicAudit.autoFixSeverity` (default **`high`** — see
+[`config/runners.js`](../../scripts/lib/config/runners.js)) and routes only
+🔴 Critical + 🟠 High findings into on-branch remediation; 🟡 Medium and
+🟢 Suggestion findings graduate to follow-up issues, because 🟡 Medium concerns
+are already remediated shift-left at the write-time and Story-scope tiers.
+Setting `medium` opts back into routing 🔴/🟠/🟡 on-branch. The severity gate
+is **unchanged** — a surviving 🔴 Critical Blocker halts the run.
 
 ## Constraints
 
 - **Always** diff against `[BASE_BRANCH]`, not against individual Story
-  branches. The audit examines the cumulative effect of the entire Epic.
-- **Always** read the Epic body and Tech Spec before walking lenses. Findings
+  branches. The Epic-close pass examines the cumulative effect of the entire
+  Epic.
+- **Always** read the Epic body and Tech Spec before the Phase 5 walk. Findings
   without spec context are noise.
-- **Always** cap focused fixes at one attempt per finding (Step 3). The
-  host LLM is the executor; there is no shared retry/anti-thrash module
-  to call. Any finding that does not resolve cleanly on the first attempt
-  routes to escalation in Step 4.
-- **Never** widen the lens roster past `selectedAudits`. The whole point of
-  the change-set selector is to avoid running irrelevant audits on a
-  scoped Epic — running extras defeats the gate.
+- **Never** walk `selectedAudits`. The roster the Phase 5 pass executes is
+  `epicCloseLenses` — the slim cumulative + global + risk-routed set. Walking
+  the pre-slim union re-verifies local-tier concerns already covered
+  shift-left, defeating the three-tier model.
+- **Never** widen the roster past `epicCloseLenses`. The whole point of the
+  change-set selector plus the tier filter is to avoid re-running irrelevant or
+  already-verified lenses on a scoped Epic.
+- **Never** post an `audit-results` structured comment. The Epic-close lens
+  findings are folded into the Phase 5 `verification-results` comment — the
+  single findings surface on the Epic.
 - **Always** propagate `degraded` envelopes verbatim. Do not paper over a
   selector failure with a full-roster fallback.

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

@@ -180,6 +180,20 @@ Run a single Story-implementation phase against the inline `acceptance[]`
    Story's own context points you at one. See
    [`.agents/instructions.md` § 3](../../instructions.md).
 
+   **Write-time audit checklists — read the threaded `checklistPath`.**
+   When the parent prompt passes a `checklistPath` (Story #4410 — the
+   repo-relative path to this Story's footprint-matched **local**-lens
+   authoring checklists at
+   `temp/epic-<epicId>/checklists/story-<storyId>.md`), read it before you
+   write and self-check your change against each listed concern as you
+   author it. These are the local audit lenses whose `filePatterns` matched
+   the Story's predicted footprint, distilled to a short checklist and
+   capped at a hard token budget by `epic-deliver-prepare.js` (matched via
+   `resolveLensTier(lens) === 'local'` + `matchesAnyFilePattern`, never
+   `selectAudits` — no provider or git diff runs on that path). When
+   `checklistPath` is null or absent, the Story's footprint matched no local
+   lens and there is nothing extra to read.
+
 3. Implement the work as one or more commits on `story-<storyId>`.
    Author commits directly with the project's editor / `git commit`,
    following