mandrel 2.74.0 → 2.75.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.
@@ -1,24 +1,77 @@
1
- /** A Story whose worktree exists and whose close has not finished. */
2
- export type InFlight = {
3
- storyId: number;
4
- /** True once close has written its gate log. */
5
- isClosing: boolean;
6
- /** Minutes since the gate log last changed, when over the stall limit. */
7
- stalledMinutes: number | null;
1
+ /** The six stages of a /mandrel-deliver Story, in order. */
2
+ export type StageName =
3
+ | 'start'
4
+ | 'build'
5
+ | 'check'
6
+ | 'handoff'
7
+ | 'close'
8
+ | 'merge';
9
+
10
+ /** One stage as the Details pane lists it; times in epoch milliseconds. */
11
+ export type StageRow = {
12
+ name: StageName;
13
+ startedAt: number | null;
14
+ /** The next stage's start, or null while this one is current or pending. */
15
+ endedAt: number | null;
16
+ };
17
+
18
+ /** One close phase: its recorded duration and the learned median, in seconds. */
19
+ export type PhaseRow = {
20
+ name: string;
21
+ seconds: number | null;
22
+ usualSeconds: number | null;
8
23
  };
9
24
 
10
- /** The newest terminal envelope from the last two hours. */
11
- export type LastResult = {
25
+ /** The Story the band follows: in flight, or the newest recent result. */
26
+ export type Focus = {
12
27
  storyId: number;
28
+ title: string | null;
29
+ /** `in-flight`, or the terminal envelope's `status`. */
13
30
  status: string;
31
+ stage: StageName;
32
+ /** The current stage's step detail, already worded. */
33
+ detail: string;
34
+ stages: StageRow[];
35
+ handoffSteps: { name: string; at: number }[];
36
+ closePhases: PhaseRow[];
14
37
  prNumber: number | null;
15
38
  checksStatus: string | null;
39
+ /** The envelope's `elapsedSeconds`, for a finished result. */
16
40
  elapsedSeconds: number | null;
41
+ /** Milliseconds into the current phase, while in flight. */
42
+ phaseElapsedMs: number | null;
43
+ /** The learned median of the current phase, once it has 3+ samples. */
44
+ usualMs: number | null;
45
+ isStalled: boolean;
46
+ /** Minutes the gate log has been quiet, when the 10-minute rule fired. */
47
+ idleMinutes: number | null;
48
+ /** `blocked.blockClass` or `failure.reason`. */
49
+ problem: string | null;
50
+ nextCommand: string | null;
51
+ /** Bullets in `follow-ups-rollup-<id>.md`, when it exists. */
52
+ followUps: number | null;
53
+ };
54
+
55
+ /** The newest live multi-Story run ledger. */
56
+ export type RunLine = {
57
+ landed: number;
58
+ total: number;
59
+ current: { storyId: number; stage: string } | null;
60
+ queued: number;
17
61
  };
18
62
 
19
63
  export type Snapshot = {
20
- inFlight: InFlight | null;
21
- last: LastResult | null;
64
+ focus: Focus | null;
65
+ run: RunLine | null;
66
+ /** When the scan ran, epoch milliseconds; 0 before the first. */
67
+ scannedAt: number;
68
+ };
69
+
70
+ /** Per close phase: the median of the newest terminal envelopes' timings. */
71
+ export type Learned = {
72
+ /** When the medians were last computed; 0 before the first pass. */
73
+ at: number;
74
+ phases: Record<string, { medianSeconds: number; samples: number }>;
22
75
  };
23
76
 
24
77
  declare module 'claude-code' {
@@ -29,6 +82,9 @@ declare module 'claude-code' {
29
82
  seen: string[];
30
83
  /** False until the first scan, which records envelopes without a toast. */
31
84
  isSeeded: boolean;
85
+ learned: Learned;
86
+ /** The focus Story the person hid the band for; it shows again on a new one. */
87
+ hiddenFor: number | null;
32
88
  };
33
89
  }
34
90
  }
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-progress.schema.json",
4
+ "title": "story-progress",
5
+ "description": "The live progress record a Story's handoff and close rewrite at every step or phase change (Story #5553), at <tempRoot>/orchestration/story-progress-<id>.json. It exists because push, PR, review, auto-merge and the merge wait leave nothing on disk until the terminal envelope. Advisory only: nothing in Mandrel reads it to decide anything, every write is best effort, and each write is atomic (a <file>.tmp sibling renamed over the target).",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "kind",
10
+ "storyId",
11
+ "stage",
12
+ "phase",
13
+ "stageStartedAt",
14
+ "phaseStartedAt",
15
+ "prNumber",
16
+ "updatedAt"
17
+ ],
18
+ "properties": {
19
+ "kind": { "type": "string", "const": "story-progress" },
20
+ "storyId": { "type": "integer", "minimum": 1 },
21
+ "stage": {
22
+ "type": "string",
23
+ "enum": ["handoff", "close"],
24
+ "description": "handoff — the worker's story-handoff.js run; close — single-story-close.js."
25
+ },
26
+ "phase": {
27
+ "type": "string",
28
+ "minLength": 1,
29
+ "description": "For close, the phase name close passes to setPhase (the phaseDurations keys). For handoff, the step name: preflight, base-merge, credited-run, seat, push, review."
30
+ },
31
+ "stageStartedAt": {
32
+ "type": "string",
33
+ "format": "date-time",
34
+ "description": "When this handoff or close run started; fixed for the run."
35
+ },
36
+ "phaseStartedAt": {
37
+ "type": "string",
38
+ "format": "date-time",
39
+ "description": "When the current phase started; resets on each phase change."
40
+ },
41
+ "prNumber": {
42
+ "type": ["integer", "null"],
43
+ "minimum": 1,
44
+ "description": "The Story PR's number from the moment close parses it; null before then and throughout handoff."
45
+ },
46
+ "updatedAt": { "type": "string", "format": "date-time" }
47
+ }
48
+ }
@@ -229,6 +229,21 @@ export function storyReviewDepositPath(sid, config) {
229
229
  );
230
230
  }
231
231
 
232
+ /**
233
+ * Live phase record for a Story's handoff or close. The trailing
234
+ * `-<id>` keys it to the Story for the retention purge.
235
+ *
236
+ * @param {number} sid
237
+ * @param {object} [config]
238
+ * @returns {string}
239
+ */
240
+ export function storyProgressPath(sid, config) {
241
+ return path.join(
242
+ orchestrationLogDir(config),
243
+ `story-progress-${storyId(sid)}.json`,
244
+ );
245
+ }
246
+
232
247
  const runId = (id) => {
233
248
  if (!Number.isInteger(id) || id <= 0) {
234
249
  throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);
@@ -30,6 +30,7 @@ import {
30
30
  NEXT_COMMANDS,
31
31
  terminalFromWaitOutcome,
32
32
  } from '../story-deliver-terminal.js';
33
+ import { createStoryProgress } from '../story-progress.js';
33
34
  import { deriveCloseNote } from './close-note.js';
34
35
  import { closeArmedPr, runAutoMergePhase } from './phases/auto-merge.js';
35
36
  import { runBaseSyncPhase } from './phases/base-sync.js';
@@ -430,6 +431,7 @@ async function openAndReviewPr(ctx, deps) {
430
431
  progress,
431
432
  });
432
433
  const prNumber = parsePrNumber(prUrl);
434
+ ctx.recordPrNumber(prNumber);
433
435
  // Already merged (landed between invocations): skip review and arm; confirm observes it.
434
436
  if (alreadyMerged) {
435
437
  discardHeldReview(ctx.heldReview, 'PR already merged', progress);
@@ -623,18 +625,34 @@ export async function runSingleStoryClose({
623
625
  let phase = 'init';
624
626
  let observedGates = null;
625
627
  const phaseTimer = createPhaseTimer();
628
+ // Inert until the config resolves; no phase is entered before then.
629
+ let storyProgress = { phase() {}, prNumber() {} };
626
630
  const setPhase = (next) => {
627
631
  phase = next;
628
632
  phaseTimer.enter(next);
633
+ storyProgress.phase(next);
629
634
  };
630
635
  const setObservedGates = (gates) => {
631
636
  observedGates = gates;
632
637
  };
633
638
  try {
634
639
  const startedAtMs = Date.now();
640
+ const deps = resolveCloseDeps(options, injected);
641
+ storyProgress = createStoryProgress({
642
+ storyId: options.storyId,
643
+ stage: 'close',
644
+ config: deps.config,
645
+ });
635
646
  return await runClosePipeline(
636
- { options, setPhase, setObservedGates, phaseTimer, startedAtMs },
637
- resolveCloseDeps(options, injected),
647
+ {
648
+ options,
649
+ setPhase,
650
+ setObservedGates,
651
+ phaseTimer,
652
+ startedAtMs,
653
+ recordPrNumber: storyProgress.prNumber,
654
+ },
655
+ deps,
638
656
  );
639
657
  } catch (err) {
640
658
  if (err && typeof err === 'object') {
@@ -1007,7 +1025,10 @@ async function resolveCloseWorktree(ctx, deps) {
1007
1025
  !existingWorktreePath({ cwd, wtIsolation, storyId: ctx.storyId }) &&
1008
1026
  resolveWorktreeEnabled({ config: deps.config });
1009
1027
  ctx.landedPr = missing ? await findLandedPr(ctx, deps) : null;
1010
- if (ctx.landedPr) return null;
1028
+ if (ctx.landedPr) {
1029
+ ctx.recordPrNumber(ctx.landedPr.prNumber);
1030
+ return null;
1031
+ }
1011
1032
  return await resolveStoryWorktree({
1012
1033
  cwd,
1013
1034
  config: deps.config,
@@ -38,6 +38,7 @@ import { getStoryBranch, gitSpawn } from '../git-utils.js';
38
38
  import { readPackageScripts } from '../npm-scripts.js';
39
39
  import { TIMEOUT_EXIT_CODE } from '../process-group.js';
40
40
  import { probeHeldReviewDiff } from './review-deposit.js';
41
+ import { createStoryProgress, handoffStepName } from './story-progress.js';
41
42
  import {
42
43
  STATE_LABELS,
43
44
  transitionTicketState,
@@ -815,7 +816,13 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
815
816
  const steps = [];
816
817
  let stop = precheck(ctx);
817
818
  if (stop) steps.push(stop);
819
+ const storyProgress = createStoryProgress({
820
+ storyId,
821
+ stage: 'handoff',
822
+ config,
823
+ });
818
824
  for (const step of stop ? [] : stepOrder(ctx.depositor)) {
825
+ storyProgress.phase(handoffStepName(step));
819
826
  const result = await step(ctx);
820
827
  steps.push(result);
821
828
  progress(result.name, `${result.outcome} — ${result.detail}`);
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The live story-progress record: which handoff step or close
3
+ * phase a Story is in right now, so live tooling can see the post-validation
4
+ * close phases that otherwise leave nothing on disk until the terminal
5
+ * envelope. Shape: `.agents/schemas/story-progress.schema.json`.
6
+ *
7
+ * Advisory only — nothing in Mandrel decides on it. Every write is best
8
+ * effort (an fs error is swallowed and logged at debug) and atomic (a
9
+ * `<file>.tmp` sibling renamed over the target), so a poller never parses
10
+ * half a file and an unwritable temp folder changes no delivery outcome.
11
+ */
12
+
13
+ import fs from 'node:fs';
14
+ import path from 'node:path';
15
+
16
+ import { storyProgressPath } from '../config/temp-paths.js';
17
+ import { Logger } from '../Logger.js';
18
+
19
+ const STORY_PROGRESS_KIND = 'story-progress';
20
+
21
+ /**
22
+ * A handoff step's reported name from its function name: `stepBaseMerge` →
23
+ * `base-merge`. The handoff suite pins that these equal the names each step
24
+ * reports in its envelope.
25
+ *
26
+ * @param {Function} step
27
+ * @returns {string}
28
+ */
29
+ export function handoffStepName(step) {
30
+ return step.name
31
+ .replace(/^step/, '')
32
+ .replace(/[A-Z]/g, (c, i) => `${i > 0 ? '-' : ''}${c.toLowerCase()}`);
33
+ }
34
+
35
+ /**
36
+ * Write `record` to `file` atomically. Never throws.
37
+ *
38
+ * @param {string} file
39
+ * @param {object} record
40
+ * @param {{ fsImpl?: typeof fs, debug?: (msg: string) => void }} [deps]
41
+ * @returns {boolean} whether the record landed
42
+ */
43
+ function writeStoryProgress(file, record, deps = {}) {
44
+ const fsImpl = deps.fsImpl ?? fs;
45
+ const debug = deps.debug ?? ((msg) => Logger.debug(msg));
46
+ const tmp = `${file}.tmp`;
47
+ try {
48
+ fsImpl.mkdirSync(path.dirname(file), { recursive: true });
49
+ fsImpl.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
50
+ fsImpl.renameSync(tmp, file);
51
+ return true;
52
+ } catch (err) {
53
+ try {
54
+ fsImpl.rmSync(tmp, { force: true });
55
+ } catch {
56
+ // The stray tmp is harmless; the next write overwrites it.
57
+ }
58
+ debug(`[story-progress] write skipped for ${file}: ${err?.message ?? err}`);
59
+ return false;
60
+ }
61
+ }
62
+
63
+ /**
64
+ * A per-run recorder: `stageStartedAt` is fixed at creation, `phaseStartedAt`
65
+ * resets on each `phase()`, and `prNumber()` re-writes the current phase with
66
+ * the PR number once known. Nothing is written until the first `phase()`.
67
+ * Construction never throws either: a bad Story id or config degrades to a
68
+ * recorder that writes nothing.
69
+ *
70
+ * @param {{ storyId: number, stage: 'handoff'|'close', config?: object,
71
+ * file?: string, now?: () => Date, fsImpl?: typeof fs,
72
+ * debug?: (msg: string) => void }} args
73
+ * @returns {{ phase: (name: string) => boolean, prNumber: (n: number|null) => boolean, file: string|null }}
74
+ */
75
+ export function createStoryProgress({
76
+ storyId,
77
+ stage,
78
+ config,
79
+ file,
80
+ now = () => new Date(),
81
+ fsImpl,
82
+ debug,
83
+ }) {
84
+ let target = file ?? null;
85
+ if (!target) {
86
+ try {
87
+ target = storyProgressPath(storyId, config);
88
+ } catch (err) {
89
+ (debug ?? ((msg) => Logger.debug(msg)))(
90
+ `[story-progress] no progress path: ${err?.message ?? err}`,
91
+ );
92
+ }
93
+ }
94
+ const stageStartedAt = now().toISOString();
95
+ let current = null;
96
+ let phaseStartedAt = stageStartedAt;
97
+ let pr = null;
98
+ const write = () => {
99
+ if (!target || current === null) return false;
100
+ return writeStoryProgress(
101
+ target,
102
+ {
103
+ kind: STORY_PROGRESS_KIND,
104
+ storyId,
105
+ stage,
106
+ phase: current,
107
+ stageStartedAt,
108
+ phaseStartedAt,
109
+ prNumber: pr,
110
+ updatedAt: now().toISOString(),
111
+ },
112
+ { fsImpl, debug },
113
+ );
114
+ };
115
+ return {
116
+ file: target,
117
+ phase(name) {
118
+ current = name;
119
+ phaseStartedAt = now().toISOString();
120
+ return write();
121
+ },
122
+ prNumber(n) {
123
+ pr = Number.isInteger(n) && n > 0 ? n : null;
124
+ return write();
125
+ },
126
+ };
127
+ }
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,14 @@ 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.75.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.74.0...mandrel-v2.75.0) (2026-10-02)
19
+
20
+
21
+ ### Added
22
+
23
+ * close and handoff write a story-progress file at every phase change, so live tooling can see post-validation close phases ([#5553](https://github.com/dsj1984/mandrel/issues/5553)) ([#5554](https://github.com/dsj1984/mandrel/issues/5554)) ([84c9a87](https://github.com/dsj1984/mandrel/commit/84c9a87c46253601e0ccbe681d0b9bd41eb20a4a))
24
+ * **mods:** mandrel-status band v2 with stage strip, learned ETAs and run line (refs [#5552](https://github.com/dsj1984/mandrel/issues/5552)) ([#5555](https://github.com/dsj1984/mandrel/issues/5555)) ([d194043](https://github.com/dsj1984/mandrel/commit/d194043b554bfb96371bfbc4ab0029b0c445bc9e))
25
+
18
26
  ## [2.74.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.73.0...mandrel-v2.74.0) (2026-10-02)
19
27
 
20
28
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.74.0",
3
+ "version": "2.75.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/",