mandrel 2.79.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 (30) hide show
  1. package/.agents/agents/auditor.md +8 -3
  2. package/.agents/audit-checklists/data-model.md +9 -1
  3. package/.agents/docs/agentrc-reference.json +3 -0
  4. package/.agents/docs/configuration.md +1 -1
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +19 -1
  7. package/.agents/schemas/audit-rules.json +5 -1
  8. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  9. package/.agents/scripts/lib/config/explain.js +1 -1
  10. package/.agents/scripts/lib/config-settings-schema.js +18 -1
  11. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  12. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  13. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  14. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  15. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  16. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  17. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
  18. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
  19. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  20. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  21. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  22. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  23. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  24. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  25. package/.agents/workflows/audit-data-model.md +94 -10
  26. package/.agents/workflows/audit-to-stories.md +22 -7
  27. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  28. package/.agents/workflows/helpers/plan-reference.md +11 -3
  29. package/docs/CHANGELOG.md +9 -0
  30. package/package.json +1 -1
@@ -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
  }
@@ -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.
@@ -175,20 +175,35 @@ one-pager, and per-group even though the visible list is flat — they are the
175
175
  identity the next sweep matches on). `plan-persist` harvests them out of the seed on the
176
176
  `plan-context.json` envelope — which carries them apart from the seed text as
177
177
  `seed.provenance`, so an oversize seed cut for size keeps every footer — and
178
- appends them to **every** Story body it persists, via `carryProvenanceFooters`
178
+ appends them to the Story bodies it persists, via `carryProvenanceFooters`
179
179
  ([`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)).
180
- The carry is additive, union-preserving and idempotent, so a resumed persist
181
- cannot stack footers and a hand-authored fingerprint is never dropped.
180
+ The carry is additive and idempotent, so a resumed persist cannot stack
181
+ footers and a hand-authored fingerprint is never dropped.
182
+
183
+ **Which Story carries which finding.** Beside the group footers the seed
184
+ emits one seed-only `audit-finding` record per finding (sha, semantic key,
185
+ `audit::` label, files — primary first). A plan that persists **one** Story,
186
+ or a seed with no such records, stamps the union of every footer on every
187
+ Story. A plan that splits into **N>1** Stories attributes per Story instead:
188
+ an authored `provenance` wins outright; otherwise a Story owns each finding
189
+ whose primary file (or, when no Story covers the primary, any other file) its
190
+ `changes[]` covers by exact path or glob. A finding no Story covers is
191
+ **unattributed**: it is still stamped on every Story without an authored
192
+ `provenance`, and persist names it in its warnings as `unattributed audit
193
+ finding <sha12> (<file>) — carried on all N Stories`, so the smear is visible
194
+ rather than silent. The record itself is never stamped on a Story body.
182
195
 
183
196
  **The carry is fail-closed.** The footers are the only cross-run dedup memory,
184
197
  so a dropped one is a finding silently re-filed by the next sweep. An envelope
185
198
  whose seed was truncated and that carries no `seed.provenance` makes persist
186
199
  refuse before creating any Issue, naming the cause — regenerate the envelope.
187
200
 
188
- **Persist stamps the labels too.** It adds the seed's `audit::<dimension>`
189
- labels — the dedup corpus is listed by them, and an indexed run answers lookups
190
- from that pool without reaching the provider, so a footer alone leaves a
191
- plan-path Story invisible. Persist writes no file.
201
+ **Persist stamps the labels too.** It adds `audit::<dimension>` labels — the
202
+ dedup corpus is listed by them, and an indexed run answers lookups from that
203
+ pool without reaching the provider, so a footer alone leaves a plan-path Story
204
+ invisible. On the union path every Story gets the seed's union labels; under
205
+ N>1 attribution each Story gets the labels of the findings stamped on it (a
206
+ stamped sha with no seed record widens to the union). Persist writes no file.
192
207
 
193
208
  This is deliberately not an authoring step. If you find yourself copying a
194
209
  footer by hand, the carry is broken — fix it there rather than papering over it
@@ -22,8 +22,8 @@ a lens performs is its report artifact (plus, where a lens explicitly declares
22
22
  it, a single measurement/baseline artifact named in that lens's own
23
23
  Constraint). A lens that names a stricter or looser read-only carve-out in its
24
24
  own body (e.g. performance's non-mutating measurements, quality's permitted
25
- committed-baseline reads, data-model's no-database rule) refines this shared
26
- constraint for that lens only.
25
+ committed-baseline reads, data-model's opt-in read-only database carve-out)
26
+ refines this shared constraint for that lens only.
27
27
 
28
28
  ## Scope interpretation (Story / plan-run mode) {#scope-interpretation}
29
29
 
@@ -276,15 +276,18 @@ lens that has one, so a lens documents only its own probe.
276
276
  device profile, colour scheme — before finishing, so a following lens or QA
277
277
  run does not inherit it.
278
278
 
279
- **Skip reasons, and how to report them.** The pass is skipped, never faked, for
280
- either of two reasons, and the Executive Summary says which:
279
+ **Skip reasons, and how to report them.** The pass is skipped, never faked,
280
+ for any of the reasons below that applies to the lens's probe, and the
281
+ Executive Summary says which. A lens whose probe has further skip conditions
282
+ lists them in its own body:
281
283
 
282
284
  | Condition | Reported as |
283
285
  | --- | --- |
284
286
  | No `qa.environments` target is configured | `skipped — no target configured` |
285
287
  | The browser tooling is unavailable in this runtime | `skipped — browser tooling unavailable` |
288
+ | A database probe finds no opted-in `database` block on the target | `skipped — no database target configured` |
286
289
 
287
- The second is the one an unattended sweep meets: a scheduled run has no browser
290
+ The browser-tooling row is the one an unattended sweep meets: a scheduled run has no browser
288
291
  MCP server attached, so a lens that treated "cannot drive" as "nothing found"
289
292
  would report a clean runtime section it never ran. Do not invent a URL, do not
290
293
  start an arbitrary dev server, and do not fall back to a static-only claim
@@ -238,7 +238,14 @@ work this plan already tracked.
238
238
  | --- | --- |
239
239
  | Present | **Exactly** the identities listed — siblings' groups never leak in. |
240
240
  | Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
241
- | **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
241
+ | **Absent**, N>1 plan, seed carries `audit-finding` records | The findings whose files this Story's `changes[]` covers (exact path or glob; the primary file first, the others only when no Story covers it), plus every **unattributed** finding. |
242
+ | **Absent**, otherwise (N==1, or a record-less seed) | The **whole seed's** footers (the union) — the recall-safe default. |
243
+
244
+ An unattributed finding — one no Story owns by `provenance` or by path — is
245
+ stamped on every Story without an authored `provenance` and listed in
246
+ persist's warnings (`unattributed audit finding <sha12> (<file>) — carried on
247
+ all N Stories`). `audit::*` labels follow the stamped findings under
248
+ attribution, and the seed union otherwise.
242
249
 
243
250
  **The union fallback is load-bearing, not legacy** — hand-carrying provenance
244
251
  out of the seed's HTML comments is a step an author forgets. Attribution is
@@ -251,8 +258,9 @@ owning Story has **closed** is masked by an open neighbour. With ownership
251
258
  stamped, the issue carrying a finding's own fingerprint decides both the match
252
259
  and its state (`lib/findings/route-finding.js`).
253
260
 
254
- The audit path authors this mechanically from the per-group footers the seed
255
- already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
261
+ The audit path attributes mechanically from the per-finding `audit-finding`
262
+ records the seed carries beside its per-group footers — see
263
+ [`audit-to-stories`](../audit-to-stories.md). A `--seed`
256
264
  or `--tickets` plan has nothing to attribute and omits the field.
257
265
 
258
266
  ## Cross-Story conflict analysis at persist
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,15 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.80.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.79.0...mandrel-v2.80.0) (2026-10-09)
19
+
20
+
21
+ ### Added
22
+
23
+ * audit-data-model: Dead Schema dimension and opt-in read-only live-schema verification pass ([#5594](https://github.com/dsj1984/mandrel/issues/5594)) ([#5595](https://github.com/dsj1984/mandrel/issues/5595)) ([3738dbe](https://github.com/dsj1984/mandrel/commit/3738dbe4af5bb7d71b97701684433d1feb13b839))
24
+ * audit-seeded N&gt;1 plans: attribute each finding's footers and audit:: label to the Stories that cover it ([#5597](https://github.com/dsj1984/mandrel/issues/5597)) ([#5600](https://github.com/dsj1984/mandrel/issues/5600)) ([a8529be](https://github.com/dsj1984/mandrel/commit/a8529bee4f51771677d646275081df6deb3a6543))
25
+ * collision predicate: a glob collides only with paths it can cover, and the message names the declarer ([#5596](https://github.com/dsj1984/mandrel/issues/5596)) ([#5599](https://github.com/dsj1984/mandrel/issues/5599)) ([dfea48c](https://github.com/dsj1984/mandrel/commit/dfea48caf755577e625002bb6873e2d54291e045))
26
+
18
27
  ## [2.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.78.0...mandrel-v2.79.0) (2026-10-09)
19
28
 
20
29
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.79.0",
3
+ "version": "2.80.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",