mandrel 2.71.0 → 2.73.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 (22) hide show
  1. package/.agents/schemas/story-deliver-terminal.schema.json +10 -1
  2. package/.agents/scripts/lib/baselines/crap-updater-cli.js +57 -15
  3. package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
  4. package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
  5. package/.agents/scripts/lib/orchestration/pr-watch.js +14 -3
  6. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +45 -0
  7. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +13 -4
  8. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +54 -6
  9. package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
  10. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
  11. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
  12. package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
  13. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
  14. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
  15. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +161 -57
  16. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
  17. package/.agents/scripts/pr-watch-with-update.js +5 -0
  18. package/.agents/scripts/single-story-confirm-merge.js +34 -3
  19. package/.agents/workflows/helpers/deliver-story-reference.md +28 -9
  20. package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
  21. package/docs/CHANGELOG.md +19 -0
  22. package/package.json +1 -1
@@ -326,6 +326,34 @@ export function emitTerminalEnvelope(
326
326
  );
327
327
  }
328
328
 
329
+ /**
330
+ * The PR facts every wait ending carries. `autoMergeReason` rides along only
331
+ * when the caller knows it — it is the evidence a later re-arm reads.
332
+ */
333
+ function prBaseFor({ prNumber, prUrl, autoMergeEnabled, autoMergeReason }) {
334
+ const base = {
335
+ number: prNumber,
336
+ url: prUrl ?? null,
337
+ autoMergeEnabled: Boolean(autoMergeEnabled),
338
+ };
339
+ return autoMergeReason === undefined ? base : { ...base, autoMergeReason };
340
+ }
341
+
342
+ /**
343
+ * A DIRTY PR the wait could not sync: labels untouched, and re-running close
344
+ * (which re-syncs in the worktree) is the remedy.
345
+ */
346
+ function failedFromWaitOutcome(waitOutcome, prBase, common) {
347
+ return buildTerminalEnvelope({
348
+ ...common,
349
+ status: 'failed',
350
+ phase: waitOutcome.phase ?? 'base-sync',
351
+ pr: { ...prBase, state: waitOutcome.prProbe?.state ?? 'OPEN' },
352
+ failure: { reason: waitOutcome.reason },
353
+ nextCommand: NEXT_COMMANDS.close(common.storyId),
354
+ });
355
+ }
356
+
329
357
  /**
330
358
  * Map a `runConfirmMergePhase` outcome onto the terminal envelope; the other
331
359
  * fields pass through.
@@ -337,14 +365,16 @@ export function terminalFromWaitOutcome({
337
365
  prNumber,
338
366
  prUrl,
339
367
  autoMergeEnabled,
368
+ autoMergeReason,
340
369
  ...common
341
370
  }) {
342
371
  const { storyId } = common;
343
- const prBase = {
344
- number: prNumber,
345
- url: prUrl ?? null,
346
- autoMergeEnabled: Boolean(autoMergeEnabled),
347
- };
372
+ const prBase = prBaseFor({
373
+ prNumber,
374
+ prUrl,
375
+ autoMergeEnabled,
376
+ autoMergeReason,
377
+ });
348
378
 
349
379
  if (waitOutcome.terminal === 'landed') {
350
380
  return buildTerminalEnvelope({
@@ -377,7 +407,17 @@ export function terminalFromWaitOutcome({
377
407
  });
378
408
  }
379
409
 
380
- // blocked — mirror the classifier's remediation, never a second opinion.
410
+ if (waitOutcome.terminal === 'failed') {
411
+ return failedFromWaitOutcome(waitOutcome, prBase, common);
412
+ }
413
+
414
+ return blockedFromWaitOutcome(waitOutcome, prBase, common);
415
+ }
416
+
417
+ /** Mirrors the classifier's remediation, never a second opinion. */
418
+ function blockedFromWaitOutcome(waitOutcome, prBase, common) {
419
+ const { storyId } = common;
420
+ const prNumber = prBase.number;
381
421
  const nextCommand =
382
422
  waitOutcome.blockClass === 'checks-failed'
383
423
  ? NEXT_COMMANDS.watchCi(storyId, prNumber)
@@ -376,6 +376,7 @@ function buildWatchArgs({
376
376
  ghPrChecksFn,
377
377
  ghPrViewFn,
378
378
  ghPrUpdateBranchFn,
379
+ ghApiFn,
379
380
  sleepFn,
380
381
  logger,
381
382
  }) {
@@ -390,6 +391,7 @@ function buildWatchArgs({
390
391
  ...(ghPrChecksFn ? { ghPrChecksFn } : {}),
391
392
  ...(ghPrViewFn ? { ghPrViewFn } : {}),
392
393
  ...(ghPrUpdateBranchFn ? { ghPrUpdateBranchFn } : {}),
394
+ ghApiFn,
393
395
  ...(sleepFn ? { sleepFn } : {}),
394
396
  logger,
395
397
  };
@@ -605,6 +607,7 @@ async function settleRedWatch({
605
607
  * @param {Function} [opts.ghPrChecksFn]
606
608
  * @param {Function} [opts.ghPrViewFn]
607
609
  * @param {Function} [opts.ghPrUpdateBranchFn]
610
+ * @param {Function} [opts.ghApiFn]
608
611
  * @param {Function} [opts.sleepFn]
609
612
  * @param {Function} [opts.writeDigestFn]
610
613
  * @param {Function} [opts.readDigestFn]
@@ -630,6 +633,7 @@ export async function runPrWatch({
630
633
  ghPrChecksFn,
631
634
  ghPrViewFn,
632
635
  ghPrUpdateBranchFn,
636
+ ghApiFn,
633
637
  sleepFn,
634
638
  writeDigestFn = writeCiDigest,
635
639
  readDigestFn = readCiDigest,
@@ -676,6 +680,7 @@ export async function runPrWatch({
676
680
  ghPrChecksFn,
677
681
  ghPrViewFn,
678
682
  ghPrUpdateBranchFn,
683
+ ghApiFn,
679
684
  sleepFn,
680
685
  logger,
681
686
  }),
@@ -27,12 +27,15 @@ import { getStoryBranch } from './lib/git-utils.js';
27
27
  import { Logger } from './lib/Logger.js';
28
28
  import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
29
29
  import { emitTerseResult } from './lib/observability/terse-result.js';
30
+ import { probeCloseArtifacts } from './lib/orchestration/deliver-recover.js';
30
31
  import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
31
32
  import { MERGE_WAIT_GH_TIMEOUT_MS } from './lib/orchestration/merge-poll.js';
33
+ import { closeArmedPr } from './lib/orchestration/single-story-close/phases/auto-merge.js';
32
34
  import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
33
35
  import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
34
36
  import { assertNoRetiredFlags } from './lib/orchestration/single-story-close/phases/options.js';
35
37
  import { runPostLandTail } from './lib/orchestration/single-story-close/phases/post-land.js';
38
+ import { resolveStoryWorktree } from './lib/orchestration/single-story-close/phases/worktree-restore.js';
36
39
  import {
37
40
  buildTerminalEnvelope,
38
41
  emitTerminalEnvelope,
@@ -268,22 +271,44 @@ async function confirmWithoutPr(ctx) {
268
271
  );
269
272
  }
270
273
 
274
+ /** Lazy: only a DIRTY sync needs the worktree, never confirming a merge. */
275
+ function lazyWaitWorktree({ cwd, config, storyId, storyBranch, ...ctx }) {
276
+ return () =>
277
+ ctx.resolveWorktreeFn({ cwd, config, storyId, storyBranch, progress });
278
+ }
279
+
280
+ /**
281
+ * What the last close recorded about the arm, off its persisted envelope.
282
+ * Only positive evidence that close armed the PR lets the wait re-arm it.
283
+ *
284
+ * @returns {{ armed: boolean, reason: string|null }}
285
+ */
286
+ function readCloseArmEvidence({ storyId, config, readCloseEnvelopeFn }) {
287
+ const { envelope } = readCloseEnvelopeFn({ storyId, config });
288
+ const pr = envelope?.storyId === storyId ? envelope.pr : null;
289
+ return { armed: closeArmedPr(pr), reason: pr?.autoMergeReason ?? null };
290
+ }
291
+
271
292
  /**
272
293
  * `--wait` runs the SAME phase as close so the cumulative budget give-up
273
294
  * (the only path to `merge.unlanded` / `agent::blocked`) is reachable from a
274
295
  * resume. The budget is anchored at the PR's `createdAt`, so resuming does
275
- * not restart the clock.
296
+ * not restart the clock. The Story worktree is resolved (and recreated when
297
+ * missing) exactly as close does, so a DIRTY PR syncs there.
276
298
  */
277
299
  async function resumeMergeWait(ctx) {
278
300
  const { storyId, storyBranch, baseBranch, prNumber } = ctx;
301
+ const evidence = readCloseArmEvidence(ctx);
279
302
  const waitOutcome = await ctx.runConfirmMergePhaseFn({
280
303
  cwd: ctx.cwd,
304
+ resolveWorktree: lazyWaitWorktree(ctx),
305
+ closeArmed: evidence.armed,
281
306
  storyId,
282
307
  storyBranch,
283
308
  baseBranch,
284
309
  prNumber,
285
310
  prUrl: `${storyBranch} PR #${prNumber}`,
286
- // The close already armed it.
311
+ // Enters the wait; re-arming a disarmed PR needs `closeArmed` above.
287
312
  autoMergeEnabled: true,
288
313
  maxWaitSeconds: ctx.maxWaitSeconds,
289
314
  provider: ctx.provider,
@@ -300,7 +325,9 @@ async function resumeMergeWait(ctx) {
300
325
  baseBranch,
301
326
  prNumber,
302
327
  prUrl: null,
303
- autoMergeEnabled: true,
328
+ // Carried forward, so the next resume reads the same evidence.
329
+ autoMergeEnabled: evidence.armed,
330
+ autoMergeReason: evidence.reason,
304
331
  // This CLI runs no close gates.
305
332
  gates: undefined,
306
333
  elapsedSeconds: elapsedSeconds(ctx),
@@ -382,6 +409,8 @@ export async function runConfirmMerge({
382
409
  injectedNotify,
383
410
  injectedReadPrMergeState,
384
411
  runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
412
+ resolveWorktreeFn = resolveStoryWorktree,
413
+ readCloseEnvelopeFn = probeCloseArtifacts,
385
414
  } = {}) {
386
415
  if (!storyId) {
387
416
  throw new Error(USAGE);
@@ -403,6 +432,8 @@ export async function runConfirmMerge({
403
432
  injectedNotify,
404
433
  injectedReadPrMergeState,
405
434
  runConfirmMergePhaseFn,
435
+ resolveWorktreeFn,
436
+ readCloseEnvelopeFn,
406
437
  };
407
438
 
408
439
  progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
@@ -326,8 +326,13 @@ The `single-story-close.js` script, in order:
326
326
  would strand a CLOSED issue with no merged work if the PR failed CI, went
327
327
  `BEHIND` base, or closed unmerged. A Story only reaches `agent::done` once
328
328
  its PR to `main` is confirmed merged (Step 5).
329
- 6. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
330
- is enabled.
329
+ 6. **Leaves the worktree in place.** Worktree lifetime is Story lifetime:
330
+ only the post-land tail reaps it (`tail.worktreeReap`, run before
331
+ `tail.refCleanup` because `git branch -D` refuses a branch a live
332
+ worktree holds; `reapOnSuccess: false` keeps it), so a `pending`,
333
+ `blocked` or `failed` close keeps its working copy. A missing worktree is
334
+ recreated from `story-<id>` before close's first git operation — and the
335
+ `--wait` resume's — never falling back to the main checkout.
331
336
  7. **Releases the Story lease** — a no-op when the operator no longer holds
332
337
  the claim, so a late close never yanks a live claim. Best-effort: a
333
338
  release failure is logged, not fatal, and reported as
@@ -335,6 +340,18 @@ The `single-story-close.js` script, in order:
335
340
  own, so a claim stranded by a failed release is cleared only by `--steal`
336
341
  or by de-assigning the ticket.
337
342
 
343
+ The merge wait recovers on its own when `main` moves under the queued PR. A
344
+ `DIRTY` PR is merged with `origin/<base>` in the Story worktree in that same
345
+ poll (baseline-only conflicts auto-resolve), pushed with hooks, and the wait
346
+ continues — each sync spends one of the BEHIND update attempts. A conflict,
347
+ any other sync failure, or a spent budget posts `friction`, leaves the labels
348
+ alone, and ends `failed` at `phase: base-sync` naming the conflicted files
349
+ and the worktree: resolve there, commit, re-run close. The worktree is
350
+ resolved only for that sync, never to confirm a merge. A PR a new head
351
+ disarmed is re-armed once per head SHA, only when close armed it (the close
352
+ itself, or its persisted envelope) — never a `--no-auto-merge` or `strict`
353
+ PR, and not when the CI digest recorded a red against that head.
354
+
338
355
  ---
339
356
 
340
357
  ## Step 4 — CI watch + fix recovery
@@ -438,15 +455,17 @@ or an unrecoverable failure (→ `status: "failed"`) ends the turn — or a
438
455
  genuine `pending` (§ Step 7). The statuses are the shipped
439
456
  [terminal schema](../../schemas/story-deliver-terminal.schema.json)'s.
440
457
 
441
- ### Resurrecting the worktree after `reapOnSuccess`
458
+ ### A missing Story worktree
442
459
 
443
- `single-story-close.js` reaps the worktree on success when
444
- `delivery.worktreeIsolation.reapOnSuccess` is enabled (the default). To
445
- fix CI you must re-attach a worktree to the existing remote branch:
460
+ The worktree survives until the land, so a red PR's worktree is normally
461
+ still at `.worktrees/story-<storyId>/`. When it is gone, re-running close (or
462
+ the `--wait` resume) recreates it from `story-<storyId>`, fetching the ref
463
+ from origin when only the remote copy is left. To fix CI by hand first:
446
464
 
447
465
  ```bash
448
466
  cd <main-repo>
449
- git fetch origin story-<storyId>
467
+ git fetch origin story-<storyId>:story-<storyId>
468
+ git worktree prune # a deleted-but-registered entry blocks the add
450
469
  git worktree add .worktrees/story-<storyId> story-<storyId>
451
470
  cd .worktrees/story-<storyId>
452
471
  ```
@@ -535,8 +554,8 @@ once per project to delete the conflicting bot workflows entirely.
535
554
 
536
555
  ## Step 6 — Local branch cleanup detail
537
556
 
538
- > **The land tail already ran this** — it is `tail.refCleanup` and
539
- > `tail.baseFastForward` in the terminal envelope. Run it by hand only when
557
+ > **The land tail already ran this** — it is `tail.worktreeReap`,
558
+ > `tail.refCleanup` and `tail.baseFastForward` in the terminal envelope. Run it by hand only when
540
559
  > either step reported `false` (a dirty shared checkout is the common, benign
541
560
  > cause), or after a manual merge on a `--no-wait-merge` run:
542
561
 
@@ -50,9 +50,9 @@ root, and shell-metacharacter injection in `root`.
50
50
  | **Sweep** | Operator-driven (`WorktreeManager.sweepStaleLocks`) | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC. |
51
51
  | **GC** | Operator-driven (`WorktreeManager.gc`) | Orphan `.worktrees/story-*` whose Stories are closed are reaped if clean. |
52
52
  | **Force-drain** | Operator-driven (`drain-pending-cleanup.js`) | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
53
- | **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`) | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch. |
53
+ | **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`); close and the `--wait` resume when it is missing | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch (fetched from origin when no local ref remains). |
54
54
  | **Run** | During Story execution | Agent runs inside the worktree; HEAD/reflog activity is isolated. |
55
- | **Reap** | After successful Story merge (in `single-story-close`) | `git worktree remove` — refuses to delete dirty trees or unmerged branches. |
55
+ | **Reap** | After a confirmed merge, in the post-land tail (`tail.worktreeReap`) | `git worktree remove`, before the local ref reap — refuses a dirty tree. A `pending`, `blocked` or `failed` close keeps the worktree. |
56
56
 
57
57
  The `WorktreeManager` (`.agents/scripts/lib/worktree-manager.js`) is the single
58
58
  authority for `ensure`, `reap`, `list`, `isSafeToRemove`, `gc`, `prune`, and
@@ -86,7 +86,7 @@ epic-runner. The lifecycle surfaces that do run automatically are:
86
86
  | Entry point | Script / caller | What it cleans |
87
87
  | --------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
88
88
  | Story init (`/mandrel-deliver <storyId>`) | `single-story-init.js` boot sweep (`sweepMergedStoryBranches`) | Merged/closed `story-*` branches (local + origin) from prior runs; it then creates only its own worktree. |
89
- | Story close (`/mandrel-deliver` close) | `single-story-close.js` worktree-reap phase (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
89
+ | Story land (close's wait, or `--wait`) | The post-land tail's worktree-reap step (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
90
90
  | Drain pending-cleanup (operator) | `drain-pending-cleanup.js` (run directly — see below) | The pending-cleanup ledger, with optional Windows handle-holder escalation. This is the only path that drains the ledger. |
91
91
 
92
92
  Operator takeaway: if worktrees or stale locks accumulate, run
@@ -95,8 +95,8 @@ Operator takeaway: if worktrees or stale locks accumulate, run
95
95
 
96
96
  ## Draining the pending-cleanup ledger
97
97
 
98
- `.worktrees/.pending-cleanup.json` accumulates entries when
99
- `single-story-close.js` cannot remove a worktree on Windows because of
98
+ `.worktrees/.pending-cleanup.json` accumulates entries when the
99
+ post-land tail cannot remove a worktree on Windows because of
100
100
  an EBUSY-class lock. If the holder is a long-lived user-mode process (a
101
101
  stranded test runner, a lingering biome/tsc, a node REPL), the lock
102
102
  never clears and the entry pins.
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,25 @@ 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.73.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.72.0...mandrel-v2.73.0) (2026-10-02)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * **baselines:** CRAP --seat-missing seats nothing, without demanding coverage, when no diff file is in the gate's scope ([#5540](https://github.com/dsj1984/mandrel/issues/5540)) ([#5541](https://github.com/dsj1984/mandrel/issues/5541)) ([169798e](https://github.com/dsj1984/mandrel/commit/169798ef90e32030148203e8e881f60ee907e404))
24
+
25
+ ## [2.72.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.71.0...mandrel-v2.72.0) (2026-10-01)
26
+
27
+
28
+ ### Added
29
+
30
+ * close keeps the worktree until land, self-syncs a DIRTY PR, re-arms a disarmed PR, and recover names both ([#5533](https://github.com/dsj1984/mandrel/issues/5533)) ([#5537](https://github.com/dsj1984/mandrel/issues/5537)) ([5e0fd9c](https://github.com/dsj1984/mandrel/commit/5e0fd9c8e2bcc7984188db291f20d3171c234c69))
31
+
32
+
33
+ ### Fixed
34
+
35
+ * pr-watch ignores a required check from a concurrency-cancelled run while a live run on the same head exists ([#5534](https://github.com/dsj1984/mandrel/issues/5534)) ([#5535](https://github.com/dsj1984/mandrel/issues/5535)) ([caa2d6a](https://github.com/dsj1984/mandrel/commit/caa2d6ab935dd70d2ba40b3b8e952e4587a1ef1e))
36
+
18
37
  ## [2.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.70.0...mandrel-v2.71.0) (2026-09-30)
19
38
 
20
39
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.71.0",
3
+ "version": "2.73.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/",