mandrel 2.3.0 → 2.5.0

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

@@ -38,89 +38,98 @@ 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-security.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 1: Vulnerability Surface Analysis
+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.
+
+## Rubric — `rules/security-baseline.md` is the contract
+
+This lens does **not** grade against recalled OWASP lore. The authoritative
+rubric is [`../rules/security-baseline.md`](../rules/security-baseline.md) — the
+project's inviolable security MUSTs (Input Validation, Authentication,
+Authorization, Output & Rendering, Data Leakage & Logging, Transport & Headers,
+Secrets Management, Dependency Hygiene). Read it first. **Every finding MUST
+name the specific `security-baseline.md` MUST it violates** (e.g. "violates
+_Secrets Management_: 'Fallback or placeholder secrets MUST NOT be committed'").
+A finding that cannot be tied to a baseline MUST — or to a CWE where the
+baseline is silent — is out of scope for this lens.
+
+## Step 1: Detection Battery (Tool-First, Read-Only)
 
 > 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:
-
-- **Input Validation:** Check where user input enters the system (API endpoints,
-  forms). Is it sanitized/validated?
-- **Injection Risks:** Search for raw SQL queries, `dangerouslySetInnerHTML`,
-  `eval()`, or command execution logic.
-- **Authentication/Authorization:** Review how sessions/tokens are handled. Are
-  there missing checks on sensitive routes?
-- **Dependency Security:** Check `package.json` for known-vulnerable versions of
-  libraries.
-- **Secret Management:** Scan for `.env` files in git, hardcoded keys, or
-  exposed credentials.
+Ground every finding in tool output, not vibes. Run the ladder below; each rung
+is **presence-gated** — when a scanner is absent, fall through to the next rung
+and note the missing tool as a `Security Misconfiguration` finding (recommend
+adopting it).
+
+1. **Dependency CVEs (`npm audit`).** Never recall CVEs from memory:
+
+   ```bash
+   npm audit --omit=dev --json 2>/dev/null || echo "npm audit unavailable"
+   ```
+
+   Each advisory reachable in production (`--omit=dev`) at `high` or `critical`
+   is a _Vulnerable Components_ finding citing the advisory id and the violated
+   _Dependency Hygiene_ MUST.
+
+2. **Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.** When
+   `gitleaks` is installed, prefer it:
+
+   ```bash
+   command -v gitleaks >/dev/null 2>&1 && gitleaks detect --no-banner --redact -v || \
+     command -v trufflehog >/dev/null 2>&1 && trufflehog filesystem . --no-update || \
+     echo "no secret scanner installed — running the grep battery below"
+   ```
+
+3. **Grep battery (deterministic fallback / augmentation).** Run these
+   regardless — they are cheap and catch what a scanner's ruleset may miss:
+
+   ```bash
+   # Hardcoded key material (violates Secrets Management)
+   rg -n -i "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"]{8,}" --glob '!**/*.test.*'
+   # eval / exec sinks (violates Output & Rendering)
+   rg -n "\b(eval|new Function|child_process\.exec|execSync)\s*\(" --glob '!**/*.test.*'
+   # Template-literal SQL (violates Output & Rendering — parameterize)
+   rg -n "(SELECT|INSERT|UPDATE|DELETE)\b[^;]*\$\{" -i
+   # Committed .env with real values (violates Secrets Management)
+   git ls-files | rg "(^|/)\.env($|\.)" | rg -v "\.env\.example$"
+   ```
+
+4. **Manual surface review.** Then read the surfaces the battery flags plus:
+   input-validation edges (API endpoints, form handlers — is input validated at
+   the boundary with a strict schema?), auth/session handling (token storage,
+   missing ownership checks on sensitive routes), and injection sinks
+   (`dangerouslySetInnerHTML`, raw SQL, command execution).
 
 ## Step 2: Evaluation Dimensions
 
-1. **Injection:** SQL, NoSQL, OS Command, and Cross-Site Scripting (XSS).
-2. **Broken Access Control:** Can a user access data they don't own?
+Grade each finding against the `security-baseline.md` MUST it breaks (and the
+CWE where one applies):
+
+1. **Injection:** SQL, NoSQL, OS Command, and Cross-Site Scripting (XSS) —
+   _Output & Rendering_.
+2. **Broken Access Control:** Can a user access data they don't own? —
+   _Authorization_.
 3. **Cryptographic Failures:** Is sensitive data (passwords, PII) hashed or
-   encrypted using modern standards?
+   encrypted using modern standards? — _Authentication_ / _Data Leakage &
+   Logging_.
 4. **Security Misconfiguration:** Are there default passwords, verbose error
-   messages in production, or insecure headers?
-5. **Vulnerable Components:** Are outdated libraries introducing risks?
+   messages in production, or insecure headers? — _Transport & Headers_.
+5. **Vulnerable Components:** Are outdated libraries introducing risks? —
+   _Dependency Hygiene_.
 
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-security-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
 # Security Audit Report
 
@@ -131,16 +140,20 @@ security posture.]
 
 ## Detailed Findings
 
-[For every vulnerability identified, use the following strict structure:]
+[For every vulnerability identified, use the following strict structure. Lead
+each title with the primary file the vulnerability lives in:]
 
-### [Short Title of the Vulnerability]
+### `path/to/primary-file.ext` — [Short title of the vulnerability]
 
 - **Dimension:** [e.g., Injection | Broken Access Control]
 - **Severity:** [Critical | High | Medium | Low]
 - **CWE ID:** [e.g., CWE-89 for SQL Injection]
+- **Baseline MUST:** [the violated `security-baseline.md` MUST — e.g. "Secrets Management: fallback secrets MUST NOT be committed"]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [Technical explanation of the flaw and its location]
 - **Recommendation & Rationale:** [Step-by-step fix and defensive hardening
   strategy]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the exploit no longer reproducing, an added regression test, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
 
@@ -154,3 +167,13 @@ security posture.]
 
 This is a **read-only** audit. Your priority is accuracy and clear impact
 assessment. Do not attempt to exploit the system or modify code.
+
+## 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-seo.md

@@ -49,41 +49,79 @@ before this section existed.
   proceed with the full codebase-wide scan defined in the remaining
   steps.
 
-## Step 1: Context Gathering (Read-Only Scan)
+## Step 0: Indexability gate (run 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`.
+**Open every SEO audit by deciding whether the surface is meant to be indexed at
+all.** SEO findings on an auth-walled, private, or internal surface are noise —
+a login-gated dashboard is *supposed* to be invisible to crawlers, so a missing
+`<meta name="description">` there is not a defect.
+
+- **Auth-walled / private surface** (every route under the change set sits
+  behind an authentication guard, a `noindex` directive, or a `Disallow`-all
+  `robots.txt`) ⇒ record a single **"SEO not applicable — surface is not
+  indexable"** note and stop. Do not emit per-file findings.
+- **Publicly indexable surface** (marketing pages, docs, blog, product pages, a
+  public app shell) ⇒ proceed to Step 1.
+- **Mixed** ⇒ scope the remaining steps to the indexable routes only, and say so
+  in the Executive Summary.
 
-Before generating the report, silently scan the codebase. Pay special attention
-to:
+## Step 1: Framework-aware metadata detection matrix
+
+> 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`.
 
-- Page `<head>` elements: `<title>`, `<meta name="description">`, canonical
-  tags, Open Graph, and Twitter Card tags.
-- Semantic HTML structure: heading hierarchy (`h1`–`h6`), landmark elements
-  (`<main>`, `<nav>`, `<article>`, `<section>`), and `<img alt>` attributes.
-- Structured data: JSON-LD blocks and Schema.org types in use.
-- Internal linking patterns and URL structure.
-- Content layout: answer-friendly formatting (FAQs, numbered steps, definition
-  lists) vs. dense prose.
+Modern web consumers almost never ship literal `<head><meta></head>` HTML — the
+metadata is produced by a framework mechanism. **Identify the mechanism first,
+then probe the surfaces that mechanism uses.** Reporting "no `<meta>` tags found"
+on a Next.js app that sets them through `generateMetadata` is a false finding.
+
+- **Step 1a — Identify the meta mechanism.** Determine which one (or more) of the
+  following the consumer uses, from its dependencies and source layout:
+
+  | Framework / library | Metadata mechanism | Where to probe |
+  | --- | --- | --- |
+  | Next.js (App Router) | `metadata` export / `generateMetadata()` | `app/**/{layout,page}.{js,jsx,ts,tsx}` |
+  | Next.js (Pages Router) | `next/head` `<Head>` | `pages/**/*.{js,jsx,ts,tsx}` |
+  | React (generic) | `react-helmet` / `react-helmet-async` | components importing `Helmet` |
+  | Vue / Nuxt | `@unhead/vue` / `useHead()` / `nuxt.config` `head` | `*.vue`, `nuxt.config.*` |
+  | Svelte / SvelteKit | `<svelte:head>` | `*.svelte` |
+  | Astro | frontmatter `<head>` in layouts | `*.astro` |
+  | Plain static | literal `<head>` HTML | `*.html` |
+
+- **Step 1b — Enumerate the routes.** Take the route list from the navigability
+  `routeGlobs` SSOT (the same route tree the navigability lens enumerates), not
+  from a guess. Each public route is a page whose metadata you assess.
+- **Step 1c — Per-route metadata probe.** For each indexable route, assert the
+  detected mechanism supplies: a `<title>`, a meta description, canonical URL,
+  Open Graph / Twitter Card tags, and (where relevant) JSON-LD structured data.
+  A route whose mechanism sets none of these is a real finding.
 
 ## Step 2: Analysis Dimensions
 
 Evaluate the gathered context against the following dimensions:
 
-1. **Traditional SEO:** Meta tags, semantic structure, accessibility, internal
-   linking logic, and keyword placement.
+1. **Traditional SEO:** Meta mechanism coverage (per Step 1), semantic structure,
+   heading hierarchy, `<img alt>`, internal linking logic, and canonical URLs.
 2. **AIO & GEO (Answer Engine Optimization):** Entity clarity, concise answer
    formatting, structured data (Schema.org), and token efficiency for LLM
    retrieval.
-3. **Core Web Vitals:** CLS, LCP, and INP risk factors visible from the codebase
-   (e.g., unsized images, render-blocking resources, large layout shifts).
-4. **Crawlability:** `robots.txt`, `sitemap.xml`, and any `noindex` directives
-   that may unintentionally block pages.
+3. **Statically-provable Core Web Vitals defects only:** flag *code-visible*
+   regressions — unsized images or media embeds (CLS risk), render-blocking synchronous
+   scripts, and fonts loaded without `display=swap`. **Do not estimate or score
+   measured CWV** (LCP/INP/CLS numbers): measured Core Web Vitals are owned by
+   the `audit-performance` lens — defer them there explicitly rather than
+   guessing a score from source.
+4. **Crawlability:** `robots.txt`, `sitemap.xml` (including generated
+   `sitemap.*`/`robots.*` route handlers), and any `noindex` directives that may
+   unintentionally block indexable pages.
 
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-seo-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
 # SEO & GEO Audit Report
 
@@ -94,9 +132,13 @@ primary gaps and the most impactful opportunities.]
 
 ## Detailed Audit Table
 
-| Issue               | Impact           | Category   | Suggested Fix |
-| ------------------- | ---------------- | ---------- | ------------- |
-| [Issue description] | High / Med / Low | SEO or GEO | [Brief fix]   |
+[A supplementary at-a-glance index only. Every row MUST also have a full
+`## Detailed Findings` entry below — the Detailed Findings blocks are the
+machine-parsed source of record; this table is not parsed.]
+
+| Issue               | Impact                      | Category   | Suggested Fix |
+| ------------------- | --------------------------- | ---------- | ------------- |
+| [Issue description] | Critical / High / Med / Low | SEO or GEO | [Brief fix]   |
 
 ## GEO-Specific Recommendations
 
@@ -106,16 +148,19 @@ reformatting key content as FAQ blocks.]
 
 ## Detailed Findings
 
-[For any issue requiring deeper explanation, use the following strict
-structure:]
+[Mandatory: emit one entry per issue in the Detailed Audit Table above, using
+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:** [SEO | GEO | Core Web Vitals | Crawlability]
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [What exists in the codebase and why it's suboptimal]
 - **Recommendation & Rationale:** [The specific fix and how it improves
   discoverability or LLM retrieval]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the meta tag now present in the rendered head, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this fix independently]`
 ```
@@ -126,3 +171,13 @@ structure:]
 
 Do NOT rewrite or modify any files. Do NOT implement the changes. Focus strictly
 on analyzing the code. 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-sre.md

@@ -10,9 +10,10 @@ Senior Site Reliability Engineer (SRE) & Lead Developer
 
 ## Context & Objective
 
-You are conducting a rigorous, read-only final code audit for a production
-release candidate. Your goal is to surface critical risks across configuration
-integrity, security, observability, and code quality — providing a prioritized,
+You are conducting a rigorous, read-only operational-readiness audit for a
+production release candidate. Your goal is to surface critical risks across
+rollback & recovery paths, observability & instrumentation, resilience &
+failure handling, and runbooks & operational docs — providing a prioritized,
 actionable report that can be handed off for remediation before deployment.
 
 ## Scope (Story / plan-run mode)
@@ -36,69 +37,89 @@ 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: Resilience 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. Pay special attention
-to:
-
-- Application configuration files (e.g., `site.config.ts`, `.env.example`,
-  `wrangler.toml`, `app.config.ts`).
-- Source files for hardcoded values (strings resembling secrets, IDs, or
-  environment-specific data).
-- Error handling patterns across services, API routes, and background jobs.
-- `package.json` for unused, deprecated, or overly heavy dependencies.
-- Any debugging artifacts likely introduced during development.
+This lens audits **operational readiness** — can this release be observed,
+survive failure, and be rolled back? It deliberately does **not** re-audit
+secrets, injection, dead code, or complexity; those are owned by
+[`audit-security`](audit-security.md) and [`audit-clean-code`](audit-clean-code.md).
+Ground findings in the greps below, then read the operational surfaces they
+flag.
+
+1. **Run the resilience battery.** Each grep maps to a Step 2 dimension:
+
+   ```bash
+   # Network calls without a timeout (a hung upstream stalls the whole request)
+   rg -n "\b(fetch|axios(\.\w+)?|http\.request|got|ky)\s*\(" --glob '!**/*.test.*' | \
+     rg -v -i "timeout|signal|AbortController"
+   # Graceful-shutdown handlers (their ABSENCE is the finding for long-lived processes)
+   rg -n "process\.on\(\s*['\"]SIG(TERM|INT)['\"]" || echo "no SIGTERM/SIGINT handler found"
+   # Error-swallowing empty catch blocks (silent failure — no signal to observe)
+   rg -n "catch\s*(\([^)]*\))?\s*\{\s*\}"
+   # Retry / backoff on network-dependent work (resilience to transient failure)
+   rg -n -i "retr(y|ies)|backoff|circuit.?breaker|p-retry"
+   # Health / readiness endpoints (needed for orchestrated rollout & rollback)
+   rg -n -i "/(health|healthz|readyz|livez|ping)\b|healthCheck"
+   ```
 
 ## Step 2: Analysis Dimensions
 
-Evaluate the gathered context against the following production-readiness
-criteria:
-
-### 1. Configuration Architecture
-
-- **Config Integrity:** Audit the application config to ensure it defines a
-  clear schema for all variable/environment-specific data.
-- **Hardcoding Scan:** Scan components, utils, and services for any hardcoded
-  values that should come from config or environment variables (e.g., API URLs,
-  feature flags, region/locale data, identifiers).
-- **Fallback Logic:** Verify how the app behaves if a required config value is
-  missing — does it fail gracefully or crash silently?
-
-### 2. Security & Secrets Management
-
-- **Secret Leaks:** Check for hardcoded API keys, tokens, or credentials
-  committed to source. Ensure all secrets use environment variables.
-- **Input Sanitization:** Identify potential XSS or injection vectors,
-  particularly where user input or URL parameters are reflected in the DOM or
-  database.
-- **Dependency Risks:** Flag obviously deprecated, unmaintained, or unused heavy
-  dependencies in `package.json`.
-
-### 3. Error Handling & Observability
-
-- **Console Hygiene:** Identify debugging artifacts (`console.log`, `debugger`,
-  commented-out test code) that must be removed before release.
-- **Error Swallowing:** Flag empty `catch` blocks or places where errors are
-  silently ignored rather than logged or re-thrown.
-- **Boundary Handling:** Ensure the app handles unexpected or invalid inputs
-  (e.g., bad URL params, missing DB records) with appropriate error responses.
-
-### 4. Code Quality & Performance
-
-- **Dead Code:** Identify unused variables, imports, functions, or unreachable
-  code blocks.
-- **Complexity:** Highlight logic with high cyclomatic complexity (deeply nested
-  `if/else`, massive switch statements) that violates DRY principles.
-- **Asset Loading:** Flag synchronous heavy operations or unoptimized asset
-  loading patterns that could hurt Core Web Vitals or API response times.
+Evaluate the release candidate against these **production-readiness** criteria.
+
+### 1. Rollback & Recovery Paths
+
+- **Rollback Path:** Is there a defined, tested way to revert this release —
+  a versioned deploy, blue-green/canary, or a documented `git revert` + redeploy
+  path? A release with no rollback path is a Critical finding.
+- **Migration Reversibility:** Any schema migration in scope must ship a
+  down-migration (or a documented forward-fix); an irreversible destructive
+  migration blocks the release.
+- **Feature-Flag Kill Switch:** Risky new behaviour should sit behind a flag
+  that can be disabled without a redeploy.
+
+### 2. Observability & Instrumentation
+
+- **Structured Logging:** Are operational events emitted through a structured
+  logger (levels, correlation ids) rather than bare `console.*`, so they are
+  queryable in production?
+- **Metrics & Tracing:** Are latency/error/throughput metrics and trace spans
+  emitted for the new code path? Missing instrumentation on a critical path is
+  a High finding.
+- **Alerting & SLOs:** Is there an SLO (or error budget) and an alert wired to
+  the signals above, so a regression pages someone?
+
+### 3. Resilience & Failure Handling
+
+- **Timeouts & Cancellation:** Every outbound call needs a timeout /
+  `AbortSignal` (grep 1 in Step 1). A call without one is a Reliability finding.
+- **Retry & Backoff:** Transient-failure-prone calls should retry with backoff;
+  flag network work that fails hard on the first error.
+- **Graceful Shutdown:** Long-lived processes must handle `SIGTERM`/`SIGINT`
+  and drain in-flight work (grep 2). Its absence risks dropped requests on
+  every deploy.
+- **Error Boundaries:** Empty `catch` blocks (grep 3) swallow failures with no
+  signal — flag each as an Observability + Resilience finding.
+
+### 4. Runbooks & Operational Docs
+
+- **Runbook Coverage:** Does an operational runbook exist for this
+  service/feature (how to deploy, roll back, and respond to the top failure
+  modes)? A new production surface with no runbook is a finding.
+- **Health & Readiness:** Are health/readiness endpoints (grep 5) present and
+  wired into the orchestrator so a bad rollout is caught before it takes
+  traffic?
+- **On-Call Escalation:** Is ownership / escalation for this surface documented?
 
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-sre-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
 # Production Release Candidate Audit
 
@@ -107,28 +128,30 @@ Generate and save a highly structured Markdown audit report to
 [A brief overview of the release candidate's health. Highlight the most critical
 risks that must be resolved before deployment.]
 
-## Findings
+## Detailed Findings
 
-[Group findings by the categories below. Use this structure for each item:]
+[Group findings by the categories below. Use this structure for each item.
+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:** [Configuration | Security | Observability | Code Quality]
-- **Severity:** [High | Medium | Low]
-- **Location:** [`path/to/file.ts` or relevant area]
+- **Category:** [Rollback & Recovery | Observability | Resilience | Runbooks]
+- **Severity:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [What exists and why it's a risk]
 - **Recommendation:** [The specific fix and rationale]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. `npm test`, a grep that now returns empty, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this fix independently]`
 
 ## Release Readiness Checklist
 
-| Category                | Status                     |
-| ----------------------- | -------------------------- |
-| Configuration Integrity | ✅ Clear / ⚠️ Issues Found |
-| Security & Secrets      | ✅ Clear / ⚠️ Issues Found |
-| Error Handling          | ✅ Clear / ⚠️ Issues Found |
-| Code Quality            | ✅ Clear / ⚠️ Issues Found |
+| Category             | Status                     |
+| -------------------- | -------------------------- |
+| Rollback & Recovery  | ✅ Clear / ⚠️ Issues Found |
+| Observability        | ✅ Clear / ⚠️ Issues Found |
+| Resilience           | ✅ Clear / ⚠️ Issues Found |
+| Runbooks             | ✅ Clear / ⚠️ Issues Found |
 ```
 
 ---
@@ -137,3 +160,13 @@ risks that must be resolved before deployment.]
 
 Do NOT generate code fixes, edit files, or create branches. 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.