@holmes-lab/holmes-kit 0.41.0 → 0.41.2

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,19 @@ 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.2] - 2026-11-14
11
+
12
+ ### Added
13
+ - **The package carries a per-version release summary, and the release checks it (A-SPEC-795).** `release-history.json` at the package root holds a short Korean and English summary of each release from 0.40.0 on: what it gives its users, the conditions for upgrading, and the limitations that still hold. The Holmes Lab website reads it from the exact published version. `verify-release` now refuses a publish whose file is absent, oversized or not JSON, lacks an entry for the version being published, repeats a version, misses a language, holds placeholder text or an absolute path or host, or is not in the packed artifact. The rules include the website reader's own, so a file the release accepts is one the site accepts. Versions before 0.40.0 have no entry; the website shows them as awaiting a summary. Nothing else in this release changes.
14
+
15
+ ## [0.41.1] - 2026-11-13
16
+
17
+ ### Fixed
18
+ - **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.
19
+ - **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.
20
+ - **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.
21
+ - **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.
22
+
10
23
  ## [0.41.0] - 2026-11-12
11
24
 
12
25
  ### 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
+ **566/566** source files (100%) trace to an approved spec · **1273/1380** approved A-SPECs (92.2%) are anchored from code.
15
+ Measured at `cd6779b43d7a` (specs `sha256:f722ad27be15`) — 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.**
@@ -96,6 +96,7 @@ The pre-push gate accepts a full `test_run` as evidence only where holmes can ch
96
96
  - **Agents clean up their own temporary work** *(new in 0.35.25)*: `holmes-kit scratch --new <label>` makes a directory under a per-user Holmes scratch root (`os.tmpdir()/holmes-scratch-<uid>`, mode 0700), and on macOS and Linux the gate lets an agent in Claude Code, Codex or Antigravity remove it with one plain `rm -rf <absolute path>` without an operator act; the root itself, tracked source, every other path and any compound command keep their verdict. Where another holmes-kit install sits in an ancestor `node_modules` of the workspace or the home directory (npm, Windows shims and pnpm alike), approval hints name the running install's own path so that copy cannot answer them (a PowerShell form on Windows), and doctor's `npx resolution` row names it.
97
97
  - **You can tell whether a harness's gate actually ran here** *(new in 0.35.24)*: the PreToolUse and Stop hooks of Claude Code, Codex and Antigravity leave a git-ignored per-harness record (`.ax/state/hook-heartbeat/`, at most one write a minute, never part of a decision). `workspace_preflight` with `harness` passes `runtime-enforcement` only after that harness's PreToolUse gate was observed within 24 h and since its wiring last changed; doctor shows one `hook observed (<harness>)` row each; `runtime-binding status` reports `activation` for this selection's gate and names every other observation and an outdated deployed dispatcher. `runtime_binding` answers an unbound workspace with its routing instead of "not registered", init states a Codex verdict for registry-owned Codex files, and doctor FAILs a running Stop hook under 75 s. Measured need: a Codex session in a release-routed workspace concluded it was ungoverned.
98
98
  - **A benchmark run the operator pre-approved finishes with zero human waits — the run delegation** *(new in 0.35.19)*: `holmes-kit autonomy delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes a run-scoped, workspace-bound (realpath), expiring delegation that covers a closed set of autonomy-grader rules — root-only or gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC; never architecture documents, un-admitted requirements, undeclared or unknown grades. A hitl spec whose only reason is a covered rule seals on its own with `source: 'delegated'` and a ledger row naming the run and the rule; an uncovered case refuses with the named limit (`does not cover`, `expired`, `for <workspace>, not this root`, `invalid document`). `autonomy status`, `approve --status` and the session-start banner show it; `revoke-delegation` or `off` ends it. The host's own approval layer is named as not covered. Measured need: X1 (2026-10-12) stopped a pre-approved fixture on `files-to-touch-root-only`. Every operator hint now also names the workspace (`--target <root>`), a context-only Codex patch is refused as a no-op by name, and `runtime-binding status`/`doctor` report a Codex lifecycle routed to Holmes from both the user-level and the workspace hooks file.
99
+ - **Each release carries its own summary** *(new in 0.41.2)*: `release-history.json` at the package root holds a short Korean and English summary of each release from 0.40.0 on (benefits, upgrade conditions, limitations), which the Holmes Lab website reads from the exact published version. The release gate refuses a publish without a valid entry for its own version.
99
100
  - **The ledger has a witness the tree cannot move** *(new in 0.41)*: in Holmes-Kit's own repository (and for a package that is not npm-installed), the gate reads its provenance chain only when the chain is the one this repository wrote — a witness in the git directory, moved by every append, says so. A chain taken back by a checkout or a stash, or extended by rows brought in from outside, closes the judgement until the tree returns or a person vouches (`holmes-kit ledger witness`). A new checkout starts closed until a person vouches once.
100
101
  - **The gate and approval-processing source is sealed by a person** *(new in 0.41)*: a spec whose Files to Touch names a module that reads or writes a grant, an actor, a seal or a decision (the hooks, guardrail and governance code, the approval CLI and MCP handlers, review verdicts, runtime dispatch, the spec transition policy) is sealed only by a person — no declared grade, run delegation or full profile seals it; a census test keeps the category whole. Such a file is also *written* only within 12 hours (`autonomy.sealWindowHours`, 1–24) of a person's seal of an approved A-SPEC whose Files to Touch names it — in the session form (or a host's approval dialog); a seal spent from a grant file does not count, since a file write can make one — and each write a window opens is recorded in the ledger; an anchor already in the file, or an older seal, opens nothing. Whatever wrote it, a gate-file change since the live gate's baseline (the commit the gate last built, recorded in the ledger) — in the working tree, the index or a commit — that no window names blocks the turn's end, a commit and a build. It stays blocked until a person seals a spec naming it, a branch switch or pull that brought it is undone, or the file is made equal to the baseline again; a commit made outside the gate (an owner's terminal commit, a pull) is judged the same way, and the refusal warns first that a restore from the baseline also discards such commits (Holmes-Kit's own repository; it prevents accidents, forgery resistance is not verified).
101
102
  - **Un-seal and retire are decisions of their own** *(new in 0.41)*: `spec-unseal` and `spec-retire` are approval kinds of their own (a seal's approval does not cover them), every path names a transition's kind from one table, and a seal records the MCP server instance that made it.
@@ -413,7 +414,7 @@ flowchart LR
413
414
  | `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
415
  | `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
416
  | `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)* |
417
+ | `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
418
  | `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
419
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
419
420
  | `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
+ 6ebb0c0f-mwg9d2un
@@ -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 {
@@ -0,0 +1,21 @@
1
+ /**
2
+ * release-history.json — the package's own reviewed, bilingual summary of each release, which the Holmes Lab website
3
+ * reads from the exact published version (its reader: A-SPEC-101.41 there, `parseSummaries`).
4
+ *
5
+ * The rules are that reader's, never looser, so a file the release accepts is a file the website accepts; then the
6
+ * package's own: an entry for the version being published, no placeholder text, no private path or host. Every
7
+ * problem is reported at once with the field it concerns, because a release refused one problem at a time is a
8
+ * release refused six times. Pure: the caller reads the file.
9
+ */
10
+ export declare const RELEASE_HISTORY_FILE = "release-history.json";
11
+ export declare const RELEASE_HISTORY_MAX_BYTES = 262144;
12
+ export type ReleaseHistoryVerdict = {
13
+ ok: true;
14
+ } | {
15
+ ok: false;
16
+ problems: string[];
17
+ };
18
+ /** The problems of `doc` as the release of `version` would publish it; `{ ok: true }` when there are none. */
19
+ export declare function validateReleaseHistory(doc: unknown, version: string): ReleaseHistoryVerdict;
20
+ /** The packed listing (`npm pack --dry-run --json` paths, /-joined) holds the file at the package root. */
21
+ export declare function releaseHistoryPacked(files: readonly string[]): boolean;
@@ -0,0 +1,116 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.RELEASE_HISTORY_MAX_BYTES = exports.RELEASE_HISTORY_FILE = void 0;
4
+ exports.validateReleaseHistory = validateReleaseHistory;
5
+ exports.releaseHistoryPacked = releaseHistoryPacked;
6
+ // @implements A-SPEC-795
7
+ /**
8
+ * release-history.json — the package's own reviewed, bilingual summary of each release, which the Holmes Lab website
9
+ * reads from the exact published version (its reader: A-SPEC-101.41 there, `parseSummaries`).
10
+ *
11
+ * The rules are that reader's, never looser, so a file the release accepts is a file the website accepts; then the
12
+ * package's own: an entry for the version being published, no placeholder text, no private path or host. Every
13
+ * problem is reported at once with the field it concerns, because a release refused one problem at a time is a
14
+ * release refused six times. Pure: the caller reads the file.
15
+ */
16
+ exports.RELEASE_HISTORY_FILE = 'release-history.json';
17
+ exports.RELEASE_HISTORY_MAX_BYTES = 262_144;
18
+ const PACKAGE = '@holmes-lab/holmes-kit';
19
+ const MAX_ENTRIES = 2000;
20
+ const TEXT_MAX = 2000;
21
+ const BENEFIT_MAX = 1000;
22
+ const LANGS = ['ko', 'en'];
23
+ /** The reader's semantic-version rule (numeric prerelease identifiers without leading zeros). */
24
+ const VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
25
+ const isVersion = (v) => {
26
+ if (typeof v !== 'string' || v.length > 100)
27
+ return false;
28
+ const m = VERSION.exec(v);
29
+ return m !== null && !(m[4] ?? '').split('.').some((p) => /^\d+$/.test(p) && p.length > 1 && p.startsWith('0'));
30
+ };
31
+ const PLACEHOLDER = /\b(TODO|TBD|FIXME|XXX|lorem)\b|<[^<>]*>/i;
32
+ const PRIVATE = /\/Users\/|\/home\/|\b[A-Za-z]:\\|(^|\s)~\/|https?:\/\/|\b[\w-]+\.(local|lan)\b/i;
33
+ const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
34
+ function checkText(x, where, max, out) {
35
+ if (typeof x !== 'string') {
36
+ out.push(`${where}: missing`);
37
+ return;
38
+ }
39
+ if (x.trim() === '') {
40
+ out.push(`${where}: blank`);
41
+ return;
42
+ }
43
+ if (x.length > max)
44
+ out.push(`${where}: over ${max} characters`);
45
+ if (PLACEHOLDER.test(x))
46
+ out.push(`${where}: placeholder text`);
47
+ if (PRIVATE.test(x))
48
+ out.push(`${where}: private path or host`);
49
+ }
50
+ function checkLocalized(x, where, out) {
51
+ if (!isObject(x)) {
52
+ out.push(`${where}: missing`);
53
+ return;
54
+ }
55
+ for (const lang of LANGS)
56
+ checkText(x[lang], `${where}.${lang}`, TEXT_MAX, out);
57
+ }
58
+ /** The problems of `doc` as the release of `version` would publish it; `{ ok: true }` when there are none. */
59
+ function validateReleaseHistory(doc, version) {
60
+ const problems = [];
61
+ if (!isObject(doc))
62
+ return { ok: false, problems: ['file: not a JSON object'] };
63
+ if (doc.schemaVersion !== 1)
64
+ problems.push('schemaVersion: must be 1');
65
+ if (doc.package !== PACKAGE)
66
+ problems.push(`package: must be ${PACKAGE}`);
67
+ const reviewedAt = doc.reviewedAt;
68
+ if (typeof reviewedAt !== 'string' || !/^\d{4}-\d\d-\d\d$/.test(reviewedAt) || !Number.isFinite(Date.parse(reviewedAt))) {
69
+ problems.push('reviewedAt: must be a YYYY-MM-DD date');
70
+ }
71
+ const bytes = Buffer.byteLength(JSON.stringify(doc), 'utf8');
72
+ if (bytes > exports.RELEASE_HISTORY_MAX_BYTES)
73
+ problems.push(`file: over ${exports.RELEASE_HISTORY_MAX_BYTES} bytes (${bytes})`);
74
+ if (!Array.isArray(doc.entries)) {
75
+ problems.push('entries: must be an array');
76
+ return { ok: false, problems };
77
+ }
78
+ if (doc.entries.length > MAX_ENTRIES)
79
+ problems.push(`entries: over ${MAX_ENTRIES}`);
80
+ const seen = new Set();
81
+ doc.entries.forEach((raw, i) => {
82
+ const at = `entries[${i}]`;
83
+ if (!isObject(raw)) {
84
+ problems.push(`${at}: not an object`);
85
+ return;
86
+ }
87
+ if (!isVersion(raw.version))
88
+ problems.push(`${at}.version: not a semantic version`);
89
+ else if (seen.has(raw.version))
90
+ problems.push(`${at}.version: duplicate ${raw.version}`);
91
+ else
92
+ seen.add(raw.version);
93
+ checkLocalized(raw.title, `${at}.title`, problems);
94
+ checkLocalized(raw.upgrade, `${at}.upgrade`, problems);
95
+ checkLocalized(raw.limitations, `${at}.limitations`, problems);
96
+ if (!isObject(raw.benefits)) {
97
+ problems.push(`${at}.benefits: missing`);
98
+ return;
99
+ }
100
+ for (const lang of LANGS) {
101
+ const list = raw.benefits[lang];
102
+ if (!Array.isArray(list) || list.length < 1 || list.length > 8) {
103
+ problems.push(`${at}.benefits.${lang}: 1 to 8 strings expected`);
104
+ continue;
105
+ }
106
+ list.forEach((b, j) => checkText(b, `${at}.benefits.${lang}[${j}]`, BENEFIT_MAX, problems));
107
+ }
108
+ });
109
+ if (!seen.has(version))
110
+ problems.push(`entries: no entry for ${version} (the version being published)`);
111
+ return problems.length === 0 ? { ok: true } : { ok: false, problems };
112
+ }
113
+ /** The packed listing (`npm pack --dry-run --json` paths, /-joined) holds the file at the package root. */
114
+ function releaseHistoryPacked(files) {
115
+ return files.includes(exports.RELEASE_HISTORY_FILE);
116
+ }
@@ -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.2",
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",
@@ -17,7 +17,8 @@
17
17
  "scripts/install.ps1",
18
18
  "docs/install-guide.md",
19
19
  "docs/language-support.md",
20
- "CHANGELOG.md"
20
+ "CHANGELOG.md",
21
+ "release-history.json"
21
22
  ],
22
23
  "engines": {
23
24
  "node": ">=20"
@@ -0,0 +1,146 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "package": "@holmes-lab/holmes-kit",
4
+ "reviewedAt": "2026-11-14",
5
+ "entries": [
6
+ {
7
+ "version": "0.41.2",
8
+ "title": {
9
+ "ko": "버전별 요약을 패키지에 싣고 발행 때 확인하기",
10
+ "en": "Ship a per-version summary in the package and check it at release"
11
+ },
12
+ "benefits": {
13
+ "ko": [
14
+ "패키지 루트에 버전별 한국어·영어 요약 파일이 실려, 웹사이트가 정확히 그 발행 버전에서 요약을 읽을 수 있습니다.",
15
+ "발행 검증이 이 파일이 없거나, 형식이 틀리거나, 발행하는 버전의 항목이 없거나, 언어가 빠졌거나, 자리표시 문구·절대 경로·URL이나 호스트가 있거나, 발행물에 빠진 경우 발행을 거부합니다."
16
+ ],
17
+ "en": [
18
+ "The package root carries a Korean and English summary per version, so the website can read it from the exact published version.",
19
+ "The release check refuses a publish whose file is absent, malformed, lacks an entry for the version being published, misses a language, holds placeholder text, an absolute path, a URL or a host, or is missing from the packed artifact."
20
+ ]
21
+ },
22
+ "upgrade": {
23
+ "ko": "도구의 동작은 바뀌지 않습니다. Holmes-Kit을 직접 발행하는 경우, 발행하는 버전의 요약 항목을 release-history.json에 추가해야 발행 검증을 통과합니다.",
24
+ "en": "The tool's behaviour does not change. Publishing Holmes-Kit itself now needs an entry for the version being published in release-history.json to pass the release check."
25
+ },
26
+ "limitations": {
27
+ "ko": "요약은 0.40.0부터 있습니다. 그 이전 버전의 요약은 패키지에 없어, 웹사이트는 그 버전들을 요약 준비 중으로 표시합니다. 요약 문구는 AI 에이전트가 CHANGELOG와 대조해 검토했고, 발행은 오너가 승인합니다. 발행 검증은 형식과 금지 문구만 확인하고 내용의 정확성은 확인하지 않습니다.",
28
+ "en": "Summaries start at 0.40.0. Versions before it have no summary in the package, so the website shows them as awaiting a summary. The text was reviewed by AI agents against the CHANGELOG, and the owner approves the publish; the release check confirms its shape and forbidden text, not the accuracy of its content."
29
+ }
30
+ },
31
+ {
32
+ "version": "0.41.1",
33
+ "title": {
34
+ "ko": "백업 정리, 원장 보증 확인, 테스트 실행 환경을 바로잡기",
35
+ "en": "Fix backup cleanup, the ledger-witness form and the test-run environment"
36
+ },
37
+ "benefits": {
38
+ "ko": [
39
+ "이 버전부터 init이 만드는 새 스킬 백업은 지워도 full 자율 프로필의 거버넌스 스테이징을 막지 않습니다. 새 백업은 감시 대상 밖의 상태 폴더에 남습니다.",
40
+ "원장 보증 폼의 첫 줄이 보증 확인 결과를 보여 주고, 정상이 아닌 결과에는 보증하지 말라는 경고가 붙습니다.",
41
+ "서버가 CLAUDE_PROJECT_DIR를 가진 경우, 전체 test_run의 준비 단계는 HEAD의 작업 트리를, 변이 실행은 그 실행의 루트를 그 값으로 받습니다. 준비 단계는 HOLMES_SPECS, HOLMES_MCP_AUTORELOAD, HOLMES_MCP_PROFILE, npm_config_dry_run, PYTEST_ADDOPTS, PYTEST_PLUGINS를 더는 받지 않습니다.",
42
+ "읽을 수 없는 ax.config.json 때문에 선언된 준비 단계가 조용히 빠진 채 통과 증거가 기록되는 일이 없어졌습니다."
43
+ ],
44
+ "en": [
45
+ "From this version on, removing a new skill backup that init makes does not close governance staging under a full autonomy profile; new backups are kept in a state folder outside what the gate watches.",
46
+ "The ledger-witness form leads with the witness's own verdict, and every verdict other than ok carries a warning not to vouch unless the chain is meant as the reference.",
47
+ "Where the server carries CLAUDE_PROJECT_DIR, a full test_run's prepare step gets it as HEAD's worktree and a mutate run as the run's root; the prepare step no longer receives HOLMES_SPECS, HOLMES_MCP_AUTORELOAD, HOLMES_MCP_PROFILE, npm_config_dry_run, PYTEST_ADDOPTS or PYTEST_PLUGINS.",
48
+ "An unreadable ax.config.json no longer lets a full run drop a declared prepare step silently and record passing evidence."
49
+ ]
50
+ },
51
+ "upgrade": {
52
+ "ko": "이미 지운 백업이 설치 manifest에 기록된 작업공간은 사람이 holmes-kit init을 한 번 실행해야 스테이징이 다시 열립니다. ax.config.json의 testRun.prepare는 없거나, 빈 배열이거나, null이면 선언 없음이고, 그 밖에 비어 있지 않은 문자열 배열이 아닌 값이면 전체 실행이 이유와 함께 실패합니다.",
53
+ "en": "A workspace whose install manifest already records a removed backup needs one holmes-kit init by a person before staging opens again. testRun.prepare in ax.config.json declares nothing when absent, empty or null; any other value that is not a non-empty array of non-empty strings fails a full run with the reason."
54
+ },
55
+ "limitations": {
56
+ "ko": "보증 확인 파일은 .git 아래에 있어 셸이 지울 수 있고, 지워지면 첫 보증처럼 읽힙니다. 푸시된 체인과의 비교는 세션이 옮길 수 있는 로컬 ref를 기준으로 합니다. 위조된 보증 파일에 대한 저항은 검증되지 않았고, 사람이 터미널에서 한 보증은 기록이 남지 않습니다. 이전 버전이 스킬 옆에 남긴 백업은 그대로 남습니다.",
57
+ "en": "The witness lives under .git, where a shell can delete it, and a removed witness reads as a first vouch. The comparison with the pushed chain goes through a local ref a session can move. Resistance to a forged witness file is not verified, and a vouch made at a person's own terminal leaves no record. Backups an earlier version left beside a skill stay where they are."
58
+ }
59
+ },
60
+ {
61
+ "version": "0.41.0",
62
+ "title": {
63
+ "ko": "승인 종류 분리, full 프로필의 명세 자율 스테이징, 런타임 쓰기 보호",
64
+ "en": "Separate approval kinds, autonomous spec staging under a full profile, and write protection for the runtime"
65
+ },
66
+ "benefits": {
67
+ "ko": [
68
+ "봉인 해제와 폐기가 각각의 승인 종류가 되어, 명세 봉인(spec-approve)으로 범위를 건 승인이 해제·폐기를 덮지 않습니다. 범위를 걸지 않은 승인은 여전히 덮습니다.",
69
+ "훅이나 CLI가 낸 승인 요청 가운데, 요청한 실행이나 서버가 없고 사람이 보류하지도 않은 채 24시간이 지난 것은 다음 세션 시작 때 실행되지 않은 상태로 닫힙니다. 요청한 실행이나 서버가 있는 요청은 대상이 아닙니다.",
70
+ "full 프로필(오너가 지정한 작업공간에서 정해진 판정을 사람 승인 없이 처리하는 자율 프로필)에서, 명세와 그 상위 명세가 모두 봉인돼 있으면 사람 없이 스테이징될 수 있습니다. 열리는 조건은 업그레이드 (1)에 있습니다.",
71
+ "훅을 실행하는 런타임 파일과 npm으로 설치된 패키지(실제 경로에 node_modules가 있는 설치본)에 대해, 명령에 경로가 드러나는 세션의 쓰기·이동·삭제를 훅이 거부합니다."
72
+ ],
73
+ "en": [
74
+ "Un-seal and retire are approval kinds of their own, so an approval scoped to sealing a specification (spec-approve) no longer covers them; an unscoped approval still does.",
75
+ "A request filed by a hook or the CLI, with no requesting run or server and not held by a person, is closed unrun at the next session start once 24 hours pass undecided. A request with a requesting run or server is not affected.",
76
+ "Under a full profile (the autonomy profile in which the owner's chosen workspaces have set judgements decided without a person's approval), a specification whose own and parent seals hold can be staged without a person; when that opens is in upgrade (1).",
77
+ "The hook refuses a session's writes, moves and removals, where the command names the path, in the runtime that dispatches the hooks and in an npm-installed package (one whose real path has a node_modules segment)."
78
+ ]
79
+ },
80
+ "upgrade": {
81
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) full 프로필에서 명세 스테이징을 사람 없이 승인하는 것이 기본입니다. 끄려면 ax.config.json에 \"autonomy\": { \"specStaging\": \"off\" }를 두세요. 이 자율 승인은 Holmes-Kit이 npm으로 설치된 경우(실제 경로에 node_modules)에 열립니다. 손으로 푼 패키지에서는 사람이 승인하고, npm link·file: 의존성·workspace로 연결한 경우는 연결 대상에 기록된 빌드가 없으면 사람이 승인합니다. 그 밖의 조건은 CHANGELOG에 있습니다. (2) spec-approve로 범위를 건 grant나 승인은 봉인 해제·폐기를 덮지 않으니, spec-unseal·spec-retire로 범위를 다시 거세요. (3) 승인 변수를 명령에 붙인 holmes-kit autonomy full·on·delegate는 거부됩니다(profile.own-request). 변수 없이 실행하면 세션 폼으로 요청이 갑니다. (4) full 프로필에서 게이트·승인 처리 범주를 범위에 둔 명세는 사람 폼으로만 봉인됩니다. 주로 Holmes-Kit 저장소의 게이트 소스가 해당하지만, dist·상위 디렉터리·루트 설정 파일을 범위에 둔 명세도 해당될 수 있습니다. (5) publish 플래그가 꺼진 full 프로필에서 publish 판정이 레지스트리 쓰기, 릴리스 도구, 패키지 스크립트 안으로 넓어졌습니다. push 플래그가 꺼져 있으면 패키지 스크립트 안의 push도 판정됩니다. 이것은 사고 방지이지 장벽이 아닙니다. npm 계정의 2FA를 켜 두고, 에이전트에는 발행 권한이 없는 토큰을 주세요.",
82
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) Under a full profile, approving spec staging without a person is the default; turn it off with \"autonomy\": { \"specStaging\": \"off\" } in ax.config.json. This autonomous approval opens where Holmes-Kit is npm-installed (its real path has a node_modules segment). A package unpacked by hand is approved by a person, and so is one reached through npm link, a file: dependency or a workspace while the checkout it points at has no recorded build. The other conditions are in the CHANGELOG. (2) A grant or approval scoped to spec-approve does not cover un-seal or retire; scope it again to spec-unseal or spec-retire. (3) holmes-kit autonomy full, on or delegate with an approval variable set in the command is refused (profile.own-request); without the variable it asks in the session form. (4) Under a full profile, a specification scoped to the gate and approval-processing category is sealed only in a person's form. That is mostly Holmes-Kit's own gate source, but a specification scoped to dist, a parent directory or a root configuration file can fall in it too. (5) Under a full profile with the publish flag off, the publish judgement now reaches registry writes, release tools and package scripts; with the push flag off, a push inside a package script is judged too. It prevents accidents and is not a barrier: keep two-factor authentication required on the npm account, and give agents a token without publish rights."
83
+ },
84
+ "limitations": {
85
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) 훅은 사고 예방을 위한 장치이며, 같은 사용자 권한의 에이전트 셸에 대한 위조 저항은 검증되지 않았습니다. (2) 쓰기 거부는 명령에 경로가 드러나는 경우에만 걸립니다. 이름을 드러내지 않고 쓰는 프로그램, 게이트가 따라갈 수 없는 cd 뒤의 상대 경로, 사람 본인의 터미널은 보지 못합니다. (3) full 프로필에서 init이 남긴 스킬 백업을 지우면 요청 없이 거버넌스 스테이징이 닫힙니다(0.41.1에서 수리. 이미 닫힌 작업공간은 사람이 holmes-kit init을 한 번 실행해야 풀립니다). (4) 설치된 복구 스킬이 실행 중인 패키지의 것과 다르면 자율 스테이징이 거부됩니다.",
86
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) Hooks aim to prevent accidents; forgery resistance against an agent shell running as the same user is not verified. (2) The write refusals apply where the command names the path: a program that writes without naming it, a relative path after a cd the gate cannot resolve, and a person's own terminal are not seen. (3) Under a full profile, removing a skill backup that init left closes governance staging with no request (repaired in 0.41.1; a workspace already closed stays closed until a person runs holmes-kit init once). (4) An installed recovery skill that differs from the running package's refuses autonomous staging."
87
+ }
88
+ },
89
+ {
90
+ "version": "0.40.1",
91
+ "title": {
92
+ "ko": "푸시마다 그 커밋의 전체 test_run을 근거로 요구",
93
+ "en": "Each push needs a full test_run of the pushed commit"
94
+ },
95
+ "benefits": {
96
+ "ko": [
97
+ "푸시 게이트가 푸시할 커밋의 깨끗한 임시 checkout(HEAD worktree)에서 돈 전체 test_run만 근거로 받아, 다른 코드의 통과 기록이나 범위 실행과 구분합니다.",
98
+ "전체 실행을 한 번 한 뒤에는, 감지된 생태계마다 테스트가 하나 이상 실행돼야 하고 실행된 시험이 없는 구현 코드는 푸시가 거부됩니다.",
99
+ "test_run에 jest 작업자 수(workers)와 실행기마다의 시간 예산(timeoutMinutes)을 지정할 수 있습니다.",
100
+ "녹색 실행 뒤에 작업 디렉터리를 편집해도 그 커밋의 증거는 무효가 되지 않습니다."
101
+ ],
102
+ "en": [
103
+ "The push gate accepts only a full test_run that ran in a clean temporary checkout of the pushed commit (a HEAD worktree), distinguishing it from tests of other code and from scoped runs.",
104
+ "Once a full run has been attempted, every detected ecosystem must have run at least one test, and implementation code with no executed test refuses the push.",
105
+ "test_run takes a jest worker count (workers) and a time budget per runner (timeoutMinutes).",
106
+ "Editing the work tree after a green run no longer voids that commit's evidence."
107
+ ]
108
+ },
109
+ "upgrade": {
110
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) 푸시는 세 경우로 갈립니다. test_run 기록이 한 번도 없는 저장소는 활성화 안내와 함께 통과합니다. 저장소에 시험 파일도 구현 코드도 없으면 알림과 기록을 남기고 통과합니다. 그 밖에는 푸시마다 그 커밋에서 전체 test_run(full: true)이 필요하며, 범위 실행과 0.40.0이 쓴 기록은 근거가 되지 않습니다. (2) 전체 실행의 비용은 스위트 전체입니다. Holmes-Kit 저장소에서는 작업자 2개로 약 40분이었고, 시간 예산은 기본 120분, 최대 180분입니다. (3) 시험이 빌드 산출물에 기대면 ax.config.json에 testRun.prepare(예: [\"npm\", \"run\", \"build\"])를 선언하세요. (4) 사람 본인 터미널에서 처음 설치할 때 holmes-kit init의 자율 승인 질문 기본값이 Y여서, Enter만 치면 저위험 명세의 자율 승인이 켜집니다. 에이전트 하네스나 CI 아래에서는 꺼진 채이고, 이미 설정된 값은 유지됩니다. 끄려면 holmes-kit init --no-autonomy를 쓰거나 .mcp.json에서 HOLMES_AUTONOMOUS_APPROVAL을 지우세요.",
111
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) A push falls into three cases: a repository with no test_run record at all passes with the activation notice; a repository with neither a test file nor implementation code passes with a notice and a record; otherwise each push needs a full test_run (full: true) at the pushed commit, and scoped runs and records written by 0.40.0 are not evidence. (2) A full run costs the whole suite: about 40 minutes at two workers on the Holmes-Kit repository, with a time budget of 120 minutes by default and 180 at most. (3) If tests need build output, declare testRun.prepare in ax.config.json (for example [\"npm\", \"run\", \"build\"]). (4) On a first install at a person's own terminal, the autonomy question of holmes-kit init defaults to Y, so pressing Enter turns on autonomous approval of low-risk specifications; under an agent harness or CI it stays off, and a value already set is kept; turn it off with holmes-kit init --no-autonomy, or remove HOLMES_AUTONOMOUS_APPROVAL from .mcp.json."
112
+ },
113
+ "limitations": {
114
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) 푸시 근거가 되는 구성은 설정 하나·프로젝트 하나의 jest, 기본 이름의 pytest, go입니다. cargo·maven/gradle·dotnet 빌드 루트, jest projects나 여러 jest 설정은 environment로 거부되며, 그 밖의 구성은 CHANGELOG에 있습니다. (2) environment 거부는 사유가 문장에 적히며, 시험 코드를 고치는 것만으로는 대개 풀리지 않습니다. 러너 설치·설정 변경·커밋·스위트 분할로 풀리는 경우가 있고, 0.40.x가 지원하지 않아 풀 수 없는 구성도 있습니다. (3) Go의 전체 실행은 Stop 훅의 명세별 실행 집계에 잡히지 않고, 범위 실행은 그 집계와 근거를 갱신하지 않습니다. (4) 시험 근거의 위조 저항은 검증되지 않았습니다. HEAD의 conftest가 로드된 모듈 기록을 바꿀 수 있습니다.",
115
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) Push evidence covers jest with one configuration and one project, pytest under default names, and go. cargo, maven/gradle and dotnet build roots, jest projects and several jest configurations are refused as environment; the rest are in the CHANGELOG. (2) An environment refusal states its reason, and changing the test code alone usually does not clear it: some are cleared by installing the runner, changing a setting, committing or splitting the suite, and some configurations 0.40.x does not support cannot be cleared. (3) A full Go run is not counted in the Stop hook's per-specification execution counts, and a scoped run refreshes neither those counts nor the evidence. (4) The forgery resistance of the test evidence is not verified: a HEAD conftest can rewrite the loaded-module record."
116
+ }
117
+ },
118
+ {
119
+ "version": "0.40.0",
120
+ "title": {
121
+ "ko": "full 프로필의 푸시·배포 플래그 강제와 승인·명령 판정 변경",
122
+ "en": "Enforce the full profile's push and publish flags, and change how approvals and commands are judged"
123
+ },
124
+ "benefits": {
125
+ "ko": [
126
+ "full 프로필(오너가 지정한 작업공간에서 정해진 판정을 사람 승인 없이 처리하는 자율 프로필)에서 git push와 npm publish가 프로필의 허용 플래그를 따릅니다. 플래그가 없으면 거부되고 grant로도 풀리지 않습니다.",
127
+ "승인 결정(approve)이 요청 id나 8자 이상의 고유한 접두어로만 이뤄져, 목록 번호가 바뀌는 사이에 읽지 않은 요청을 승인하는 일을 줄입니다.",
128
+ "run start가 하네스 설정이 실제로 Holmes-Kit 패키지를 실행하는지 판정해, 이름만 holmes인 설정은 통과하지 않습니다."
129
+ ],
130
+ "en": [
131
+ "Under a full profile (the autonomy profile in which the owner's chosen workspaces have set judgements decided without a person's approval), git push and npm publish follow the profile's flags: without the flag they are refused, and a grant does not lift that.",
132
+ "Approval decisions (approve) take a request id or a unique id prefix of eight or more characters only, which reduces granting a request no one read after a list number moved.",
133
+ "run start judges whether the harness configuration actually launches the Holmes-Kit package; configuration that only names holmes no longer passes."
134
+ ]
135
+ },
136
+ "upgrade": {
137
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) full 프로필에서 --allow-push 없는 git push와 --allow-publish 없는 npm publish는 거부되고 grant로 풀리지 않습니다. 도움말·dry-run 형태는 통과하지만, push 플래그가 꺼져 있으면 강제 푸시는 그 형태도 거부됩니다. (2) git add -A, git add ., git commit -a가 다른 복제본(다른 기기, 연결된 worktree, run 실행)의 provenance 원장 파일에 닿으면 사람의 몫입니다. (3) 실행 중에 .ax 경로를 만들어 쓰는 셸 명령은 .ax 보호 경로를 직접 쓴 명령과 같이 판정되어 거부될 수 있고, .ax로 cd한 뒤 읽기가 아닌 것을 실행하는 형태도 거부됩니다. 거부문이 안내하는 대로 명령에서 .ax 언급을 빼거나 명령을 나누세요. 주석, here-document 본문, 메시지 문자열 속의 경로는 명령 전체가 확실히 읽힐 때 세지 않습니다. (4) approve --grant·--deny·--ask·--withdraw는 id나 8자 이상의 고유 접두어만 받고 목록 번호는 거부합니다. (5) run start는 하네스 설정이 Holmes-Kit 패키지의 MCP 진입점과 PreToolUse·Stop 훅 스크립트를 실제로 실행할 때만 통과합니다. 이름만 holmes인 설정은 실패합니다. (6) 업그레이드 뒤 MCP 서버를 다시 시작하세요. (7) 봉인이 기록되기 전에 봉인한 명세는 후계의 근거가 되지 않으니, spec_unseal 뒤 spec_approve(사람의 승인)로 이행하세요. 후계와 스테이징의 근거는 신뢰된 원장 기록에서만 읽으므로, 폐기 이력도 그 기록이 있어야 인정됩니다.",
138
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) Under a full profile, a git push without --allow-push and an npm publish without --allow-publish are refused, and a grant does not lift that; help and dry-run forms pass, except a force push while the push flag is off. (2) git add -A, git add . and git commit -a that reach another replica's provenance ledger file (another machine, a linked worktree, a run) are a person's act. (3) A shell command that builds a path into .ax while it runs is judged like one that names a protected .ax path and can be refused, and so is a command that changes into .ax and runs something that is not a read; as the refusal says, take the .ax mention out of the command or split it. Comments, here-document bodies and message text do not count when the whole command is read with certainty. (4) approve --grant, --deny, --ask and --withdraw take an id or a unique id prefix of eight or more characters only; a list number is refused. (5) run start passes only when the harness configuration actually runs the Holmes-Kit package's MCP entry and its PreToolUse and Stop hook scripts; configuration that only names holmes fails. (6) Restart MCP servers after upgrading. (7) A specification sealed before seals were recorded is no basis for a successor; migrate it with spec_unseal, then spec_approve (a person's approval). A successor and a staging proof are read only from trusted ledger events, so a retirement counts only with such a record."
139
+ },
140
+ "limitations": {
141
+ "ko": "이 요약은 설치해 쓰는 프로젝트에 조용히 영향을 주는 변경만 고른 것입니다. 업그레이드 전에 CHANGELOG의 이 버전 절(Upgrading·Known limitations)을 읽으세요. (1) 훅은 같은 사용자 권한의 에이전트 셸에 대한 보안 경계가 아니며 위조 저항은 검증되지 않았습니다. (2) push·publish 플래그는 게이트가 읽는 명령 형태에만 적용되고, 러너·명령 치환·패키지 스크립트 안에서 실행되는 것은 읽지 못합니다. (3) full 프로필은 범위 밖의 일반 쓰기를 거부하지 않습니다(재귀 삭제는 거부). (4) full 프로필에서도 게이트가 인식하는 형태의 명세 스테이징은 사람의 승인을 묻습니다. 스테이징 게이트는 사고 방지 장치이며, 승인된 스테이징만 일어난다고 보장하지 않습니다. 다만 이 버전의 spec_approve는 명세 등급과 무관하게 곧바로 봉인하므로, 사람 승인이 필요한 봉인 계약 수정도 full 프로필이 봉인합니다. (5) 접두어 대조는 명령을 입력한 뒤에 접수된 요청을 보지 못합니다. (6) 홈 경로에 공백이나 비ASCII 문자(예: 한글 사용자 이름)가 있으면 세션 승인 폼이 열리지 않습니다.",
142
+ "en": "This summary picks only the changes that quietly affect a project using the package. Before upgrading, read this version's section of the CHANGELOG (Upgrading and Known limitations). (1) The hook is not a security boundary against the same user's agent shell, and its forgery resistance is not verified. (2) The push and publish flags apply to the command forms the gate reads; what a runner, a substitution or a package script runs inside is not read. (3) A full profile does not refuse a plain write outside its scope (a recursive delete is refused). (4) Even under a full profile, spec staging in a form the gate recognises asks for a person's approval; the staging gate prevents accidents and does not guarantee approval-only staging. But this version's spec_approve seals at once whatever the specification's grade, so a sealed-contract amendment that needs a person's approval is sealed by the full profile. (5) The prefix check does not see a request filed after the command was typed. (6) A home path holding a space or non-ASCII characters (such as a Korean user name) gives no in-session approval form."
143
+ }
144
+ }
145
+ ]
146
+ }