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.
- package/.agents/README.md +3 -0
- package/.agents/docs/runbooks/mods.md +157 -0
- package/.agents/mods/mandrel-status/.claude-plugin/plugin.json +9 -0
- package/.agents/mods/mandrel-status/hooks/hooks.json +1 -0
- package/.agents/mods/mandrel-status/hooks/register.tsx +1068 -0
- package/.agents/mods/mandrel-status/types/index.d.ts +90 -0
- package/.agents/schemas/story-progress.schema.json +48 -0
- package/.agents/scripts/lib/audit-suite/selector.js +6 -1
- package/.agents/scripts/lib/close-validation/gates.js +37 -9
- package/.agents/scripts/lib/config/temp-paths.js +15 -0
- package/.agents/scripts/lib/coverage-capture-affected.js +5 -16
- package/.agents/scripts/lib/coverage-capture-delta.js +25 -1
- package/.agents/scripts/lib/coverage-capture-fullscope.js +8 -5
- package/.agents/scripts/lib/coverage-capture-incremental.js +8 -5
- package/.agents/scripts/lib/coverage-capture.js +129 -8
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +15 -18
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
- package/.agents/scripts/lib/orchestration/story-handoff.js +21 -7
- package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
- package/.agents/workflows/helpers/deliver-reference.md +12 -5
- package/.agents/workflows/mandrel-update.md +4 -0
- package/docs/CHANGELOG.md +21 -0
- package/lib/cli/sync.js +38 -0
- package/package.json +1 -1
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
import { getQuality } from '../../../config/quality.js';
|
|
11
11
|
import { resolveConfig } from '../../../config-resolver.js';
|
|
12
|
-
import {
|
|
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
|
-
|
|
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
|
|
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
|
|
136
|
+
function resolveCoveragePath(resolveConfigImpl, cwd) {
|
|
137
137
|
try {
|
|
138
|
-
return getQuality(resolveConfigImpl({ cwd }))?.crap?.
|
|
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
|
|
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[] },
|
|
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,
|
|
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
|
|
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)
|
|
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:
|
|
176
|
-
`
|
|
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
|
-
{
|
|
637
|
-
|
|
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)
|
|
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
|
-
|
|
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,
|
|
327
|
-
|
|
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
|
-
//
|
|
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
|
|
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`.
|
|
401
|
-
|
|
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.**
|
|
429
|
-
so a baseline-JSON-only seat commit leaves it fresh and the
|
|
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