mandrel 2.78.0 → 2.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +8 -3
  3. package/.agents/audit-checklists/architecture.md +1 -0
  4. package/.agents/audit-checklists/clean-code.md +1 -0
  5. package/.agents/audit-checklists/data-model.md +9 -1
  6. package/.agents/audit-checklists/devops.md +4 -1
  7. package/.agents/audit-checklists/security.md +1 -1
  8. package/.agents/docs/agentrc-reference.json +3 -0
  9. package/.agents/docs/configuration.md +2 -2
  10. package/.agents/docs/workflows.md +1 -1
  11. package/.agents/schemas/agentrc.schema.json +20 -2
  12. package/.agents/schemas/audit-rules.json +5 -1
  13. package/.agents/scripts/bootstrap.js +87 -16
  14. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  15. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  16. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  17. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  18. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  19. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  20. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  21. package/.agents/scripts/lib/config/explain.js +3 -2
  22. package/.agents/scripts/lib/config-settings-schema.js +20 -2
  23. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  24. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  25. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  26. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  27. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  28. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  29. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
  30. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
  31. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  32. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  33. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  34. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  35. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  36. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  37. package/.agents/scripts/lib/test-run-credit.js +46 -17
  38. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  39. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  40. package/.agents/workflows/audit-architecture.md +20 -4
  41. package/.agents/workflows/audit-clean-code.md +17 -1
  42. package/.agents/workflows/audit-data-model.md +94 -10
  43. package/.agents/workflows/audit-devops.md +58 -14
  44. package/.agents/workflows/audit-performance.md +22 -0
  45. package/.agents/workflows/audit-quality.md +30 -0
  46. package/.agents/workflows/audit-security.md +23 -8
  47. package/.agents/workflows/audit-to-stories.md +22 -7
  48. package/.agents/workflows/helpers/audit-lens-core.md +56 -7
  49. package/.agents/workflows/helpers/plan-reference.md +11 -3
  50. package/README.md +13 -1
  51. package/docs/CHANGELOG.md +24 -0
  52. package/lib/cli/registry.js +85 -12
  53. package/lib/cli/uninstall.js +34 -18
  54. package/lib/cli/update.js +37 -6
  55. package/lib/migrations/index.js +2 -0
  56. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  57. package/package.json +1 -1
@@ -9,6 +9,11 @@
9
9
 
10
10
  import path from 'node:path';
11
11
 
12
+ import {
13
+ resolveTestCommand,
14
+ resolveTestGateArgv,
15
+ } from './close-validation/commands.js';
16
+ import { resolveConfig } from './config-resolver.js';
12
17
  import { gitSpawn as defaultGitSpawn } from './git-utils.js';
13
18
  import {
14
19
  recordPass as defaultRecordPass,
@@ -19,11 +24,36 @@ import {
19
24
 
20
25
  const GATE_NAME = 'test';
21
26
 
22
- /** Must hash identically to the command close spawns. */
23
- const GATE_COMMAND = Object.freeze({
24
- cmd: 'npm',
25
- args: Object.freeze(['test']),
26
- });
27
+ /**
28
+ * The `test` credit identity. It must hash identically to the argv close
29
+ * spawns, so both derive from {@link resolveTestGateArgv}
30
+ * (`project.commands.test`, default `npm test`).
31
+ *
32
+ * @param {object|null|undefined} config - Resolved config; null → the default.
33
+ * @param {string} cwd
34
+ * @returns {string}
35
+ */
36
+ function testGateConfigHash(config, cwd) {
37
+ const { cmd, args } = resolveTestGateArgv(config);
38
+ return hashCommandConfig({ cmd, args, cwd: path.resolve(cwd) });
39
+ }
40
+
41
+ /**
42
+ * The injected config, else the checkout's resolved config, or null (→ the
43
+ * `npm test` default) when it cannot be read — a deposit never fails the run.
44
+ *
45
+ * @param {object|null|undefined} config
46
+ * @param {string} cwd
47
+ * @returns {object|null}
48
+ */
49
+ function depositConfig(config, cwd) {
50
+ if (config !== undefined) return config;
51
+ try {
52
+ return resolveConfig({ cwd });
53
+ } catch {
54
+ return null;
55
+ }
56
+ }
27
57
 
28
58
  /**
29
59
  * @param {Function} gitSpawnFn
@@ -73,9 +103,11 @@ export function resolveEvidenceRoot(cwd, gitSpawnFn) {
73
103
  * tier?: string,
74
104
  * status?: number,
75
105
  * durationMs?: number|null,
106
+ * config?: object|null,
76
107
  * gitSpawnFn?: typeof defaultGitSpawn,
77
108
  * recordPassFn?: typeof defaultRecordPass,
78
109
  * }} args
110
+ * `config` defaults to the checkout's resolved config.
79
111
  * @returns {{ deposited: boolean, reason: string, storyId?: number, sha?: string }}
80
112
  */
81
113
  export function depositTestRunCredit({
@@ -83,6 +115,7 @@ export function depositTestRunCredit({
83
115
  tier = 'full',
84
116
  status = 0,
85
117
  durationMs = null,
118
+ config,
86
119
  gitSpawnFn = defaultGitSpawn,
87
120
  recordPassFn = defaultRecordPass,
88
121
  } = {}) {
@@ -102,6 +135,7 @@ export function depositTestRunCredit({
102
135
  storyId,
103
136
  sha,
104
137
  cwd,
138
+ config: depositConfig(config, cwd),
105
139
  evidenceRoot,
106
140
  durationMs,
107
141
  gitSpawnFn,
@@ -134,6 +168,7 @@ export function reportTestRunCredit({
134
168
  * Every uncertainty resolves `false`.
135
169
  *
136
170
  * @param {{
171
+ * config?: object|null,
137
172
  * storyId?: number|null,
138
173
  * cwd?: string,
139
174
  * evidenceCwd?: string|null,
@@ -144,6 +179,7 @@ export function reportTestRunCredit({
144
179
  * @returns {boolean}
145
180
  */
146
181
  export function predictsTestEvidenceCredit({
182
+ config,
147
183
  storyId,
148
184
  cwd,
149
185
  evidenceCwd,
@@ -161,18 +197,14 @@ export function predictsTestEvidenceCredit({
161
197
  storyId,
162
198
  gateName: GATE_NAME,
163
199
  currentSha: sha,
164
- configHash: hashCommandConfig({
165
- cmd: GATE_COMMAND.cmd,
166
- args: [...GATE_COMMAND.args],
167
- cwd: path.resolve(cwd),
168
- }),
200
+ configHash: testGateConfigHash(config, cwd),
169
201
  inputFingerprint: treeFingerprint(cwd, gitSpawnImpl),
170
202
  },
171
203
  { cwd: evidenceCwd ?? cwd, standalone: true },
172
204
  );
173
205
  if (verdict.skip !== true) return false;
174
206
  log?.(
175
- '[close-validation] a green `npm test` already deposited the test credit for this tree — registering the plain `test` gate so close reports it as credited.',
207
+ `[close-validation] a green \`${resolveTestCommand(config)}\` already deposited the test credit for this tree — registering the plain \`test\` gate so close reports it as credited.`,
176
208
  );
177
209
  return true;
178
210
  } catch {
@@ -181,13 +213,14 @@ export function predictsTestEvidenceCredit({
181
213
  }
182
214
 
183
215
  /**
184
- * @param {{ storyId: number, sha: string, cwd: string, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
216
+ * @param {{ storyId: number, sha: string, cwd: string, config: object|null, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
185
217
  * @returns {{ deposited: boolean, reason: string, storyId: number, sha: string }}
186
218
  */
187
219
  function writeRecord({
188
220
  storyId,
189
221
  sha,
190
222
  cwd,
223
+ config,
191
224
  evidenceRoot,
192
225
  durationMs,
193
226
  gitSpawnFn,
@@ -199,11 +232,7 @@ function writeRecord({
199
232
  storyId,
200
233
  gateName: GATE_NAME,
201
234
  sha,
202
- configHash: hashCommandConfig({
203
- cmd: GATE_COMMAND.cmd,
204
- args: [...GATE_COMMAND.args],
205
- cwd: path.resolve(cwd),
206
- }),
235
+ configHash: testGateConfigHash(config, cwd),
207
236
  exitCode: 0,
208
237
  durationMs,
209
238
  inputFingerprint: treeFingerprint(cwd, gitSpawnFn),
@@ -2,12 +2,15 @@
2
2
  * lib/wave-runner/footprint.js — whether two Stories' declared footprints
3
3
  * intersect. The footprint is the declaration only: paths scraped from
4
4
  * titles, specs or prose manufactured far more serialisation than they
5
- * prevented, so two Stories collide only when both declare a path (or one
6
- * declares a glob). Reads and mutates nothing.
5
+ * prevented, so two Stories collide only when both declare a path, one
6
+ * declares a glob covering the other's path, or both declare globs whose
7
+ * static bases overlap. Reads and mutates nothing.
7
8
  *
8
9
  * @module lib/wave-runner/footprint
9
10
  */
10
11
 
12
+ import picomatch from 'picomatch';
13
+
11
14
  /**
12
15
  * One class today; kept on the envelope so consumers keyed on `source` stay
13
16
  * stable if a second class appears.
@@ -45,37 +48,118 @@ export function storyFootprint(story) {
45
48
  * @param {string} path
46
49
  * @returns {boolean}
47
50
  */
48
- function isGlobPath(path) {
51
+ export function isGlobPath(path) {
49
52
  return path.includes('*') || path.includes('?') || path.includes('{');
50
53
  }
51
54
 
55
+ const GLOB_OPTIONS = Object.freeze({ dot: true });
56
+
57
+ /**
58
+ * The glob's static directory prefix — `''` for a glob such as `**` or
59
+ * `*.md` that is rooted nowhere.
60
+ *
61
+ * @param {string} glob
62
+ * @returns {string}
63
+ */
64
+ function globBase(glob) {
65
+ return picomatch.scan(glob).base;
66
+ }
67
+
68
+ /**
69
+ * Whole-segment prefix overlap: `lib` covers `lib/x`, never `libs`. An empty
70
+ * base overlaps everything.
71
+ *
72
+ * @param {string} x
73
+ * @param {string} y
74
+ * @returns {boolean}
75
+ */
76
+ function basesOverlap(x, y) {
77
+ if (x === '' || y === '' || x === y) return true;
78
+ const [short, long] = x.length < y.length ? [x, y] : [y, x];
79
+ return long.startsWith(`${short}/`);
80
+ }
81
+
52
82
  /**
53
- * A glob is unknown width, not no width: exact-string comparison would pass
54
- * `lib/**` alongside a file beneath it, so a glob collides with everything.
83
+ * Whether two globs may match a common path, judged by their static bases.
84
+ * Conservative by design: two globs sharing a base may still be disjoint
85
+ * (`lib/*.js` vs `lib/*.md`), and the predicate serializes them anyway.
55
86
  *
56
- * @param {Set<string>} hits
57
- * @param {Set<string>} side
87
+ * @param {string} g
88
+ * @param {string} h
89
+ * @returns {boolean}
58
90
  */
59
- function collectGlobs(hits, side) {
60
- for (const path of side) {
61
- if (isGlobPath(path)) hits.add(path);
91
+ export function globsOverlap(g, h) {
92
+ return basesOverlap(globBase(g), globBase(h));
93
+ }
94
+
95
+ /**
96
+ * Record that `side` declared `path` as a colliding path.
97
+ *
98
+ * @param {Map<string, Set<string>>} hits
99
+ * @param {string} path
100
+ * @param {'a'|'b'} side
101
+ */
102
+ function addHit(hits, path, side) {
103
+ const sides = hits.get(path) ?? new Set();
104
+ sides.add(side);
105
+ hits.set(path, sides);
106
+ }
107
+
108
+ /**
109
+ * Collect the globs on `globSide` that cover a concrete path or overlap a
110
+ * glob on `otherSide`. A glob hit reports the glob — the thing an author
111
+ * edits — never the concrete path it matched.
112
+ *
113
+ * @param {Map<string, Set<string>>} hits
114
+ * @param {{ globs: string[], concrete: string[] }} mine
115
+ * @param {{ globs: string[], concrete: string[] }} theirs
116
+ * @param {'a'|'b'} side
117
+ */
118
+ function collectGlobHits(hits, mine, theirs, side) {
119
+ for (const glob of mine.globs) {
120
+ const matches = picomatch(glob, GLOB_OPTIONS);
121
+ const covers =
122
+ theirs.concrete.some((path) => matches(path)) ||
123
+ theirs.globs.some((other) => globsOverlap(glob, other));
124
+ if (covers) addHit(hits, glob, side);
62
125
  }
63
126
  }
64
127
 
128
+ /**
129
+ * @param {Set<string>} footprint
130
+ * @returns {{ globs: string[], concrete: string[] }}
131
+ */
132
+ function partition(footprint) {
133
+ const globs = [];
134
+ const concrete = [];
135
+ for (const path of footprint)
136
+ (isGlobPath(path) ? globs : concrete).push(path);
137
+ return { globs, concrete };
138
+ }
139
+
65
140
  /**
66
141
  * Colliding paths, or `null`. An empty footprint never collides —
67
142
  * withholding on absence would serialize every run.
68
143
  *
144
+ * Two footprints collide on a concrete path both declare, on a glob that
145
+ * matches a concrete path the other side declares, or on two globs whose
146
+ * static bases overlap. The `**` UNKNOWN sentinel therefore collides with
147
+ * every non-empty footprint by construction: it matches every concrete path
148
+ * and its empty base overlaps every glob.
149
+ *
69
150
  * `concreteOnly` is for the cross-beat reservation: an in-flight Story holds
70
151
  * its footprint for hours, and unparseable bodies resolve to an UNKNOWN glob
71
152
  * sentinel, so honouring globs there would make one bad Story serialize the
72
153
  * whole run. The beat-local guard honours globs.
73
154
  *
155
+ * `declaredBy` maps each colliding path to the side that declared it —
156
+ * `'a'`, `'b'` or `'both'` — so a refusal can name its declarer.
157
+ *
74
158
  * @param {object} a
75
159
  * @param {object} b
76
160
  * @param {object} [options]
77
161
  * @param {boolean} [options.concreteOnly=false] Skip glob paths on both sides.
78
- * @returns {{ paths: string[], source: string }|null}
162
+ * @returns {{ paths: string[], source: string, declaredBy: Record<string, 'a'|'b'|'both'> }|null}
79
163
  */
80
164
  export function detectCollision(a, b, { concreteOnly = false } = {}) {
81
165
  const fa = storyFootprint(a);
@@ -83,14 +167,27 @@ export function detectCollision(a, b, { concreteOnly = false } = {}) {
83
167
  const fb = storyFootprint(b);
84
168
  if (fb.size === 0) return null;
85
169
 
86
- const hits = new Set();
87
- for (const path of fa) {
88
- if (!isGlobPath(path) && fb.has(path)) hits.add(path);
170
+ const pa = partition(fa);
171
+ const pb = partition(fb);
172
+ /** @type {Map<string, Set<string>>} */
173
+ const hits = new Map();
174
+ for (const path of pa.concrete) {
175
+ if (fb.has(path)) {
176
+ addHit(hits, path, 'a');
177
+ addHit(hits, path, 'b');
178
+ }
89
179
  }
90
180
  if (!concreteOnly) {
91
- collectGlobs(hits, fa);
92
- collectGlobs(hits, fb);
181
+ collectGlobHits(hits, pa, pb, 'a');
182
+ collectGlobHits(hits, pb, pa, 'b');
93
183
  }
94
184
  if (hits.size === 0) return null;
95
- return { paths: [...hits].sort(), source: OVERLAP_SOURCES.DECLARED };
185
+ const paths = [...hits.keys()].sort();
186
+ const declaredBy = Object.fromEntries(
187
+ paths.map((path) => {
188
+ const sides = hits.get(path);
189
+ return [path, sides.size === 2 ? 'both' : [...sides][0]];
190
+ }),
191
+ );
192
+ return { paths, source: OVERLAP_SOURCES.DECLARED, declaredBy };
96
193
  }
@@ -83,9 +83,9 @@ export function classifyStory(story) {
83
83
 
84
84
  /**
85
85
  * Beat-local overlap guard: `true` when two footprints intersect. A glob
86
- * (unknown width) overlaps everything, since exact-string comparison would
87
- * otherwise pass two Stories that really race; this fail-safe is beat-local
88
- * only.
86
+ * collides with every path it can match and with any glob whose static base
87
+ * overlaps its own, so the `**` UNKNOWN sentinel still collides with every
88
+ * declared footprint; honouring globs is beat-local only.
89
89
  *
90
90
  * @param {StoryRecord} a
91
91
  * @param {StoryRecord} b
@@ -282,6 +282,17 @@ function blockingCollision({ rec, id, selected, reserved, evidence }) {
282
282
  return peer ? { ...peer, scope: WITHHOLD_SCOPES.BEAT } : null;
283
283
  }
284
284
 
285
+ /**
286
+ * A withhold row keeps `paths` and `source` only — the ledger shape predates
287
+ * the collision's `declaredBy` attribution.
288
+ *
289
+ * @param {number|null} blockedBy
290
+ * @param {{ paths: string[], source: string }} collision
291
+ */
292
+ function blockerRow(blockedBy, { paths, source }) {
293
+ return { blockedBy, paths, source };
294
+ }
295
+
285
296
  /**
286
297
  * The same-beat peer this candidate would race, with the colliding paths, so
287
298
  * an unfilled slot is never unexplained.
@@ -294,7 +305,7 @@ function blockingCollision({ rec, id, selected, reserved, evidence }) {
294
305
  function findBeatBlocker(candidate, selected, options = {}) {
295
306
  for (const picked of selected) {
296
307
  const collision = detectCollision(picked, candidate, options);
297
- if (collision) return { blockedBy: storyIdOf(picked), ...collision };
308
+ if (collision) return blockerRow(storyIdOf(picked), collision);
298
309
  }
299
310
  return null;
300
311
  }
@@ -315,7 +326,7 @@ function findInFlightBlocker(candidate, candidateId, reserved, options = {}) {
315
326
  const heldId = storyIdOf(held);
316
327
  if (heldId === null || heldId === candidateId) continue;
317
328
  const collision = reservesConcretePath(held, candidate, options);
318
- if (collision) return { blockedBy: heldId, ...collision };
329
+ if (collision) return blockerRow(heldId, collision);
319
330
  }
320
331
  return null;
321
332
  }
@@ -75,14 +75,30 @@ the failure mode this lens exists to prevent.
75
75
  that is both heavily depended upon and frequently churned is the
76
76
  highest-priority structural hotspot; lead the Triage Summary with it.
77
77
 
78
- 4. **LLM triage on top.** Only after the tools have run do you apply the Step 2
78
+ 4. **Non-JS ecosystems.** Detect ecosystems per the core's
79
+ [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
80
+ run each detected one's rung (absent scanner = Low `Standardization` gap;
81
+ undetected ecosystem = inapplicable, never a finding). **Python:**
82
+
83
+ ```bash
84
+ pydeps <package> --show-cycles --no-output # import graph / cycles
85
+ lint-imports # import-linter layer contracts
86
+ vulture <srcDir> # dead-export / dead-wiring candidates
87
+ radon cc -s -n C <srcDir> # testable surface: complex units to check for interleaved I/O
88
+ ```
89
+
90
+ Rank Python hotspots by fan-in / fan-out from the `pydeps` graph exactly as
91
+ step 3 does. Go and Rust use the core's fallback table.
92
+
93
+ 5. **LLM triage on top.** Only after the tools have run do you apply the Step 2
79
94
  dimensions to interpret, rank, and phrase the findings. A structural claim
80
95
  that no tool grounds and no Step 2 dimension covers does not belong in this
81
96
  report — route it to the ceded clean-code dimensions instead.
82
97
 
83
- When a shipped checker exits non-zero or is genuinely absent, record that as an
84
- **Automated Architecture Guardrails** finding (the guardrail is missing or
85
- broken) rather than skipping the step silently.
98
+ When a checker for a **detected** ecosystem exits non-zero or is genuinely
99
+ absent, record that as an **Automated Architecture Guardrails** finding (the
100
+ guardrail is missing or broken) rather than skipping the step silently. A
101
+ checker for an undetected ecosystem is inapplicable and never a finding.
86
102
 
87
103
  ## Step 1: Context Gathering (Read-Only Scan)
88
104
 
@@ -81,7 +81,23 @@ run the tools first.
81
81
  files auto-loaded by convention (globbed listener/plugin dirs): reachable
82
82
  via the framework, not the import graph.
83
83
 
84
- 5. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
84
+ 5. **Non-JS ecosystems.** Detect ecosystems per the core's
85
+ [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
86
+ run each detected one's rung (absent scanner = Low `Standardization` gap;
87
+ undetected ecosystem = inapplicable, never a finding). **Python:**
88
+
89
+ ```bash
90
+ radon cc -s -a <srcDir> && radon mi -s <srcDir> # complexity / MI
91
+ pylint --disable=all --enable=duplicate-code <srcDir> # duplication (or jscpd)
92
+ vulture <srcDir> # dead code
93
+ ruff check --select E722,BLE,S110,N <srcDir> # silent failures, naming
94
+ ```
95
+
96
+ Apply the dead-code exclusion taxonomy above to `vulture` output too
97
+ (entry points, `__all__` exports, decorator-registered hooks). Go and Rust
98
+ use the core's fallback table.
99
+
100
+ 6. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
85
101
  **churn × complexity** (frequently-changed files that also score poorly on
86
102
  MI/CRAP) and **cap the Detailed Findings at the top ~15 hotspots** so the
87
103
  report stays a ranked, actionable batch rather than an exhaustive dump. Note
@@ -1,5 +1,5 @@
1
1
  ---
2
- 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.
2
+ description: Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-less repos skip cleanly.
3
3
  ---
4
4
 
5
5
  # Data Model & Persistence Audit
@@ -8,11 +8,15 @@ You are a Data Modeler & Database Reliability Engineer analyzing the persistence
8
8
  layer — ORM model definitions, the migrations they should produce, and the seed
9
9
  data — as a first-class artifact, finding where model, migrations, and runtime
10
10
  schema silently disagree, where an assumed invariant is not enforced by a
11
- constraint, and where a migration is unsafe against a live database. The shared lens machinery lives in
11
+ constraint, where a migration is unsafe against a live database, and where
12
+ schema exists that nothing uses. The shared lens machinery lives in
12
13
  [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
13
14
  `{{auditOutputDir}}/audit-data-model-results.md`. Dimension values:
14
15
  `Drift | Constraint Completeness | Migration Hygiene | Type Fidelity |
15
- Access-Pattern Fit`; the report adds a **Low-Hanging Fruit** section.
16
+ Access-Pattern Fit | Dead Schema`. Extra finding field: **Evidence:** (a
17
+ reference-count or introspection command plus a `measured`, `static`, or
18
+ `provisional` tag). The report adds a **Low-Hanging Fruit** section and a
19
+ **Live Schema Verification** section.
16
20
 
17
21
  ## Applicability
18
22
 
@@ -54,9 +58,13 @@ the consumer ships the tooling:
54
58
 
55
59
  - **ORM drift tooling (preferred):** When the consumer ships an ORM CLI, run its
56
60
  read-only drift/status command and treat its output as primary evidence —
57
- `prisma migrate diff` / `prisma migrate status`, `drizzle-kit check`, or
58
- `typeorm schema:log`. These report exactly where the model definitions and the
59
- migration history disagree without a live database.
61
+ `prisma migrate diff` / `prisma migrate status`, or `typeorm schema:log`. On
62
+ Drizzle, run `drizzle-kit generate --out <temp dir>` with the output pointed
63
+ under `{{auditOutputDir}}`: a non-empty generated migration is exactly the
64
+ model↔migration drift, and the repo's own migrations directory is never
65
+ written. Drizzle's snapshot-consistency check validates the snapshot chain,
66
+ not drift, so it is not drift evidence. None of these needs a live
67
+ database.
60
68
  - **Read-only file fallback:** When no ORM CLI is present (or it needs a live
61
69
  database this audit must not touch), fall back to reading the model
62
70
  definitions, the migration files, and the seed scripts directly. This
@@ -96,6 +104,73 @@ Evaluate the persistence layer along these five dimensions:
96
104
  unindexed foreign keys and unindexed frequent filter columns, relations that
97
105
  force N+1 access, and soft-delete rows that leak through default queries
98
106
  because no default scope excludes them.
107
+ 6. **Dead schema:** Is every table, column, index, and enum the schema defines
108
+ actually used, and does everything the code uses actually exist?
109
+ - **Unused schema:** a schema symbol with zero references in the **query
110
+ surface** — every source file minus the schema files themselves,
111
+ `**/migrations/**`, and seed/fixture files. A symbol referenced only from
112
+ tests is still reported, with that fact in Current State. Cite the
113
+ reference-count command in **Evidence**.
114
+ - **Schema gap:** the reverse — a table or column the code references that the
115
+ schema lacks. Unindexed foreign keys stay under Access-Pattern Fit.
116
+ - **Provisional until corroborated:** raw SQL strings, `select *`, and
117
+ JSON/builder access hide references from a static count, so a zero-count
118
+ finding is tagged `provisional` and never graded above Medium until the
119
+ live pass corroborates it.
120
+ - **Common identifiers are runtime-only:** a column whose name is a common
121
+ identifier (`id`, `name`, `createdAt`, `updatedAt`, and the like) matches
122
+ unrelated code, so the static pass never reports it.
123
+
124
+ The core's **Entry points & public API surface** and **Dynamic / framework
125
+ reachability** exclusions apply unchanged.
126
+
127
+ ## Step 3: Live Schema Verification (opt-in, manual runs only)
128
+
129
+ Static detection always runs; this pass corroborates it against a live
130
+ database. It reuses the shared scaffold in
131
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass) for
132
+ target resolution and the skip-never-fake rule. Scaffold steps 2 (route
133
+ sampling) and 4 (median-of-3) do not apply: schema introspection is
134
+ deterministic and has no routes.
135
+
136
+ **When it runs.** Only on a manual invocation — when the `{{changedFiles}}`
137
+ fence above is the literal token. A populated fence (a `/mandrel-deliver` close
138
+ lens or a plan-run audit) always reports `skipped — change-set scoped run`; a
139
+ database connection never enters the close gate.
140
+
141
+ **The target.** The resolved environment's `qa.environments.<env>.database`
142
+ block names the environment variable holding the connection string
143
+ (`urlEnv`) and opts the environment in (`allowAudit`). Read the connection
144
+ string from that variable only; never print, log, or write it into the report.
145
+
146
+ **The probe.** Run only these read-only steps:
147
+
148
+ - **Introspection diff:** introspect the live schema into
149
+ `{{auditOutputDir}}/live-schema/` with the ORM's read-only introspection
150
+ command (`drizzle-kit introspect`, or `prisma db pull` against a temp copy of
151
+ the schema file), then diff it against the committed schema. Each hunk is a
152
+ model↔live **Drift** finding tagged `measured`.
153
+ - **Migration ledger:** compare the repo's migration journal to the live
154
+ migrations table. Report applied-but-absent-from-repo, pending, and
155
+ hash-mismatched entries under **Migration Hygiene**.
156
+ - **Catalog statistics (Postgres):** read `pg_stat_user_tables` and
157
+ `pg_stat_user_indexes`. A table never scanned or an index never used
158
+ graduates the matching provisional **Dead Schema** finding to `measured`.
159
+ Columns have no catalog statistic and stay static. Note the statistics reset
160
+ time, since a recent reset makes zero scans meaningless.
161
+
162
+ **Skip reasons.** The pass is skipped, never faked, and the Executive Summary
163
+ names which:
164
+
165
+ | Condition | Reported as |
166
+ | --- | --- |
167
+ | The fence carries a change set | `skipped — change-set scoped run` |
168
+ | No `database` block on the resolved environment, or `allowAudit` is false | `skipped — no database target configured` |
169
+ | The variable is unset or the connection fails | `skipped — database unreachable` |
170
+ | No ORM introspection command is available | `skipped — ORM introspection unavailable` |
171
+
172
+ When no SQL client is on PATH, the catalog step alone reports `catalog client
173
+ unavailable` and Dead Schema findings stay provisional.
99
174
 
100
175
  ## Not-applicable report
101
176
 
@@ -118,9 +193,18 @@ _None — lens not applicable._
118
193
 
119
194
  ## Constraint (lens-specific carve-out)
120
195
 
121
- This lens is read-only over **repo-observable state only** — schema files,
122
- migrations, ORM config, and read-only ORM drift/status commands. It MUST NOT
123
- connect to, read from, or mutate a production database; it MUST NOT run a
124
- migration or a destructive ORM command. API-contract/serialization coverage is
196
+ This lens is read-only over repo-observable state — schema files, migrations,
197
+ ORM config, and read-only ORM drift/status commands — plus, in Step 3 only, an
198
+ opted-in database:
199
+
200
+ - It MUST NOT connect to a **production** database, under any configuration.
201
+ - It connects to any other database **only** when that environment opts in via
202
+ `allowAudit`, **only** through the environment variable named by `urlEnv`,
203
+ and **only** with read-only introspection and catalog `SELECT`s. Any direct
204
+ session it opens sets `default_transaction_read_only=on` first.
205
+ - It MUST NOT run a migration, a `push` / `migrate` / `generate` against the
206
+ live target, a destructive ORM command, or any statement that writes.
207
+ - Besides the report, its only writes are the generated drift output and the
208
+ introspected schema under `{{auditOutputDir}}`. API-contract/serialization coverage is
125
209
  out of scope (deferred `audit-contract-compat` territory), and runtime query
126
210
  profiling belongs to `audit-performance`, which owns measured behavior.