mandrel 2.103.0 → 2.105.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/docs/configuration.md +1 -1
  6. package/.agents/docs/execution-reference.md +35 -0
  7. package/.agents/instructions.md +4 -2
  8. package/.agents/rules/testing-standards.md +7 -1
  9. package/.agents/schemas/agentrc.schema.json +1 -1
  10. package/.agents/scripts/lib/close-validation/test-delta.js +8 -2
  11. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  12. package/.agents/scripts/lib/coverage-capture-affected.js +3 -2
  13. package/.agents/scripts/lib/coverage-capture-delta.js +101 -34
  14. package/.agents/scripts/lib/coverage-capture.js +14 -7
  15. package/.agents/scripts/lib/orchestration/code-review.js +56 -28
  16. package/.agents/scripts/lib/orchestration/evidence-stream.js +16 -7
  17. package/.agents/scripts/lib/orchestration/review-deposit.js +24 -7
  18. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +231 -0
  19. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -0
  20. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +6 -1
  21. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +11 -1
  22. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +4 -1
  23. package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +7 -3
  24. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +7 -0
  25. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +7 -20
  26. package/.agents/scripts/lib/orchestration/review-providers/types.js +9 -0
  27. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +1 -0
  28. package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js +13 -5
  29. package/.agents/scripts/lib/orchestration/story-handoff.js +77 -18
  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
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * story-handoff.js — the story-worker's whole post-implementation tail as one
3
3
  * deterministic sequence: blocking preflight (lint, quality-preview, baselined
4
- * ratchets) → base merge → the one credited run → baseline seating → push +
5
- * remote-ref check → held review. It runs
4
+ * ratchets) → base merge → the one credited run with the held review beside
5
+ * it → baseline seating → push + remote-ref check → review awaited. It runs
6
6
  * exactly what deliver-digest § 5 and deliver-reference § Held review define,
7
7
  * changing nothing close credits or adopts, and settles one envelope:
8
8
  *
@@ -131,7 +131,7 @@ const SEAT_SCRIPTS = Object.freeze({
131
131
  /**
132
132
  * A settled step. `stop` carries the envelope status that ends the run.
133
133
  *
134
- * @typedef {{ name: string, outcome: 'ran'|'skipped'|'failed'|'error',
134
+ * @typedef {{ name: string, outcome: 'ran'|'skipped'|'failed'|'error'|'aborted',
135
135
  * detail: string, evidencePath?: string|null, conflictFiles?: string[],
136
136
  * stop?: 'fix-required'|'blocked', reason?: string }} StepResult
137
137
  */
@@ -203,9 +203,10 @@ function worktreeEnv(ctx, env) {
203
203
  * @param {string} cmd
204
204
  * @param {string[]} args
205
205
  * @param {Record<string, string|undefined>} [env] the child's whole env.
206
+ * @param {AbortSignal} [signal]
206
207
  * @returns {Promise<{ status: number, output: string, evidencePath: string }>}
207
208
  */
208
- async function runLogged(ctx, logName, cmd, args, env) {
209
+ async function runLogged(ctx, logName, cmd, args, env, signal) {
209
210
  ctx.progress(logName, `${cmd} ${args.join(' ')}`);
210
211
  const file = ctx.evidencePathFor(logName);
211
212
  ctx.storyProgress.evidence(file);
@@ -218,6 +219,7 @@ async function runLogged(ctx, logName, cmd, args, env) {
218
219
  opts: { cwd: ctx.cwd, env: worktreeEnv(ctx, env) },
219
220
  file,
220
221
  tag: logName,
222
+ signal,
221
223
  });
222
224
  }
223
225
 
@@ -462,8 +464,8 @@ function testGateArgv(config) {
462
464
  return [cmd, ...args];
463
465
  }
464
466
 
465
- /** @param {object} ctx @returns {Promise<StepResult>} */
466
- async function stepCreditedRun(ctx) {
467
+ /** @param {object} ctx @param {AbortSignal} signal @returns {Promise<StepResult>} */
468
+ async function creditedRun(ctx, signal) {
467
469
  const name = 'credited-run';
468
470
  if (ctx.state.creditHead === ctx.head) {
469
471
  return skipped(
@@ -489,7 +491,7 @@ async function stepCreditedRun(ctx) {
489
491
  ...testGateArgv(ctx.config),
490
492
  ];
491
493
  const { result: run, timings } = await withLockProgress(ctx, (env) =>
492
- runLogged(ctx, 'credited-run', 'node', args, env),
494
+ runLogged(ctx, 'credited-run', 'node', args, env, signal),
493
495
  );
494
496
  const { lockWait, suiteTimings, spawns } = timings;
495
497
  const extra = {
@@ -498,6 +500,14 @@ async function stepCreditedRun(ctx) {
498
500
  lockWait,
499
501
  suiteTimings,
500
502
  };
503
+ if (signal.aborted) {
504
+ return {
505
+ name,
506
+ outcome: 'aborted',
507
+ detail: 'aborted: the held review found a CRITICAL mid-run; no credit',
508
+ ...extra,
509
+ };
510
+ }
501
511
  if (run.status !== 0) {
502
512
  return fixRequired(name, describeSuiteFailure(run.status), extra);
503
513
  }
@@ -747,7 +757,7 @@ function reviewVerdict(deposit, depositPath, settled) {
747
757
  }
748
758
 
749
759
  /** @param {object} ctx @returns {Promise<StepResult>} */
750
- async function stepReview(ctx) {
760
+ async function computeHeldReview(ctx) {
751
761
  const name = 'review';
752
762
  const held = ctx.probeReview({
753
763
  cwd: ctx.cwd,
@@ -796,6 +806,38 @@ async function stepReview(ctx) {
796
806
  );
797
807
  }
798
808
 
809
+ /** Pinned to the head it resolves now; never rejects. */
810
+ function startReview(ctx) {
811
+ const startedAt = ctx.now();
812
+ ctx.reviewPending = computeHeldReview(ctx)
813
+ .catch((err) => ({
814
+ name: 'review',
815
+ outcome: 'error',
816
+ detail: `held review failed (${err?.message ?? err}); close computes the review itself`,
817
+ }))
818
+ .finally(() => {
819
+ ctx.reviewMs = ctx.now() - startedAt;
820
+ });
821
+ return ctx.reviewPending;
822
+ }
823
+
824
+ /** A review that halts mid-run aborts the run. */
825
+ async function stepCreditedRun(ctx) {
826
+ const abort = new AbortController();
827
+ let halted = null;
828
+ startReview(ctx).then((result) => {
829
+ if (!result.stop) return;
830
+ halted = result;
831
+ abort.abort();
832
+ });
833
+ const run = await creditedRun(ctx, abort.signal);
834
+ return run.outcome === 'aborted' ? [run, halted] : run;
835
+ }
836
+
837
+ function stepReview(ctx) {
838
+ return ctx.reviewPending;
839
+ }
840
+
799
841
  /**
800
842
  * The run's step order. On the evidence-gate path the `test` credit is keyed
801
843
  * on the tree, so seating (static MI) goes first and cannot void it; the
@@ -813,6 +855,25 @@ function stepOrder(depositor) {
813
855
  return [stepPreflight, stepBaseMerge, ...middle, stepPush, stepReview];
814
856
  }
815
857
 
858
+ /**
859
+ * Run the steps in order into `steps`; a step may settle several results.
860
+ *
861
+ * @returns {Promise<StepResult|null>} the result that stopped the run.
862
+ */
863
+ async function runSteps(ctx, steps) {
864
+ for (const step of stepOrder(ctx.depositor)) {
865
+ ctx.storyProgress.phase(handoffStepName(step));
866
+ const results = [await step(ctx)].flat();
867
+ for (const result of results) {
868
+ steps.push(result);
869
+ ctx.progress(result.name, `${result.outcome} — ${result.detail}`);
870
+ }
871
+ const stop = results.find((r) => r.stop);
872
+ if (stop) return stop;
873
+ }
874
+ return null;
875
+ }
876
+
816
877
  /**
817
878
  * Refusals before any step: the handoff runs on the Story branch with the
818
879
  * implementation committed.
@@ -922,6 +983,7 @@ async function defaultBlock({
922
983
  * signalTarget?: import('node:events').EventEmitter,
923
984
  * reraise?: (signal: string) => void,
924
985
  * evidenceFs?: typeof fs,
986
+ * now?: () => number,
925
987
  * }} deps `runCommand` receives `onChunk`, `signal` and (when set)
926
988
  * `timeoutMs` beside `cwd`/`env`; a runner that never calls `onChunk`
927
989
  * still gets its whole output written at settle.
@@ -948,6 +1010,7 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
948
1010
  signalTarget,
949
1011
  reraise,
950
1012
  evidenceFs,
1013
+ now = Date.now,
951
1014
  } = deps;
952
1015
  const block =
953
1016
  deps.block ??
@@ -983,8 +1046,11 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
983
1046
  sleep,
984
1047
  lockPollMs,
985
1048
  env,
1049
+ now,
986
1050
  state: readState(statePath, progress),
987
1051
  review: null,
1052
+ reviewPending: null,
1053
+ reviewMs: null,
988
1054
  reviewPath: storyReviewDepositPath(storyId, config),
989
1055
  depositor: selectCreditedDepositor({
990
1056
  config,
@@ -1013,16 +1079,8 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
1013
1079
  const steps = [];
1014
1080
  let stop = precheck(ctx);
1015
1081
  if (stop) steps.push(stop);
1016
- for (const step of stop ? [] : stepOrder(ctx.depositor)) {
1017
- storyProgress.phase(handoffStepName(step));
1018
- const result = await step(ctx);
1019
- steps.push(result);
1020
- progress(result.name, `${result.outcome} — ${result.detail}`);
1021
- if (result.stop) {
1022
- stop = result;
1023
- break;
1024
- }
1025
- }
1082
+ else stop = await runSteps(ctx, steps);
1083
+ await ctx.reviewPending;
1026
1084
 
1027
1085
  const status = stop?.stop ?? HANDOFF_STATUS.READY;
1028
1086
  const credited = steps.find((s) => s.name === 'credited-run');
@@ -1040,6 +1098,7 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
1040
1098
  review: ctx.review,
1041
1099
  lockWait: credited?.lockWait ?? null,
1042
1100
  suiteTimings: credited?.suiteTimings ?? null,
1101
+ reviewMs: ctx.reviewMs,
1043
1102
  ...(stop
1044
1103
  ? {
1045
1104
  failedStep: stop.name,
@@ -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.105.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.104.0...mandrel-v2.105.0) (2026-10-26)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * ground held-review claims in the reviewed repository's cwd, not the process cwd ([#5909](https://github.com/dsj1984/mandrel/issues/5909)) ([#5910](https://github.com/dsj1984/mandrel/issues/5910)) ([a86c601](https://github.com/dsj1984/mandrel/commit/a86c60138abc68ed3ec9c6ffd332cc4d98c5a37c))
24
+
25
+ ## [2.104.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.103.0...mandrel-v2.104.0) (2026-10-25)
26
+
27
+
28
+ ### Added
29
+
30
+ * 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))
31
+ * 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))
32
+ * **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))
33
+
34
+
35
+ ### Fixed
36
+
37
+ * 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))
38
+
18
39
  ## [2.103.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.102.0...mandrel-v2.103.0) (2026-10-25)
19
40
 
20
41
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.103.0",
3
+ "version": "2.105.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/",