mandrel 2.7.0 → 2.9.0

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

@@ -5,299 +5,74 @@ description: >-
   `git stash` entries — each step gated by operator confirmation.
 ---
 
-# Git Cleanup Workflow
+# /git-cleanup [--fast-forward-main] [--prune-remotes] [--branches] [--stashes] [--execute] [--remote] [--yes] [--drop-stashes <ref>] [--exclude <pattern>] [--json]
 
-`/git-cleanup` folds the four cleanup steps that operators routinely
-run by hand after a busy session into a single pipeline with per-step
-confirmation:
+`/git-cleanup` folds the four cleanup steps operators routinely run by hand
+after a busy session into a single pipeline with per-step confirmation. It is a
+**recovery tool**, not a routine chore: the delivering flows already reap their
+own merged refs and fast-forward the base branch (see
+[`rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md)).
+Reach for it when the automated hygiene left an unusual state behind.
 
-1. **fast-forward `main`** — `git fetch origin <base>` then
-   `git merge --ff-only origin/<base>` on a clean working tree.
-2. **prune stale remote-tracking refs** — `git fetch --prune origin`
-   to drop `refs/remotes/origin/*` entries that GitHub already deleted.
-3. **reap merged local branches** — the existing squash-aware
-   `gh pr list --state merged` + `git branch --merged <base>` sweep,
-   with attached worktrees removed first. Optionally also deletes the
-   `origin/<branch>` ref when `--remote` is passed. Every default run
-   also **enumerates** `refs/remotes/origin/*` and reports any
-   **remote-only** merged branches — branches whose local ref is
-   already gone (or never existed) but whose `origin/<branch>` still
-   points at a merged PR — even without `--remote`; `--remote` is still
-   required to *delete* them. A third branch, whose content already
-   landed in `<base>` by another route (a squash-merged PR, a
-   cherry-pick, a manual `merge --squash`), is caught by a
-   **content-equivalence probe** (`git merge-tree --write-tree`,
-   git ≥ 2.38) even when it has no merged PR of its own and is not a
-   git ancestor of `<base>`.
-4. **triage `git stash` entries** — list every stash and prompt for
-   `drop / keep / quit` per entry (or pass `--drop-stashes <ref>` for
-   non-interactive use).
-
-The enumeration + reap logic lives in
-[`git-cleanup.js`](../scripts/git-cleanup.js). When no phase flag is
-passed, **all four phases run** sequentially. Pass any of
-`--fast-forward-main`, `--prune-remotes`, `--branches`, `--stashes` to
-narrow the run.
-
-> **When to run**: After a session that landed several PRs, or before
-> starting a new Story, to put the local checkout into a known
-> tidy state.
+> **When to run**: after a session that landed several PRs, or before starting a
+> new Story, to put the local checkout into a known tidy state.
 >
 > **Persona**: `devops-engineer` · **Skills**:
 > `core/git-workflow-and-versioning`
 
-<!-- markdownlint-disable-next-line MD028 -->
+The enumeration + reap logic lives in
+[`git-cleanup.js`](../scripts/git-cleanup.js) — it computes the candidate list,
+the skip taxonomy, the detection signals, and the JSON envelope (add `--json`),
+and prints them itself. Without `--execute` the script is a **dry-run preview**; nothing is
+mutated. When no phase flag is passed, **all four phases run** sequentially; pass
+any of `--fast-forward-main`, `--prune-remotes`, `--branches`, `--stashes` to
+narrow the run. A failure in one phase does not short-circuit the others — each
+runs and reports independently.
+
+## Phases
+
+| Phase | What it does | Safety contract |
+| --- | --- | --- |
+| **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere and does **not** restore the prior branch. |
+| **prune-remotes** | `git fetch --prune origin` to drop `refs/remotes/origin/*` GitHub already deleted. | Prompts before pruning. Runs as its own phase regardless of `--remote`. |
+| **branches** | Reaps merged local branches (squash-aware: merged-PR, git-ancestry, and content-equivalence signals), removing an attached worktree first. Also enumerates **remote-only** merged branches. | Prints the candidate list, then prompts `Reap N merged branch(es)?`. `--remote` is required **on top of** `--execute` to delete any `origin/<branch>`. `content-merged` candidates carry a weaker-signal warning. |
+| **stashes** | Lists every stash and triages it. | Interactive: `drop / keep / quit` per entry (default `keep`). Under `--yes` / `--json`, drops require an explicit `--drop-stashes <ref>` allowlist (repeatable) — there is no "drop all". |
 
-> [!WARNING] The `--execute` flag mutates state: it can fast-forward
-> `main`, delete local branches, delete remote refs (with `--remote`),
-> and drop stashes. Without `--execute` the script is a dry-run preview.
+## Constraint
 
-## Step 1 — Dry-run preview
+> [!WARNING] `--execute` mutates state: it can fast-forward `main`, delete local
+> branches, delete remote refs (with `--remote`), and drop stashes. Without
+> `--execute` the script only previews.
 
-```powershell
-node .agents/scripts/git-cleanup.js
-```
+- **`--execute`** — the master gate. Omit it for a preview of all four phases.
+- **`--remote`** — extends the branches phase to delete the matching
+  `origin/<branch>` ref (and to delete remote-only merged branches). Cannot be
+  undone without re-pushing.
+- **`--yes`** — bypass every per-step prompt (CI / non-interactive). Under it,
+  stash drops still require `--drop-stashes <ref>`.
+- **`--exclude '<pattern>'`** — carve a branch out of the reap. This is the only
+  way to protect an in-scope merged-PR branch you want to keep.
 
-Walks all four phases without mutating anything. The fast-forward phase
-reports whether the tree is clean and how far behind `origin/<base>` the
-local ref is. The branches phase prints the merged-branch candidate
-list. The stashes phase lists every stash with its created-at and
-message.
+Do **not** run with `--execute` if there is unmerged work that needs saving. The
+fast-forward phase skips on a dirty tree (safe), but the branches phase reaps any
+merged-PR branch in scope unless `--exclude`d.
 
-Add `--json` for a structured `{ fastForward, prune, stashes,
-candidates, … }` envelope.
+## Examples
 
-## Step 2 — Run a single phase
+```bash
+# Preview all four phases (no mutation).
+node .agents/scripts/git-cleanup.js
 
-Each phase is independently selectable. Useful when you want to scope
-the cleanup tightly:
+# Run everything non-interactively, including origin refs.
+node .agents/scripts/git-cleanup.js --execute --remote --yes
 
-```powershell
-# Only fast-forward main (skip everything else)
+# Only fast-forward main.
 node .agents/scripts/git-cleanup.js --fast-forward-main --execute
 
-# Only sweep merged branches + their origin refs
+# Only sweep merged branches + their origin refs.
 node .agents/scripts/git-cleanup.js --branches --execute --remote
 
-# Only prune stale tracking refs
-node .agents/scripts/git-cleanup.js --prune-remotes --execute
-```
-
-## Step 3 — Run all four phases
-
-The default. Confirms each destructive step independently:
-
-```powershell
-node .agents/scripts/git-cleanup.js --execute
-```
-
-The script prompts before each mutation:
-
-- **fast-forward-main**: skipped silently when the tree is dirty or the
-  FF would not be a fast-forward; otherwise prompts
-  `Fast-forward main by N commit(s)? [y/N]`.
-- **prune-remotes**: prompts before running
-  `git fetch --prune origin`.
-- **branches**: prints the dry-run candidate list, then prompts
-  `Reap N merged branch(es)? [y/N]`.
-- **stashes**: prompts per-stash with `drop / keep / quit`. A `quit`
-  reply stops the per-stash loop without dropping anything further.
-
-Add `--remote` to also reap `origin/<branch>` during the branches phase.
-
-## Step 4 — Non-interactive / CI
-
-Pass `--yes` to bypass every per-step prompt:
-
-```powershell
-node .agents/scripts/git-cleanup.js --execute --remote --yes
-```
-
-For the stash phase under `--yes` or `--json`, drops require an explicit
-allowlist via `--drop-stashes <ref>` (repeatable). Without that flag,
-stashes are listed but never dropped:
-
-```powershell
+# Drop specific stashes under --yes.
 node .agents/scripts/git-cleanup.js --stashes --execute --yes \
   --drop-stashes 'stash@{0}' --drop-stashes 'stash@{2}'
 ```
-
-This keeps the JSON / CI invocation contract explicit — the operator
-names exactly which stashes to drop, by ref.
-
-## Step 5 — JSON envelope
-
-`--json` emits a single line of structured output suitable for
-programmatic consumption:
-
-```json
-{
-  "dryRun": false,
-  "baseBranch": "main",
-  "fastForward": {
-    "ok": true,
-    "applied": true,
-    "skipped": false,
-    "behind": 2
-  },
-  "prune": {
-    "ok": true,
-    "attempted": true,
-    "remote": "origin",
-    "pruned": ["fix/old"]
-  },
-  "candidates": [
-    {
-      "branch": "fix/foo",
-      "prNumber": 1471,
-      "mergedAt": "2026-05-09T12:00:00Z",
-      "hasWorktree": true,
-      "worktreePath": "C:/repo/.worktrees/fix-foo",
-      "detectedBy": "gh"
-    }
-  ],
-  "skipped": [
-    { "branch": "story-4200", "reason": "not-merged", "lastCommitAt": "2026-05-01T00:00:00Z" }
-  ],
-  "ghDegraded": false,
-  "worktrees": [{ "path": "C:/repo/.worktrees/fix-foo", "ok": true, "dirty": false }],
-  "local":  [{ "branch": "fix/foo", "ok": true, "alreadyGone": false }],
-  "remote": [{ "branch": "fix/foo", "ok": true, "alreadyGone": true }],
-  "stashes": {
-    "ok": true,
-    "actions": [
-      { "ref": "stash@{0}", "action": "drop", "dropped": true }
-    ],
-    "failures": []
-  },
-  "failures": [],
-  "ok": true
-}
-```
-
-## Exit codes
-
-- `0` — clean: dry-run preview, or at least one phase produced work and
-  no phase failed.
-- `1` — at least one phase reported a failure (fast-forward, prune,
-  branch reap, or stash drop). A failure in one phase **does not**
-  short-circuit later phases — each runs and reports independently.
-- `2` — every active phase produced nothing to do (informational; the
-  repo is already tidy).
-
-## Phase-specific behaviour
-
-### fast-forward-main
-
-- Skip reasons surfaced in `fastForward.reason`:
-  - `dirty-tree` — `git status --porcelain` returned non-empty.
-  - `not-fast-forward` — local `<base>` has commits the remote does
-    not (`git rev-list --left-right --count` shows local-ahead > 0).
-  - `already-up-to-date` — local and remote `<base>` point at the same
-    commit.
-  - `fetch-failed` / `merge-failed` — surface git's stderr verbatim.
-- When the current HEAD is not `<base>`, the script runs
-  `git checkout <base>` before merging. The original branch is **not**
-  restored at the end — operators on a feature branch should run
-  `git checkout -` after.
-
-### prune-remotes
-
-Runs as its own phase regardless of whether `--remote` was passed
-during the branches phase. The branches phase still runs its own
-follow-up prune when `--remote` is set, so passing both is idempotent
-(the second prune just reports `pruned: []`).
-
-### branches
-
-The merged-branch sweep recognizes three detection signals, in order:
-
-1. **`detectedBy: 'gh'`** — the branch has a merged PR
-   (`gh pr list --head <branch> --state all`, classified by the
-   **latest** PR's state).
-2. **`detectedBy: 'git-merged'`** — the branch is a git ancestor of
-   `<base>` (`git branch --merged <base>`), or of `origin/<base>` when
-   that remote-tracking ref exists (unioned so a stale local `<base>` —
-   fast-forward phase skipped, or `--branches` run alone — no longer
-   hides a branch already merged on the remote).
-3. **`detectedBy: 'content-merged'`** (Story #4395) — the branch has no
-   reapable PR verdict and is not an ancestor of `<base>` under either
-   anchor, but simulating the merge via
-   `git merge-tree --write-tree <base> <branch>` (git ≥ 2.38) produces a
-   tree identical to `<base>`'s own tree — i.e. applying the branch's
-   changes on top of `<base>` is a content no-op. This catches
-   `story-<id>` branches whose PR **squash-merged** to `main` (the story
-   commits are not ancestors of `main`), and any other branch whose content
-   landed via a different route (a renamed
-   head, a cherry-pick, a manual `merge --squash`). When git rejects
-   `--write-tree` (git < 2.38) or the simulated merge conflicts, the
-   probe is inconclusive and the branch keeps its existing `not-merged`
-   skip — the signal never guesses. `content-merged` candidates render
-   with a "weaker signal — verify before deleting" annotation in the
-   dry-run list and are called out separately in the confirmation
-   prompt, since — unlike a merged PR or git ancestry — no CI or GitHub
-   merge check ever validated this branch's exact diff.
-
-Other candidate semantics:
-
-- A branch is a candidate iff it is not `<base>`, not the current HEAD,
-  not in `git config branch.protectedBranches`, and matches one of the
-  three signals above.
-- When a candidate has an attached worktree, the worktree is removed
-  (force if dirty) **before** `git branch -D`, mirroring the pattern in
-  [`worktree-lifecycle.md`](helpers/worktree-lifecycle.md).
-- `--remote` is required on top of `--execute` to touch `origin/`.
-- A throwing `gh` runner (auth failure, rate limit, missing binary) no
-  longer aborts the run: the branches phase logs one warning and
-  continues with the git-only signals (ancestry + content-equivalence).
-  The JSON envelope's `ghDegraded: true` records that this happened for
-  the run, and the dry-run text carries a matching warning line.
-
-The skip taxonomy:
-
-- `reason: 'protected'` — the base branch or a name in
-  `git config branch.protectedBranches`. Not reapable; ignore.
-- `reason: 'current-head'` — the current branch. Reapable after
-  `git checkout <base>`. The dry-run output surfaces a remediation
-  hint so the operator sees the recovery path without having to look
-  in the JSON envelope.
-- `reason: 'tip-diverged-from-merge'` — the latest PR merged, but the
-  branch's tip has since moved past the merged commit (a post-merge
-  force-push). The dry-run line names both SHAs and a remediation hint
-  (delete manually via `git branch -D <branch>`, or push the follow-up
-  commit).
-- `reason: 'not-merged'` — none of the three detection signals matched.
-  Previously silent; the dry-run output now lists every surviving
-  `not-merged` branch as a one-line-per-branch summary with its
-  last-commit age, so the operator can see why a leftover branch isn't
-  reaped instead of hunting for it by hand.
-
-Every default run also opts the planner into a **remote-only
-enumeration pass**: in addition to walking `refs/heads/*`, the planner
-also walks `refs/remotes/origin/*` and emits candidates for any branch
-that exists on `origin` with a merged PR but has no local ref. These
-candidates carry `detectedBy: 'remote-only'` and `localExists: false`
-and are always shown in the dry-run list; **deleting** them (via the
-`git push --delete origin/<branch>` path — no local `git branch -D` is
-attempted, since there is no local branch) still requires `--remote` on
-top of `--execute`, unchanged.
-
-### stashes
-
-- Stashes are dropped high-index-first so the indices of remaining
-  stashes stay stable across consecutive drops (git renumbers from the
-  top of the stack).
-- In interactive mode (no `--yes`, no `--json`), each stash gets a
-  prompt: `drop / keep / quit`. The default on bare ENTER is `keep`.
-- In `--yes` or `--json` mode, only refs explicitly named via
-  `--drop-stashes <ref>` are dropped. Everything else is kept. There is
-  intentionally no "drop all" shorthand.
-
-## Constraint
-
-Do **not** run with `--execute` if there is unmerged work that needs
-saving. The fast-forward phase skips on a dirty tree (safe), but the
-branches phase will reap any merged-PR branch in scope — passing
-`--exclude '<pattern>'` is the only way to carve out exceptions. The
-remote reap (`--remote`) crosses `origin/` and cannot be undone without
-re-pushing.

package/.agents/workflows/helpers/audit-lens-core.md

@@ -0,0 +1,230 @@
+# Audit lens core (shared contract)
+
+> **Single source of truth for every audit lens's shared machinery
+> (Story #4665).** Each `audit-<lens>.md` workflow references this file instead
+> of re-stating the blocks below. A lens carries only its own frontmatter, a
+> short preamble, its `{{changedFiles}}` fence, and its genuinely lens-specific
+> dimensions / detection batteries / applicability gates / boundary
+> demarcations. Everything a lens shares with every other lens — the read-only
+> constraint, scope interpretation, the report envelope and finding-block
+> skeleton, the severity scale, the self-cross-check, and the execution
+> strategy — lives here.
+>
+> This file absorbs the three retired helpers `audit-severity-scale.md`,
+> `audit-self-check.md`, and `audit-dual-path.md`.
+
+## Read-only constraint {#read-only}
+
+Every audit lens is a **read-only** analysis. Do **not** modify application
+code, styles, configuration, dependencies, branches, or labels. Surfacing the
+findings is the deliverable; fixing them is a separate pass. The **only** write
+a lens performs is its report artifact (plus, where a lens explicitly declares
+it, a single measurement/baseline artifact named in that lens's own
+Constraint). A lens that names a stricter or looser read-only carve-out in its
+own body (e.g. performance's non-mutating measurements, quality's permitted
+committed-baseline reads, data-model's no-database rule) refines this shared
+constraint for that lens only.
+
+## Scope interpretation (Story / plan-run mode) {#scope-interpretation}
+
+Each lens carries its own `{{changedFiles}}` fence — the substitution anchor
+consumed by `.agents/scripts/lib/audit-suite/` — and reads it as follows:
+
+- When this lens is invoked from `/deliver` close lenses (or a plan-run audit),
+  the fence is populated with the Story (or plan-run) change-set file list.
+  **Restrict analysis to those files** (and their direct dependencies when the
+  lens explicitly calls for cross-file reasoning).
+- Otherwise — for any manual `/audit-<lens>` invocation — the fence renders the
+  literal string `{{changedFiles}}`. Treat that as **no scope filter — run the
+  lens codebase-wide** exactly as if the block were absent.
+
+A handful of lenses deliberately deviate (documentation intersects the fence
+with its config-driven target set; navigability always evaluates the whole
+route tree regardless of the fence). Those lenses state their deviation in
+their own Scope section; every other lens follows the rule above verbatim.
+
+## Report envelope & finding-block skeleton {#report-envelope}
+
+Each lens writes exactly one structured Markdown report to
+`{{auditOutputDir}}/audit-<lens>-results.md` (the lens preamble names its own
+path). The report MUST include every section its lens template mandates — write
+`_No findings._` rather than omitting a section — and always an
+`## Executive Summary` and a `## Detailed Findings` section. The Executive
+Summary carries the self-cross-check `kept <k> / dropped <d>` line
+([below](#self-cross-check)).
+
+Every finding under `## Detailed Findings` uses the shared 7-field skeleton
+below. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
+`Baseline MUST`, a `Route / Door` + `Persona(s)` pair, an `Evidence` tag) and
+may **relabel** the two normalized axes — `Severity` ↔ `Impact`, `Dimension` ↔
+`Category` ↔ `Type` — as its preamble declares; the parser
+(`lib/audit-to-stories/parse-audit-md.js`) recognizes every variant. It never
+drops or renames a shared field.
+
+```markdown
+## Executive Summary
+
+[The lens's headline read plus the self-cross-check `kept <k> / dropped <d>`
+line. A lens may mandate additional report sections between here and the
+findings — its own body names them.]
+
+## Detailed Findings
+
+[For every finding, use the following strict structure. Lead each title with
+the primary file the finding lives in:]
+
+### `path/to/primary-file.ext` — [Short title of the issue]
+
+- **Dimension:** [the lens-specific dimension — see the lens's own list]
+- **Severity:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
+- **Current State:** [the specific file/line/module and why it is problematic]
+- **Recommendation & Rationale:** [how to remediate and why it matters]
+- **Acceptance signal:** [the command or observable that proves this finding is
+  remediated — e.g. a grep that now returns empty, an added regression test, or
+  a re-run of this lens]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
+```
+
+## Severity scale {#severity-scale}
+
+Every finding grades its severity (labelled `Severity` or `Impact`) on this
+ordered scale. `parse-audit-md.js` recognizes every level, and a surviving
+**Critical** finding halts the delivery gate
+(`lib/audit-suite/findings.js#hasSurvivingCritical`).
+
+- **Critical** — an active, exploitable, or data-losing defect that must be
+  fixed before the change can ship (e.g. a leaked secret, an auth bypass, a
+  guaranteed production outage or data-loss path).
+- **High** — a serious correctness, security, or maintainability risk that
+  should be fixed promptly, but does not by itself block the release.
+- **Medium** — a real problem worth scheduling; contained blast radius, or a
+  reasonable workaround exists.
+- **Low** — minor or cosmetic; fix opportunistically.
+
+## Self-cross-check (mandatory — filter false positives before you finalize) {#self-cross-check}
+
+You are your own adversarial reviewer. After you have drafted the Detailed
+Findings but **before** you write the report artifact, re-open every finding
+and hold it to the bar below. This pass is **read-only** — it filters and
+tightens the findings you already have; it never invents new ones. It gives the
+sequential single-pass path the same false-positive filter the orchestrated
+path's independent adversarial reviewer applies.
+
+### Per-finding evidence bar (keep or drop)
+
+Keep a finding only when **all** of the following hold. Drop it otherwise.
+
+- **Grounded location** — it names a concrete `path:line` (or a concrete
+  symbol / config key) that you have actually read, not a hypothetical or a
+  "somewhere in the codebase" claim.
+- **Reproducible evidence** — the problem is backed by an observable: a tool
+  reading (a baseline row, a complexity/MI/duplication number, a failing
+  command), a quoted code snippet, or a specific standard it violates. A
+  finding whose entire basis is "this looks wrong" does not clear the bar.
+- **In-scope** — when a change-set scope filter was supplied (the fence
+  resolved to a file list), the finding lives in that scope or a direct
+  dependency the lens explicitly reasons across. A finding outside the scope
+  filter is dropped, not reported.
+- **Actionable** — the recommendation is specific enough to execute. Drop
+  vague exhortations ("improve error handling generally") that carry no
+  concrete change.
+
+### Exclusion list (never a finding)
+
+Treat the following as **out of scope by construction** and drop any finding
+that rests on one of them:
+
+- **Sanctioned test seams** — exports consumed only by tests, and other
+  patterns the `test-seams` rule blesses. Never a production defect.
+- **Entry points & public API surface** — CLI mains, `bin/` scripts, declared
+  `exports` / `bin` / `main`, and barrel contracts consumed out-of-tree. A
+  zero in-repo consumer count is not death.
+- **Dynamic / framework reachability** — symbols reached via `import()`,
+  string-keyed dispatch, decorators, lifecycle listeners, or convention-loaded
+  plugin directories. Invisible to static analysis, not dead.
+- **Intentional, documented deviations** — a pattern an in-tree comment, ADR,
+  or config explicitly sanctions. Cite it and drop the finding.
+- **Style-only nits already enforced by a formatter/linter** — do not
+  re-litigate what the committed tooling already governs.
+
+### Final re-open-and-drop pass (mandatory)
+
+1. Walk your Detailed Findings once more, applying the bar and the exclusion
+   list above. Remove every finding that fails.
+2. Count what you kept (`k`) and what you dropped (`d`).
+3. Record the outcome in the report's **Executive Summary** as a single line:
+
+   ```text
+   Self-cross-check: kept <k> / dropped <d>.
+   ```
+
+   When `d > 0`, name the dropped findings (title + the bar/exclusion reason)
+   in one short list under that line, so the filtering is auditable and never
+   silent.
+
+A lens that keeps every finding still records `dropped 0` — the line's absence
+is itself a defect (it means the pass did not run).
+
+## Execution strategy {#execution-strategy}
+
+A lens is a self-contained, read-only unit of work — exactly the shape a
+role-scoped subagent is for. Run it along the first path below that is
+available; every path emits the **identical** report contract (the finding-block
+skeleton above), so downstream consumers (`audit-to-stories`) are agnostic to
+which path produced it.
+
+1. **Subagent dispatch (first-class).** Dispatch the lens as a single
+   `subagent_type: auditor` call — the standalone boot context in
+   [`../../agents/auditor.md`](../../agents/auditor.md) carries the read-only
+   MUSTs, the finding-block skeleton, the severity scale, and the
+   self-cross-check bar, so the child needs only the lens's own dimensions to
+   run. The subagent returns the **report path plus the Executive Summary**
+   (including the self-cross-check line); the parent never needs the full
+   findings inline. This is the default: the auditor boots without the full
+   project closure, so the spawn is cheap relative to running the lens inline
+   in the parent's context.
+
+   - **Per-dimension fan-out (heavyweight lenses).** `audit-architecture`,
+     `audit-performance`, and `audit-documentation` carry enough independent
+     dimensions to be worth fanning out: dispatch one `subagent_type: auditor`
+     call **per dimension** in a single turn via
+     [`parallel-tooling.md`](parallel-tooling.md) Rule 3, then **merge** the
+     per-dimension findings under this file's self-cross-check (the merge is
+     where cross-dimension duplicates and false positives are dropped). Respect
+     the nesting-depth budget and the concurrency cap that Rule 3 documents.
+
+2. **Sequential inline execution (documented fallback).** When subagent
+   dispatch is unavailable, run the lens's steps turn-by-turn in the current
+   context exactly as written, ending with the self-cross-check. This changes
+   nothing about the report contract.
+
+> **Orchestrated dynamic-workflow path (optimization note).** Six lenses ship a
+> saved project workflow at `.claude/workflows/audit-<lens>.workflow.js` that,
+> **when Claude Code dynamic workflows are available** (runtime is Claude Code,
+> `disableWorkflows` unset, version `>= 2.1.154`), fans the dimensions out as
+> parallel read-only subagents and runs an independent adversarial cross-check
+> stage before synthesising the report. It derives its per-dimension prompts
+> from the *lens* markdown at run time — the lens stays the single source of
+> truth. This is a performance optimization over path 1, **not** a separate
+> contract: strategy selection lives in
+> [`../../scripts/lib/dynamic-workflow/capability.js`](../../scripts/lib/dynamic-workflow/capability.js)
+> (`selectAuditStrategy`), and it is not covered by the No-Shim / hard-cutover
+> rule in [`../../rules/git-conventions.md`](../../rules/git-conventions.md)
+> because there is one report contract and only the execution strategy varies —
+> the same capability-degradation pattern the protocol endorses for live-docs
+> fallback. Force a path for testing with `MANDREL_AUDIT_STRATEGY=sequential`
+> or `MANDREL_AUDIT_STRATEGY=orchestrated`; exercise the real disable signals
+> with `CLAUDE_CODE_DISABLE_WORKFLOWS=1` or `disableWorkflows: true` in
+> `.claude/settings.json`. On the orchestrated path the analysis subagents are
+> granted only read/search tools (`Read`, `Grep`, `Glob`) — the single write is
+> the final report artifact.
+
+## Parallel tooling {#parallel-tooling}
+
+When a lens batches independent reads/greps, runs a long shell (a scanner, a
+profiler, a suite time), or fans out per-dimension, apply
+[`parallel-tooling.md`](parallel-tooling.md): batch independent reads in one
+turn (Rule 1), run long shells via `run_in_background` + `Monitor` (Rule 2),
+and dispatch N independent units as N `Agent` calls in one turn (Rule 3).

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

@@ -18,10 +18,6 @@ is merged to `main`. The live v2 path is **Story scope only**:
   after the PR opens and before auto-merge. Findings post to the PR;
   critical findings block close (`agent::blocked`).
 
-Legacy `scope: epic` / Epic-branch review procedure (including
-`epic-audit-prepare.js` / `epic-audit-recheck.js`) was removed with the
-v2 Story-only cutover.
-
 **Invariant — Story-scope review runs outside the maker's LLM context.**
 The Story-scope review executes inside the `single-story-close.js` close
 subprocess, **not** in the delivering child's (maker agent's) LLM context.
@@ -45,28 +41,21 @@ The caller passes the following arguments (`/deliver` passes
 
 | Argument    | Type                                  | Required | Meaning                                                                                          |
 | ----------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `scope`     | `"story"` \| `"epic"`                 | yes      | Live path is `"story"`. `"epic"` remains only for legacy cumulative adapters.                    |
-| `ticketId`  | integer                               | yes      | GitHub issue number of the Story (when `scope === 'story'`) or cumulative ticket (legacy `scope === 'epic'`). |
-| `baseRef`   | string (git ref)                      | yes      | The diff base. Story scope: `main` (or `project.baseBranch`). Legacy cumulative scope: caller-provided base. |
-| `headRef`   | string (git ref)                      | yes      | The branch tip under review. Story scope: `story-<storyId>`. Legacy cumulative scope: caller-provided head. |
+| `scope`     | `"story"`                             | yes      | The live delivery path.                                                                          |
+| `ticketId`  | integer                               | yes      | GitHub issue number of the Story.                                                                |
+| `baseRef`   | string (git ref)                      | yes      | The diff base — `main` (or `project.baseBranch`).                                                |
+| `headRef`   | string (git ref)                      | yes      | The branch tip under review — `story-<storyId>`.                                                 |
 | `depth`     | `"light"` \| `"standard"` \| `"deep"` | no       | Risk-derived review thoroughness lever. Absent → `standard`. See **Review depth** below.         |
 
-All scope-dependent behavior in this helper branches off the first four
-arguments. Do not hard-code branch names or ticket types — read them from
-the argument envelope.
+Do not hard-code branch names or ticket types — read them from the argument
+envelope.
 
 ### Review depth (`depth`)
 
-`depth` is the thoroughness lever introduced by Story #3876, made a live
-consumed signal end to end by Story #3937, and re-based on an observable signal
-by Story #4542. `runCodeReview` derives it from the diff it already enumerates,
-via [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js): the
-changed files' intersection with the `sensitivePaths` classes registered in
-`audit-rules.json` gives the level, their count gives the width, and
-`resolveDepth` folds the two (a sensitive path OR a wide diff → `deep`; neither,
-on a small diff → `light`; an unenumerable diff → `standard`). It takes no
-planner-authored input and reads no checkpoint. `runCodeReview` forwards `depth`
-to every provider's `runReview` input.
+`depth` is the thoroughness lever: `runCodeReview` derives it from the diff via
+[`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) (Story #4542
+re-based it on that observable signal, so it takes no planner-authored input) and
+forwards it to every provider's `runReview` input.
 
 It is an **input-only** signal: it changes *how thorough* the review is, never
 the findings envelope (`{ status, severity, posted, report, halted,
@@ -270,8 +259,7 @@ prior baseline before merging.
 Findings are **persisted as a `verification-results` structured comment on
 the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract of
 Story #4411; this single comment carries the
-Epic-close lens findings). The target ticket is the Story when
-`scope === 'story'` and the Epic when `scope === 'epic'`. The comment
+Story-scope lens findings). The target ticket is the Story. 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