mandrel 2.4.0 → 2.5.0

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

@@ -18,56 +18,12 @@ existing external APIs or business logic.
 
 ## 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-architecture.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.
+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.
 
 ## Scope (Story / plan-run mode)
 
@@ -90,6 +46,56 @@ before this section existed.
   proceed with the full codebase-wide scan defined in the remaining
   steps.
 
+## Step 0: Tool-first detection (mandatory — run before any LLM dimension)
+
+Ground every structural finding in a measured instrument this repo already
+ships rather than free-associating over the source. Run the shipped checkers
+**first** and treat their output as the spine of the report; the LLM
+dimensions in Step 2 only *interpret, rank, and phrase* what the tools
+surface. Skipping this step and reasoning about boundaries from prose alone is
+the failure mode this lens exists to prevent.
+
+1. **Cycle detection.** Run the shipped circular-dependency checker:
+
+   ```bash
+   node .agents/scripts/check-arch-cycles.js
+   ```
+
+   Each reported cycle is a grounded finding under the **Automated
+   Architecture Guardrails** dimension. When the shipped checker is
+   unavailable in the consumer project, fall back to
+   `npx madge --circular <srcDir>` or
+   `npx depcruise --validate <config> <srcDir>` (dependency-cruiser).
+
+2. **Dead-export detection.** Run the shipped dead-export checker:
+
+   ```bash
+   node .agents/scripts/check-dead-exports.js
+   ```
+
+   Each unreferenced export is a grounded candidate. **Cede it** to
+   audit-clean-code's Dead Code dimension rather than re-deriving it here (see
+   the deferral in Step 2). When the shipped checker is unavailable, fall back
+   to `npx knip --production` — and heed the `!`-suffix entry-pattern caveat
+   that [`audit-clean-code`](audit-clean-code.md) documents, since
+   `knip --production` is a silent no-op without it.
+
+3. **Hotspot ranking.** Rank the modules the checkers implicate by
+   **fan-in / fan-out** (how many modules import a file versus how many it
+   imports) and by **churn** (e.g.
+   `git log --format= --name-only -n 200 | sort | uniq -c | sort -rn`). A file
+   that is both heavily depended upon and frequently churned is the
+   highest-priority structural hotspot; lead the Triage Summary with it.
+
+4. **LLM triage on top.** Only after the tools have run do you apply the Step 2
+   dimensions to interpret, rank, and phrase the findings. A structural claim
+   that no tool grounds and no Step 2 dimension covers does not belong in this
+   report — route it to the ceded clean-code dimensions instead.
+
+When a shipped checker exits non-zero or is genuinely absent, record that as an
+**Automated Architecture Guardrails** finding (the guardrail is missing or
+broken) rather than skipping the step silently.
+
 ## 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`.
@@ -136,23 +142,19 @@ Structural Change can be Medium. As a loose default, Quick Wins typically land
 High (cheap to fix, real payoff) and Structural Changes Medium/High, but grade
 Impact on the risk itself rather than deriving it mechanically from Category.
 
-Evaluate the gathered context against the following clean code dimensions:
-
-1. **Over-Engineering & Abstractions:** Identify "dry-run" complexity, premature
-   optimizations, or interfaces/classes that add boilerplate without clear value
-   (e.g., interfaces with only one implementation).
-2. **Cognitive Load & Nesting:** Pinpoint deeply nested logic (arrow code),
-   massive functions violating the Single Responsibility Principle (SRP), or
-   excessive cyclomatic complexity.
-3. **Dead Code & Redundancy:** Locate unused exports, redundant utility
-   functions that duplicate standard library features, or obsolete commented-out
-   code blocks.
-4. **Naming & Self-Documentation:** Find poorly named variables/functions,
-   inconsistent naming conventions, or areas that rely heavily on comments to
-   explain *what* the code does rather than *why*.
-5. **Coupling & Cohesion:** Spot tight coupling between modules that should be
-   independent or god-objects handling too many concerns.
-6. **Testable Surface (Humble-Object Boundary):** Flag modules that interleave
+> **Ceded to audit-clean-code.** The five clean-code-overlapping dimensions
+> this lens historically enumerated — Over-Engineering & Abstractions,
+> Cognitive Load & Nesting, Dead Code & Redundancy, Naming &
+> Self-Documentation, and Coupling & Cohesion — are now owned by
+> [`audit-clean-code`](audit-clean-code.md). Do **not** duplicate them here: a
+> smell in one of those five belongs in the clean-code report, and the
+> dead-export candidates from Step 0 flow into audit-clean-code's Dead Code
+> dimension. This lens keeps only the two structural dimensions no other lens
+> owns — the testable-surface boundary and the automated-guardrail maturity.
+
+Evaluate the gathered context against the following architecture dimensions:
+
+1. **Testable Surface (Humble-Object Boundary):** Flag modules that interleave
    hard-to-test I/O — filesystem (`fs`), process spawning (`child_process`,
    `exec`, `spawn`), network calls, database access, or GUI/terminal
    rendering — directly with business logic. The humble-object /
@@ -189,7 +191,7 @@ Evaluate the gathered context against the following clean code dimensions:
    thin `runAsCli` shell — not the logic — owns the `process.exit` side effect,
    keeping the wrapped logic exercisable under a stubbed `process.exit`. Cite
    that precedent where it applies rather than restating it.
-7. **Automated Architecture Guardrails:** Assess whether the project encodes
+2. **Automated Architecture Guardrails:** Assess whether the project encodes
    its architectural boundaries as **deterministic, automated checks** rather
    than relying on convention or reviewer memory. When relevant to the
    consumer project's shape, evaluate enforcement for:
@@ -245,6 +247,9 @@ Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-architecture-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
 # Architecture & Clean Code Review
 
@@ -297,16 +302,19 @@ marked `n/a`.]
 
 ## 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]
 
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
 - **Category:** [Quick Win | Structural Change]
 - **Dimension:** [e.g., Cognitive Load & Nesting | Testable Surface (Humble-Object Boundary) | Automated Architecture Guardrails]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [The specific file/function and why it is problematic]
 - **Recommendation & Rationale:** [The specific refactor strategy and how it
   improves readability or maintainability]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a maintainability-index re-check, `npm test`, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this refactor independently. Must explicitly state NOT to change external APIs.]`
 ```
@@ -318,3 +326,13 @@ marked `n/a`.]
 Do NOT execute any code modifications, edit files, create branches, or implement
 changes. This is strictly a read-only analysis. Ensure all recommendations
 preserve existing functionality and external APIs. 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-clean-code.md

@@ -38,56 +38,74 @@ 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-clean-code.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.
+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: Tool-first detection (mandatory — measure before you judge)
+
+Ground the maintainability, duplication, and dead-code findings in the exact
+instruments this repo ships, then let the LLM triage in Steps 1–2 interpret and
+rank the numbers. Do **not** eyeball complexity or "spot" dead code from prose —
+run the tools first.
+
+1. **Complexity / maintainability (scoped mode).** When a change-set is in
+   scope, run the quality preview against the base:
+
+   ```bash
+   node .agents/scripts/quality-preview.js --changed-since <base>
+   ```
+
+   It reports the per-file maintainability-index and complexity deltas the
+   `check-baselines.js` gate enforces. Treat any per-file MI drop beyond
+   `delivery.quality.gates.maintainability.tolerance` (default 0.5pt) as a
+   grounded must-fix finding, and any cyclomatic reading over the
+   `codingGuardrails` ceilings (flag > 8, must-fix > 12) as measured, not
+   guessed.
+
+2. **Committed baselines (codebase-wide mode).** Read the committed metric
+   baselines under `baselines/` — `baselines/maintainability.json`,
+   `baselines/duplication.json`, `baselines/crap.json`,
+   `baselines/dead-exports.json` — and cite the outlier rows as evidence
+   rather than re-deriving them. These are the same artifacts the delivery
+   gates read, so a finding that quotes a baseline row is reproducible.
+
+3. **Duplication.** Run the shipped duplication checker
+   (`node .agents/scripts/check-baselines.js --gate duplication`, backed by
+   jscpd) and lift its clone clusters into the DRY dimension.
+
+4. **Dead code.** Run the shipped dead-export checker
+   (`node .agents/scripts/check-dead-exports.js`); it is backed by `knip`.
+   **`knip --production` is a silent no-op unless entry points are declared
+   with `!`-suffixed patterns** — a run that reports `{"issues":[]}` without
+   `!`-suffixed entries has measured nothing, so verify the entry config before
+   trusting a clean result. Apply the **dead-code exclusion taxonomy** below so
+   the report does not drown real dead code in false positives:
+
+   - **Entry points** — CLI mains, `bin/` scripts, and files named in
+     `package.json` `main` / `exports` / `bin`: reachable by definition, never
+     dead.
+   - **Public API surface** — exports that are the package's declared
+     `exports` / barrel contract: consumed out-of-tree, so a zero in-repo
+     importer count is not death.
+   - **Dynamic imports** — symbols reached via `import()`,
+     `require(variable)`, or string-keyed dispatch tables: invisible to static
+     export-graph analysis, so exclude unless you confirm no dynamic reference.
+   - **Test-only seams** — exports consumed only by tests (the sanctioned
+     `test-seams` pattern): flag as test-only, not dead, and never as a
+     production-dead finding.
+   - **Framework/registration hooks** — decorators, lifecycle listeners, and
+     files auto-loaded by convention (globbed listener/plugin dirs): reachable
+     via the framework, not the import graph.
+
+5. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
+   **churn × complexity** (frequently-changed files that also score poorly on
+   MI/CRAP) and **cap the Detailed Findings at the top ~15 hotspots** so the
+   report stays a ranked, actionable batch rather than an exhaustive dump. Note
+   the cap in the Executive Summary when it bites.
 
 ## Step 1: Quality Scan
 
@@ -139,6 +157,9 @@ Generate and save a highly structured Markdown audit report to
 `{{auditOutputDir}}/audit-clean-code-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
 # Clean Code Audit Report
 
@@ -149,15 +170,18 @@ primary 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 file the finding lives in:]
 
-### [Short Title of the Issue]
+### `path/to/primary-file.ext` — [Short title of the issue]
 
 - **Dimension:** [e.g., SOLID Principles | DRY | KISS | Dead Code]
-- **Impact:** [High | Medium | Low]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [Problematic code snippet, file, or pattern description]
 - **Recommendation & Rationale:** [The specific refactor strategy and how it
   improves long-term velocity]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a duplication re-check, `npm test`, or a re-run of this lens]
 - **Agent Prompt:**
   `[A copy-pasteable, highly specific prompt to execute this refactor independently]`
 
@@ -177,3 +201,13 @@ standards.]
 
 This workflow is **read-only**. Provide the analysis and the roadmap, but 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-data-model.md

@@ -0,0 +1,198 @@
+---
+description: Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, and access-pattern fit; gated by a persistence-layer applicability probe so DB-less repos skip cleanly.
+---
+
+# Data Model & Persistence Audit
+
+## Role
+
+Data Modeler & Database Reliability Engineer
+
+## Context & Objective
+
+Analyze the project's persistence layer — its ORM model definitions, the schema
+migrations those definitions are supposed to produce, and the seed data that
+populates them — as a first-class artifact. Your goal is to find where the
+model, the migrations, and the runtime schema silently disagree, where an
+invariant the application assumes is not actually enforced by a constraint, and
+where a migration is unsafe to run against a live database.
+
+This lens is **only applicable to a project that has a persistence layer.** A
+repository with no ORM dependency, no migrations directory, and no tracked
+`.prisma` / `.sql` schema files has nothing for this lens to read: resolve
+**not applicable** and emit the explicit not-applicable report (below) rather
+than empty findings. The applicability probe (`hasPersistenceLayer` in
+[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js), gated
+by `target: "data-model"` in
+[`schemas/audit-rules.json`](../schemas/audit-rules.json)) makes this decision
+automatically in `/deliver` and plan-run modes; in a manual invocation you MUST
+make the same determination yourself before reading anything else.
+
+## Scope (Story / plan-run mode)
+
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) 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 (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.
+
+In scoped mode, restrict analysis to the changed models and migrations plus
+their **direct dependents** — a model related to a changed model, a migration
+ordered after a changed one. A Story that adds a destructive migration is the
+canonical routed case: the change set names the migration and the models it
+rewrites, and this lens inspects exactly that surface.
+
+## Step 1: Applicability & Persistence-Surface 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`.
+
+First confirm the project **has a persistence layer** (see Context above). If it
+does not, stop and emit the not-applicable report. If it does, discover the
+persistence surface, preferring **tool-first** detection over hand-reading where
+the consumer ships the tooling:
+
+- **ORM drift tooling (preferred):** When the consumer ships an ORM CLI, run its
+  read-only drift/status command and treat its output as primary evidence —
+  `prisma migrate diff` / `prisma migrate status`, `drizzle-kit check`, or
+  `typeorm schema:log`. These report exactly where the model definitions and the
+  migration history disagree without a live database.
+- **Read-only file fallback:** When no ORM CLI is present (or it needs a live
+  database this audit must not touch), fall back to reading the model
+  definitions, the migration files, and the seed scripts directly. This
+  fallback is always available and never mutates state.
+- **Model & schema inventory:** Enumerate the ORM model/entity definitions and
+  the schema files (`schema.prisma`, `*.sql`, entity classes) they map to.
+- **Migration history:** Enumerate the ordered migration files and note which
+  are applied, pending, or manually edited after generation.
+- **Seed & fixture data:** Locate seed scripts and fixtures that assume a
+  particular shape, so drift against them surfaces too.
+
+## Step 2: Evaluation Dimensions
+
+Evaluate the persistence layer along these five dimensions:
+
+1. **Model↔migration↔seed drift:** Do the ORM model definitions match the schema
+   the migrations actually produce, and do the seeds/fixtures match both? Flag a
+   column, index, enum, or relation present in the model but never migrated (or
+   migrated but dropped from the model), and seed data that would violate the
+   current schema.
+2. **Constraint completeness:** Is every invariant the application code silently
+   assumes actually enforced by a constraint? Flag missing foreign-key, unique,
+   not-null, and check constraints; stringly-typed columns that should be a
+   database enum; orphanable relations with no FK or cascade rule; and
+   cascade-delete behavior that is either missing (orphans) or too aggressive
+   (unintended wide deletes).
+3. **Migration hygiene:** Is each migration safe to run against a live database?
+   Flag irreversible/destructive steps (a `DROP` / data-losing change with no
+   documented rollback), non-null columns added without a default or a backfill,
+   **expand-contract** violations (a single migration that both adds and removes
+   in a way that breaks a rolling deploy), and ordering/idempotency hazards that
+   make a migration unsafe to re-run or apply out of order.
+4. **Type fidelity:** Do column types match the domain? Flag money stored as a
+   float (rounding loss), timezone-less timestamps, bare-string IDs where a
+   typed/UUID column belongs, and over-wide or under-wide numeric types.
+5. **Access-pattern fit:** Does the schema fit how the code queries it? Flag
+   unindexed foreign keys and unindexed frequent filter columns, relations that
+   force N+1 access, and soft-delete rows that leak through default queries
+   because no default scope excludes them.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-data-model-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).
+
+When the project **has a persistence layer**, use the findings template:
+
+```markdown
+# Data Model & Persistence Audit Report
+
+## Executive Summary
+
+[Overview of the persistence layer's health, plus the `kept <k> / dropped <d>`
+self-cross-check counts from the mandatory step below.]
+
+## Detailed Findings
+
+[For every issue identified, use the following strict structure. Lead each
+title with the primary file the issue lives in:]
+
+### `path/to/migration-or-model.ext` — [Short title of the issue]
+
+- **Dimension:** [e.g., Drift | Constraint Completeness | Migration Hygiene | Type Fidelity | Access-Pattern Fit]
+- **Impact:** [Critical | High | Medium | Low]
+- **Location:** `path/to/migration-or-model.ext:line`
+- **Current State:** [Technical explanation of the drift, missing constraint,
+  or unsafe migration step — cite the model definition and the migration it
+  disagrees with]
+- **Recommendation & Rationale:** [The specific corrective migration or
+  constraint, and the failure it prevents]
+- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. `prisma migrate status` clean, a constraint present in the schema, or a re-run of this lens]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this fix independently]`
+
+## Low-Hanging Fruit
+
+- [List up to 3 low-risk schema/constraint fixes that provide immediate safety gains.]
+```
+
+When the project has **no persistence layer**, emit the explicit
+not-applicable report instead — never empty findings — and stop:
+
+```text
+# Data Model & Persistence Audit Report
+
+## Executive Summary
+
+**Not applicable** — this project has no persistence layer (no ORM dependency,
+no migrations directory, and no tracked `.prisma` / `.sql` schema files), so the
+data-model lens has nothing to inspect and was skipped.
+
+## Detailed Findings
+
+_None — lens not applicable._
+```
+
+## Constraint
+
+This is a **read-only** audit over repo-observable state only — schema files,
+migrations, ORM config, and read-only ORM drift/status commands. It MUST NOT
+connect to, read from, or mutate a production database; it MUST NOT run a
+migration or a destructive ORM command. API-contract/serialization coverage is
+out of scope (deferred `audit-contract-compat` territory), and runtime query
+profiling belongs to `audit-performance`, which owns measured behavior.
+
+## 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.