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.
- package/.agents/agents/auditor.md +8 -3
- package/.agents/audit-checklists/data-model.md +9 -1
- package/.agents/docs/agentrc-reference.json +3 -0
- package/.agents/docs/configuration.md +1 -1
- package/.agents/docs/workflows.md +1 -1
- package/.agents/schemas/agentrc.schema.json +19 -1
- package/.agents/schemas/audit-rules.json +5 -1
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
- package/.agents/scripts/lib/config/explain.js +1 -1
- package/.agents/scripts/lib/config-settings-schema.js +18 -1
- package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
- package/.agents/scripts/lib/findings/route-finding.js +4 -3
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
- package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
- package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
- package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
- package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
- package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
- package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
- package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
- package/.agents/workflows/audit-data-model.md +94 -10
- package/.agents/workflows/audit-to-stories.md +22 -7
- package/.agents/workflows/helpers/audit-lens-core.md +8 -5
- package/.agents/workflows/helpers/plan-reference.md +11 -3
- package/docs/CHANGELOG.md +9 -0
- 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
|
|
6
|
-
* declares a glob
|
|
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
|
-
*
|
|
54
|
-
*
|
|
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 {
|
|
57
|
-
* @param {
|
|
87
|
+
* @param {string} g
|
|
88
|
+
* @param {string} h
|
|
89
|
+
* @returns {boolean}
|
|
58
90
|
*/
|
|
59
|
-
function
|
|
60
|
-
|
|
61
|
-
|
|
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
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
92
|
-
|
|
181
|
+
collectGlobHits(hits, pa, pb, 'a');
|
|
182
|
+
collectGlobHits(hits, pb, pa, 'b');
|
|
93
183
|
}
|
|
94
184
|
if (hits.size === 0) return null;
|
|
95
|
-
|
|
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
|
-
*
|
|
87
|
-
*
|
|
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
|
|
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
|
|
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,
|
|
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,
|
|
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
|
|
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`, `
|
|
58
|
-
`
|
|
59
|
-
|
|
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
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
|
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
|
|
181
|
-
|
|
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
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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
|
|
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,
|
|
280
|
-
|
|
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
|
|
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
|
|
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
|
|
255
|
-
|
|
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>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