mandrel 2.102.0 → 2.104.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 (34) hide show
  1. package/.agents/agents/acceptance-critic.md +2 -0
  2. package/.agents/agents/auditor.md +2 -0
  3. package/.agents/agents/plan-critic.md +2 -0
  4. package/.agents/agents/story-worker.md +2 -0
  5. package/.agents/audit-checklists/quality.md +8 -0
  6. package/.agents/docs/configuration.md +1 -1
  7. package/.agents/docs/execution-reference.md +35 -0
  8. package/.agents/instructions.md +4 -2
  9. package/.agents/rules/testing-standards.md +7 -1
  10. package/.agents/schemas/agentrc.schema.json +1 -1
  11. package/.agents/scripts/lib/close-validation/test-delta.js +8 -2
  12. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  13. package/.agents/scripts/lib/coverage-capture-affected.js +3 -2
  14. package/.agents/scripts/lib/coverage-capture-delta.js +101 -34
  15. package/.agents/scripts/lib/coverage-capture.js +14 -7
  16. package/.agents/scripts/lib/orchestration/code-review.js +24 -10
  17. package/.agents/scripts/lib/orchestration/evidence-stream.js +16 -7
  18. package/.agents/scripts/lib/orchestration/review-deposit.js +24 -7
  19. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +183 -0
  20. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -0
  21. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +6 -1
  22. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +11 -1
  23. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +4 -1
  24. package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +7 -3
  25. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +7 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +7 -20
  27. package/.agents/scripts/lib/orchestration/review-providers/types.js +9 -0
  28. package/.agents/scripts/lib/orchestration/story-handoff.js +77 -18
  29. package/.agents/workflows/audit-quality.md +73 -1
  30. package/.agents/workflows/helpers/code-review.md +8 -0
  31. package/.agents/workflows/helpers/deliver-digest.md +8 -8
  32. package/.agents/workflows/helpers/deliver-reference.md +21 -14
  33. package/docs/CHANGELOG.md +21 -0
  34. package/package.json +1 -1
@@ -199,13 +199,85 @@ Evaluate the gathered context against the following test quality dimensions:
199
199
  terminal state") plus its generator shape (the input domain to draw
200
200
  from) — never a bare "add property tests".
201
201
 
202
+ 9. **Boundary-Value Coverage — Domain Edges Nobody Picked.** Flag a unit
203
+ that mishandles an input at the edge of its own domain when no test
204
+ drives that edge. This dimension owns **pure code only**: a function's
205
+ own input domain where no external dependency, no concurrency and no
206
+ trust boundary is involved. Dimension 8 owns a *stated* invariant; this
207
+ dimension owns the unstated edges every domain has. Walk each candidate
208
+ unit against the edge catalogue and keep only the edges it demonstrably
209
+ mishandles:
210
+
211
+ - **Emptiness and extent** — an empty collection or string, a single
212
+ element, the off-by-one at a length (`arr[length]`, a `slice` at the
213
+ end), an input larger than any fixture.
214
+ - **Numbers** — zero, a negative, `NaN`, `Infinity`, `-0`, the max safe
215
+ integer, a float where an integer is assumed, a numeric string.
216
+ - **Text** — a combining character or surrogate pair where `length` is
217
+ read as a glyph count, a BOM, `CRLF`, a trailing newline, surrounding
218
+ whitespace, a locale-sensitive compare.
219
+ - **Paths and names** — a trailing slash, `..`, an absolute path where a
220
+ relative one is assumed, a Windows separator, a case-only difference.
221
+ - **Time** — a DST transition, a leap day, a month end, epoch zero, a
222
+ timezone other than the author's, a clock that goes backwards.
223
+ - **Presence** — `null` versus `undefined` versus a missing key versus an
224
+ empty string, an optional field at its default, a field present with
225
+ the wrong type.
226
+ - **Ordering** — a sort that assumes stability or a single key, a
227
+ deduplication that assumes insertion order, a first-wins or last-wins
228
+ merge the callers disagree on.
229
+
230
+ **The reproduction gate (every finding).** "What if it is null" is not a
231
+ finding. A boundary finding names all four of the following or is
232
+ dropped: (a) **the input** as a concrete value, not a class (`[]`, never
233
+ "an empty collection"); (b) **the line** — the `path:line` that
234
+ mishandles it and what it does instead (returns `NaN`, throws
235
+ `TypeError`, drops the last element); (c) **the producer** — an in-repo
236
+ call site, config key, CLI flag or exported signature that can supply
237
+ that value, cited by `path:line` — a value no caller can produce is not a
238
+ finding, and a public entry point counts as a producer; (d) **the test**
239
+ — the assertion that would fail today, in the tier
240
+ [`rules/testing-standards.md`](../rules/testing-standards.md) assigns the
241
+ unit, so the gap is a named missing test and never a bare "add edge-case
242
+ tests".
243
+
244
+ **Evidence: `reproduced` or `reasoned`.** A finding is `reproduced` when
245
+ you drove the unit with the input in a throwaway process and quote the
246
+ command and the output line that shows the wrong result — e.g.
247
+ `node --input-type=module -e "import { f } from './lib/f.js'; console.log(f([]))"`,
248
+ `python -c`, or the ecosystem's equivalent, run from the repo root or as
249
+ a scratch script under the workspace `temp/` tree. Importing a module
250
+ into a throwaway process is a read, not the suite run the Constraint
251
+ forbids, and it is permitted only for a unit whose sole side effect is
252
+ its return value — a function that writes a file, sends a request or
253
+ mutates shared state stays `reasoned`. **High requires `reproduced`**: a
254
+ `reasoned` finding caps at Medium whatever its consequence.
255
+
256
+ - Severity: the mishandled edge corrupts or silently drops data, feeds an
257
+ irreversible write, or decides a gate or guard → **High**; it returns a
258
+ wrong value or throws on a reachable input → **Medium**; the wrong
259
+ output is a message or a cosmetic rendering → **Low**.
260
+ - Category: file under `Coverage`. Rank candidates by Step 0's churn ×
261
+ coverage gap and cite the `baselines/` coverage row of the branch the
262
+ edge lives on where one exists; cap the batch at the top eight and roll
263
+ the remainder into one finding per catalogue row.
264
+ - Not a finding: a defensive check on an input no producer supplies, or
265
+ an edge a sibling lens owns whole — cite the sibling when you drop it.
266
+ An external call's timeout or empty-on-outage is `audit-resilience`'s;
267
+ a check-then-act race is `audit-performance`'s Interleaving dimension;
268
+ an input crossing a trust boundary is `audit-security`'s Tier B; a
269
+ poisoned or exhausting input is `audit-red-team`'s Hostile Operations;
270
+ an empty `catch` is `audit-clean-code`'s Error Handling.
271
+
202
272
  ## Constraint (lens-specific carve-out)
203
273
 
204
274
  Do NOT **run** the test suite (do not invoke `npm test`, a coverage run, or a
205
275
  mutation run — those mutate state and cost minutes). Reading the **committed**
206
276
  coverage / CRAP / mutation artifacts under `baselines/` is explicitly permitted
207
277
  and required (Step 0): citing an already-computed metric is read-only analysis,
208
- not a suite run.
278
+ not a suite run. So is dimension 9's reproduction — one pure unit driven with
279
+ one input in a throwaway process — which runs no test file and writes nothing
280
+ outside the workspace `temp/` tree.
209
281
 
210
282
  ## Report additions
211
283
 
@@ -239,6 +239,14 @@ spec decision, a swallowed error on a real failure path) is a 🔴.
239
239
  `Failure witness:` line records a mutant it was seen to fail against, its
240
240
  generator cannot reach the inputs the stated invariant constrains, or its
241
241
  assertion would hold for any implementation.
242
+ - **Null-implementation tests** — a new or changed example test, at any tier,
243
+ that would still pass with the unit under test stubbed to return
244
+ `undefined`: it asserts only that the call did not throw; asserts on a
245
+ value the test itself built, or that a mock returned, rather than one the
246
+ code computed; asserts only that a mock was called when the caller-visible
247
+ outcome is observable; or makes a truthiness or type check any
248
+ non-throwing call satisfies. It is the test-side counterpart of **Stub
249
+ returns**.
242
250
 
243
251
  For every hit, name the file and line, the taxonomy category, and *why the
244
252
  code — not the check — should have changed*. A finding here is legitimate only
@@ -100,7 +100,7 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
100
100
  ## 5. The one credited run — `story-handoff.js`
101
101
 
102
102
  After the self-eval loop's last fix commit the worker runs **one** command,
103
- which performs this section in order and prints one envelope:
103
+ which runs this section in order and prints one envelope:
104
104
 
105
105
  `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
106
106
 
@@ -119,8 +119,8 @@ it in the **background**.
119
119
  2. **Base merge.** It will merge `origin/<baseBranch>` into the Story branch
120
120
  **first**, ahead of this run and the push: close's base-sync then no-ops,
121
121
  so neither stamp goes stale.
122
- 3. **One depositor**, by the predicate close registers `coverage-capture` on
123
- (one shared function) — coverage or CRAP gate on **and** a `captureScript`:
122
+ 3. **One depositor**, by the one predicate close registers `coverage-capture`
123
+ on — coverage or CRAP gate on **and** a `captureScript`:
124
124
  - **Capture-active** →
125
125
  `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
126
126
  behind the host full-suite lock. Signal: `Wrote content-digest capture
@@ -131,15 +131,15 @@ it in the **background**.
131
131
  4. **Seat.** CRAP or MI gate on → `--seat-missing` for each (signal
132
132
  `seated: N`), committed as `chore(baselines): baseline-refresh: …`.
133
133
  5. **Push** `story-<id>`; the remote ref must equal HEAD.
134
- 6. **Held review** — [`deliver-reference.md`](deliver-reference.md)
135
- § Held review.
134
+ 6. **Held review** beside step 3, which a CRITICAL aborts —
135
+ [`deliver-reference.md`](deliver-reference.md) § Held review.
136
136
 
137
- A later commit voids either credit; a baseline-JSON seat keeps the stamp. The
138
- handoff reads the **output**, not the exit code: a run that prints no signal
137
+ A later commit voids either credit; a baseline-JSON seat keeps the stamp. It
138
+ reads the **output**, not the exit code: a run that prints no signal
139
139
  deposits nothing. Seat order, runner shapes, redraft rounds:
140
140
  [`deliver-reference.md`](deliver-reference.md) § Credited run.
141
141
 
142
- `verify[]` is scoped entries **plus** this one run: an entry that is itself a
142
+ `verify[]` is scoped entries **plus** this one run: an entry that is a
143
143
  full-suite command is reported credited against the same record, never
144
144
  respawned.
145
145
 
@@ -446,10 +446,11 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
446
446
  ## Held review at hand-off {#held-review}
447
447
 
448
448
  The one home of this rule; the digest and the worker contract point here.
449
- After the credited run **and** the push, `story-handoff.js` computes the
450
- Story-scope code review as its last step, skipping it when a deposit already
451
- matches the diff digest. The same computation stands alone for a manual
452
- re-run:
449
+ `story-handoff.js` starts the Story-scope code review as the credited run
450
+ starts — pinned to HEAD at that moment, after a `test`-depositor seat — and
451
+ awaits it after the push, skipping the computation when a deposit already
452
+ matches the diff digest. The envelope's `reviewMs` sits beside the run's
453
+ `suiteTimings`. The same computation stands alone for a manual re-run:
453
454
 
454
455
  ```bash
455
456
  node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd <workCwd>
@@ -459,21 +460,27 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
459
460
  provider chain) against `origin/<baseBranch>...story-<id>`, posts nothing,
460
461
  takes no full-suite lock, and writes
461
462
  `temp/orchestration/story-review-<id>.json` beside the terminal envelope,
462
- keyed on the **diff digest** (sha256 of the exact three-dot diff text). It
463
- never stops the handoff on a provider throw — the step reports `error`
464
- and close computes the review itself.
463
+ keyed on the **diff digest** (sha256 of the three-dot diff with every
464
+ `linguist-generated` section removed; a failed attribute lookup hashes it
465
+ whole). It never stops the handoff on a provider throw — the step reports
466
+ `error` and close computes the review itself.
465
467
  - **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
466
- naming the deposit; fix, commit, and re-run the handoff (the fix commit
467
- voided the credit, so it re-runs the suite, pushes and re-computes) — the
468
- acceptance loop's redraft discipline, bounded by
468
+ naming the deposit. One that lands while the credited run is in flight
469
+ aborts the run (the SIGTERM a Ctrl-C sends; the child frees the full-suite
470
+ lock), records no credit and pushes nothing; a CRITICAL after the run still
471
+ settles after the push, as before. Any earlier stop still awaits the
472
+ review, so no provider is orphaned. Fix, commit, and re-run the handoff
473
+ (the fix commit voided the credit, so it re-runs the suite, pushes and
474
+ re-computes) — the acceptance loop's redraft discipline, bounded by
469
475
  `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
470
476
  blocked path. Anything else goes in the hand-off as the severity tally.
471
477
  - **Close adopts, else computes.** When the deposit's digest equals the
472
478
  digest of the diff at close's held-review start, close starts no review and
473
- posts the deposit after PR-open. A clean base-sync merge moves HEAD without
474
- changing the diff, so it keeps the deposit; a commit that changes the diff
475
- does not, and close reviews as it would without one. The CRITICAL halt and
476
- `--override-review-block` apply to an adopted result unchanged.
479
+ posts the deposit after PR-open. A clean base-sync merge or a seat commit
480
+ that writes only generated baselines keeps the deposit; a commit that
481
+ changes a reviewed path does not, and close reviews as it would without
482
+ one. The CRITICAL halt and `--override-review-block` apply to an adopted
483
+ result unchanged.
477
484
 
478
485
  ## Gate output {#gate-output}
479
486
 
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,27 @@ 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.104.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.103.0...mandrel-v2.104.0) (2026-10-25)
19
+
20
+
21
+ ### Added
22
+
23
+ * held review grounds path-absent and remaining-caller CRITICALs against the reviewed head before halting ([#5904](https://github.com/dsj1984/mandrel/issues/5904)) ([#5906](https://github.com/dsj1984/mandrel/issues/5906)) ([2153489](https://github.com/dsj1984/mandrel/commit/2153489d7cde4a4839c404ddd28a8160a1781527))
24
+ * story handoff runs the held review concurrently with the credited run and stops early on a CRITICAL ([#5905](https://github.com/dsj1984/mandrel/issues/5905)) ([#5908](https://github.com/dsj1984/mandrel/issues/5908)) ([f030bc6](https://github.com/dsj1984/mandrel/commit/f030bc62d2020a2f1170cc1854e4b22021328111))
25
+ * **testing:** flag tests that would still pass against a null implementation (refs [#5899](https://github.com/dsj1984/mandrel/issues/5899)) ([#5900](https://github.com/dsj1984/mandrel/issues/5900)) ([7458b8d](https://github.com/dsj1984/mandrel/commit/7458b8dc6c0e8f2744b6fab99234194f7a9146dd))
26
+
27
+
28
+ ### Fixed
29
+
30
+ * coverage delta refresh fires on tree-digest-only staleness and ignores non-suite-input overlap ([#5903](https://github.com/dsj1984/mandrel/issues/5903)) ([#5907](https://github.com/dsj1984/mandrel/issues/5907)) ([65413a4](https://github.com/dsj1984/mandrel/commit/65413a467b1701f46ba393fa7be4948ab60bf68f))
31
+
32
+ ## [2.103.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.102.0...mandrel-v2.103.0) (2026-10-25)
33
+
34
+
35
+ ### Added
36
+
37
+ * **audit-quality:** add a Boundary-Value Coverage dimension gated on input, line, producer and test ([#5895](https://github.com/dsj1984/mandrel/issues/5895)) ([3344213](https://github.com/dsj1984/mandrel/commit/3344213eb8ad5d9686eb13a0658f9e808eb10466))
38
+
18
39
  ## [2.102.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.101.0...mandrel-v2.102.0) (2026-10-23)
19
40
 
20
41
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.102.0",
3
+ "version": "2.104.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/",