mandrel 2.3.0 → 2.5.0

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

@@ -35,53 +35,158 @@ before this section existed.
   proceed with the full codebase-wide scan defined in the remaining
   steps.
 
-## Step 1: Inventory & Stale Check
-
-> 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`.
-
-1. Run `npm outdated` (or equivalent for the package manager) to see which
-   packages are behind.
-2. Identify "stale" dependencies (packages with no updates for >1 year).
-3. Check for "bloat" — large dependencies that could be replaced by smaller
-   alternatives or native code.
-
-## Step 2: Vulnerability Scan
-
-1. Run `npm audit` to find security vulnerabilities.
-2. Cross-reference critical dependencies with known CVE databases if necessary.
-3. Highlight any peer dependency conflicts that might arise from upgrades.
-
-## Step 3: Output Requirements
+## Step 1: Inventory, Staleness & Unused Detection
+
+> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scans below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+
+Run each probe as a concrete, machine-readable command so the Health Summary
+counts are **exact** rather than eyeballed:
+
+1. **Outdated inventory.** Run `npm outdated --json` (or the package
+   manager's equivalent). Every key is a behind package with its `current`,
+   `wanted`, and `latest` fields; the count of keys is the exact **Outdated
+   Packages** figure — never hand-count from prose.
+2. **Unused dependencies.** Run `npx knip --production` to find declared
+   dependencies with no import reachable from a production entry point.
+   ⚠️ **`knip --production` silent-no-op gotcha:** knip's `--production`
+   mode analyses nothing **unless the project's `entry` patterns carry a
+   `!` suffix** — without the bang-suffixed production entries it reports
+   `{"issues":[]}` and looks green while scanning zero files. Confirm the
+   consumer's knip config uses `!`-suffixed entries before trusting a clean
+   result; when it does not, fall back to `npx depcheck --json` and record
+   the config gap itself as a finding. Report each genuinely-unused
+   dependency as a `Removal` finding.
+3. **Staleness.** For each critical or outdated dependency, probe its last
+   publish with `npm view <pkg> time.modified` and flag any package with no
+   release in over a year as **stale** (unmaintained-supply-chain risk),
+   independent of whether a newer version exists.
+4. **Node-engine drift.** Compare the Node version declared across every
+   source of truth and flag any mismatch between them:
+   - `package.json` `engines.node`,
+   - `.nvmrc`,
+   - the CI matrix `node-version` entries under `.github/workflows/**`,
+   - the locally observed `node --version`.
+   A drift between any two (e.g. `.nvmrc` pinning `20` while the CI matrix
+   still tests `18`) is a finding: the floor the code is actually tested
+   against has diverged from the floor it advertises.
+
+## Step 2: Reachability-triaged Vulnerability Scan
+
+A vulnerability in a build-only devDependency is not the same risk as one that
+ships to production. Triage every advisory by **production reachability**
+before grading it — this mirrors the security baseline's "reachable in
+production code" standard.
+
+1. **Two-pass audit diff.** Run `npm audit --json` (the full tree) **and**
+   `npm audit --json --omit=dev` (production-reachable only). An advisory
+   present in the full run but absent from the `--omit=dev` run is
+   **dev-only**; one present in both is **production-reachable**.
+2. **Severity rubric.** Grade each advisory on the shared
+   [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md)
+   as a function of the advisory's own CVSS band, its reachability
+   (production-reachable escalates; dev-only caps at Medium), and its
+   dependency position (a direct dependency whose version you control is more
+   actionable than a deep transitive one).
+3. **Report shape — no flooding.** Emit **one finding per
+   production-reachable Critical or High advisory** — these are the ones that
+   gate a release. Collapse **all dev-only advisories into a single aggregate
+   finding** ("N dev-only advisories, no production reachability") rather than
+   one block per advisory, so dev-only noise never drowns the production
+   signal.
+
+## Step 3: Supply-chain scoped mode (lockfile-delta)
+
+When the `## Scope` block above resolved to a change-set file list **and that
+list contains a lockfile** (`package-lock.json`, `pnpm-lock.yaml`, or
+`yarn.lock`), run this lens as a **supply-chain delta pass** instead of a
+whole-manifest re-scan. The close-time question is not "what is stale across
+the whole repo" — it is "what just entered the dependency tree, and is it
+safe". Diff the lockfile against the base branch and analyse only the delta:
+
+1. **Enumerate the delta.** Run `git diff <base>...HEAD -- <lockfile>` and
+   list every **added** package and every **version-bumped** package the
+   change introduces. These are the only packages in scope for this pass.
+2. **Provenance.** Run `npm audit signatures` to verify the registry
+   signatures / provenance attestations of the installed tree, and flag any
+   added package that fails signature verification.
+3. **New install scripts.** Flag any added or bumped package that declares a
+   `preinstall`, `install`, or `postinstall` lifecycle script — arbitrary
+   code that runs at `npm install` time is the classic supply-chain execution
+   vector and warrants an explicit eyeball.
+4. **Typosquat near-misses.** Compare each **added** package name against the
+   existing dependency set and well-known package names for a near-miss
+   (single-character edits, dropped scopes, hyphen/underscore swaps) that
+   suggests a typosquat, and flag it.
+
+## Step 4: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-dependencies-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).
+>
+> **Version-free titles (mandatory).** A finding title MUST NOT embed a
+> concrete version number — write ``### `package.json` — lodash unused``, not
+> ``… — lodash@4.17.20 unused``. Periodic re-runs of this lens re-detect the
+> same issue at a drifted version; a version-free title keeps the finding's
+> fingerprint stable so `audit-to-stories` dedupes it against the existing
+> Story instead of filing a fresh duplicate on every bump.
+
 ```markdown
 # Dependency Audit Report
 
 ## Health Summary
 
-- **Outdated Packages:** [Count]
-- **Vulnerabilities:** [Critical: #, High: #, Mod: #]
+- **Outdated Packages:** [exact count from `npm outdated --json`]
+- **Unused Dependencies:** [exact count from `npx knip --production` / `depcheck`]
+- **Vulnerabilities:** [Critical: #, High: #, Mod: #] (production-reachable / dev-only split)
+- **Node-engine drift:** [None | describe the mismatch across engines / .nvmrc / CI matrix]
 
 ## Detailed Findings
 
-[For every security fix or major update identified, use the following strict
-structure:]
+[For every production-reachable Critical/High advisory, unused dependency, or
+Node-engine drift, use the strict structure below. Lead each title with the
+manifest the dependency lives in, and keep the title version-free:]
 
-### [Package Name Update]
+### `path/to/package.json` — [Package name — issue, no version]
 
-- **Dimension:** [Security Fix | Major Upgrade | Removal]
-- **Impact:** [High | Medium | Low]
-- **Current State:** [Current vs Target version and reason for update]
-- **Recommendation & Rationale:** [How to perform the update and potential
-  breaking changes to watch for]
+- **Dimension:** [Security Fix | Removal | Engine Drift | Major Upgrade | Supply-chain]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/package.json:line`
+- **Current State:** [Current vs target, the reachability verdict (production-reachable | dev-only), and the reason for the change]
+- **Recommendation & Rationale:** [How to remediate and the breaking changes to watch for]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. `npm audit --omit=dev` reporting zero for this advisory, or `npx knip --production` no longer listing the package]
 - **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this update independently (e.g., npm install package@version)]`
+  `[A copy-pasteable, highly specific prompt to execute this update independently (e.g., npm install package@latest)]`
+
+### Dev-only advisories (aggregate)
+
+- **Dimension:** Security Fix
+- **Impact:** [Low | Medium]
+- **Location:** `package-lock.json`
+- **Current State:** [N dev-only advisories with no production reachability; not release-gating]
+- **Recommendation & Rationale:** [Batch-remediate on the next dependency-maintenance pass — do not block the release on these]
+- **Acceptance signal:** `npm audit --json` dev-only advisory count returns to zero.
+
+## Upgrade Batches
+
+Group the safe upgrade path into batches so a maintainer can act on them as
+discrete units. Each batch carries its own acceptance signal:
+
+- **Batch: patch + minor bumps** — every non-breaking `npm outdated` entry
+  whose `wanted` satisfies the declared range, grouped into ONE batch.
+  - **Acceptance signal:** `npm outdated` reports no remaining patch/minor
+    drift and the test suite passes after the bump.
+- **Batch: `<package>` major upgrade** — one batch **per** major bump (each
+  crosses a breaking boundary and lands independently).
+  - **Acceptance signal:** `<package>` at the new major with its migration
+    notes applied and the test suite green.
 
 ## Recommended Removals/Replacements
 
+- Remove `[unused-package]` — no production import per `npx knip --production`.
 - Replace `[heavy-library]` with `[light-library]` or native `[browser-api]`.
 ```
 
@@ -89,3 +194,13 @@ structure:]
 
 This is a **read-only** evaluation. Do not run `npm install` or `npm update`
 unless explicitly requested by the user after reviewing this report.
+
+## 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-devops.md

@@ -36,43 +36,121 @@ before this section existed.
   proceed with the full codebase-wide scan defined in the remaining
   steps.
 
-## Step 1: Context Gathering (Read-Only Scan)
+## Step 1: Detection Battery (Read-Only, Tool-First)
 
 > 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`.
 
-Before generating the report, silently scan the workspace for relevant
-configuration files. Pay special attention to:
+Do **not** audit CI/CD from memory. Run the deterministic battery below first
+and let its output ground every finding. Each tool is **presence-gated**: when
+the binary is absent, record the gap as a Low-severity `Standardization`
+finding (recommend adopting the scanner) and continue — a missing scanner
+degrades the audit gracefully, it never aborts it.
 
-- CI/CD pipelines (e.g., `.github/workflows/`, `.gitlab-ci.yml`,
-  `azure-pipelines.yml`).
-- Dependency manifests and script definitions (e.g., `package.json`,
-  `pnpm-workspace.yaml`).
-- Linting, formatting, and static analysis configs (e.g., `.eslintrc*`,
-  `.prettierrc*`, `biome.json`, `tsconfig.json`).
-- Git hooks and commit standards (e.g., `.husky/`, `commitlint.config.js`).
+1. **Workflow static analysis (`actionlint`).** When `.github/workflows/`
+   contains any `*.yml` / `*.yaml`, run:
+
+   ```bash
+   command -v actionlint >/dev/null 2>&1 && actionlint -color=never || \
+     echo "actionlint: not installed — recommend adding it (Standardization gap)"
+   ```
+
+   Every diagnostic `actionlint` emits is a finding (shell-quoting bugs,
+   invalid `runs-on`, undefined `needs`, mis-scoped `${{ }}` expressions).
+
+2. **Workflow security posture (`zizmor`).** Over the same
+   `.github/workflows/` set, run:
+
+   ```bash
+   command -v zizmor >/dev/null 2>&1 && zizmor --no-progress .github/workflows/ || \
+     echo "zizmor: not installed — recommend adding it (Security & Compliance gap)"
+   ```
+
+   Treat each `zizmor` finding (unpinned action refs, `pull_request_target`
+   misuse, over-broad `GITHUB_TOKEN` permissions, template-injection sinks) as
+   a Security & Compliance finding at the severity `zizmor` assigns.
+
+3. **Container linting (`hadolint`), presence-gated on Dockerfiles.** Only when
+   the change set (or repo) contains a `Dockerfile*`:
+
+   ```bash
+   command -v hadolint >/dev/null 2>&1 && hadolint <Dockerfile paths> || \
+     echo "hadolint: not installed — recommend adding it (Security & Compliance gap)"
+   ```
+
+4. **Pipeline reliability history (`gh run list`).** Cite real durations and
+   failure rates rather than guessing which steps are slow or flaky:
+
+   ```bash
+   gh run list --limit 50 --json conclusion,durationMs,workflowName,createdAt 2>/dev/null || \
+     echo "gh run history unavailable — Performance/Reliability findings degrade to config-only reasoning"
+   ```
+
+   Compute the failure rate (`failure` + `cancelled` / total) and the p50/p95
+   duration per workflow; a workflow whose recent failure rate is non-trivial
+   or whose p95 duration is an outlier is a Reliability or Performance finding
+   with the observed number cited in **Current State**.
+
+Then read the surfaces the battery flags plus the standing config set:
+CI/CD pipelines (`.github/workflows/`, `.gitlab-ci.yml`, `azure-pipelines.yml`),
+dependency/script manifests (`package.json`, `pnpm-workspace.yaml`), lint/format
+configs (`.eslintrc*`, `.prettierrc*`, `biome.json`, `tsconfig.json`), and git
+hooks / commit standards (`.husky/`, `commitlint.config.js`).
 
 ## Step 2: Analysis Dimensions
 
-Evaluate the gathered context against the following dimensions:
+Evaluate the battery output and gathered context against the following
+dimensions. The three **presence-gated sub-steps** (Dockerfile, IaC, Release
+pipeline) run only when their surface is present in the change set or repo —
+when absent, state "not present in scope" and skip.
 
 1. **Redundancy & Duplication:** Overlapping tools or conflicting rules (e.g.,
    Prettier vs. ESLint formatting, duplicated scripts in `package.json` and CI).
 2. **Performance Gaps:** Bottlenecks in CI/CD, slow caching strategies, or
-   unoptimized hooks (e.g., missing `lint-staged`).
+   unoptimized hooks (e.g., missing `lint-staged`) — cite the `gh run list`
+   durations from Step 1.
 3. **Security & Compliance:** Missing secret scanning, loose permissions (e.g.,
    `GITHUB_TOKEN` scopes), outdated or vulnerable dependency resolution
-   strategies.
+   strategies — grounded in the `zizmor` output.
 4. **Standardization & Modernization:** Opportunities to consolidate tooling
    (e.g., migrating to unified tools like Biome) or extract inline
-   configurations into dedicated dotfiles.
+   configurations into dedicated dotfiles; include any absent-scanner gaps
+   surfaced in Step 1.
 5. **Reliability & Resilience:** Fragile pipeline steps, missing error handling,
-   silent failures, or lack of retries for network-dependent tasks.
+   silent failures, or lack of retries for network-dependent tasks — cite the
+   `gh run list` failure rates from Step 1.
+
+### Sub-step A — Dockerfile hardening (gated: `Dockerfile*` present)
+
+Audit each Dockerfile for the standard hardening set: a pinned, digest-or-tag
+base image (never `:latest`), a non-root `USER`, multi-stage builds that keep
+build tooling out of the runtime image, no secrets baked into layers
+(`ARG`/`ENV` for credentials), a `HEALTHCHECK`, and `.dockerignore` coverage.
+Ground every finding in the `hadolint` output from Step 1.
+
+### Sub-step B — Infrastructure-as-Code (gated: `*.tf` / `infra/**` / k8s manifests present)
+
+Audit IaC for hardcoded secrets and account IDs, over-permissive IAM / security
+groups (`0.0.0.0/0` ingress, wildcard actions), unpinned module/provider
+versions, missing remote state locking, and resources provisioned without
+encryption-at-rest. Recommend `tflint` / `checkov` / `tfsec` where the scanner
+is absent.
+
+### Sub-step C — Release & deployment pipeline (gated: release/deploy workflow present)
+
+Audit the release path for an unpinned or mutable deployment action, missing
+environment protection rules / required reviewers on the production
+environment, absent rollback or canary strategy, and publish steps that run
+without provenance / SLSA attestation. Cite the `gh run list` history for the
+release workflow's reliability.
 
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-devops-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
 # DevOps Infrastructure Audit Report
 
@@ -83,15 +161,18 @@ highlight the most critical overarching themes from the findings.]
 
 ## 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]
 
 - **Dimension:** [e.g., Security & Compliance]
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [What is currently configured in the codebase]
 - **Recommendation & Rationale:** [The specific fix and why it improves the
   system]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a green CI run, a hardened config lint, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this fix independently]`
 
@@ -108,3 +189,13 @@ Phase 3: Modernization / Tech Debt.]
 
 Do NOT execute any code modifications, edit files, create branches, or install
 packages. This is strictly a read-only analysis. 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.

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

@@ -70,56 +70,12 @@ 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-documentation.workflow.js` fans the semantic
-  dimensions below out as parallel read-only subagents — each agent walks
-  the full target set per doc for its dimension — runs an **adversarial
-  verify** stage (an independent agent re-checks every stale-claim finding
-  against the current code and drops claims it cannot reproduce — doc
-  staleness is notoriously false-positive-prone), 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. Step 1's
-  deterministic checkers still run in the calling session (the analysis
-  subagents are read-only and cannot execute them); their results are
-  passed to the workflow as the `deterministicFindings` input and folded
-  into the synthesis.
-- **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.
+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 1: Deterministic Signal First
 
@@ -245,6 +201,9 @@ Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-documentation-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
 # Documentation Audit Report
 
@@ -261,16 +220,19 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
 
 ## 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 doc the finding lives in:]
 
-### [Short Title of the Issue]
+### `path/to/primary-doc.md` — [Short title of the issue]
 
 - **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity | History Bloat | Contradiction | Authority Drift]
-- **Impact:** [High | Medium | Low] — for a Context Economy finding, this is the base severity **after** any read-tier escalation (Step 2.5); state the doc's tier in Current State.
+- **Impact:** [Critical | High | Medium | Low] — for a Context Economy finding, this is the base severity **after** any read-tier escalation (Step 2.5); state the doc's tier in Current State.
+- **Location:** `path/to/primary-doc.md:line`
 - **Current State:** [The doc, the exact claim, and what the code actually
   does — cite file paths and lines on both sides]
 - **Recommendation & Rationale:** [The specific doc edit (or generator
   rerun) and why it restores accuracy]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. `npm run docs:check` passing, the corrected claim now matching the code, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this doc fix independently]`
 ```
@@ -301,3 +263,13 @@ This workflow is **read-only** with respect to the repository: run the
 deterministic checkers in `--check` mode only, and do not edit any
 documentation or code. The single write is the report artifact. Provide the
 analysis and remediation prompts; do not apply changes.
+
+## 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-navigability.md

@@ -69,17 +69,19 @@ exemption never lets a foreign Epic's change set leak into a scoped lens.
 
 Read the consumer's navigability config (resolved from `.agentrc.json`):
 
-- `delivery.quality.navigability.routeGlobs` — globs identifying the
-  route-adding files / route tree (e.g. `pages/**`, `app/**/route.ts`). Drives
-  both the route-tree enumeration here and the plan-persist draft
-  reachability gate
-  ([`plan-reachability.js`](../scripts/lib/orchestration/plan-reachability.js)).
-- `delivery.quality.navigability.navRegistry` — path(s) to the consumer's
-  nav-registry SSOT this lens reads.
-
-If **neither** `routeGlobs` nor `navRegistry` is present, emit a one-line
-"navigability not configured — skipped" note and exit without findings. Do
-**not** invent a route tree or guess a nav registry.
+- `planning.navigation.routeGlobs` — globs identifying the route-adding files /
+  route tree (e.g. `pages/**`, `app/**/route.ts`). This is the same key the
+  plan-persist draft reachability gate
+  ([`plan-reachability.js`](../scripts/lib/orchestration/plan-reachability.js))
+  reads via `resolveNavConfig`, so the lens and the plan gate enumerate the
+  route tree from one SSOT.
+- `planning.navigation.navRegistry` — path(s) to the consumer's nav-registry
+  SSOT this lens reads.
+
+If **neither** `routeGlobs` nor `navRegistry` is present under
+`planning.navigation`, emit a one-line "navigability not configured — skipped"
+note and exit without findings. Do **not** invent a route tree or guess a nav
+registry.
 
 ## Step 1: Enumerate the route tree
 
@@ -93,20 +95,61 @@ only** — never the full route body or any persona PII.
 Read every nav door from the `navRegistry` SSOT. Record each door's target
 path and the persona shell it renders in.
 
-## Step 3: Cross-check (the two invariants)
+## Step 3: Run the deterministic cross-check
 
-1. **Every route has a persona nav door.** For each enumerated route, assert at
-   least one nav-registry entry surfaces it for an entitled persona. A route
-   with no door for any of its personas is an **orphaned route**.
-2. **No nav href is dead.** For each nav door, assert its target resolves to a
-   real route in the route tree. A door whose target is absent is a **dead nav
-   href**.
+The two invariants are a **set-difference over two identifier lists**, not a
+judgement call — so run them mechanically rather than eyeballing the two files.
+Serialize the enumerated route tree (Step 1) and nav registry (Step 2) to two
+JSON files and run the shipped diff tool:
+
+```bash
+node .agents/scripts/nav-registry-diff.js \
+  --routes <routes.json> --nav <nav-registry.json> [--refs <inbound-refs.json>] --json
+```
+
+It prints, deterministically, the two invariants:
+
+1. **Every route has a persona nav door.** A route no door surfaces for an
+   entitled persona is an **orphaned route** (`orphanedRoutes`).
+2. **No nav href is dead.** A door whose target resolves to no route is a
+   **dead nav href** (`deadHrefs`).
+
+The tool also returns `exemptRoutes` — routes it verified are _not_ genuine
+orphans (see Step 3a). **Triage the tool's output**: promote each
+`orphanedRoutes` / `deadHrefs` entry to a Detailed Finding, and do not report
+anything the tool placed in `exemptRoutes`.
+
+## Step 3a: Orphan-verification exemption taxonomy
+
+A naive route-minus-nav set-difference over-reports. Before an unsurfaced route
+is reported as orphaned, it must survive this exemption taxonomy (the diff tool
+applies it, and you MUST apply the same reasoning to anything you assess by
+hand):
+
+- **Dynamic-segment children of a surfaced parent** — a detail route such as
+  `/users/:id` (or `/blog/[slug]`) is reached _through_ its surfaced parent
+  list, so it is exempt when its parent path has a nav door. It is **not** exempt
+  when the parent itself is unsurfaced.
+- **System routes** — `/login`, `/logout`, `/register`, `/auth/callback`,
+  `/404`, `/401`, `/403`, `/500`, `/unauthorized`, `/forbidden`, and similar are
+  reachable by construction (auth walls, error boundaries), never through a
+  persona nav door.
+- **Inbound in-app references** — a route linked from within the app (a
+  `<Link to="…">`, a programmatic `router.push`, an in-content anchor) is
+  reachable even without a top-level nav door. Grep the source for an inbound
+  reference before reporting the route as orphaned; feed the referenced paths to
+  the tool via `--refs`.
+
+Only a route that clears **all** of these is a genuine orphan worth a finding.
 
 ## Step 4: Output Requirements
 
 Generate and save a structured Markdown audit report to
 `{{auditOutputDir}}/audit-navigability-results.md`, using the template below.
 
+> Grade every finding's severity on the shared
+> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
+
 ```markdown
 # Navigability Audit report
 
@@ -116,19 +159,22 @@ Generate and save a structured Markdown audit report to
 
 ## Detailed Findings
 
-[For every orphaned route or dead nav href, use the following strict
-structure:]
+[For every orphaned route or dead nav href, use the following strict structure.
+Lead each title with the primary file (route module or nav registry) the
+finding lives in:]
 
-### [Short Title of the Issue]
+### `path/to/nav-registry-or-route.ext` — [Short title of the issue]
 
 - **Dimension:** [Orphaned Route | Dead Nav Href]
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/nav-registry-or-route.ext:line`
 - **Route / Door:** [the route path or nav-door identifier — identifier only]
 - **Persona(s):** [the persona(s) affected]
 - **Current State:** [why the route is unreachable or the href is dead]
 - **Recommendation & Rationale:** [the nav-registry change that restores
   reachability — add a door for the orphaned route, or fix/remove the dead
   href]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a re-run of this lens reporting the route reachable]
 - **Agent Prompt:**
   `[A copy-pasteable, specific prompt to execute the nav-registry fix.]`
 ```
@@ -138,3 +184,13 @@ structure:]
 This is a **read-only** audit. Provide the critique and the nav-registry fixes,
 but do not modify the route tree or the nav registry. Log route and door
 identifiers only — never full route bodies, source contents, or persona data.
+
+## 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.