mandrel 1.57.0

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

@@ -0,0 +1,110 @@
+---
+description: Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps.
+---
+
+# DevOps Infrastructure Audit
+
+## Role
+
+Principal DevOps Engineer & Infrastructure Architect
+
+## Context & Objective
+
+You are performing a comprehensive, read-only audit of this repository's DevOps
+infrastructure, developer experience (DX) tooling, and CI/CD pipelines. Your
+goal is to identify inefficiencies, security risks, and areas for modernization
+without making any immediate changes.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Step 1: Context Gathering (Read-Only Scan)
+
+> 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:
+
+- 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`).
+
+## Step 2: Analysis Dimensions
+
+Evaluate the gathered context against the following dimensions:
+
+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`).
+3. **Security & Compliance:** Missing secret scanning, loose permissions (e.g.,
+   `GITHUB_TOKEN` scopes), outdated or vulnerable dependency resolution
+   strategies.
+4. **Standardization & Modernization:** Opportunities to consolidate tooling
+   (e.g., migrating to unified tools like Biome) or extract inline
+   configurations into dedicated dotfiles.
+5. **Reliability & Resilience:** Fragile pipeline steps, missing error handling,
+   silent failures, or lack of retries for network-dependent tasks.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-devops-results.md`, using the exact template below.
+
+```markdown
+# DevOps Infrastructure Audit Report
+
+## Executive Summary
+
+[Provide a brief 2–3 sentence overview of the current infrastructure state and
+highlight the most critical overarching themes from the findings.]
+
+## Detailed Findings
+
+[For every gap identified, use the following strict structure:]
+
+### [Short Title of the Issue]
+
+- **Dimension:** [e.g., Security & Compliance]
+- **Impact:** [High | Medium | Low]
+- **Current State:** [What is currently configured in the codebase]
+- **Recommendation & Rationale:** [The specific fix and why it improves the
+  system]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this fix independently]`
+
+## Proposed Implementation Roadmap
+
+[Organize the recommended changes into a logical, phased approach — e.g., Phase
+1: Critical Security & Fixing Broken Builds, Phase 2: Performance Optimizations,
+Phase 3: Modernization / Tech Debt.]
+```
+
+---
+
+## Constraint
+
+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.

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

@@ -0,0 +1,260 @@
+---
+description: Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report
+---
+
+# Lighthouse Audit & Analysis
+
+## Role
+
+Senior Web Performance & Quality Engineer. You operate Lighthouse end-to-end:
+launch the run, parse the JSON, surface the highest-leverage findings across
+all four categories, and produce a structured report the operator can act on.
+
+## Context & Objective
+
+This is a **read-only** audit. Your job is to run Lighthouse, **parse and
+analyze the full result set** (scores, opportunities, diagnostics, per-audit
+failures), and emit a meaningful Markdown report at
+`{{auditOutputDir}}/audit-lighthouse-results.md`. Do not modify application
+code. The report's recommendations should be specific enough that a follow-up
+implementation pass (or the `/audit-performance` workflow) can act on them
+without re-running Lighthouse.
+
+**Target URL:** `[TARGET_URL]` — replace with the URL of a running build
+(e.g. `http://localhost:3000`, a preview deploy, or production). The dev
+server should be running in production mode where possible — dev-mode bundles
+inflate Performance scores misleadingly.
+
+**Form factor:** Run **Desktop** by default. If the project is mobile-first
+(check `viewport` meta, responsive CSS, or operator instruction), run
+**Mobile** instead and note the choice in the report.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Step 1: Pre-flight
+
+> 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. Confirm the target URL is reachable (HTTP 200) before invoking Lighthouse.
+   If the server is not running, stop and ask the operator to start it — do
+   not attempt to start arbitrary dev servers yourself.
+2. Confirm `{{auditOutputDir}}` exists. Create it if missing.
+3. Note the run context in the report header: URL, form factor, timestamp,
+   build mode (dev / prod / preview).
+
+## Step 2: Run Lighthouse
+
+Use the `mcp__chrome-devtools__lighthouse_audit` tool (available via the
+chrome-devtools MCP server) against `[TARGET_URL]`. Capture **all four
+categories**: Performance, Accessibility, Best Practices, SEO.
+
+If the chrome-devtools MCP server is unavailable, fall back to the
+`lighthouse` CLI:
+
+```bash
+npx lighthouse [TARGET_URL] \
+  --output=json --output=html \
+  --output-path={{auditOutputDir}}/lighthouse-raw \
+  --preset=desktop \
+  --chrome-flags="--headless --no-sandbox"
+```
+
+Save the raw JSON alongside the report so future runs can diff against it.
+
+If Lighthouse fails to launch (Chromium not found, port in use, target
+unreachable), stop and report the environmental issue. Do not silently
+continue with partial data.
+
+## Step 3: Parse & Analyze
+
+Extract and reason about the following from the JSON result:
+
+### 3a. Category scores
+
+| Category | Score (0-100) |
+| --- | --- |
+| Performance | — |
+| Accessibility | — |
+| Best Practices | — |
+| SEO | — |
+
+### 3b. Core Web Vitals & key metrics (Performance)
+
+Pull from `audits` and `categories.performance.auditRefs`:
+
+| Metric | Value | Score | Threshold (good / needs-improvement / poor) |
+| --- | --- | --- | --- |
+| Largest Contentful Paint (LCP) | — | — | ≤2.5s / ≤4.0s / >4.0s |
+| First Contentful Paint (FCP) | — | — | ≤1.8s / ≤3.0s / >3.0s |
+| Total Blocking Time (TBT) | — | — | ≤200ms / ≤600ms / >600ms |
+| Cumulative Layout Shift (CLS) | — | — | ≤0.1 / ≤0.25 / >0.25 |
+| Speed Index | — | — | ≤3.4s / ≤5.8s / >5.8s |
+| Time to Interactive (TTI) | — | — | ≤3.8s / ≤7.3s / >7.3s |
+| Interaction to Next Paint (INP, if present) | — | — | ≤200ms / ≤500ms / >500ms |
+
+### 3c. Failed audits & opportunities
+
+For each category, enumerate every audit where `score < 1` (or
+`score === null` with a non-pass `scoreDisplayMode`). Group into:
+
+- **Opportunities** (Performance only): items with measurable
+  `details.overallSavingsMs` or `overallSavingsBytes`. Rank by
+  `overallSavingsMs` desc.
+- **Diagnostics**: informational findings without estimated savings.
+- **Failed audits** (Accessibility / Best Practices / SEO): every audit
+  with `score < 1`. Include the affected nodes / URLs from `details.items`
+  where present (cap at 5 examples per finding to keep the report
+  readable).
+
+### 3d. Cross-cutting observations
+
+After enumerating, look for **patterns across audits** — not just per-audit
+failures. Examples:
+
+- Same third-party origin showing up in `third-party-summary`,
+  `render-blocking-resources`, and `network-rtt` → flag as a single
+  systemic issue, not three separate ones.
+- Multiple Accessibility failures all rooted in one shared component
+  (e.g. a design-system `<Button>` missing `aria-label`) → call that out
+  explicitly so the fix is one place, not twenty.
+- LCP element is an image with no `width`/`height` and a low priority hint
+  → connects LCP, CLS, and `unsized-images` into one fix.
+
+## Step 4: Generate the Report
+
+Write `{{auditOutputDir}}/audit-lighthouse-results.md` using the template
+below. The report MUST include all sections, even if empty (write
+"_No findings._" rather than omitting). Include the absolute path to the raw
+JSON / HTML so the operator can drill in.
+
+```markdown
+# Lighthouse Audit Report
+
+## Run Context
+
+- **URL:** [TARGET_URL]
+- **Form factor:** Desktop | Mobile
+- **Build mode:** prod | dev | preview
+- **Timestamp:** YYYY-MM-DDTHH:MM:SSZ
+- **Lighthouse version:** [from JSON `lighthouseVersion`]
+- **Raw artifacts:** `{{auditOutputDir}}/lighthouse-raw.report.json`,
+  `{{auditOutputDir}}/lighthouse-raw.report.html`
+
+## Category Scores
+
+| Category | Score | Verdict |
+| --- | --- | --- |
+| Performance | — / 100 | good (≥90) / needs-improvement (50-89) / poor (<50) |
+| Accessibility | — / 100 | … |
+| Best Practices | — / 100 | … |
+| SEO | — / 100 | … |
+
+## Core Web Vitals
+
+[Table from Step 3b, with verdict colour-word per row.]
+
+## Top Findings
+
+> Prioritized across all four categories by estimated impact. List the top
+> 5–10 here so the operator has a clear "fix these first" list. Each entry
+> must be specific enough to act on without re-opening Lighthouse.
+
+### 1. [Short title]
+
+- **Category:** Performance | Accessibility | Best Practices | SEO
+- **Audit ID:** [e.g. `unused-javascript`, `color-contrast`]
+- **Impact:** High | Medium | Low
+- **Estimated savings:** [e.g. "1.4s LCP / 320 KB transfer"] — omit for
+  non-Performance findings.
+- **Evidence:** [Specific files / selectors / nodes from `details.items`,
+  capped at 5 examples.]
+- **Recommendation:** [Concrete next step — file to edit, attribute to add,
+  config to change. No vague "consider optimizing".]
+
+[Repeat for each top finding.]
+
+## Performance — Full Breakdown
+
+### Opportunities (ranked by overallSavingsMs)
+
+| Audit | Savings | Bytes | Notes |
+| --- | --- | --- | --- |
+| … | … | … | … |
+
+### Diagnostics
+
+| Audit | Description | Notes |
+| --- | --- | --- |
+| … | … | … |
+
+## Accessibility — Failed Audits
+
+| Audit | Severity | Affected nodes (count) | Example |
+| --- | --- | --- | --- |
+| … | … | … | … |
+
+## Best Practices — Failed Audits
+
+[Same structure as Accessibility.]
+
+## SEO — Failed Audits
+
+[Same structure as Accessibility.]
+
+## Cross-Cutting Observations
+
+[From Step 3d. Patterns that span multiple audits / a single root cause
+showing up as several Lighthouse findings.]
+
+## Suggested Next Steps
+
+- [3–5 bullet points the operator can hand to a follow-up workflow
+  (`/audit-performance` for backend bottlenecks, manual fix passes for
+  per-component a11y violations, etc.) Each bullet should map to a finding
+  above by ID.]
+```
+
+## Step 5: Sanity-check the Report
+
+Before returning, re-read the generated report and verify:
+
+- Every category in Step 3a has a score (no dashes left as placeholders).
+- Every "Top Findings" entry has a concrete `Recommendation` — not a
+  generic "improve performance".
+- The raw artifact paths exist on disk.
+- Section "Cross-Cutting Observations" is non-empty if and only if the
+  result set actually contains overlapping findings (don't fabricate
+  patterns to fill the section — write "_No cross-cutting patterns
+  detected._" if there genuinely aren't any).
+
+## Constraints
+
+- **Read-only.** Do not modify application code, dependencies, or
+  configuration as part of this workflow. Surfacing fix recommendations is
+  the deliverable; applying them is a separate workflow.
+- **Single run.** One Lighthouse invocation per run of this workflow. Do
+  not loop — variance between runs is expected and a single snapshot is
+  sufficient for the report. If the operator wants a stability profile,
+  that's a different workflow (`/audit-performance`).
+- **No fabrication.** Every score, metric, and audit ID in the report must
+  trace back to the raw JSON. If a value is missing from the run (e.g.
+  INP often is), say so — don't invent it.

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

@@ -0,0 +1,161 @@
+---
+description: Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations.
+---
+
+# Performance & Bottleneck Audit
+
+## Role
+
+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.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Execution strategy (dual-path)
+
+This lens runs along one of two execution paths. Both emit the **identical**
+report contract (Step 3); downstream consumers (`/epic-deliver` Phase 4
+epic-audit, `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
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-performance-results.md`, using the exact template
+below.
+
+```markdown
+# Performance Audit Report
+
+## Executive Summary
+
+[Overview of performance summary vs target benchmarks.]
+
+## 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]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this optimization independently]`
+
+## Low-Hanging Fruit
+
+- [List 3 quick changes that provide immediate performance gains.]
+```
+
+## 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.

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

@@ -0,0 +1,104 @@
+---
+description: Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps.
+---
+
+# Privacy and PII Data Audit
+
+## Role
+
+Data Privacy Officer & Security Engineer
+
+## Context & Objective
+
+You are conducting a privacy audit to identify potential mishandling of
+Personally Identifiable Information (PII) and ensure compliance with data
+protection standards (GDPR, CCPA). Your goal is to find accidental logging,
+insecure storage, or unnecessary collection of sensitive data.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Step 1: Scanning for PII Patterns
+
+> 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.
+
+## Step 2: Analysis Dimensions
+
+Evaluate the codebase against these privacy pillars:
+
+1. **Data Minimization:** Is the application collecting more PII than strictly
+   necessary for its functions?
+2. **Leaky Logging:** Are sensitive objects being logged to stdout/stderr or
+   external logging services?
+3. **Insecure Transmission:** Is PII sent over non-TLS connections or via GET
+   parameters?
+4. **Hardcoded Secrets:** Are there any API keys, salts, or credentials stored
+   in plain text?
+5. **Consent & Retention:** Check for logic related to data deletion (Right to
+   be Forgotten) and consent management.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-privacy-results.md`, using the exact template below.
+
+```markdown
+# Privacy & PII Audit Report
+
+## Executive Summary
+
+[Overview of the privacy posture and critical risks identified.]
+
+## Privacy Scorecard
+
+- **Data Encryption:** [Pass/Fail/Partial]
+- **Logging Safety:** [Pass/Fail/Partial]
+- **Minimization:** [Pass/Fail/Partial]
+
+## Detailed Findings
+
+[For every gap identified, use the following strict structure:]
+
+### [Short Title of the Issue]
+
+- **Type:** [Leaky Log | Insecure Storage | Data Over-collection]
+- **Impact:** [Critical | High | Medium | Low]
+- **Current State:** [The specific file/line/module and why it is problematic]
+- **Recommendation & Rationale:** [How to remediate and why it's necessary for
+  compliance]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
+```
+
+## Constraint
+
+This is a **read-only** audit. Do not modify any code. Focus on identifying
+risks and providing clear remediation steps.