@holmes-lab/holmes-kit 0.41.0 → 0.41.1

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/CHANGELOG.md CHANGED
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  <!-- @implements A-SPEC-209 -->
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.41.1] - 2026-11-13
11
+
12
+ ### Fixed
13
+ - **Removing a backup `init` left no longer closes governance staging (A-SPEC-794.121; 0.41.0 Known limitation, present since 0.40.1).** `init` recorded every file under a recovery skill's directory in the install manifest, so its own backup of a user's edited skill (`SKILL.md.holmes-bak-<id>`) became a product file: removed, it was `missing`, and under a full autonomy profile governance staging was refused with no request. `init` now records only what the package ships there, each skill's `SKILL.md`, and the next `init` drops an earlier record of anything else inside a recovery skill's directory — by location, not by file name. A workspace whose manifest already records a removed backup stays closed until a person runs `holmes-kit init` once; the refusal now says so. `init` and `skills refresh` now keep the backup of a rewritten recovery skill under `.ax/state/skill-backups/holmes-<name>/` (git-ignored, outside everything the gate watches) instead of beside the skill, and the report names that path (A-SPEC-794.126). A backup an earlier version left beside a skill stays where it is and is no longer recorded; in Holmes-Kit's own checkout principle 7 still counts it, as every file under `.claude`, until a person moves or deletes it. The settings backup `init` writes beside `.claude/settings*.json` is unchanged.
14
+ - **The ledger-witness form leads with the witness's verdict (A-SPEC-794.125; 0.41.0 Known limitation, supervisor review M1).** The form a person reads before vouching opened with the comparison against the pushed chain, read through the local upstream ref (`@{u}`), which a session can move — so its first line could be made to say "This chain is the pushed one". Line 1 is now the witness's own verdict, and every verdict but `ok` carries a warning: "Do not vouch unless you mean this chain, as it is, to be the reference", or, for `no-witness`, that this is either the first vouch or a removed witness (the witness lives under `.git`, which a shell can delete) — and that it was removed when the chain records a vouch decided in the session form. The lists cover the whole chain for every verdict (A-SPEC-794.127, 794.129): the witness checks the witnessed row and the length, not the rows before it, so no verdict vouches for a prefix; under `ok` they say so, and under every other verdict a list cut at 40 rows says to check the chain file itself (A-SPEC-794.130). Resistance to a forged witness file is not verified; the form is as strong as the witness (A-SPEC-794.114's same-uid limit), and a vouch made at a person's own terminal leaves no record, so there a removed witness reads as a first vouch. Line 2 is the comparison, prefixed "By the local ref <ref> (a session can move it; compare with the remote yourself if it matters)". The rows the form lists ("Rows a person acts on", "Gate rows") no longer depend on the ref; a ref pointed at a copy of the chain used to hide them. The request's subject, the grant and the judgement are unchanged.
15
+ - **A full test_run's `testRun.prepare` and a mutate run's jest are told the tree they run in (A-SPEC-794.123).** 0.41.0 gave a test run's children `CLAUDE_PROJECT_DIR` naming the tree that runs (A-SPEC-794.119), and named two children as left out: the prepare (a build in HEAD's worktree) still saw the server's checkout, and `test_run` with `mutate` ran its jest outside the run's scope. Both now take the test environment: `CLAUDE_PROJECT_DIR`, where the server carries it, names the worktree (prepare) or the run's root (mutate). The prepare also no longer receives the keys an evidence run never hands a test child: newly `HOLMES_SPECS`, `HOLMES_MCP_AUTORELOAD`, `HOLMES_MCP_PROFILE`, `npm_config_dry_run`, `PYTEST_ADDOPTS` and `PYTEST_PLUGINS` (the approval, ledger-key and gate-bypass keys were already removed from every child). `PATH`, `HOME` and the npm registry settings reach it as before.
16
+ - **A full test_run no longer drops a declared `testRun.prepare` silently (A-SPEC-794.123).** A HEAD whose `ax.config.json` could not be parsed was read as the default configuration, so the run went ahead with no prepare and could record green evidence without the step the commit declared. Now such a config ends the run as not passed with the reason (`testRun.prepare could not be read: …`), and nothing is recorded. The contract (A-SPEC-794.128, replacing the clause the `config.ts` comment under A-SPEC-128.13 stated): `testRun.prepare` absent, `[]` or `null` declares none; any other value that is not a non-empty array of non-empty strings makes a full run fail with that reason.
17
+
10
18
  ## [0.41.0] - 2026-11-12
11
19
 
12
20
  ### Upgrading
package/README.md CHANGED
@@ -11,8 +11,8 @@
11
11
  <!-- holmes-kit:attest:begin -->
12
12
  ![traced files](.ax/badges/traced.svg)
13
13
 
14
- **565/565** source files (100%) trace to an approved spec · **1263/1370** approved A-SPECs (92.1%) are anchored from code.
15
- Measured at `c4a016695ba7` (specs `sha256:ac5e4f7df00f`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
14
+ **565/565** source files (100%) trace to an approved spec · **1272/1379** approved A-SPECs (92.2%) are anchored from code.
15
+ Measured at `774b6d166839` (specs `sha256:dcdcb2217da0`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
16
16
  <!-- holmes-kit:attest:end -->
17
17
 
18
18
  ### 0.40.x push evidence: the supported surface
@@ -20,7 +20,7 @@ Measured at `c4a016695ba7` (specs `sha256:ac5e4f7df00f`) — reproduce with `hol
20
20
  The pre-push gate accepts a full `test_run` as evidence only where holmes can check the run afterwards without changing your runner configuration. Outside that surface the push is refused as `environment`, with one message: "이 구성은 0.40.x가 증빙하지 않습니다 — 0.41 / 오너 결정". General support is planned for 0.41.
21
21
 
22
22
  **A full run tests the commit, not your work tree.**
23
- - It checks HEAD out as a temporary git worktree **outside the repository**, in `<os tmp>/holmes-headwt-<user>/<repository key>/<id>/`, made with no git hooks and no write to your git configuration. It links your gitignored `node_modules`, runs `ax.config.json` `testRun.prepare` there if you declare one (for example `["npm", "run", "build"]`; nothing is guessed, and a package-manager install is refused because `node_modules` is your work tree's), runs the suite within the run's time budget, and removes the worktree.
23
+ - It checks HEAD out as a temporary git worktree **outside the repository**, in `<os tmp>/holmes-headwt-<user>/<repository key>/<id>/`, made with no git hooks and no write to your git configuration. It links your gitignored `node_modules`, runs `ax.config.json` `testRun.prepare` there if you declare one (for example `["npm", "run", "build"]`; nothing is guessed, and a package-manager install is refused because `node_modules` is your work tree's; `[]` or `null` declares none, and any other malformed value ends the run with the reason *(0.41.1)*), runs the suite within the run's time budget, and removes the worktree. The prepare and the tests are told that worktree as `CLAUDE_PROJECT_DIR` *(0.41.1)*.
24
24
  - holmes removes only a worktree git lists at that exact path, through `git worktree remove`; it never deletes a directory itself and never runs `git worktree prune`. A leftover of a run whose process is gone is removed by the next run.
25
25
  - Untracked, ignored, modified, assume-unchanged and skip-worktree files never reach the run, so a red commit cannot pass on a green work tree. Nothing is written inside your repository, and nothing has to be added to `.gitignore`.
26
26
  - **The run must read only HEAD, judged by what it loaded.**
@@ -413,7 +413,7 @@ flowchart LR
413
413
  | `holmes-kit runtime-binding setup --workspace <root> --package <built-package> --release-package <release-install> --dry-run` | Preview explicit development/release routing; omit `--dry-run` only after reviewing the plan and satisfying its approval request |
414
414
  | `holmes-kit runtime-binding status --workspace <root>` | Inspect selected package, build, spec store and wiring conflicts, and whether this selection's PreToolUse gate was observed running (`activation`); an observation is evidence the hook ran, not a guarantee every call is judged |
415
415
  | `holmes-kit doctor --target <root> --registry <bindings.json>` | Diagnose the same operator registry used by custom routing installations |
416
- | `holmes-kit ledger witness` | Vouch for this repository's provenance chain as it is — a person decides it in the session's approval form, which compares the chain with the pushed one and lists the rows to recognise *(new in 0.41)* |
416
+ | `holmes-kit ledger witness` | Vouch for this repository's provenance chain as it is — a person decides it in the session's approval form, which leads with the witness's verdict, compares the chain with the pushed one as the local ref names it, and lists the rows to recognise from row 0 *(new in 0.41; form order 0.41.1)* |
417
417
  | `holmes-kit ledger rechain [--dry-run]` | Re-chain forked ledger files against the committed mainline; the rewrite applies only to a plan a person approved (`--dry-run` is free) |
418
418
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
419
419
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- f30ee53d-mwegud15
1
+ 35d54f07-mwfu2hez
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
- // @implements A-SPEC-794.110, A-SPEC-794.107, A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
39
+ // @implements A-SPEC-794.121, A-SPEC-794.110, A-SPEC-794.107, A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-769.11
42
42
  // @implements A-SPEC-340
@@ -1397,11 +1397,20 @@ function runInitUnguarded(opts) {
1397
1397
  } })();
1398
1398
  const foreignNow = new Set(nowStates.filter((x) => x.state === 'foreign').map((x) => x.name));
1399
1399
  const foreignFiles = [...foreignNow].flatMap((n) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, n))));
1400
+ // @implements A-SPEC-794.121 — a playbook skill ships one file, its SKILL.md (installPlaybookSkills): that is what
1401
+ // is recorded, never a walk of the directory, so a backup init leaves or a file a user adds beside it is not
1402
+ // product; an earlier record of anything else inside a playbook skill directory is dropped (by location in the
1403
+ // package's skill directories, not by a file name)
1404
+ const skillFile = (name) => path.normalize((0, playbook_skills_1.skillPathFor)(opts.target, name));
1405
+ const skillDirs = new Set(skillStates.map((x) => path.dirname(skillFile(x.name))));
1406
+ const shipped = new Set(skillStates.filter((x) => !foreignNow.has(x.name)).map((x) => skillFile(x.name)));
1407
+ const besideSkills = (manifest.readInstallManifest(opts.target) ?? []).map((f) => path.normalize(path.join(opts.target, f.path)))
1408
+ .filter((abs) => skillDirs.has(path.dirname(abs)) && !shipped.has(abs));
1400
1409
  manifest.writeInstallManifest(opts.target, [
1401
1410
  ...changes.filter((c) => c.after !== null).map((c) => c.path),
1402
- ...skillStates.filter((x) => !foreignNow.has(x.name)).flatMap((x) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, x.name)))),
1411
+ ...[...shipped].filter((f) => fs.existsSync(f)),
1403
1412
  path.join(opts.target, '.ax', 'roles', 'README.md'),
1404
- ].flatMap(filesUnder), (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? 'unknown', { drop: foreignFiles });
1413
+ ].flatMap(filesUnder), (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? 'unknown', { drop: [...foreignFiles, ...besideSkills] });
1405
1414
  }
1406
1415
  }
1407
1416
  catch (e) {
@@ -37,7 +37,7 @@ exports.ledgerWitnessFacts = ledgerWitnessFacts;
37
37
  exports.ledgerWitnessGate = ledgerWitnessGate;
38
38
  exports.underGrant = underGrant;
39
39
  exports.rechainGate = rechainGate;
40
- // @implements A-SPEC-794.114, A-SPEC-794.116
40
+ // @implements A-SPEC-794.114, A-SPEC-794.116, A-SPEC-794.125, A-SPEC-794.127, A-SPEC-794.129, A-SPEC-794.130
41
41
  /**
42
42
  * The person's acts over the ledger witness (A-SPEC-794.114):
43
43
  * - `holmes-kit ledger witness` — vouch for this repository's provenance chain as it is. From a session it files a
@@ -59,6 +59,32 @@ const node_child_process_1 = require("node:child_process");
59
59
  const ledger_store_1 = require("../governance/ledger-store");
60
60
  const ledger_witness_1 = require("../governance/ledger-witness");
61
61
  const approval_queue_1 = require("../governance/approval-queue");
62
+ /** @implements A-SPEC-794.127 — the grant-spend row's prefix, from approval-grants (one copy); a form-decided vouch leaves one. */
63
+ const GRANT_SPEND_PREFIX = require('../governance/approval-grants').GRANT_SPEND_SUMMARY;
64
+ const DO_NOT_VOUCH = 'Do not vouch unless you mean this chain, as it is, to be the reference.';
65
+ /**
66
+ * @implements A-SPEC-794.125 — the warning line 1 carries for a verdict that is not ok, one case per kind (exhaustive). A
67
+ * vouch made at a person's own terminal spends no grant, so there "first" and "removed" cannot be told apart (named limit).
68
+ */
69
+ function warningFor(kind, vouchedAt) {
70
+ switch (kind) {
71
+ case 'no-witness':
72
+ return vouchedAt !== undefined
73
+ ? `No witness, but this chain records a vouch at ${vouchedAt}: the witness was removed after a vouch recorded at ${vouchedAt} — check every row below before vouching again.`
74
+ : 'No witness: either the first vouch or the witness was removed — check every row below before vouching.';
75
+ case 'taken-back':
76
+ case 'extended':
77
+ case 'broken':
78
+ case 'replica-changed':
79
+ case 'unreadable':
80
+ case 'no-repository':
81
+ return DO_NOT_VOUCH;
82
+ default: {
83
+ const never = kind;
84
+ return `${DO_NOT_VOUCH} (${String(never)})`;
85
+ }
86
+ }
87
+ }
62
88
  const rowsOf = (text) => text.split('\n').filter((l) => l.trim() !== '').map((l) => { try {
63
89
  return JSON.parse(l);
64
90
  }
@@ -87,60 +113,74 @@ function ledgerWitnessFacts(root) {
87
113
  }
88
114
  catch { /* [no-substitution: absent is the empty chain, as its head says] */ }
89
115
  const rows = rowsOf(text);
90
- // 1. against the pushed chain
116
+ // 2. against the pushed chain, as the local upstream ref names it
91
117
  const rel = path.relative(gitText(root, ['rev-parse', '--show-toplevel'])?.trim() || root, chain).split(path.sep).join('/');
92
118
  const upstreamRef = gitText(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])?.trim() || null;
93
119
  const pushedText = upstreamRef === null ? null : gitText(root, ['show', `${upstreamRef}:${rel}`]);
94
120
  const pushed = pushedText === null ? null : rowsOf(pushedText);
121
+ // @implements A-SPEC-794.125 — the point after which rows are listed comes from the witness alone: the upstream ref is
122
+ // the session's to move, and pointed at a copy of this chain it used to hide every row after the witnessed one
123
+ // @implements A-SPEC-794.129 (review D-M1) — every verdict is listed from row 0: the witness checks the witnessed row's
124
+ // hash and the length, not the prefix, so no verdict (extended included) vouches for the rows before it
125
+ const from = 0;
126
+ // A-SPEC-794.129 (review D-M2) — under these verdicts the rows cut from a long list may be the changed ones
127
+ // A-SPEC-794.130 (review E-M1) — every verdict but ok: a warning that says "check every row" points at the file holding them
128
+ const changed = !verdict.ok;
95
129
  let upstream = 'none';
96
- let from = 0; // the compared point: rows after it are listed
97
- let first;
130
+ let compared;
98
131
  if (upstreamRef === null) {
99
- first = 'There is no upstream branch to compare this chain with, so judge from the rows below and the baseline alone.';
100
- from = verdict.ok ? 0 : (verdict.witnessed ? verdict.witnessed.seq + 1 : 0);
101
- }
102
- else if (pushed === null) {
103
- first = `The upstream ${upstreamRef} holds no copy of this chain (${rel}), so judge from the rows below and the baseline alone.`;
104
- from = verdict.ok ? 0 : (verdict.witnessed ? verdict.witnessed.seq + 1 : 0);
132
+ compared = 'There is no upstream branch to compare this chain with, so judge from the rows below and the baseline alone.';
105
133
  }
106
134
  else {
107
- let common = 0;
108
- while (common < Math.min(rows.length, pushed.length) && rows[common].hash !== undefined && rows[common].hash === pushed[common].hash)
109
- common++;
110
- if (common === rows.length && common === pushed.length) {
111
- upstream = 'same';
112
- first = `This chain is the pushed one (${upstreamRef}, ${pushed.length} rows).`;
113
- from = rows.length;
114
- }
115
- else if (common === pushed.length) {
116
- upstream = 'extends';
117
- first = `This chain extends the pushed one (${upstreamRef}, ${pushed.length} rows) by ${rows.length - common} row(s).`;
118
- from = common;
119
- }
120
- else if (common === rows.length) {
121
- upstream = 'shorter';
122
- first = `THIS CHAIN IS SHORTER than the pushed one (${upstreamRef}: ${pushed.length} rows, here ${rows.length}) — it was taken back. Do not vouch unless you mean to make this older chain the reference; return the tree instead.`;
123
- from = rows.length;
135
+ const label = `By the local ref ${upstreamRef} (a session can move it; compare with the remote yourself if it matters): `;
136
+ if (pushed === null) {
137
+ compared = `${label}the upstream holds no copy of this chain (${rel}), so judge from the rows below and the baseline alone.`;
124
138
  }
125
139
  else {
126
- upstream = 'diverged';
127
- first = `This chain has DIVERGED from the pushed one (${upstreamRef}) after row ${common}: ${rows.length - common} row(s) here are not in it, and ${pushed.length - common} there are not here.`;
128
- from = common;
140
+ let common = 0;
141
+ while (common < Math.min(rows.length, pushed.length) && rows[common].hash !== undefined && rows[common].hash === pushed[common].hash)
142
+ common++;
143
+ if (common === rows.length && common === pushed.length) {
144
+ upstream = 'same';
145
+ compared = `${label}this chain is the pushed one (${pushed.length} rows).`;
146
+ }
147
+ else if (common === pushed.length) {
148
+ upstream = 'extends';
149
+ compared = `${label}this chain extends the pushed one (${pushed.length} rows) by ${rows.length - common} row(s).`;
150
+ }
151
+ else if (common === rows.length) {
152
+ upstream = 'shorter';
153
+ compared = `${label}THIS CHAIN IS SHORTER than the pushed one (${pushed.length} rows there, ${rows.length} here) — it was taken back. Do not vouch unless you mean to make this older chain the reference; return the tree instead.`;
154
+ }
155
+ else {
156
+ upstream = 'diverged';
157
+ compared = `${label}this chain has DIVERGED from the pushed one after row ${common}: ${rows.length - common} row(s) here are not in it, and ${pushed.length - common} there are not here.`;
158
+ }
129
159
  }
130
160
  }
131
- // 2. the judgement's own verdict, as it reads now
132
- const lines = [first, `The judgement reads this chain as: ${verdict.ok ? 'ok' : `${verdict.kind} — ${verdict.detail}`}. Vouching makes the chain as it is now (${head.seq + 1} rows, sha256 ${head.sha256.slice(0, 16)}…) the one this repository wrote.`];
133
- // 3. the rows a person acts on after the compared point, and the gate's own rows
161
+ // 1. the witness's own verdict first — the line a session cannot move. Only ok carries no warning; each other kind has
162
+ // its words, and the switch is exhaustive, so a kind added later does not compile until it is given some
163
+ // @implements A-SPEC-794.125 (review A of b3e26751, H) — the witness lives under .git, which a shell can delete, and a
164
+ // deleted one reads as no-witness: a grant spent on `ledger witness` in this chain says a vouch was made here
165
+ const vouchedAt = [...rows].reverse().find((r) => typeof r.summary === 'string' && r.summary.startsWith(`${GRANT_SPEND_PREFIX}ledger witness`))?.ts;
166
+ const warning = verdict.ok ? '' : ` ${warningFor(verdict.kind, vouchedAt)}`;
167
+ const lines = [
168
+ `The witness reads this chain as: ${verdict.ok ? 'ok' : `${verdict.kind} — ${verdict.detail}`}.${warning} Vouching makes the chain as it is now (${head.seq + 1} rows, sha256 ${head.sha256.slice(0, 16)}…) the one this repository wrote.`,
169
+ compared,
170
+ ];
171
+ // 3. the rows a person acts on after the compared point, and the gate's own rows; under ok the lists cover the whole
172
+ // chain and say so (review A of b3e26751, M: "after row 0" read as after a vouch)
173
+ const span = verdict.ok ? `in the whole chain (the witness is current at row ${verdict.head.seq + 1})` : `from row ${from}`; // A-SPEC-794.130 (F-L5) — the list starts at row 0, so it reads "from"
134
174
  const after = rows.slice(from);
135
175
  const { isHumanChannelActor } = require('../governance/human-channel');
136
176
  const personal = after.filter((r) => isHumanChannelActor(r.actor) || /^grant:/.test(String(r.actor ?? '')) || /^spec-(?:approved|unsealed|retired)$/.test(String(r.kind ?? '')));
137
177
  const name = (r) => `${r.ts ?? '?'} ${r.kind ?? '?'}${Array.isArray(r.inputs) && r.inputs.length > 0 ? ` ${String(r.inputs[0])}` : ''} by ${String(r.actor ?? '?')}`;
138
178
  lines.push(personal.length === 0
139
- ? `Rows a person acts on after row ${from}: none.`
140
- : `Rows a person acts on after row ${from} — recognise each one: ${personal.slice(-LIST_MAX).map(name).join('; ')}${personal.length > LIST_MAX ? ` (and ${personal.length - LIST_MAX} earlier)` : ''}.`);
179
+ ? `Rows a person acts on ${span}: none.`
180
+ : `Rows a person acts on ${span} — recognise each one: ${personal.slice(-LIST_MAX).map(name).join('; ')}${personal.length > LIST_MAX ? ` (and ${personal.length - LIST_MAX} earlier${changed ? ' — check the chain file itself' : ''})` : ''}.`);
141
181
  const gateRows = after.filter((r) => String(r.actor ?? '') === 'holmes-kit');
142
182
  const baselines = gateRows.filter((r) => r.kind === 'principle7-baseline');
143
- lines.push(`Gate rows after row ${from}: ${gateRows.length} (refusals and records the gate wrote, including while the judgement was closed)${baselines.length > 0 ? `; baselines recorded: ${baselines.map((b) => `${String(b.inputs?.[0] ?? '').replace(/^commit:/, '').slice(0, 12)} at ${b.ts}`).join(', ')}` : ''}.`);
183
+ lines.push(`Gate rows ${span}: ${gateRows.length} (refusals and records the gate wrote, including while the judgement was closed)${baselines.length > 0 ? `; baselines recorded: ${baselines.map((b) => `${String(b.inputs?.[0] ?? '').replace(/^commit:/, '').slice(0, 12)} at ${b.ts}`).join(', ')}` : ''}.`);
144
184
  // 4. the latest baseline and the principle 7 files changed from it to HEAD
145
185
  const latest = [...rows].reverse().find((r) => r.kind === 'principle7-baseline' && String(r.actor ?? '') === 'holmes-kit');
146
186
  const commit = latest && Array.isArray(latest.inputs) ? String(latest.inputs.find((i) => /^commit:/.test(String(i))) ?? '').slice(7) : '';
@@ -38,7 +38,7 @@ exports.installPlaybookSkills = installPlaybookSkills;
38
38
  exports.removePlaybookSkills = removePlaybookSkills;
39
39
  exports.skillLabel = skillLabel;
40
40
  exports.installedPlaybookCount = installedPlaybookCount;
41
- // @implements A-SPEC-190
41
+ // @implements A-SPEC-190, A-SPEC-794.126, A-SPEC-794.129
42
42
  // @implements A-SPEC-142
43
43
  const fs = __importStar(require("node:fs"));
44
44
  const path = __importStar(require("node:path"));
@@ -200,13 +200,45 @@ function installPlaybookSkills(packageRoot, target) {
200
200
  return false;
201
201
  }
202
202
  };
203
+ // @implements A-SPEC-794.126 — the backup is kept under the target's .ax/state (git-ignored by init's block, outside
204
+ // every root principle 7 watches, never in the install manifest), not beside the skill under .claude: a file there
205
+ // is one the gate counts, and leaving the gate an exception for it was a relaxation (0.41.1 review H1)
203
206
  const suffix = `.holmes-bak-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
204
- const bak = [
205
- `${dest}${suffix}`,
206
- path.join(path.dirname(path.dirname(dest)), `${(0, playbook_skill_states_1.invocableSkillName)(name)}.SKILL.md${suffix}`),
207
- ].find(insideTarget);
207
+ const bakDir = path.join(target, '.ax', 'state', 'skill-backups', (0, playbook_skill_states_1.invocableSkillName)(name));
208
+ // nothing is created until the nearest existing ancestor of the directory resolves inside the target: a linked
209
+ // .ax/state must not receive even an empty directory
210
+ const nearest = (() => { let d = bakDir; while (!fs.existsSync(d) && path.dirname(d) !== d)
211
+ d = path.dirname(d); return d; })();
212
+ // @implements A-SPEC-794.129 (review C-L2) — no component of the path below the target may be a link, even one
213
+ // that resolves inside the target
214
+ const linkOnPath = (() => {
215
+ let d = target;
216
+ for (const part of path.relative(target, bakDir).split(path.sep)) {
217
+ d = path.join(d, part);
218
+ try {
219
+ if (fs.lstatSync(d).isSymbolicLink())
220
+ return d;
221
+ }
222
+ catch {
223
+ return null;
224
+ } // [no-substitution: absent from here on → created below as plain directories]
225
+ }
226
+ return null;
227
+ })();
228
+ if (linkOnPath !== null) {
229
+ out.failed.push({ name, reason: `${dest} 의 이전 내용을 보존할 수 없어 다시 쓰지 않았습니다 — ${linkOnPath} is a link — a backup is not written through a link. 링크를 풀고 다시 실행하십시오` });
230
+ continue;
231
+ }
232
+ const contained = insideTarget(path.join(nearest, 'x'));
233
+ if (contained) {
234
+ try {
235
+ fs.mkdirSync(bakDir, { recursive: true });
236
+ }
237
+ catch { /* [no-substitution: the containment check below refuses it] */ }
238
+ }
239
+ const bak = contained ? [path.join(bakDir, `SKILL.md${suffix}`)].find(insideTarget) : undefined;
208
240
  if (bak === undefined) {
209
- out.failed.push({ name, reason: `${dest} 의 이전 내용을 타깃(${target}) 안에 보존할 수 없어 다시 쓰지 않았습니다 — .claude/skills 가 타깃 밖을 가리키는 링크입니다. 링크를 풀거나 그 저장소에서 직접 갱신하십시오` });
241
+ out.failed.push({ name, reason: `${dest} 의 이전 내용을 타깃(${target}) 안에 보존할 수 없어 다시 쓰지 않았습니다 — ${path.join(target, '.ax', 'state')} 가 타깃 밖을 가리키는 링크이거나 만들 수 없습니다. 링크를 풀고 다시 실행하십시오` });
210
242
  continue;
211
243
  }
212
244
  try {
@@ -76,3 +76,9 @@ export declare function removeWhenReleased(dir: string, ms?: number, remove?: (d
76
76
  * in the report is the honest form. `reason` is required for the same reason it is required there.
77
77
  */
78
78
  export declare function win32Only(reason: string, platform?: string): typeof it | typeof it.skip;
79
+ /**
80
+ * @implements A-SPEC-794.124 — as `win32Only`, for a fact of darwin's own tools: its /bin/sh execs a lone `-c` command,
81
+ * which another platform's /bin/sh may not. Elsewhere the case is a reported skip with its reason, never a body that
82
+ * returns early and counts as a pass (A-SPEC-220.3).
83
+ */
84
+ export declare function darwinOnly(reason: string, platform?: string): typeof it | typeof it.skip;
@@ -40,6 +40,7 @@ exports.posixOnlyWithCommand = posixOnlyWithCommand;
40
40
  exports.bashWord = bashWord;
41
41
  exports.removeWhenReleased = removeWhenReleased;
42
42
  exports.win32Only = win32Only;
43
+ exports.darwinOnly = darwinOnly;
43
44
  const fs = __importStar(require("node:fs"));
44
45
  const path = __importStar(require("node:path"));
45
46
  const node_crypto_1 = require("node:crypto");
@@ -191,3 +192,14 @@ function win32Only(reason, platform = process.platform) {
191
192
  }
192
193
  return platform === 'win32' ? it : it.skip;
193
194
  }
195
+ /**
196
+ * @implements A-SPEC-794.124 — as `win32Only`, for a fact of darwin's own tools: its /bin/sh execs a lone `-c` command,
197
+ * which another platform's /bin/sh may not. Elsewhere the case is a reported skip with its reason, never a body that
198
+ * returns early and counts as a pass (A-SPEC-220.3).
199
+ */
200
+ function darwinOnly(reason, platform = process.platform) {
201
+ if (typeof reason !== 'string' || reason.trim().length === 0) {
202
+ throw new Error('darwinOnly(reason): 사유 없는 스킵은 문법만 바뀐 침묵입니다 — 왜 이 단언이 darwin 밖에서 무의미한지 적으십시오.');
203
+ }
204
+ return platform === 'darwin' ? it : it.skip;
205
+ }
@@ -76,7 +76,11 @@ export interface AxConfig {
76
76
  * @implements A-SPEC-128.7 — an entry holding `/` is a root-relative path prefix (`test/fixtures/pyproj`); one without is
77
77
  * a directory name at any depth (`pyproj`). A leading `./` and a trailing `/` are ignored.
78
78
  * @implements A-SPEC-128.13 — `prepare`: the argv a full run runs in HEAD's worktree before its units (`["npm", "run",
79
- * "build"]`), no shell. Absent, or anything but a non-empty array of strings, declares none — no prepare is guessed.
79
+ * "build"]`), no shell. No prepare is guessed.
80
+ * @implements A-SPEC-794.128 — the contract, as A-SPEC-794.123 and 794.128 replace 128.13's clause: `prepare` absent,
81
+ * `[]` or `null` declares none; any other value that is not a non-empty array of non-empty strings makes a full run fail
82
+ * with the reason. Here the parsed config only drops a malformed value; the full run reads HEAD's file itself
83
+ * (test-execution.ts declaredPrepare), which is where the failure is decided.
80
84
  */
81
85
  testRun: {
82
86
  excludeDirs: string[];
@@ -294,6 +294,8 @@ export declare class GrantSpendRefusal extends Error {
294
294
  * `spendGrants`, which removes them after the act.
295
295
  */
296
296
  export declare function spendGrantApprovals(root: string, approvals: readonly Approval[], what: string, rationale?: string): void;
297
+ /** @implements A-SPEC-794.127 — exported: the vouching form reads a session-form vouch's spend row by this one prefix. */
298
+ export declare const GRANT_SPEND_SUMMARY = "consumed approval grant for: ";
297
299
  /**
298
300
  * @implements A-SPEC-245.9 (1b-1) — the store's beforePublish (A-SPEC-245.14) for an act a grant authorized: undefined
299
301
  * when no grant authorized it (an env approval runs as before).
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.GrantSpendRefusal = exports.GrantSettlement = exports.CLAIM_PREFIX = exports.GRANT_NO_EXPIRY = exports.GRANTS_RELDIR = void 0;
36
+ exports.GRANT_SPEND_SUMMARY = exports.GrantSpendRefusal = exports.GrantSettlement = exports.CLAIM_PREFIX = exports.GRANT_NO_EXPIRY = exports.GRANTS_RELDIR = void 0;
37
37
  exports.readGrants = readGrants;
38
38
  exports.ledgerSpendFacts = ledgerSpendFacts;
39
39
  exports.readGrantFiles = readGrantFiles;
@@ -55,7 +55,7 @@ exports.spendGrants = spendGrants;
55
55
  exports.spendGrantApprovals = spendGrantApprovals;
56
56
  exports.grantSpend = grantSpend;
57
57
  exports.staleClaims = staleClaims;
58
- // @implements A-SPEC-245, A-SPEC-532.5, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-222.10, A-SPEC-794.4, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37
58
+ // @implements A-SPEC-245, A-SPEC-794.127, A-SPEC-532.5, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-222.10, A-SPEC-794.4, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37
59
59
  const crypto = __importStar(require("node:crypto"));
60
60
  const fs = __importStar(require("node:fs"));
61
61
  const path = __importStar(require("node:path"));
@@ -737,7 +737,7 @@ function spendGrantApprovals(root, approvals, what, rationale) {
737
737
  const own = rationale === undefined ? new Set() : ownSpends(root, rationale);
738
738
  const spends = [...new Map(approvals.filter((a) => typeof a.nonce === 'string' && a.nonce.trim() !== '' && !own.has((0, provenance_chain_1.nonceFingerprint)(a.nonce)))
739
739
  .map((a) => [String(a.nonce), a])).values()]
740
- .map((a) => ({ nonce: String(a.nonce), actor: a.actor, summary: `${GRANT_SPEND_SUMMARY}${what}`.slice(0, 200),
740
+ .map((a) => ({ nonce: String(a.nonce), actor: a.actor, summary: `${exports.GRANT_SPEND_SUMMARY}${what}`.slice(0, 200),
741
741
  rationale: rationale ?? a.rationale, authorization: (0, provenance_chain_1.authorizationRef)(a.actor, a.token) }));
742
742
  if (spends.length === 0)
743
743
  return;
@@ -751,7 +751,8 @@ function spendGrantApprovals(root, approvals, what, rationale) {
751
751
  if (r === 'error' || r.ok === false)
752
752
  throw new GrantSpendRefusal(r);
753
753
  }
754
- const GRANT_SPEND_SUMMARY = 'consumed approval grant for: ';
754
+ /** @implements A-SPEC-794.127 — exported: the vouching form reads a session-form vouch's spend row by this one prefix. */
755
+ exports.GRANT_SPEND_SUMMARY = 'consumed approval grant for: ';
755
756
  /** The fingerprints this operation (its op id in `rationale`) already spent. */
756
757
  function ownSpends(root, rationale) {
757
758
  const dir = path.join(root, '.ax', 'ledger');
@@ -762,7 +763,7 @@ function ownSpends(root, rationale) {
762
763
  // @implements A-SPEC-222.10 — H-C: trusted rows only (a forged own-spend row would leave a single-use grant unspent)
763
764
  const { TrustedLedgerStore } = require('./recorded-pairs');
764
765
  return new Set(new TrustedLedgerStore(dir).loadAll().filter((e) => e.kind === (0, spend_kinds_1.spendKind)('grant') && e.rationale === rationale
765
- && typeof e.summary === 'string' && e.summary.startsWith(`${GRANT_SPEND_SUMMARY}entity-`)).flatMap((e) => e.inputs ?? []));
766
+ && typeof e.summary === 'string' && e.summary.startsWith(`${exports.GRANT_SPEND_SUMMARY}entity-`)).flatMap((e) => e.inputs ?? []));
766
767
  }
767
768
  /**
768
769
  * @implements A-SPEC-245.9 (1b-1) — the store's beforePublish (A-SPEC-245.14) for an act a grant authorized: undefined
@@ -71,7 +71,7 @@ exports.autonomyBanner = autonomyBanner;
71
71
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
72
72
  exports.versionBumpKind = versionBumpKind;
73
73
  exports.releaseAutonomy = releaseAutonomy;
74
- // @implements A-SPEC-794.113, A-SPEC-794.111, A-SPEC-794.110, A-SPEC-794.107, A-SPEC-794.106, A-SPEC-794.97, A-SPEC-794.96, A-SPEC-794.95, A-SPEC-794.94, A-SPEC-794.91, A-SPEC-794.88, A-SPEC-794.55, A-SPEC-552.3, A-SPEC-552.4,A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4, A-SPEC-532.7, A-SPEC-792.7, A-SPEC-794.47, A-SPEC-794.49
74
+ // @implements A-SPEC-794.126, A-SPEC-794.113, A-SPEC-794.111, A-SPEC-794.110, A-SPEC-794.107, A-SPEC-794.106, A-SPEC-794.97, A-SPEC-794.96, A-SPEC-794.95, A-SPEC-794.94, A-SPEC-794.91, A-SPEC-794.88, A-SPEC-794.55, A-SPEC-552.3, A-SPEC-552.4,A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4, A-SPEC-532.7, A-SPEC-792.7, A-SPEC-794.47, A-SPEC-794.49
75
75
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
76
76
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
77
77
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -569,6 +569,8 @@ function principle7Changes(root, base) {
569
569
  // .git/info/exclude was not seen, and the first row of a chain recorded it as a reference
570
570
  // (review A, L-1) and the gate's wiring and compiler configuration: a new tsconfig.x.json or .mcp.json an ignore
571
571
  // rule hides. The harness's worktrees under .claude are whole checkouts and are not walked.
572
+ // @implements A-SPEC-794.126 — every ignored file here counts, beside a skill too: 794.121's exclusion was a gate
573
+ // relaxation and is withdrawn; init now writes its skill backups under .ax/state, outside these roots
572
574
  const ignored = names(['ls-files', '-z', '-o', '-i', '--exclude-standard', '--', 'src', 'bin', 'playbooks', ':(glob)tsconfig*.json', '.mcp.json', '.claude', ':(exclude).claude/worktrees']);
573
575
  // A-SPEC-794.97 r4 (high-1) — an entry marked assume-unchanged (lowercase tag) or skip-worktree (S) hides its working
574
576
  // tree from diff: its content is hashed and compared with the baseline's
@@ -39,7 +39,7 @@ exports.writeInstallManifest = writeInstallManifest;
39
39
  exports.removeInstallManifest = removeInstallManifest;
40
40
  exports.productInstalledProblems = productInstalledProblems;
41
41
  exports.describeProductInstalled = describeProductInstalled;
42
- // @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57, A-SPEC-794.100, A-SPEC-794.106, A-SPEC-794.107, A-SPEC-794.110, A-SPEC-794.111, A-SPEC-794.113
42
+ // @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57, A-SPEC-794.100, A-SPEC-794.106, A-SPEC-794.107, A-SPEC-794.110, A-SPEC-794.111, A-SPEC-794.113, A-SPEC-794.121
43
43
  /**
44
44
  * The files the product installed in a target, by path and digest, as init recorded them. A self-approval must never
45
45
  * cover one of them: a changed, staged or missing product file — or no record at all — is a reason to refuse.
@@ -52,6 +52,8 @@ const runningPackage = __importStar(require("../project/running-package"));
52
52
  exports.INSTALL_MANIFEST = path.join('.ax', 'state', 'install-manifest.json');
53
53
  const problemDetail = new WeakMap();
54
54
  const withDetail = (p, d) => { problemDetail.set(p, d); return p; };
55
+ /** @implements A-SPEC-794.121 — a missing entry an earlier init recorded beside a recovery skill (a backup, a user file). */
56
+ const besideSkill = new WeakSet();
55
57
  const MANIFEST_EVENT = 'install-manifest';
56
58
  const digestOf = (abs) => {
57
59
  try {
@@ -209,6 +211,11 @@ function productInstalledProblems(root, staged = [], packageRoot = runningPackag
209
211
  const out = [...head];
210
212
  const skills = recoverySkillVerdicts(root, packageRoot);
211
213
  const reference = referenceOf(packageRoot);
214
+ // A-SPEC-794.121 — the playbook skill directories, by the package's playbook list (a location, not a file name)
215
+ // (playbookNames answers [] when the playbooks cannot be listed: then the plain text, and the judgement is the same)
216
+ const { playbookNames, skillPathFor: skillFileOf } = require('../project/playbook-skill-states');
217
+ const skillDirs = new Set(playbookNames(packageRoot).map((n) => norm(path.dirname(path.relative(root, skillFileOf(root, n))))));
218
+ const isBesideSkill = (rel) => skillDirs.has(norm(path.dirname(rel))) && path.basename(rel) !== 'SKILL.md';
212
219
  for (const f of files) {
213
220
  const skill = skills?.verdicts.get(norm(f.path));
214
221
  const now = digestOf(path.join(root, f.path));
@@ -227,8 +234,12 @@ function productInstalledProblems(root, staged = [], packageRoot = runningPackag
227
234
  else if (skill === 'missing')
228
235
  out.push({ path: f.path, why: 'missing' });
229
236
  }
230
- else if (now === null)
231
- out.push({ path: f.path, why: 'missing' });
237
+ else if (now === null) {
238
+ const p = { path: f.path, why: 'missing' };
239
+ if (isBesideSkill(f.path))
240
+ besideSkill.add(p);
241
+ out.push(p);
242
+ }
232
243
  else if (now !== f.sha256)
233
244
  out.push({ path: f.path, why: 'changed' });
234
245
  // A-SPEC-794.57 — what the command stages, and what the index already holds, are told apart
@@ -285,6 +296,9 @@ function describeProductInstalled(problems) {
285
296
  if (p.why === 'drifted')
286
297
  return `product-installed: ${p.path} differs from the playbook of holmes-kit ${d.reference.version} at ${d.reference.path} (drifted) — run ${refresh} with that install, then a person commits the file`;
287
298
  }
299
+ // A-SPEC-794.121 — the text only; the judgement is unchanged
300
+ if (besideSkill.has(p))
301
+ return `product-installed: ${p.path} (missing) — recorded by an earlier init beside a recovery skill and since removed — run \`holmes-kit init\` (a person) to refresh the record`;
288
302
  return `product-installed: ${p.path} (${p.why === 'in-index' ? 'already in the index' : p.why})`;
289
303
  })].join('; ');
290
304
  }
@@ -22,6 +22,12 @@ export interface TestExecutionContext {
22
22
  unresolvedFiles: string[];
23
23
  }>;
24
24
  }
25
+ /**
26
+ * @implements A-SPEC-794.123 — the `testRun.prepare` HEAD's `ax.config.json` declares, read strictly: absent file, no
27
+ * prepare, `[]` or `null` → none (A-SPEC-128.13's "absent or empty declares none"); a file that is not JSON, or a prepare
28
+ * with content in the wrong shape → thrown, so a full run never records evidence without the step the commit declared.
29
+ */
30
+ export declare function declaredPrepare(dir: string): string[] | undefined;
25
31
  export declare function createTestExecutionHandlers(context: TestExecutionContext): {
26
32
  test_run(a: {
27
33
  root: string;
@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.declaredPrepare = declaredPrepare;
36
37
  exports.createTestExecutionHandlers = createTestExecutionHandlers;
37
38
  // @implements A-SPEC-616, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-128, A-SPEC-130, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-534.5, A-SPEC-534.8, A-SPEC-578.4, A-SPEC-614, A-SPEC-734, A-SPEC-768.1, A-SPEC-466.1, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.6, A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.6, A-SPEC-128.7, A-SPEC-128.8, A-SPEC-128.9, A-SPEC-128.10, A-SPEC-128.13, A-SPEC-794.119
38
39
  const fs = __importStar(require("node:fs"));
@@ -60,6 +61,31 @@ const maintenance_evidence_1 = require("../maintenance-evidence");
60
61
  const bounded_io_1 = require("../../project/bounded-io");
61
62
  // @implements A-SPEC-768.1 — the one sentence every anchor-separator diagnostic carries.
62
63
  const ANCHOR_SEPARATOR_HINT = 'only a comma-separated list is an anchor list; ids after the separator are not attributed — write `@' + 'implements A, B` or one marker per line';
64
+ /**
65
+ * @implements A-SPEC-794.123 — the `testRun.prepare` HEAD's `ax.config.json` declares, read strictly: absent file, no
66
+ * prepare, `[]` or `null` → none (A-SPEC-128.13's "absent or empty declares none"); a file that is not JSON, or a prepare
67
+ * with content in the wrong shape → thrown, so a full run never records evidence without the step the commit declared.
68
+ */
69
+ function declaredPrepare(dir) {
70
+ const file = path.join(dir, 'ax.config.json');
71
+ if (!fs.existsSync(file))
72
+ return undefined;
73
+ let parsed;
74
+ try {
75
+ parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
76
+ }
77
+ catch (e) {
78
+ throw new Error(`HEAD's ax.config.json cannot be read as JSON (${(e instanceof Error ? e.message : String(e)).slice(0, 160)}) — a declared testRun.prepare cannot be told apart from none`);
79
+ }
80
+ const tr = parsed !== null && typeof parsed === 'object' ? parsed.testRun : undefined;
81
+ const prep = tr !== null && typeof tr === 'object' ? tr.prepare : undefined;
82
+ if (prep === undefined || prep === null || (Array.isArray(prep) && prep.length === 0))
83
+ return undefined;
84
+ if (!Array.isArray(prep) || !prep.every((x) => typeof x === 'string' && x !== '')) {
85
+ throw new Error(`HEAD's ax.config.json declares testRun.prepare as ${JSON.stringify(prep).slice(0, 120)} — it must be a non-empty array of non-empty strings (an argv, no shell)`);
86
+ }
87
+ return prep;
88
+ }
63
89
  // @implements A-SPEC-534.8
64
90
  // The governed source file a `kills` mutation targets: one that @implements the A-SPEC AND contains
65
91
  // the `where` literal. Bounded walk, skips vendored/test/hidden dirs. null when none qualifies.
@@ -207,14 +233,14 @@ function createTestExecutionHandlers(context) {
207
233
  // worktree of HEAD (outside the repository, A-SPEC-128.14), where the scan, the configuration and the ignore rules are HEAD's. Scoped
208
234
  // runs stay in the work tree (W5); a tree with no git or no commit runs in place and is never push evidence.
209
235
  const opened = testScope.tier === 'full' && head !== '' ? (0, head_worktree_1.openHeadWorktree)(root, head, {
210
- prepareOf: (dir) => { try {
211
- return (0, config_1.loadConfig)(dir).testRun.prepare;
212
- }
213
- catch {
214
- return undefined;
215
- } },
236
+ // @implements A-SPEC-794.123 — a declared prepare is never silently dropped: loadConfig turns a malformed config into
237
+ // the default one (no prepare), so HEAD's file is read here and a config that cannot be parsed, or a prepare that is
238
+ // not a non-empty array of non-empty strings, is thrown — openHeadWorktree answers it as the run's environment
239
+ prepareOf: (dir) => declaredPrepare(dir),
216
240
  // @implements A-SPEC-128.14 — L4: the prepare is bounded by the run's own budget
217
- run: (cmd, args, cwd, budgetMs) => (0, test_runner_1.runBounded)(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: bounded_io_1.GIT_MAX_BUFFER, env: (0, root_1.cleanSubprocessEnv)() }, budgetMs),
241
+ // @implements A-SPEC-794.123 — the prepare is a child of the evidence run: it takes the test environment, told the
242
+ // worktree it runs in (CLAUDE_PROJECT_DIR, where the server carries one) and without the keys a test child never gets
243
+ run: (cmd, args, cwd, budgetMs) => (0, test_runner_1.runBounded)(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: bounded_io_1.GIT_MAX_BUFFER, env: (0, root_1.cleanTestEnv)(process.env, { projectDir: cwd }) }, budgetMs),
218
244
  prepareBudgetMs: timeoutMinutes * 60_000,
219
245
  // @implements A-SPEC-128.16 — W1: the walk bound is HEAD's declared testRun.linkWalk, only when both are positive numbers
220
246
  walkBoundOf: (dir) => {
@@ -310,7 +310,15 @@ function openHeadWorktree(root, head, opts) {
310
310
  return { ok: false, reason: linked };
311
311
  }
312
312
  const t1 = Date.now();
313
- const prepare = opts.prepareOf(dir);
313
+ // @implements A-SPEC-794.123 — a config the caller could not read is the run's environment, as a failed prepare is
314
+ let prepare;
315
+ try {
316
+ prepare = opts.prepareOf(dir);
317
+ }
318
+ catch (e) {
319
+ close();
320
+ return { ok: false, reason: `testRun.prepare could not be read: ${firstLine(e instanceof Error ? e.message : String(e))}` };
321
+ }
314
322
  if (prepare && prepare.length > 0) {
315
323
  if (installPrepare(prepare)) {
316
324
  close();
@@ -354,7 +354,17 @@ function runJestOutcomes(files, cwd, timeoutMinutes) {
354
354
  if (files.length === 0)
355
355
  return {};
356
356
  // @implements A-SPEC-466.6 — a mutation's jest child is a runner child of the run too
357
- return withRunBudget(timeoutMinutes, () => runJest(files, 'scoped', cwd).outcomes);
357
+ // @implements A-SPEC-794.123 — and is told the tree it runs in, held for this run only and put back after, as runTestScope does
358
+ return withRunBudget(timeoutMinutes, () => {
359
+ const prevRoot = RUN_PROJECT_ROOT;
360
+ RUN_PROJECT_ROOT = cwd;
361
+ try {
362
+ return runJest(files, 'scoped', cwd).outcomes;
363
+ }
364
+ finally {
365
+ RUN_PROJECT_ROOT = prevRoot;
366
+ }
367
+ });
358
368
  }
359
369
  /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
360
370
  // @implements A-SPEC-502.1 — exported for the wiring test (a fake venv python capturing argv).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209, A-SPEC-794.58",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.41.0",
4
+ "version": "0.41.1",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",