mandrel 2.123.0 → 2.124.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 (61) hide show
  1. package/.agents/README.md +1 -1
  2. package/.agents/docs/agentrc-reference.json +1 -0
  3. package/.agents/docs/configuration.md +4 -3
  4. package/.agents/runtime-deps.json +2 -2
  5. package/.agents/schemas/agentrc.schema.json +25 -3
  6. package/.agents/schemas/audit-rules.schema.json +1 -1
  7. package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
  8. package/.agents/scripts/check-doc-links.js +4 -4
  9. package/.agents/scripts/lib/audit-baselines/surface-entry.js +2 -2
  10. package/.agents/scripts/lib/audit-exceptions/globs.js +2 -2
  11. package/.agents/scripts/lib/audit-exceptions/scope.js +2 -2
  12. package/.agents/scripts/lib/audit-suite/selector.js +3 -3
  13. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +3 -3
  14. package/.agents/scripts/lib/baselines/components.js +2 -2
  15. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +2 -2
  16. package/.agents/scripts/lib/bdd-runner-detect.js +3 -4
  17. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +2 -2
  18. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  19. package/.agents/scripts/lib/config/handoff.js +21 -6
  20. package/.agents/scripts/lib/config-settings-schema-delivery.js +19 -10
  21. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  22. package/.agents/scripts/lib/coverage-baseline.js +3 -3
  23. package/.agents/scripts/lib/coverage-capture-delta.js +2 -2
  24. package/.agents/scripts/lib/coverage-capture-own-fix.js +2 -2
  25. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  26. package/.agents/scripts/lib/git-test-guard.js +119 -0
  27. package/.agents/scripts/lib/git-utils.js +3 -0
  28. package/.agents/scripts/lib/maintainability-utils.js +4 -4
  29. package/.agents/scripts/lib/observability/handoff-telemetry.js +2 -0
  30. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +3 -2
  31. package/.agents/scripts/lib/orchestration/block-class-recovery.js +44 -0
  32. package/.agents/scripts/lib/orchestration/code-review.js +35 -19
  33. package/.agents/scripts/lib/orchestration/diff-magnitude.js +1 -1
  34. package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js +3 -3
  35. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +3 -4
  36. package/.agents/scripts/lib/orchestration/review-history.js +9 -10
  37. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +9 -2
  38. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +8 -5
  39. package/.agents/scripts/lib/orchestration/review-providers/codex.js +3 -11
  40. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  41. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +22 -0
  42. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +10 -2
  43. package/.agents/scripts/lib/orchestration/review-providers/types.js +2 -0
  44. package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js +13 -2
  45. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +40 -15
  46. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +8 -1
  47. package/.agents/scripts/lib/orchestration/story-handoff.js +216 -54
  48. package/.agents/scripts/lib/test-temp.js +5 -5
  49. package/.agents/scripts/lib/test-tiers.js +3 -3
  50. package/.agents/scripts/lib/util/glob-match.js +64 -0
  51. package/.agents/scripts/lib/wave-runner/footprint.js +3 -3
  52. package/.agents/scripts/run-tests.js +2 -1
  53. package/.agents/scripts/single-story-init.js +3 -3
  54. package/.agents/workflows/helpers/code-review.md +8 -1
  55. package/.agents/workflows/helpers/deliver-digest.md +22 -23
  56. package/.agents/workflows/helpers/deliver-reference.md +55 -24
  57. package/.agents/workflows/helpers/deliver-story-reference.md +10 -3
  58. package/.agents/workflows/helpers/deliver-story.md +27 -7
  59. package/.agents/workflows/mandrel-deliver.md +8 -2
  60. package/docs/CHANGELOG.md +15 -0
  61. package/package.json +2 -2
@@ -23,6 +23,7 @@ import { fileURLToPath } from 'node:url';
23
23
  import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
24
24
  import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
25
25
  import { runAsCli } from './lib/cli-utils.js';
26
+ import { armGitGuard } from './lib/git-test-guard.js';
26
27
  import { buildWebhookSafeTestEnv } from './lib/test-env.js';
27
28
  import { reportTestRunCredit } from './lib/test-run-credit.js';
28
29
  import {
@@ -224,7 +225,7 @@ export async function runTestSuite({
224
225
  ...options,
225
226
  files,
226
227
  cwd,
227
- env: buildWebhookSafeTestEnv(process.env),
228
+ env: armGitGuard(buildWebhookSafeTestEnv(process.env), process.env),
228
229
  stdout,
229
230
  });
230
231
  } finally {
@@ -57,7 +57,7 @@ import { createProvider } from './lib/provider-factory.js';
57
57
  import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
58
58
  import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
59
59
  // `sweepMergedStoryBranches` is imported dynamically: its graph reaches
60
- // `picomatch`, which would crash before `assertDepsInstalled()` can report.
60
+ // `minimatch`, which would crash before `assertDepsInstalled()` can report.
61
61
  import { WorktreeManager } from './lib/worktree-manager.js';
62
62
 
63
63
  export { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
@@ -68,11 +68,11 @@ export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
68
68
  * opaque `ERR_MODULE_NOT_FOUND` from deep in the sweep graph. Builtins only.
69
69
  */
70
70
  function assertDepsInstalled(projectRoot) {
71
- const probe = path.join(projectRoot, 'node_modules', 'picomatch');
71
+ const probe = path.join(projectRoot, 'node_modules', 'minimatch');
72
72
  if (!existsSync(probe)) {
73
73
  throw new Error(
74
74
  [
75
- 'Project dependencies are not installed (missing node_modules/picomatch).',
75
+ 'Project dependencies are not installed (missing node_modules/minimatch).',
76
76
  `Run \`npm install\` from ${projectRoot} before invoking this script.`,
77
77
  ].join(' '),
78
78
  );
@@ -87,6 +87,13 @@ The `code-review` provider also maps depth to `claude --effort`: `low` at
87
87
  `light` and `standard`, `high` at `deep`. `delivery.codeReview.effortByDepth`
88
88
  overrides that per depth (`low`/`medium`/`high`/`xhigh`/`max`).
89
89
 
90
+ A Story's **first pass** (its review history holds no run) is always `deep`
91
+ and carries `exhaustive: true`: the LLM-backed providers append one shared
92
+ directive asking the reviewer to sweep every changed file for every instance
93
+ of each defect class it raises, and every added read, write and response path
94
+ for an access or role-narrowing class. The history marks that run
95
+ `exhaustive`. A review with no history seam is never a first pass.
96
+
90
97
  The LLM-backed review providers (code-review, codex, security-review,
91
98
  ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
92
99
  model actually changes thoroughness. The native provider deliberately ignores
@@ -111,7 +118,7 @@ severity rule, excuse a `shortcut:` comment, or change the output shape. Over
111
118
  8,000 characters it is truncated and recorded as a degraded gate.
112
119
 
113
120
  Prose cannot silence a finding. Only `delivery.codeReview.skipPaths`
114
- (picomatch globs) drops findings, after grounding and verification and before
121
+ (globs) drops findings, after grounding and verification and before
115
122
  severity is counted; the report states how many were dropped.
116
123
 
117
124
  ### Bug classes, instances and repeats
@@ -99,22 +99,20 @@ After the self-eval's last fix commit the worker runs **one** command:
99
99
  `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
100
100
 
101
101
  `ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
102
- deferred suite, a base-merge conflict, a non-fast-forward push,
103
- a `commit_refs_rules` push stepping missed or a CRITICAL: fix, commit,
104
- re-run; labels untouched. `blocked` (exit 1) → only a remote-refused push,
105
- an unreachable remote, an unconfirmed base branch, an unregistered merge
106
- driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
107
- `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
102
+ deferred suite, a base-merge conflict, a push to fix or a CRITICAL: fix,
103
+ commit, re-run; labels untouched. `blocked` (exit 1) → only a remote-refused
104
+ push, an unreachable remote, an unconfirmed base branch, an unregistered
105
+ merge driver, `review-cap` or `host-resources` (exit 77): it flips
106
+ `agent::blocked` and posts `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
108
107
 
109
108
  1. **Base merge:** merge `origin/<baseBranch>` into the Story branch
110
109
  **first**, ahead of every check: close's base-sync then no-ops. Then close's **duplication re-score**, committed
111
110
  **untagged** before any credit.
112
- 2. **Preflight — blocking.** `typecheck`/`lint`/`format` (close's credit),
113
- `quality-preview.js --changed-since origin/<baseBranch>`, each baselined
114
- ratchet, `check-baselines`; one `fix-required` lists all. Serial unless
115
- per-host `.agentrc.local.json` sets `delivery.execution.preflightConcurrency`
116
- above 1 (default 1): close's independent gates then run in admitted
117
- lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
111
+ 2. **Preflight — blocking.** Fast lane first: `delivery.handoff.firstChecks`,
112
+ `check-baselines`; a finding stops there. Then `typecheck`/`lint`/`format`
113
+ (close's credit), `quality-preview.js --changed-since origin/<baseBranch>`,
114
+ each baselined ratchet; one `fix-required` lists all. Lanes:
115
+ `preflightConcurrency` — [`deliver-reference.md`](deliver-reference.md) § Preflight.
118
116
  3. **One depositor** (`suiteOfRecord: ci`: CI's), by one predicate close registers `coverage-capture`
119
117
  on — coverage or CRAP gate on **and** a `captureScript`:
120
118
  - **Capture-active** →
@@ -130,8 +128,10 @@ driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
130
128
  …`; then post-capture checks: close's `quality-preview-crap` and `check-baselines`,
131
129
  then `delivery.handoff.postSeatChecks`. Children get `MANDREL_HANDOFF_STEP`.
132
130
  5. **Push** `story-<id>`; the remote ref must equal HEAD.
133
- 6. **Held review** from step 1, beside 2: a CRITICAL skips or aborts 3,
134
- one envelope with any finding — [`deliver-reference.md`](deliver-reference.md) § Held review.
131
+ 6. **Held review**, from a clean fast lane: a CRITICAL skips or aborts 3.
132
+ Fix, commit, re-run: a **review-first retry** settles the review before
133
+ any check; `blocked` (`review-cap`) at `acceptanceEval.maxRounds`
134
+ rounds — [`deliver-reference.md`](deliver-reference.md) § Held review.
135
135
 
136
136
  A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
137
137
  reads the **output**, not the exit code: no signal deposits nothing. Seat order, runner shapes:
@@ -146,25 +146,24 @@ respawned.
146
146
  `single-story-close.js` emits exactly one envelope on stdout between
147
147
  `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
148
148
  [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
149
- — the SSOT. Relay it verbatim; never hand-compose one.
149
+ — the SSOT; relay it verbatim.
150
150
 
151
151
  | `status` | Exit | Meaning | You do |
152
152
  | --- | --- | --- | --- |
153
- | `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. Done. |
153
+ | `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. |
154
154
  | `pending` | 3 | **Resumable, not a failure** — the bounded wait expired healthy, or a human owns the merge. Nothing was mutated. | Run `nextCommand`. Each beat: run every `confirm[]` verbatim, pre-epilogue. |
155
- | `blocked` | 1 | Hard block; `blocked.blockClass` names it | `checks-failed` → fix + resume; else relay |
155
+ | `blocked` | 1 | `blocked.blockClass` names it, `blocked.recovery` who clears it | `agent` (stays `agent::closing`) → fix, push, resume; `operator` → relay, pause |
156
156
  | `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close. `base-sync` conflict (files in `failure.reason`): resolve in `workCwd`, commit, run `nextCommand`; block only if you cannot |
157
157
 
158
158
  Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
159
- `phase` (the schema's enum names where it stopped), `elapsedSeconds`,
160
- `nextCommand`. `gates`
159
+ `phase` (where it stopped), `elapsedSeconds`, `nextCommand`. `gates`
161
160
  reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
162
161
  never omitted, so a missing gate never reads as passing.
163
162
 
164
163
  ## 7. When to leave this file
165
164
 
166
- Unclear state / a re-run refusal → `deliver-recover.js --story <id>`; boot
167
- auto-lists stalled `agent::executing` Stories with it (read-only, advisory).
165
+ Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (boot
166
+ runs it on stalled Stories).
168
167
  Lease, sweep, worktree scope; sequencing, epilogue, checklist threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
169
- [`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
170
- [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
168
+ [`deliver-reference.md`](deliver-reference.md). After the PR opens, loop to
169
+ `landed`: [`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge).
@@ -71,7 +71,9 @@ dispatchable and nothing in flight, with the undone Stories and their unmet
71
71
  blockers named; land a blocker or add it to `--ids`. **4** — `blocked`: a Story
72
72
  carries `agent::blocked` with `blockedReason`, the protocol's HITL pause
73
73
  ([`instructions.md` § 1.J](../../instructions.md)). Blocked outranks a wedge,
74
- but not a cycle.
74
+ but not a cycle. Only an operator-owned block lands here: a close that ends
75
+ `blocked.recovery: "agent"` leaves its Story `agent::closing` (in flight), and
76
+ you fix and resume it before the next close.
75
77
 
76
78
  **Resuming an exit-4 `blocked`.** Read the friction comment with
77
79
  `gh issue view <id> --comments`, and resume only once the operator has
@@ -419,8 +421,18 @@ then the shipped standalone ratchets CI's `baselines` job runs —
419
421
  and `check-cyclomatic.js` — in the worktree. It runs **before** the credited
420
422
  run because a fix commit afterwards would void that run's credit.
421
423
 
422
- - **One pass, every finding.** Every check runs, even after a finding. Any
423
- finding settles one `fix-required` whose `detail` lists each finding on its
424
+ - **The fast lane runs first.** Each `delivery.handoff.firstChecks` entry,
425
+ in config order, then close's independent baseline compare
426
+ (`check-baselines`, scoring committed rows, so under admitted lanes it waits
427
+ for the overlapped duplication re-score to join; the first checks run beside
428
+ that scan). A finding there settles `fix-required` naming the check and
429
+ quoting its failure rows, and none of typecheck, lint, format,
430
+ quality-preview, the ratchets or the held review starts; `--report-all`
431
+ lists it and runs the rest. A clean lane starts the held review, then the
432
+ checks below.
433
+ - **One pass, every finding.** After the fast lane, every check runs, even
434
+ after a finding. Any finding settles one `fix-required` whose `detail` lists
435
+ each finding on its
424
436
  own line, in check order, and whose `findings[]` carries `{ check, detail,
425
437
  evidencePath }` per failing check; the envelope's `evidencePath` is the
426
438
  first one's in check order. No suite runs before the credited run. Only a
@@ -635,13 +647,16 @@ review; post-seat checks wait for a real run, because it seats nothing.
635
647
  ## Held review at hand-off {#held-review}
636
648
 
637
649
  The one home of this rule; the digest and the worker contract point here.
638
- `story-handoff.js` starts the Story-scope code review once base-merge settles
639
- HEAD — pinned to the post-merge HEAD, before preflight's first check (and
640
- before a `test`-depositor seat, whose generated-only commit keeps the digest)
641
- — so it runs alongside preflight, and awaits it after the push, skipping the
642
- computation when a deposit already matches the diff digest. A precheck
643
- refusal or a base merge that does not settle (conflict, failed fetch, missing
644
- merge driver) starts no review. The envelope's `reviewMs` sits beside the run's
650
+ `story-handoff.js` starts the Story-scope code review once preflight's fast
651
+ lane passes — the `delivery.handoff.firstChecks` entries and close's
652
+ independent baseline compare — before its first credited check (and before a
653
+ `test`-depositor seat, whose generated-only commit keeps the digest), so it
654
+ runs alongside the rest of preflight, and awaits it after the push, skipping
655
+ the computation when a deposit already matches the diff digest. A fast-lane
656
+ finding starts no review: its fix changes the diff, so that review would be
657
+ thrown away. A precheck refusal, a base merge that does not settle (conflict,
658
+ failed fetch, missing merge driver) or any stop before preflight starts no
659
+ review either. The envelope's `reviewMs` sits beside the run's
645
660
  `suiteTimings`. The same computation stands alone for a manual re-run:
646
661
 
647
662
  ```bash
@@ -661,20 +676,36 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
661
676
  raw diff. It never stops the handoff on a provider throw — the step reports
662
677
  `error` and close computes the review itself.
663
678
  - **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
664
- naming the deposit. It never cuts preflight short: every check runs to its
665
- own result. One that has landed before the credited run would begin stops
666
- the handoff there — no `test`-depositor seat, no run, no full-suite lock,
667
- no credit, no push. One that lands while the run is in flight aborts it
668
- (the SIGTERM a Ctrl-C sends; the child frees the full-suite lock), records
669
- no credit and pushes nothing; a CRITICAL after the run still settles after
670
- the push. Any earlier stop still awaits the review and appends its result
671
- to `steps[]` once, so no provider is orphaned and one envelope carries both
672
- findings, each with its own evidence path; `status` and `failedStep` stay
673
- the first stop's, and a review `error` never blocks. Fix, commit, and re-run the handoff
674
- (the fix commit voided the credit, so it re-runs the suite, pushes and
675
- re-computes) — the acceptance loop's redraft discipline, bounded by
676
- `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
677
- blocked path. Anything else goes in the hand-off as the severity tally.
679
+ naming the deposit. On a first run it never cuts preflight short: every
680
+ check runs to its own result. One that has landed before the credited run
681
+ would begin stops the handoff there — no `test`-depositor seat, no run, no
682
+ full-suite lock, no credit, no push. One that lands while the run is in
683
+ flight aborts it (the SIGTERM a Ctrl-C sends; the child frees the
684
+ full-suite lock), records no credit and pushes nothing; a CRITICAL after the
685
+ run still settles after the push. Any earlier stop still awaits the review
686
+ and appends its result to `steps[]` once, so no provider is orphaned and one
687
+ envelope carries both findings, each with its own evidence path; `status`
688
+ and `failedStep` stay the first stop's unless the review blocks, and a
689
+ review `error` never blocks. Fix, commit, and re-run the handoff.
690
+ - **The fix is retried review-first.** When the previous run (its state file
691
+ holds `{ state, envelope }`) stopped on `review-critical` and its preflight
692
+ had passed at that run's head, the next run merges the base, then awaits
693
+ the held review before the duplication re-score, the static seat and
694
+ preflight. Still CRITICAL → it settles at once and lists every step it did
695
+ not run as `skipped` (`review-first retry: held review still CRITICAL`).
696
+ Clean → it continues as a normal handoff, and close adopts the deposit. Any
697
+ other prior stop, no state file, and `--report-all` run as before.
698
+ - **The round cap is script-enforced.** A *CRITICAL round* is a run in
699
+ `story-review-history-<id>.json` holding a CRITICAL that is not
700
+ `unverified`, not `ungrounded` and not overridden; an adopted deposit adds
701
+ no run. When the review settles CRITICAL, the envelope carries
702
+ `reviewRound: { round, cap }`, where `cap` is
703
+ `delivery.acceptanceEval.maxRounds` read by the acceptance gate's own rule
704
+ (below 1 counts as 1). At `round >= cap` the handoff settles `blocked`
705
+ (cause `review-cap`), flips `agent::blocked` and posts a `friction` comment
706
+ listing each open CRITICAL's title. The cap is checked only on a CRITICAL,
707
+ so once an operator clears the block a fix that reviews clean hands off.
708
+ Anything else goes in the hand-off as the severity tally.
678
709
  - **Close adopts, else computes — and deposits.** When the deposit's digest
679
710
  equals the digest of the diff at close's held-review start, close starts no
680
711
  review and posts the deposit after PR-open. A base-sync merge that moves
@@ -381,9 +381,16 @@ PR, and not when the CI digest recorded a red against that head.
381
381
 
382
382
  ## Step 4 — CI watch + fix recovery
383
383
 
384
- Enter this step **only** when Step 3 returned `blocked` with
385
- `blockClass: "checks-failed"` (a required check went red), or when a
386
- `--no-wait-merge` run left the PR for you to shepherd. When a required check is
384
+ Enter this step when Step 3 returned `blocked` with `blocked.recovery:
385
+ "agent"` — `checks-failed` (a required check went red), `queue-ejected`,
386
+ `checks-pending-timeout`, an advisory-gate red or `api-race-other` — or when
387
+ a `--no-wait-merge` run left the PR for you to shepherd. Those blocks leave
388
+ the Story at `agent::closing` (`merged-flip-failed` is also `agent`, but the
389
+ merge already landed: re-run its `nextCommand`). The fix is this session's,
390
+ in this turn ([`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge)).
391
+ An `operator` class (`branch-protection-human-required`, `arm-failure`,
392
+ `predicate-refused`, `merge-queue-rest-unsupported`) carries `agent::blocked`
393
+ and waits for a human. When a required check is
387
394
  red, the agent owns the green-CI outcome, not just the push: CI runs on a
388
395
  different OS and concurrency, and coverage rounding, platform-conditional
389
396
  branches, and timing-sensitive tests routinely drift from the dev host.
@@ -137,12 +137,31 @@ child, and never end your turn while it is still running: "close is running"
137
137
  is not a return value. On a host that limits background commands (cloud,
138
138
  `-p`, Agent SDK, CI) a one-Story close still runs in the foreground but adds
139
139
  `--merge-watch-mode async`, so its merge wait moves into the background
140
- confirm (reference § Async merge-confirm mode). Branch on the envelope's `status` per **digest § 6**
141
- (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
142
- → Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
143
- back with labels untouched — resolve it in `workCwd`, commit, run
144
- `nextCommand`, and take the blocked path only if you cannot). Gate output is
145
- captured.
140
+ confirm (reference § Async merge-confirm mode). Gate output is captured.
141
+
142
+ ### Drive to merge {#drive-to-merge}
143
+
144
+ **Once the PR is open, the land is yours until it merges.** A red check, a
145
+ conflict or a slow CI run is the next step of the delivery, not where it
146
+ ends. Loop on the envelope's `status` (**digest § 6**) until `landed`:
147
+
148
+ 1. **`landed`** → Step 7.
149
+ 2. **`pending`** → run `nextCommand`. When it can outlive the host's
150
+ foreground ceiling, run it in the background and resume when it exits;
151
+ never end the turn on prose over an unconfirmed merge.
152
+ 3. **`failed`** → diagnose, fix, re-run close; a `phase: base-sync`
153
+ conflict comes back with labels untouched — resolve it in `workCwd`,
154
+ commit, run `nextCommand`, and take the blocked path only if you cannot.
155
+ 4. **`blocked`, `blocked.recovery: "agent"`** (the Story stays
156
+ `agent::closing`) → apply the friction comment's remedy in this turn:
157
+ read the CI digest, fix at source per
158
+ [`rules/ci-remediation.md`](../../rules/ci-remediation.md), commit, push,
159
+ re-watch, then run `nextCommand` (reference § Step 4).
160
+ 5. **Pause only** on `blocked.recovery: "operator"` (close already set
161
+ `agent::blocked`), a PR a human closed, a `capacity` /
162
+ `unreproducible-tier` verdict filed with `--block`, or the third failure
163
+ with the same fix shape ([`instructions.md` § 1.I](../../instructions.md)) — for the last two, flip
164
+ `agent::blocked` with `update-ticket-state.js` and say why.
146
165
 
147
166
  Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
148
167
  `autoMerge` policy and every close flag: reference § Step 3.
@@ -158,7 +177,8 @@ shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
158
177
  ## Steps 4–6 — Recovery (**recovery-only**) {#recover}
159
178
 
160
179
  A `landed` envelope means everything ran — go to Step 7. Enter recovery **only**
161
- when the envelope routes you there; procedures are reference §§ Step 4–6.
180
+ when [§ Drive to merge](#drive-to-merge) routes you there; procedures are
181
+ reference §§ Step 4–6.
162
182
  Two rules the spine keeps: a red **disarms auto-merge**,
163
183
  so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at source
164
184
  and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
@@ -115,7 +115,8 @@ to an attended run.
115
115
  - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
116
116
  route per reference. **4** is the protocol's HITL pause
117
117
  ([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
118
- the operator; never poll.
118
+ the operator; never poll. A CI red the session can fix leaves its Story
119
+ at `agent::closing`, so it never reaches exit 4.
119
120
 
120
121
  4. **Land what the workers hand back** (§ Closing what the workers hand back —
121
122
  the beat renders each command), then, with every Story landed, run the
@@ -151,7 +152,10 @@ resume what it names.
151
152
 
152
153
  **Reading the outcome.** Each close ends the Story in one schema-validated
153
154
  envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
154
- fields are digest § 6. `pending` is **not** a failure — run its `nextCommand`.
155
+ fields are digest § 6. Drive each close you run to merge before starting the
156
+ next — [`deliver-story.md` § Drive to merge](helpers/deliver-story.md#drive-to-merge):
157
+ run `pending`'s `nextCommand`, resolve a `base-sync` conflict, and fix, push
158
+ and resume a `blocked.recovery: "agent"` block yourself.
155
159
 
156
160
  **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
157
161
  required checks), per digest § 2; dependent Stories land sequentially. The
@@ -165,6 +169,8 @@ table is reference § Ceremony.
165
169
  - **Land or block — never a silent local build** (digest § 2). Attended delivers
166
170
  default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
167
171
  `agent::closing` only when a human owns the merge.
172
+ - **A run ends at `landed` or an operator-owned block** — never at a red
173
+ check or a conflict this session can fix.
168
174
  - **`/mandrel-deliver` never plans.** Planned tickets come from
169
175
  [`/mandrel-plan`](mandrel-plan.md), and a refused prompt **escalates**: the
170
176
  light path ends, and the escalation's `nextCommand` is what owns the work —
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,21 @@ 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.124.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.123.0...mandrel-v2.124.0) (2026-11-17)
19
+
20
+
21
+ ### Added
22
+
23
+ * a Story's first held review is an exhaustive deep pass that sweeps every instance of each defect class ([#6100](https://github.com/dsj1984/mandrel/issues/6100)) ([#6102](https://github.com/dsj1984/mandrel/issues/6102)) ([ba0b87f](https://github.com/dsj1984/mandrel/commit/ba0b87f20709a37152885826f04493ae7ddddf16))
24
+ * deliver drives the PR to merge: agent-recoverable CI reds and conflicts are fixed in-session, only operator-owned blocks pause ([#6091](https://github.com/dsj1984/mandrel/issues/6091)) ([#6092](https://github.com/dsj1984/mandrel/issues/6092)) ([07caf64](https://github.com/dsj1984/mandrel/commit/07caf6459d1ffd8e266b530529f0f28670837226))
25
+ * story-handoff bounds the held-review loop, retries a review-critical fix review-first, and fails fast on cheap blocking gates ([#6099](https://github.com/dsj1984/mandrel/issues/6099)) ([#6103](https://github.com/dsj1984/mandrel/issues/6103)) ([9a4db8a](https://github.com/dsj1984/mandrel/commit/9a4db8aca84b54c1b4b518e8a8f4a6c911a1c580))
26
+
27
+
28
+ ### Fixed
29
+
30
+ * **deps:** replace picomatch with minimatch behind one glob seam ([#6093](https://github.com/dsj1984/mandrel/issues/6093)) ([2db3b96](https://github.com/dsj1984/mandrel/commit/2db3b969e15f7b749f0bac1502c590a8ccdbf035))
31
+ * **test:** give suite-admission AC-6's first backfiller its own window (refs [#6105](https://github.com/dsj1984/mandrel/issues/6105)) ([#6106](https://github.com/dsj1984/mandrel/issues/6106)) ([896851e](https://github.com/dsj1984/mandrel/commit/896851e220733a242ad32773e37b52005cbfd2f9))
32
+
18
33
  ## [2.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
19
34
 
20
35
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.123.0",
3
+ "version": "2.124.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/",
@@ -124,7 +124,7 @@
124
124
  "escomplex-plugin-metrics-module": "^0.1.0",
125
125
  "escomplex-plugin-syntax-babylon": "^0.1.0",
126
126
  "js-yaml": "^5.4.3",
127
- "picomatch": "^4.0.7",
127
+ "minimatch": "^11.0.9",
128
128
  "typhonjs-ast-walker": "^0.2.1",
129
129
  "typhonjs-escomplex-commons": "^0.1.1"
130
130
  },