mandrel 2.3.0 → 2.5.0

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

@@ -1,5 +1,5 @@
 ---
-description: Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`single-story-close`, dispatcher, gates); propose remediations.
+description: Audit performance by measuring first — profile hot paths, I/O, memory, and payload against the repo's own numbers — and audit interleaving/partial-failure correctness (TOCTOU, unawaited promises, non-atomic writes) as a first-class dimension.
 ---
 
 # Performance & Bottleneck Audit
@@ -10,9 +10,23 @@ Performance Engineer & Systems Architect
 
 ## Context & Objective
 
-Analyze the application for performance regressions, bottlenecks, and efficiency
-gaps. Your goal is to identify why a system is slow or where it might fail under
-load.
+Find where a system is slow, wasteful, or unsafe under concurrency — and prove
+it with numbers, not opinions. This lens has three standing commitments that
+separate it from a prose read-through:
+
+1. **Measure before you judge.** A performance claim that is not backed by a
+   profile, a timing, or a byte count is a hypothesis, not a finding. Step 0
+   times the repo's own suite and entry points and produces the evidence every
+   finding must cite.
+2. **Adapt to the repo profile.** A CLI/tooling repo has no bundle and no Core
+   Web Vitals; a frontend app does. Step 1 detects the target profile and
+   activates only the dimensions that apply, declaring the rest inapplicable
+   rather than fabricating findings for a surface that does not exist.
+3. **Interleaving correctness is a performance concern.** The most expensive
+   defects this repo has shipped were not slow loops — they were races
+   (check-then-act on a lease, non-atomic checkout mutation under concurrent
+   close, shared-cache poisoning). Step 2 treats interleaving & partial-failure
+   correctness as a first-class dimension, statically and repo-observably.
 
 ## Scope (Story / plan-run mode)
 
@@ -37,88 +51,154 @@ before this section existed.
 
 ## Execution strategy (dual-path)
 
-This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
-
-- **Orchestrated (dynamic-workflow) path.** When Claude Code's
-  [dynamic workflows](https://code.claude.com/docs/en/workflows) are
-  available, the saved project workflow
-  `.claude/workflows/audit-performance.workflow.js` fans the dimensions below
-  out as parallel read-only subagents, runs an **adversarial cross-check**
-  stage (an independent agent reviews each dimension's findings and drops
-  false positives before they enter the report), then synthesises the Step 3
-  report. The orchestrator derives its per-dimension prompts from *this*
-  markdown at run time — the lens stays the single source of truth; the
-  script does not fork a second copy of the spec. The three-phase fan-out
-  itself is the shared
-  [`runAuditOrchestration`](../scripts/lib/dynamic-workflow/audit-orchestrator.js)
-  engine, not a per-lens copy.
-- **Sequential (single-pass) path.** When dynamic workflows are unavailable,
-  follow Steps 1–3 below turn-by-turn exactly as before. This is the default
-  fallback and changes nothing about the existing behaviour.
-
-**Strategy selection** is computed by
-[`lib/dynamic-workflow/capability.js`](../scripts/lib/dynamic-workflow/capability.js)
-(`selectAuditStrategy`). The orchestrated path is chosen only when the runtime
-is Claude Code, `disableWorkflows` is not set (settings.json **or**
-`CLAUDE_CODE_DISABLE_WORKFLOWS`), and the Claude Code version meets the
-research-preview floor (`>= 2.1.154`). Any other runtime, a disabled setting,
-or an older version degrades gracefully to the sequential path.
-
-> **Capability degradation, not a contract shim.** This dual path is **not**
-> covered by the No-Shim / hard-cutover rule in
-> [`git-conventions.md`](../rules/git-conventions.md). That rule forbids
-> running two shapes of the *same contract* side by side. Here there is **one**
-> report contract; only the *execution strategy* is selected from a runtime
-> capability — the same pattern the protocol already endorses for live-docs
-> fallback in [`instructions.md` §1.C/§1.D](../instructions.md). The full
-> capability-degradation rationale lives in the
-> [`capability.js`](../scripts/lib/dynamic-workflow/capability.js) module
-> docstring; the orchestrated-run evidence and per-lens cost/precision gate
-> verdicts live in [`docs/roadmap.md`](../../docs/roadmap.md) (Part 3 —
-> Dynamic-Workflow Orchestration).
-
-**Forcing a path (for testing).** Set `MANDREL_AUDIT_STRATEGY=sequential` to
-verify the fallback path with the feature notionally disabled, or
-`MANDREL_AUDIT_STRATEGY=orchestrated` to pin the dynamic path. To exercise the
-real disable signals instead, set `CLAUDE_CODE_DISABLE_WORKFLOWS=1` (env) or
-`disableWorkflows: true` in `.claude/settings.json` and re-run the lens — both
-degrade to the sequential path.
-
-> **Read-only on both paths.** The lens is read-only (see Constraint). The
-> orchestrated subagents run in `acceptEdits` and inherit the session tool
-> allowlist, but the workflow script grants the analysis agents only
-> read/search tools (`Read`, `Grep`, `Glob`) — no write/edit/shell-mutation
-> tools. The single write in an orchestrated run is the final report artifact.
-
-## Step 1: Bottleneck Discovery
-
-> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
-
-Investigate the following areas:
-
-- **Database/API Efficiency:** Look for N+1 query patterns, missing indexes, or
-  oversized JSON payloads.
-- **Frontend Rendering:** Identify unnecessary re-renders (in React/Vue), large
-  DOM trees, or layout thrashing.
-- **Bundle Size:** Check for heavy dependencies, missing code-splitting, or
-  unoptimized assets.
-- **Resource Usage:** Identify potential memory leaks or high CPU usage logic
-  (e.g., synchronous loops over large datasets).
-- **Network Path:** Check for excessive round-trips or lack of caching headers.
-
-## Step 2: Evaluation Dimensions
-
-1. **Latency:** How long does it take for a user action to complete?
-2. **Throughput:** How many concurrent operations can the system handle before
-   degrading?
-3. **Efficiency:** Is the code using the minimum amount of CPU/Memory/Network
-   required?
-4. **Scalability:** Does the performance hold as the data size or user count
-   increases?
-5. **Core Web Vitals:** (For frontend) LCP, FID, and CLS metrics.
-
-## Step 3: Output Requirements
+This lens runs along one of two execution paths (orchestrated dynamic-workflow
+or sequential single-pass). Both emit the **identical** Step 4 report contract;
+downstream consumers (`audit-to-stories`) are agnostic to which path produced
+it. See [`helpers/audit-dual-path.md`](helpers/audit-dual-path.md) for strategy
+selection, the forcing flags, and the read-only guarantee — read `audit-<lens>`
+there as this lens's name.
+
+> **Measurement is non-mutating, not forbidden.** This lens is read-only with
+> respect to source, but it MUST be allowed to *run* measurements. The
+> orchestrated path grants its measurement agents a `Bash` tool restricted to a
+> **non-mutating command allowlist** (profilers, timers, bundle-stat and
+> file-size probes — never a command that writes source, installs, or mutates
+> git/labels). See the allowlist in
+> [`.claude/workflows/audit-performance.workflow.js`](../../.claude/workflows/audit-performance.workflow.js).
+
+## Step 0: Measure before you judge (mandatory)
+
+Produce evidence first; every finding in Step 4 carries an **Evidence** field
+that cites a repro command and tags itself `measured` or `estimated`. Run the
+measurements that apply to the repo (Step 1 tells you which), preferring the
+repo's own scripts over invented ones.
+
+**Timing (all repos).** Time the project's own test suite and any CLI entry
+points. Prefer `hyperfine` for stable multi-run statistics; fall back to
+`/usr/bin/time -v` (or `time`) when it is absent:
+
+```bash
+hyperfine --warmup 1 'npm test'            # suite wall-clock + variance
+hyperfine --warmup 1 'node bin/<entry>.js --help'   # CLI cold-start cost
+/usr/bin/time -v node bin/<entry>.js <args> 2>&1 | tail -n 20   # fallback + RSS
+```
+
+**CPU profile (all repos).** Profile a detected entry script with the V8
+sampling profiler and read the hottest self-time frames:
+
+```bash
+node --cpu-prof --cpu-prof-dir=temp/audits/cpuprof bin/<entry>.js <args>
+```
+
+Then inspect the emitted `.cpuprofile` (the top self-time nodes) for the real
+hot path.
+
+**Payload / bundle (web repos only).** Emit build stats and size the shipped
+payload; do not estimate what the bundler will tell you exactly:
+
+```bash
+npx vite build --profile        # or the repo's own build script
+du -sh dist/ && find dist -name '*.js' -exec wc -c {} + | sort -n | tail
+```
+
+**Evidence discipline.** A finding tagged `measured` names the command above
+whose output produced its number. A finding tagged `estimated` (e.g. a
+Big-O argument read off the code without a runnable repro) says so plainly and
+is graded no higher than **Medium** unless a measurement upgrades it. Attach
+the repro command to the finding so the operator can reproduce it in one paste.
+
+### Step 0b: Perf baseline artifact + diff-aware trend
+
+Write a per-run baseline capturing the Step 0 numbers to
+`{{auditOutputDir}}/perf-baseline.json` (suite time, per-entry cold-start, RSS,
+bundle bytes where applicable, and the hot-frame list). On every run:
+
+- **Diff against the previous baseline** when one exists. A metric that
+  regressed past the previous run's value is an **automatic High** finding with
+  the delta (old → new, absolute and %) as its Evidence.
+- **Suppress unchanged known findings.** A finding whose measured value is
+  within noise of the prior baseline is reported as *unchanged* in a trend
+  summary line, not re-litigated as a fresh finding. New or regressed metrics
+  are what the run surfaces.
+- Record the baseline path and the trend verdict (`first-run` /
+  `improved` / `unchanged` / `regressed`) in the Executive Summary.
+
+## Step 1: Repo profile & active dimensions
+
+Detect the target profile from repo-observable markers, then activate only the
+dimensions that apply. Declare the inapplicable ones explicitly in the report
+(so a reader knows they were considered and ruled out, not forgotten).
+
+Detection signals:
+
+- A **CLI / tooling / library** repo — a `bin` field or executable entry
+  scripts, no framework marker, no frontend directory: bundle and Core Web
+  Vitals are **inapplicable**.
+- A **web / frontend** repo — a framework marker (`react`, `vue`, `svelte`,
+  `next`, `vite`, `webpack`) and/or a frontend surface (`src/components/**`,
+  `*.html`, `*.css`, a `dist/` build): payload/bundle and CWV **apply**.
+- A **service / backend** repo — server entry, route/controller/API surface:
+  I/O and interleaving dominate; bundle is **inapplicable**.
+
+The interleaving & partial-failure dimension and the CPU / I/O / memory
+dimensions apply to **every** profile. Only payload/bundle (and its re-homed
+CWV material) is web-gated.
+
+## Step 2: Analysis dimensions (orthogonal set)
+
+The historically overlapping ten dimensions collapse to four orthogonal
+resource dimensions plus one correctness dimension. Audit each *active*
+dimension (per Step 1) against measured evidence from Step 0.
+
+- **CPU & algorithmic hot paths:** super-linear complexity on a path that runs
+  under load, redundant recomputation, synchronous work blocking the event
+  loop. Ground every claim in a `--cpu-prof` hot frame or a timed repro.
+- **I/O & syscall efficiency:** N+1 queries/reads, unbatched network or
+  filesystem round-trips, missing caching, oversized payloads crossing a
+  boundary, chatty `fs` calls in a loop. Cite the call site and a timing.
+- **Memory & leaks:** unbounded caches/arrays, retained closures, listeners
+  never removed, growth across a repeated operation. Cite RSS from Step 0 or a
+  heap delta.
+- **Payload & bundle (web only):** heavy or duplicated dependencies, missing
+  code-splitting, unoptimized assets, render-blocking resources. Re-homed from
+  the retired lighthouse lens: capture a **per-route Core-Web-Vitals score
+  baseline** and measure with a **median-of-3** protocol (three runs, report
+  the median LCP/CLS/INP/TBT per route) so single-run variance never drives a
+  finding. Inapplicable — and omitted — on non-web repos.
+- **Interleaving & partial-failure correctness:** the concurrency dimension.
+  Statically, repo-observably, look for: unawaited / floating promises;
+  `Promise.all` over independently-failing branches where `allSettled` is
+  required; **check-then-act (TOCTOU)** on files, locks, labels, or uniqueness
+  constraints; non-atomic read-modify-write; in-place writes where
+  temp-file-plus-rename is required for crash-atomicity; missing
+  transaction/compensation around a multi-step write; non-idempotent retried
+  side effects; and shared-cache poisoning (one run writing state a concurrent
+  run reads). **Speculative races are the known failure mode of this
+  dimension** — a claimed race with no concrete interleaving and no
+  repo-observable shared-state path is a false positive; lean hard on the
+  self-cross-check to drop it.
+
+## Step 3: Severity rubric (performance-anchored)
+
+Grade every finding on the shared
+[`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md),
+anchored to performance/correctness cost rather than gut feel:
+
+- Grade **Critical** for a guaranteed data-loss or corruption path under normal
+  concurrency (e.g. a lost-update TOCTOU on persisted state), or a hang/outage
+  under expected load.
+- Grade **High** for a measured regression past the previous baseline (delta is
+  the Evidence), or a hot-path cost (frequency × per-call cost) on a path proven
+  to run under load, or a race with a concrete losing interleaving.
+- Grade **Medium** for a real but bounded cost: an `estimated`-only algorithmic
+  concern, a cold-path inefficiency, or a concurrency smell with a plausible but
+  unproven interleaving.
+- Grade **Low** for minor or opportunistic issues; fix when nearby.
+
+Latency thresholds, when a user-facing route is in scope, follow the CWV bands
+in the payload/bundle dimension (LCP ≤2.5s good / ≤4.0s needs-improvement).
+
+## Step 4: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-performance-results.md`, using the exact template
@@ -129,22 +209,32 @@ below.
 
 ## Executive Summary
 
-[Overview of performance summary vs target benchmarks.]
+[Overview of performance posture vs the Step 0 measurements. State the repo
+profile detected (Step 1) and which dimensions were inapplicable. State the
+baseline trend verdict (first-run / improved / unchanged / regressed) and the
+`perf-baseline.json` path. Close with the self-cross-check `kept k / dropped d`
+line.]
 
 ## Detailed Findings
 
-[For every bottleneck identified, use the following strict structure:]
-
-### [Short Title of the Bottleneck]
-
-- **Dimension:** [e.g., Latency | Throughput | Efficiency]
-- **Impact:** [High | Medium | Low]
-- **Current State:** [Technical explanation of where and why the bottleneck
-  occurs]
-- **Recommendation & Rationale:** [Specific optimization tactic and expected
-  performance gain]
+[For every bottleneck or correctness defect identified, use the following
+strict structure. Lead each title with the primary file it lives in:]
+
+### `path/to/primary-file.ext` — [Short title of the finding]
+
+- **Dimension:** [CPU & algorithmic | I/O | Memory & leaks | Payload & bundle | Interleaving & partial-failure]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
+- **Evidence:** [A repro command from Step 0 (or a quoted code path) and a
+  `measured` or `estimated` tag — e.g. "`measured`: `hyperfine 'npm test'` →
+  regressed 8.1s → 11.4s (+40%) vs perf-baseline.json"]
+- **Current State:** [Technical explanation of where and why the bottleneck or
+  race occurs]
+- **Recommendation & Rationale:** [Specific optimization/fix tactic and the
+  expected gain or the interleaving it closes]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a benchmark below the target threshold, a re-run of this lens showing the baseline no longer regressed, or a test exercising the losing interleaving]
 - **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this optimization independently]`
+  `[A copy-pasteable, highly specific prompt to execute this fix independently]`
 
 ## Low-Hanging Fruit
 
@@ -153,8 +243,22 @@ below.
 
 ## Constraint
 
-This is a **read-only** audit. Note: This workflow differs from
-`audit-lighthouse.md` (which runs Lighthouse and reports per-category scores
-and findings) by focusing on deep architectural and logic bottlenecks across
-the whole stack — backend, data access, and runtime hot paths — rather than
-the page-load surface Lighthouse measures.
+This is a **read-only** audit **with respect to source**: it does not edit,
+create, or delete application code, dependencies, or configuration. It **does**
+run non-mutating measurements (Step 0) and writes exactly two artifacts — the
+report and `perf-baseline.json`. Note: this lens supersedes the retired
+`audit-lighthouse` lens by folding its measured Core-Web-Vitals material (the
+per-route score baseline and median-of-3 protocol) into the web branch of the
+payload/bundle dimension.
+
+## Self-cross-check (mandatory — filter false positives before you finalize)
+
+Before you write the report artifact from the previous step, run the shared
+adversarial self-cross-check over your Detailed Findings — see
+[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
+per-finding evidence bar, the exclusion list, and the final re-open-and-drop
+pass whose `kept <k> / dropped <d>` counts you record in the Executive
+Summary, so the sequential single-pass path filters unverified findings just as
+the orchestrated path's adversarial reviewer does. The **interleaving**
+dimension leans on this pass hardest: drop every claimed race that lacks a
+concrete losing interleaving over a repo-observable shared-state path.

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

@@ -36,19 +36,41 @@ before this section existed.
   proceed with the full codebase-wide scan defined in the remaining
   steps.
 
-## Step 1: Scanning for PII Patterns
+## Step 1: Sink-First Detection
 
 > Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
 
-Scan the codebase for patterns related to sensitive data. Pay attention to:
-
-- **Log Statements:** Search for `console.log`, `logger.info`, etc., that might
-  be outputting `user`, `email`, `password`, `token`, `address`, or `phone`.
-- **Storage:** Check `localStorage`, `sessionStorage`, and database schemas for
-  unencrypted sensitive fields.
-- **API Requests:** Review outgoing requests to ensure PII is not leaked in URLs
-  (query params) or unencrypted headers.
-- **Analytics:** Ensure third-party analytics calls are anonymized.
+A PII leak is a **source → sink** flow: sensitive data reaching an egress point.
+Enumerate the **sinks** first, then trace which ones receive PII. Report only
+**proven flows** — a sink that never touches a PII source is not a finding.
+
+1. **Enumerate the sinks.** Run these verbatim `rg` commands (they anchor every
+   finding to a real line):
+
+   ```bash
+   # Logging sinks
+   rg -n "\b(console\.(log|info|warn|error|debug)|logger\.(info|warn|error|debug|log))\s*\(" --glob '!**/*.test.*'
+   # Telemetry / analytics sinks
+   rg -n "\b(track|capture|analytics|telemetry|reportEvent|Sentry\.(captureException|captureMessage))\s*\(" --glob '!**/*.test.*'
+   # Persistence sinks
+   rg -n "\b(localStorage|sessionStorage|\.set\(|db\.(insert|update|save)|prisma\.\w+\.(create|update|upsert))\b" --glob '!**/*.test.*'
+   # Outbound-HTTP sinks (PII in URLs / bodies / headers)
+   rg -n "\b(fetch|axios|http\.request|got|ky)\s*\(" --glob '!**/*.test.*'
+   ```
+
+2. **Secret scan.** Prefer `gitleaks`; fall back to `rg`:
+
+   ```bash
+   command -v gitleaks >/dev/null 2>&1 && gitleaks detect --no-banner --redact -v || \
+     rg -n -i "(api[_-]?key|secret|password|token|salt)\s*[:=]\s*['\"][^'\"]{8,}" --glob '!**/*.test.*'
+   ```
+
+3. **Trace PII sources to the enumerated sinks.** PII source tokens to follow:
+   `email`, `password`, `token`, `phone`, `address`, `ssn`, `dob`, `ip`,
+   `fullName`, `firstName`/`lastName`, `creditCard`, `user` object spreads. For
+   each sink from step 1, decide whether a PII source reaches it (directly, or
+   via a variable/object logged whole). Only a **proven** source→sink flow
+   becomes a finding; cite both the source line and the sink line.
 
 ## Step 2: Analysis Dimensions
 
@@ -70,6 +92,9 @@ Evaluate the codebase against these privacy pillars:
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-privacy-results.md`, using the exact template below.
 
+> Grade every finding's severity on the shared
+> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
+
 ```markdown
 # Privacy & PII Audit Report
 
@@ -85,15 +110,18 @@ Generate and save a highly structured Markdown audit report to
 
 ## Detailed Findings
 
-[For every gap identified, use the following strict structure:]
+[For every gap identified, use the following strict structure. Lead each title
+with the primary file the finding lives in:]
 
-### [Short Title of the Issue]
+### `path/to/primary-file.ext` — [Short title of the issue]
 
-- **Type:** [Leaky Log | Insecure Storage | Data Over-collection]
+- **Dimension:** [Leaky Log | Insecure Storage | Data Over-collection]
 - **Impact:** [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's necessary for
   compliance]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a grep for the leaky log that now returns empty, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
 ```
@@ -102,3 +130,13 @@ Generate and save a highly structured Markdown audit report to
 
 This is a **read-only** audit. Do not modify any code. Focus on identifying
 risks and providing clear remediation steps.
+
+## Self-cross-check (mandatory — filter false positives before you finalize)
+
+Before you write the report artifact from the previous step, run the shared
+adversarial self-cross-check over your Detailed Findings — see
+[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
+per-finding evidence bar, the exclusion list, and the final re-open-and-drop
+pass whose `kept <k> / dropped <d>` counts you record in the Executive
+Summary, so the sequential single-pass path filters unverified findings just as
+the orchestrated path's adversarial reviewer does.

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

@@ -47,62 +47,52 @@ before this section existed.
 
 ## Execution strategy (dual-path)
 
-This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
-
-- **Orchestrated (dynamic-workflow) path.** When Claude Code's
-  [dynamic workflows](https://code.claude.com/docs/en/workflows) are
-  available, the saved project workflow
-  `.claude/workflows/audit-quality.workflow.js` fans the dimensions below
-  out as parallel read-only subagents, runs an **adversarial cross-check**
-  stage (an independent agent reviews each dimension's findings and drops
-  false positives before they enter the report), then synthesises the Step 3
-  report. The orchestrator derives its per-dimension prompts from *this*
-  markdown at run time — the lens stays the single source of truth; the
-  script does not fork a second copy of the spec.
-- **Sequential (single-pass) path.** When dynamic workflows are unavailable,
-  follow Steps 1–3 below turn-by-turn exactly as before. This is the default
-  fallback and changes nothing about the existing behaviour.
-
-**Strategy selection** is computed by
-[`lib/dynamic-workflow/capability.js`](../scripts/lib/dynamic-workflow/capability.js)
-(`selectAuditStrategy`). The orchestrated path is chosen only when the runtime
-is Claude Code, `disableWorkflows` is not set (settings.json **or**
-`CLAUDE_CODE_DISABLE_WORKFLOWS`), and the Claude Code version meets the
-research-preview floor (`>= 2.1.154`). Any other runtime, a disabled setting,
-or an older version degrades gracefully to the sequential path.
-
-> **Capability degradation, not a contract shim.** This dual path is **not**
-> covered by the No-Shim / hard-cutover rule in
-> [`git-conventions.md`](../rules/git-conventions.md). That rule forbids
-> running two shapes of the *same contract* side by side. Here there is **one**
-> report contract; only the *execution strategy* is selected from a runtime
-> capability — the same pattern the protocol already endorses for live-docs
-> fallback in [`instructions.md` §1.C/§1.D](../instructions.md). The full
-> capability-degradation rationale lives in the
-> [`capability.js`](../scripts/lib/dynamic-workflow/capability.js) module
-> docstring; the orchestrated-run evidence and per-lens cost/precision gate
-> verdicts live in [`docs/roadmap.md`](../../docs/roadmap.md) (Part 3 —
-> Dynamic-Workflow Orchestration).
-
-**Forcing a path (for testing).** Set `MANDREL_AUDIT_STRATEGY=sequential` to
-verify the fallback path with the feature notionally disabled, or
-`MANDREL_AUDIT_STRATEGY=orchestrated` to pin the dynamic path. To exercise the
-real disable signals instead, set `CLAUDE_CODE_DISABLE_WORKFLOWS=1` (env) or
-`disableWorkflows: true` in `.claude/settings.json` and re-run the lens — both
-degrade to the sequential path.
-
-> **Read-only on both paths.** The lens is read-only (see Constraint). The
-> orchestrated subagents run in `acceptEdits` and inherit the session tool
-> allowlist, but the workflow script grants the analysis agents only
-> read/search tools (`Read`, `Grep`, `Glob`) — no write/edit/shell-mutation
-> tools. The single write in an orchestrated run is the final report artifact.
-
-## Step 0 - Project Context
-
-1.  Read the Story under audit — its `## Goal`, inline `acceptance[]` /
-    `verify[]`, and folded `## Spec` — to identify the target features.
-2.  Identify the target codebase paths for the audit.
+This lens runs along one of two execution paths (orchestrated dynamic-workflow
+or sequential single-pass). Both emit the **identical** Step 3 report contract;
+downstream consumers (`audit-to-stories`) are agnostic to which path produced
+it. See [`helpers/audit-dual-path.md`](helpers/audit-dual-path.md) for strategy
+selection, the forcing flags, and the read-only guarantee — read `audit-<lens>`
+there as this lens's name.
+
+## Step 0 - Mode split + tool-first artifact read (mandatory)
+
+**Resolve the mode first**, then read the numbers before judging. The two modes
+do not share a Step 0 — a codebase-wide run must not try to read a Story it was
+never given.
+
+- **Story-scoped mode** (the `## Scope` block above is populated with a change
+  set): read the Story under audit — its `## Goal`, inline `acceptance[]` /
+  `verify[]`, and folded `## Spec` — to identify the target features, and scope
+  the audit to the change set and its direct dependencies.
+- **Codebase-wide mode** (the `## Scope` block renders the literal
+  `{{changedFiles}}` token): there is **no Story** — do not look for one. Audit
+  the whole test surface, ranked (below).
+
+**Read the committed test-quality artifacts as evidence** (both modes). This
+lens grounds every coverage/quality claim in the metrics the delivery gates
+already compute and commit, rather than prose-scanning the tests:
+
+- `baselines/coverage.json` — per-file line/branch coverage. Cite the covered
+  ratio for any file you flag as under-tested.
+- `baselines/crap.json` — the CRAP score (complexity × uncoveredness). A high
+  CRAP row is a measured "complex **and** under-tested" hotspot — the single
+  strongest coverage-gap signal.
+- `baselines/mutation.json` — mutation-testing survivors where present: tests
+  that execute code without asserting on it (coverage without confidence).
+
+**Rank churn-by-coverage.** Order candidate findings by **churn × coverage
+gap** — frequently-changed files (`git log --format= --name-only -n 200 | sort
+| uniq -c | sort -rn`) that also score low coverage / high CRAP are the
+highest-value gaps. Lead the report with them; cap the Detailed Findings at the
+top hotspots so the output is an actionable batch, not an exhaustive dump.
+
+**Anchor the rubric** to [`rules/testing-standards.md`](../rules/testing-standards.md):
+the three-tier pyramid, assertion-placement, and mocking/isolation MUSTs are the
+standard a finding is measured against — cite the rule the test violates rather
+than asserting a bare opinion.
+
+Reading these committed artifacts is **read-only** and explicitly permitted (see
+the Constraint) — it is not "running the suite".
 
 ## Step 1: Context Gathering (Read-Only Scan)
 
@@ -149,6 +139,9 @@ Evaluate the gathered context against the following test quality dimensions:
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-quality-results.md`, using the exact template below.
 
+> Grade every finding's severity on the shared
+> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
+
 ```markdown
 # Testing & Quality Assurance Audit
 
@@ -168,16 +161,19 @@ primary vulnerabilities, coverage gaps, and areas causing developer friction.]
 
 ## Detailed Findings
 
-[For every gap identified, use the following strict structure:]
+[For every gap identified, use the following strict structure. Lead each title
+with the primary file the finding lives in:]
 
-### [Short Title of the Issue]
+### `path/to/primary-file.ext` — [Short title of the issue]
 
 - **Category:** [Flakiness | Coverage | Performance | Mocking | Test Plans]
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [How the tests are currently written and why it's
   problematic]
 - **Recommendation & Rationale:** [The specific testing pattern or refactor
   strategy to fix the issue]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the new test failing before / passing after the fix, a coverage re-check, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this fix independently]`
 ```
@@ -186,5 +182,19 @@ primary vulnerabilities, coverage gaps, and areas causing developer friction.]
 
 ## Constraint
 
-Do NOT execute any code modifications, edit files, create branches, or run the
-test suite. This is strictly a read-only analysis. Output the report and stop.
+Do NOT execute any code modifications, edit files, create branches, or **run**
+the test suite (do not invoke `npm test`, a coverage run, or a mutation run —
+those mutate state and cost minutes). Reading the **committed** coverage / CRAP
+/ mutation artifacts under `baselines/` is explicitly permitted and required
+(Step 0): citing an already-computed metric is read-only analysis, not a suite
+run. Output the report and stop.
+
+## Self-cross-check (mandatory — filter false positives before you finalize)
+
+Before you write the report artifact from the previous step, run the shared
+adversarial self-cross-check over your Detailed Findings — see
+[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
+per-finding evidence bar, the exclusion list, and the final re-open-and-drop
+pass whose `kept <k> / dropped <d>` counts you record in the Executive
+Summary, so the sequential single-pass path filters unverified findings just as
+the orchestrated path's adversarial reviewer does.