mandrel 2.73.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.
@@ -9,7 +9,7 @@
9
9
 
10
10
  import { getQuality } from '../../../config/quality.js';
11
11
  import { resolveConfig } from '../../../config-resolver.js';
12
- import { filterFilesUnderTargets } from '../../../coverage-capture.js';
12
+ import { filterSuiteInputPaths } from '../../../coverage-capture.js';
13
13
  import { syncBranchFromBase } from '../../../git/sync-from-base.js';
14
14
  import { Logger } from '../../../Logger.js';
15
15
  import { AGENT_LABELS } from '../../../label-constants.js';
@@ -85,7 +85,7 @@ export async function runBaseSyncPhase({
85
85
  for (const line of buildStampInvalidatedWarning({
86
86
  baseBranch,
87
87
  result: syncResult,
88
- targetDirs: resolveCrapTargetDirs(resolveConfigImpl, syncCwd),
88
+ coveragePath: resolveCoveragePath(resolveConfigImpl, syncCwd),
89
89
  })) {
90
90
  progress('SYNC', line);
91
91
  }
@@ -127,17 +127,17 @@ function resolveHandedBack({ result, baseConfirmed, handBack }) {
127
127
  }
128
128
 
129
129
  /**
130
- * The CRAP scoring scope, or `[]` when unresolvable.
130
+ * The coverage artifact path, or `null` when unresolvable.
131
131
  *
132
132
  * @param {typeof resolveConfig} resolveConfigImpl
133
133
  * @param {string} cwd
134
- * @returns {string[]}
134
+ * @returns {string|null}
135
135
  */
136
- function resolveCrapTargetDirs(resolveConfigImpl, cwd) {
136
+ function resolveCoveragePath(resolveConfigImpl, cwd) {
137
137
  try {
138
- return getQuality(resolveConfigImpl({ cwd }))?.crap?.targetDirs ?? [];
138
+ return getQuality(resolveConfigImpl({ cwd }))?.crap?.coveragePath ?? null;
139
139
  } catch {
140
- return [];
140
+ return null;
141
141
  }
142
142
  }
143
143
 
@@ -146,21 +146,19 @@ const WARNED_PATH_LIMIT = 12;
146
146
  /**
147
147
  * Warn that the sync spent pre-push credit, or `[]` when it changed nothing.
148
148
  * Gate evidence is keyed on the tree, so any tracked path spends it; the
149
- * full-suite capture stamp is spent only by a path under `crap.targetDirs`.
149
+ * full-suite capture stamp is spent by any path its tree digest reads —
150
+ * everything but baseline JSON and the coverage artifact.
150
151
  * A content-changing fast-forward warns just as a merge does.
151
152
  *
152
- * @param {{ baseBranch: string, result: { kind?: string, changedPaths?: string[] }, targetDirs?: string[] }} args
153
+ * @param {{ baseBranch: string, result: { kind?: string, changedPaths?: string[] }, coveragePath?: string|null }} args
153
154
  * @returns {string[]} Progress lines, in order. Empty when nothing changed.
154
155
  */
155
- function buildStampInvalidatedWarning({ baseBranch, result, targetDirs }) {
156
+ function buildStampInvalidatedWarning({ baseBranch, result, coveragePath }) {
156
157
  const changed = Array.isArray(result?.changedPaths)
157
158
  ? result.changedPaths
158
159
  : [];
159
160
  if (changed.length === 0) return [];
160
- const dirs = Array.isArray(targetDirs) ? targetDirs : [];
161
- // An unresolvable scope cannot prove the stamp survived: fail closed.
162
- const scored =
163
- dirs.length === 0 ? changed : filterFilesUnderTargets(changed, dirs);
161
+ const scored = filterSuiteInputPaths(changed, coveragePath);
164
162
  const shown = changed.slice(0, WARNED_PATH_LIMIT);
165
163
  const overflow = changed.length - shown.length;
166
164
  return [
@@ -170,11 +168,10 @@ function buildStampInvalidatedWarning({ baseBranch, result, targetDirs }) {
170
168
  `That evidence cannot be credited; those gates re-run below.`,
171
169
  scored.length > 0
172
170
  ? `⚠️ The full-suite capture stamp is spent too: ${scored.length} of ` +
173
- `those path(s) fall under the CRAP target dirs [${dirs.join(', ')}], ` +
171
+ `those path(s) are suite inputs (anything but baseline JSON), ` +
174
172
  `so the suite re-runs against the merged tree. This is expected, not a fault.`
175
- : `⚠️ The full-suite capture stamp SURVIVES: no merged path falls under ` +
176
- `the CRAP target dirs [${dirs.join(', ')}], so the coverage artifact still ` +
177
- `describes this tree and the suite is not re-run.`,
173
+ : `⚠️ The full-suite capture stamp SURVIVES: every merged path is ` +
174
+ `baseline JSON, so the suite already ran on this tree and is not re-run.`,
178
175
  ...shown.map((f) => `⚠️ ${f}`),
179
176
  ...(overflow > 0 ? [`⚠️ …and ${overflow} more`] : []),
180
177
  ];
@@ -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,
@@ -25,8 +25,8 @@ import { fileURLToPath } from 'node:url';
25
25
  import { spawnCaptureAsync } from '../child-exec.js';
26
26
  import { resolveLintCommand } from '../close-validation/commands.js';
27
27
  import {
28
- isCoverageCaptureActive,
29
28
  isCrapGateEnabled,
29
+ resolveCreditedDepositor,
30
30
  } from '../close-validation/gates.js';
31
31
  import {
32
32
  orchestrationLogDir,
@@ -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,
@@ -65,7 +66,9 @@ const EXIT_CODES = Object.freeze({
65
66
  /** The § 5 output signals — a depositor that prints none deposited nothing. */
66
67
  const SIGNALS = Object.freeze({
67
68
  captureRan: /Wrote content-digest capture stamp/,
68
- captureFresh: /skipping capture/,
69
+ // A `no changed files … — skipping capture` line ran no suite: not credit.
70
+ captureFresh:
71
+ /\bis fresh(?: \((?:incremental|affected)\))? — skipping capture/,
69
72
  testRan: /✓ test passed/,
70
73
  testFresh: /⏭ test skipped/,
71
74
  seated: /seated:\s*(\d+)/,
@@ -320,11 +323,12 @@ async function stepBaseMerge(ctx) {
320
323
  /**
321
324
  * The depositor close will credit, from the one shared predicate.
322
325
  *
323
- * @param {{ config: object, scripts: Record<string, string>|null }} args
326
+ * @param {{ config: object, scripts: Record<string, string>|null, cwd: string, getChangedFilesImpl?: Function }} args
324
327
  * @returns {'coverage-capture'|'test'}
325
328
  */
326
- function selectCreditedDepositor({ config, scripts }) {
327
- return isCoverageCaptureActive(config, scripts) ? 'coverage-capture' : 'test';
329
+ function selectCreditedDepositor({ config, ...probe }) {
330
+ const baseBranch = config?.project?.baseBranch ?? 'main';
331
+ return resolveCreditedDepositor({ config, baseBranch, ...probe });
328
332
  }
329
333
 
330
334
  /** @param {object} ctx @returns {Promise<StepResult>} */
@@ -421,7 +425,7 @@ async function commitSeatedRows(ctx, total, evidencePath) {
421
425
  const creditedPrior = ctx.state.creditHead === ctx.head;
422
426
  ctx.head = headSha(ctx) ?? ctx.head;
423
427
  ctx.state.seatHead = ctx.head;
424
- // The capture stamp digests scorable sources only, so a baseline-JSON-only
428
+ // Both capture-stamp digests leave `baselines/` out, so a baseline-JSON-only
425
429
  // commit keeps the credit it already holds.
426
430
  if (creditedPrior && ctx.depositor === 'coverage-capture') {
427
431
  ctx.state.creditHead = ctx.head;
@@ -652,7 +656,7 @@ async function stepReview(ctx) {
652
656
  /**
653
657
  * The run's step order. On the evidence-gate path the `test` credit is keyed
654
658
  * on the tree, so seating (static MI) goes first and cannot void it; the
655
- * capture stamp digests scorable sources only, so a baseline seat after it
659
+ * capture stamp's digests leave `baselines/` out, so a baseline seat after it
656
660
  * keeps the stamp fresh.
657
661
  *
658
662
  * @param {'coverage-capture'|'test'} depositor
@@ -748,6 +752,7 @@ async function defaultBlock({
748
752
  * probeReview?: typeof probeHeldReviewDiff,
749
753
  * computeReview: (input: { storyId: number, cwd: string, config: object }) => Promise<{ written: boolean, path?: string, reason?: string, deposit?: object }>,
750
754
  * readPackageScriptsFn?: typeof readPackageScripts,
755
+ * getChangedFilesFn?: typeof import('../changed-files.js').getChangedFiles,
751
756
  * block?: (args: { storyId: number, config: object, reason: string, detail: string }) => Promise<void>,
752
757
  * createProviderFn?: Function,
753
758
  * progress?: (tag: string, msg: string) => void,
@@ -763,6 +768,7 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
763
768
  probeReview = probeHeldReviewDiff,
764
769
  computeReview,
765
770
  readPackageScriptsFn = readPackageScripts,
771
+ getChangedFilesFn,
766
772
  createProviderFn,
767
773
  progress = () => {},
768
774
  logDir = orchestrationLogDir(config),
@@ -796,6 +802,8 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
796
802
  depositor: selectCreditedDepositor({
797
803
  config,
798
804
  scripts: readPackageScriptsFn(cwd),
805
+ cwd,
806
+ getChangedFilesImpl: getChangedFilesFn,
799
807
  }),
800
808
  writeEvidence: (name, text) => {
801
809
  const file = path.join(logDir, `story-handoff-${storyId}-${name}.log`);
@@ -808,7 +816,13 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
808
816
  const steps = [];
809
817
  let stop = precheck(ctx);
810
818
  if (stop) steps.push(stop);
819
+ const storyProgress = createStoryProgress({
820
+ storyId,
821
+ stage: 'handoff',
822
+ config,
823
+ });
811
824
  for (const step of stop ? [] : stepOrder(ctx.depositor)) {
825
+ storyProgress.phase(handoffStepName(step));
812
826
  const result = await step(ctx);
813
827
  steps.push(result);
814
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
+ }
@@ -397,8 +397,15 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
397
397
  covers this change set` and pays the whole suite on the serialized tail. The
398
398
  worker's capture writes the content-digest stamp in the worktree, and
399
399
  close's capture then exits on its freshness probe without spawning
400
- `test:coverage`. A base-sync that merges a path under `crap.targetDirs`
401
- spends the stamp, and close re-captures.
400
+ `test:coverage`. The stamp holds two digests — the scorable sources and
401
+ every suite input (all tracked and dirty paths but `baselines/` and the
402
+ coverage directory) — so any later commit or base-sync outside baseline
403
+ JSON spends it, and close re-captures.
404
+ - **Predicted skip.** With `incrementalCoverage.skipWhenUnchanged` on and no
405
+ changed file under `crap.targetDirs`, the capture would run nothing, so
406
+ the shared predicate (`resolveCreditedDepositor`) picks the `test`
407
+ depositor for both close and the handoff. A `no changed files … —
408
+ skipping capture` line is never credit.
402
409
  - **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
403
410
  the project's test script routes through mandrel's own runner, which prints
404
411
  the outcome. On any other runner it deposits nothing and prints nothing, so
@@ -425,9 +432,9 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
425
432
  over the in-scope files is exactly 100% — a lower rate means the artifact's
426
433
  coordinates predate the tree. The refusal names the rate, the unresolved
427
434
  files and the fix: re-run the digest § 5 capture, then seat.
428
- - **Seat order vs credit.** The capture stamp digests scorable sources only,
429
- so a baseline-JSON-only seat commit leaves it fresh and the capture credit
430
- stands. The evidence-gate `test` credit is keyed on the tree, so on that
435
+ - **Seat order vs credit.** Neither capture-stamp digest reads
436
+ `baselines/`, so a baseline-JSON-only seat commit leaves it fresh and the
437
+ capture credit stands. The evidence-gate `test` credit is keyed on the tree, so on that
431
438
  path the handoff seats first — MI is static and needs no coverage — then
432
439
  runs the suite.
433
440
 
@@ -214,6 +214,10 @@ between the installed and target versions:
214
214
  contradict a tightened rule.
215
215
  2. **Project-specific runbooks.** Sweep any docs that paraphrase framework
216
216
  workflows for renamed flags / changed exit codes / removed scripts.
217
+ 3. **Framework runbooks.** Step 1's sync output ends with one
218
+ `📖 Runbook:` line per file in `.agents/docs/runbooks/`. Read each one
219
+ the changelog touches and relay any opt-in or action it describes to the
220
+ operator. Never enable an opt-in on their behalf.
217
221
 
218
222
  Do not invent updates — silence is a valid review outcome. Stage every
219
223
  consumer-side edit alongside the dependency bump so the upgrade and the
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.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
+
26
+ ## [2.74.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.73.0...mandrel-v2.74.0) (2026-10-02)
27
+
28
+
29
+ ### Added
30
+
31
+ * add a runbook index: mandrel sync (and so init/update/postinstall) list… ([#5547](https://github.com/dsj1984/mandrel/issues/5547)) ([#5549](https://github.com/dsj1984/mandrel/issues/5549)) ([f768059](https://github.com/dsj1984/mandrel/commit/f768059f7d7229c8d8c32b773b9f8e26fecec30b))
32
+ * beta: opt-in read-only Claude Code mod showing /mandrel-deliver status above the prompt ([#5544](https://github.com/dsj1984/mandrel/issues/5544)) ([#5545](https://github.com/dsj1984/mandrel/issues/5545)) ([1fa4f1f](https://github.com/dsj1984/mandrel/commit/1fa4f1f518bf20df116f1479e2db1c8cc0c2a74c))
33
+
34
+
35
+ ### Fixed
36
+
37
+ * coverage-capture credit must only vouch for a tree the suite actually ran on ([#5548](https://github.com/dsj1984/mandrel/issues/5548)) ([#5550](https://github.com/dsj1984/mandrel/issues/5550)) ([fea9553](https://github.com/dsj1984/mandrel/commit/fea955352f2524e3546cd559b4f457b017d4f9f5))
38
+
18
39
  ## [2.73.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.72.0...mandrel-v2.73.0) (2026-10-02)
19
40
 
20
41
 
package/lib/cli/sync.js CHANGED
@@ -30,6 +30,13 @@ export const LOCAL_ZONE_DIR = 'local';
30
30
  /** Consumer local-override basenames (`instructions.local.md`, …). */
31
31
  export const LOCAL_OVERRIDE_RE = /\.local\.[^.]+$/;
32
32
 
33
+ /**
34
+ * `.agents/`-relative directory of the operator runbooks every sync lists in
35
+ * its closing report, so `init`, `update` and the npm postinstall surface them
36
+ * too. Adding or deleting a file here is the whole registration.
37
+ */
38
+ export const RUNBOOKS_DIR = path.join('docs', 'runbooks');
39
+
33
40
  /** `.agents/`-relative path of the version marker written after each sync. */
34
41
  export const VERSION_MARKER_RELATIVE_PATH = '.mandrel-version';
35
42
 
@@ -290,6 +297,11 @@ export function runSync({
290
297
  } else {
291
298
  write(`✅ Installed ${payloadFiles.length} file(s) into ./.agents/\n`);
292
299
  }
300
+ for (const runbook of listRunbooks(payloadFiles, (rel) =>
301
+ fs.readFileSync(path.join(destRoot, rel), 'utf8'),
302
+ )) {
303
+ write(`📖 Runbook: ${runbook.title} — ${runbook.path}\n`);
304
+ }
293
305
  return {
294
306
  copied: payloadFiles.length,
295
307
  planned: payloadFiles.length,
@@ -298,6 +310,32 @@ export function runSync({
298
310
  };
299
311
  }
300
312
 
313
+ /**
314
+ * The payload's runbooks, each titled by its first `# ` heading (its file name
315
+ * when it has none), in path order.
316
+ *
317
+ * @param {string[]} payloadFiles - `.agents/`-relative payload paths.
318
+ * @param {(rel: string) => string} readText - reads one payload file.
319
+ * @returns {{ title: string, path: string }[]}
320
+ */
321
+ export function listRunbooks(payloadFiles, readText) {
322
+ return payloadFiles
323
+ .filter((rel) => path.dirname(rel) === RUNBOOKS_DIR && rel.endsWith('.md'))
324
+ .sort()
325
+ .map((rel) => {
326
+ let title;
327
+ try {
328
+ title = /^# (.+)$/m.exec(readText(rel))?.[1]?.trim();
329
+ } catch {
330
+ title = undefined;
331
+ }
332
+ return {
333
+ title: title || path.basename(rel, '.md'),
334
+ path: path.join(AGENTS_DIR, rel).split(path.sep).join('/'),
335
+ };
336
+ });
337
+ }
338
+
301
339
  /**
302
340
  * @param {string[]} argv - Subcommand arguments (after `mandrel sync`).
303
341
  * @returns {Promise<void>}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.73.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/",