@holmes-lab/holmes-kit 0.35.24 → 0.35.25

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,71 @@ 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.35.25] - 2026-10-17
11
+
12
+ Upgrading:
13
+ - Where another holmes-kit copy sits in an ancestor `node_modules` of the workspace, approval hints now name the
14
+ running install's own path (`'<node>' '<…>/bin/holmes-kit.js' approve …`). Elsewhere they stay `npx holmes-kit approve
15
+ …`.
16
+ - doctor's new `npx resolution` row names such a copy.
17
+
18
+ ### Added
19
+
20
+ - **`holmes-kit scratch [--new <label>]`** (REQ-773, A-SPEC-773): a per-user Holmes scratch root,
21
+ `os.tmpdir()/holmes-scratch-<uid>`, mode 0700.
22
+ - On macOS and Linux, an agent in Claude Code, Codex or Antigravity can remove an existing subdirectory of it
23
+ without an operator act, using one plain `rm -r[f]` of absolute paths, at most 64 of them.
24
+ - The gate checks on each call that the root is still this user's own, not a link, with no group/other bits. It
25
+ judges each target by its real path.
26
+ - These keep today's refusal:
27
+ - the root itself, the rest of the temporary directory, links out of the root, `..` and globs;
28
+ - tracked source;
29
+ - any command that is not a single plain `rm`: pipes into `xargs`/`parallel`, aliases, and a link or move earlier
30
+ in the same command (adversarial review, round 1).
31
+ - On Windows the directory is made, but the gate does not relax.
32
+ - The refusal of an out-of-project recursive `rm` now names `holmes-kit scratch --new <label>`.
33
+ - Known limits:
34
+ - `mv` is not gated, so data moved into the root by an earlier command can then be removed. The same two steps
35
+ were already possible with `rm -r` without `-f`.
36
+ - The window between the gate's judgement and the command's execution is not closed.
37
+ - The Codex and Antigravity hook `TMPDIR` has not been measured live. Where it differs from the agent's shell, the
38
+ gate simply does not relax.
39
+ - Owner decision, 2026-10-17: agents could not clean up review probes and had to ask.
40
+
41
+ ### Fixed
42
+
43
+ - **Approval hints reach the install that issued them** (A-SPEC-770.3–770.6).
44
+ - The incident: under a home directory holding `~/node_modules/@holmes-lab/holmes-kit` 0.19.3, a 0.35.23 refusal's
45
+ own `npx holmes-kit approve --grant <id>` ran 0.19.3 and answered "no pending request matches".
46
+ - The hint now walks the ancestors of the workspace and of the home directory, as npx does. It looks for a
47
+ `node_modules/.bin/holmes-kit` file entry that belongs to another install. Shim files (npm on Windows, pnpm) are
48
+ identified through the package directory beside them.
49
+ - When it finds one, the hint names the running install's quoted absolute path. That form needs no network, no npm
50
+ cache and no published version. On Windows it is PowerShell syntax.
51
+ - The emitters are the refusals, the Stop block, the dialog notices, the approve screens, the governance-wiring
52
+ message, the decline reason and the stale-grant hint.
53
+ - A version-pinned `npx -p …@<version>` was tried and withdrawn before release (review round 1). On a cold cache it
54
+ was a 703 MB download behind a prompt, and it failed for an unpublished version.
55
+ - The hint also treats as a shadow a project whose own `package.json` declares a `holmes-kit` bin. npx runs that bin
56
+ first, so this covers a holmes-kit checkout or fork.
57
+ - doctor WARNs on such a copy and names it.
58
+ - Known limit: a workspace member under a root that declares the bin is not detected yet.
59
+ - **`holmes-kit approve --refusals --target <root>` runs** (A-SPEC-770.11). Every refusal outside the inbox prints
60
+ this command. It exited with "--refusals requires a value" because the count was mandatory. The count is now optional
61
+ and defaults to 20.
62
+ - **A Codex or Antigravity hook that inherited `CLAUDE_PROJECT_DIR` is no longer denied** (A-SPEC-751.7). Claude Code
63
+ passes the variable to every process it launches. Through the runtime dispatcher, a Codex session under one of them
64
+ had every tool call denied as "Conflicting runtime workspace hints". The variable is now a hint for the Claude harness
65
+ only.
66
+ - **The pre-edit evidence warning no longer says "no-analysis" when an analysis exists** (A-SPEC-278.4, A-SPEC-278.5).
67
+ - With no digest (every Edit or Write), an analysis persisted at this HEAD that did not predict the file was skipped.
68
+ The warning then claimed no analysis at all.
69
+ - It now gives that analysis's own verdict, `target-out-of-scope`, naming its digest. The remediation no longer asks
70
+ for a digest retry the session cannot make.
71
+ - **`runtime-binding status` reads the heartbeat where the kernel writes it** (A-SPEC-772.12).
72
+ - In a nested checkout without `.ax`, status said `unverified` while doctor said observed.
73
+ - `observedUnrouted` now names each unrouted event, PreToolUse first, as `observedOther` does.
74
+
10
75
  ## [0.35.24] - 2026-10-17
11
76
 
12
77
  Upgrading: run `holmes-kit runtime-binding setup` again with this build, so the deployed dispatcher passes the routing
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **442/444** source files (99.5%) trace to an approved spec · **819/882** approved A-SPECs (92.8%) are anchored from code.
13
- Measured at `20e40719f1f2` (specs `sha256:0263ca8394c8`) — reproduce with `holmes-kit attest`.
12
+ **444/446** source files (99.5%) trace to an approved spec · **835/900** approved A-SPECs (92.7%) are anchored from code.
13
+ Measured at `a36f0d1b502f` (specs `sha256:d41ff5dd491a`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,7 @@ Measured at `20e40719f1f2` (specs `sha256:0263ca8394c8`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **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.
26
27
  - **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.
27
28
  - **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.
28
29
  - **A refusal you cannot see in the inbox is still answerable from its own hint** *(new in 0.35.18)*: six repairs measured in a Codex X1 runtime session and a field report. Every refusal line written to the refusal log ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the inbox (`approve --list` / `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line spells the same command (the positional `approve <id>` the first repair wrote is refused by the CLI, so it was measured and rewritten). An autonomy refusal on a parent spec names the child rule that forces the human decision (`upstream-has-human-aspec: <id> — <rule>`). A runtime deadline refusal ends with the per-phase millisecond split, and the Stop hook prints how much of its 18 s budget it used once it passes half. `runtime-binding status` separates `drift` (operator-config / stale-workspace) from `conflicts` and reports whether the router is intact. The `--autonomy` usage, the `init` refusal and the interactive prompt now say the same thing.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- ba30504b-mvc1xwsd
1
+ e7fd416c-mvcf1aig
@@ -48,7 +48,7 @@ exports.decisionDetail = decisionDetail;
48
48
  exports.renderRefusals = renderRefusals;
49
49
  exports.renderNonTtyHint = renderNonTtyHint;
50
50
  exports.runInteractive = runInteractive;
51
- // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5
51
+ // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5, A-SPEC-770.3, A-SPEC-770.6
52
52
  // @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
53
53
  // surface the Hangul-absence guard reads.
54
54
  const execution_context_1 = require("../project/execution-context");
@@ -182,7 +182,7 @@ function grantRequest(root, id, opts) {
182
182
  // a subject keeps the default, because there the clock is all that stands between the decision and a changed act.
183
183
  const untilUsed = opts.ttlMinutes === undefined && typeof entry?.subject === 'string' && entry.subject !== '';
184
184
  if (!entry)
185
- return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.npxBin)()} holmes-kit approve --list` };
185
+ return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.holmesKitCommand)(root)} approve --list` };
186
186
  if (!recordIsSelfConsistent(entry))
187
187
  return { ok: false, reason: TAMPERED };
188
188
  // A "does this match what the operator saw" parameter was written here too and then removed: the
@@ -360,7 +360,7 @@ function outsideInboxFooter(outside, root) {
360
360
  const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
361
361
  // `◆` rather than the `◇` the spec sketched: §13 (approve-corpus) admits only the template's own glyphs on a decision
362
362
  // row, and U+25C7 is of ambiguous width while U+25C6 is already furniture of this screen.
363
- return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --refusals${target} · grant one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`;
363
+ return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --refusals${target} · grant one: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --grant <id>${target}`;
364
364
  }
365
365
  function renderPending(state, view, outside, root) {
366
366
  const withFooter = (lines) => {
@@ -500,7 +500,7 @@ function renderRefusals(refusals, limit = 20, root) {
500
500
  // @implements A-SPEC-770.1 — `--grant <id>`: the positional form this line named since 2026-09-06 is refused.
501
501
  // @implements A-SPEC-770.2 — and the workspace whose log this screen read, when the caller knows it.
502
502
  const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
503
- lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`);
503
+ lines.push('', `decide one: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --grant <id>${target}`);
504
504
  return lines.join('\n');
505
505
  }
506
506
  function renderNonTtyHint(state) {
@@ -255,6 +255,12 @@ export type CodexGateReading = {
255
255
  * beside a Codex-only report read as Codex's activation.
256
256
  */
257
257
  export declare function activationText(observed: string[], agent?: string): string;
258
+ /**
259
+ * @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
260
+ * target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
261
+ * 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
262
+ */
263
+ export declare function npxResolutionCheck(target: string, runningVersion: string): Check | null;
258
264
  export declare function hookObservationChecks(targetIn: string, now?: number, agent?: Agent): Check[];
259
265
  /**
260
266
  * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
@@ -54,6 +54,7 @@ exports.mcpProbeEnv = mcpProbeEnv;
54
54
  exports.pushGateCheck = pushGateCheck;
55
55
  exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
56
56
  exports.activationText = activationText;
57
+ exports.npxResolutionCheck = npxResolutionCheck;
57
58
  exports.hookObservationChecks = hookObservationChecks;
58
59
  exports.codexStopGateCheck = codexStopGateCheck;
59
60
  exports.ciMatrixCheck = ciMatrixCheck;
@@ -71,7 +72,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
71
72
  exports.semanticCoverageCheck = semanticCoverageCheck;
72
73
  exports.semanticTierVerdict = semanticTierVerdict;
73
74
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
74
- // @implements A-SPEC-751.4, A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
75
+ // @implements A-SPEC-751.4, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
75
76
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
76
77
  const doctor_guidance_1 = require("./doctor-guidance");
77
78
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -908,6 +909,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
908
909
  checks.push(...wiringVersionChecks(target, opts?.codexConfigPath, cli));
909
910
  }
910
911
  }
912
+ // @implements A-SPEC-770.3 — the copy the bare npx command would run from the target, when it is not this install.
913
+ {
914
+ const cli = (0, mcp_launcher_1.readPackageVersion)(packageRoot);
915
+ const row = cli ? npxResolutionCheck(target ?? process.cwd(), cli) : null;
916
+ if (row)
917
+ checks.push(row);
918
+ }
911
919
  // 7. Target wiring — do the configured commands point at THIS installed package and exist?
912
920
  if (target) {
913
921
  // @implements A-SPEC-190 §13 (round 11) — `init --settings project` wires `.claude/settings.json`,
@@ -2984,6 +2992,49 @@ function activationText(observed, agent) {
2984
2992
  return `live activation observed (${agent})`;
2985
2993
  return `live activation unverified for ${agent}${observed.length ? ` (observed: ${observed.join(', ')})` : ''}`;
2986
2994
  }
2995
+ /**
2996
+ * @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
2997
+ * target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
2998
+ * 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
2999
+ */
3000
+ function npxResolutionCheck(target, runningVersion) {
3001
+ // @implements A-SPEC-770.6 — what npx resolves: the first node_modules/.bin/holmes-kit link from the target up (round
3002
+ // 1: a pnpm link and an unscoped package were run by npx and missed here). The command is spelled via npxBin().
3003
+ const { shadowCopy, runningCli, powershellLiteral, posixLiteral, binEntryNames } = require('../project/npx-bin');
3004
+ const shadowed = `${(0, npx_bin_1.npxBin)()} holmes-kit`;
3005
+ const shadow = shadowCopy(target);
3006
+ if (shadow === null) {
3007
+ // @implements A-SPEC-770.7 — PASS only when npx would take a file entry here and it is this install; a dangling link
3008
+ // or a directory is skipped by npx, so it gives no row (round 2: a dangling link read as PASS).
3009
+ for (let dir = path.resolve(target);; dir = path.dirname(dir)) {
3010
+ // @implements A-SPEC-770.9 — the platform's entry names, as shadowCopy reads them (round 4: .cmd PASS on POSIX).
3011
+ if (binEntryNames().some((n) => { try {
3012
+ return fs.statSync(path.join(dir, 'node_modules', '.bin', n)).isFile();
3013
+ }
3014
+ catch {
3015
+ return false;
3016
+ } })) {
3017
+ return { name: 'npx resolution', level: 'PASS', detail: `${shadowed} from ${target} runs this install (${runningCli()})` };
3018
+ }
3019
+ if (path.dirname(dir) === dir)
3020
+ return null;
3021
+ }
3022
+ }
3023
+ // @implements A-SPEC-770.7 — the fix names the package directory itself, quoted for this platform, and never a
3024
+ // node_modules directory (round 2: a shim made it `rm -r <project>/node_modules`).
3025
+ const q = process.platform === 'win32' ? powershellLiteral : posixLiteral;
3026
+ const removable = shadow.packageDir !== null && path.basename(shadow.packageDir) !== 'node_modules';
3027
+ // @implements A-SPEC-770.10 — npx runs the project's OWN bin here (a holmes-kit checkout or fork): nothing to remove.
3028
+ if (path.basename(shadow.link) === 'package.json' && shadow.packageDir === null) {
3029
+ return { name: 'npx resolution', level: 'WARN',
3030
+ detail: `npx run here starts this project's own bin.holmes-kit (${shadow.version || 'unknown version'}), not this install (${runningVersion}) — expected in a holmes-kit checkout; approval hints name this install's own path` };
3031
+ }
3032
+ return { name: 'npx resolution', level: 'WARN',
3033
+ detail: `${shadowed} from ${target} or below runs ${shadow.link}${shadow.packageDir ? ` (${shadow.packageDir})` : ''} ${shadow.version || '(unknown version)'}, not this install (${runningVersion}); approval hints there name this install's own path so they reach it`,
3034
+ fix: removable
3035
+ ? `Remove that copy (rm -r ${q(shadow.packageDir)} and the link ${q(shadow.link)}) or update it to ${runningVersion}.`
3036
+ : `Update or remove the holmes-kit install that provides ${q(shadow.link)}.` };
3037
+ }
2987
3038
  /** @implements A-SPEC-772.11 — the workspace a target belongs to (a subdirectory reads its project's records). */
2988
3039
  function governedRootOf(target) {
2989
3040
  try {
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
- // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734, A-SPEC-751, A-SPEC-752, A-SPEC-772.4
40
+ // @implements A-SPEC-704, A-SPEC-773, A-SPEC-770.11,A-SPEC-709, A-SPEC-734,A-SPEC-751, A-SPEC-752, A-SPEC-772.4
41
41
  // @implements A-SPEC-549.2
42
42
  // @implements A-SPEC-591, A-SPEC-626
43
43
  const cli_execution_1 = require("./cli-execution");
@@ -85,6 +85,8 @@ const KNOWN_FLAGS = {
85
85
  doctor: ['help', 'target', 'json', 'agent', 'registry'],
86
86
  // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
87
87
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
88
+ // @implements A-SPEC-773 — the Holmes scratch root an agent may clean up on its own.
89
+ scratch: ['help', 'new'],
88
90
  skills: ['help', 'target'],
89
91
  ci: ['help', 'target', 'specs-dir', 'json'],
90
92
  serve: ['help', 'target', 'port'],
@@ -129,6 +131,8 @@ class UnknownFlagError extends Error {
129
131
  // A-SPEC-251.1 (round 26): `yes` — `upgrade --yes` was refused as "--yes requires a value", so the non-interactive
130
132
  // upgrade its own guidance names could not run (measured).
131
133
  const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy', 'yes']); // A-SPEC-650: --status
134
+ /** @implements A-SPEC-770.11 — value flags whose value may be omitted; the handler supplies the default. */
135
+ const OPTIONAL_VALUE_FLAGS = new Set(['refusals']);
132
136
  /** @implements A-SPEC-771.1 — value flags that may be given more than once. */
133
137
  const REPEATABLE_FLAGS = new Set(['limit']);
134
138
  function parseFlags(argv, known) {
@@ -273,6 +277,9 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
273
277
  --target <dir> also verify that target's wiring points at this install
274
278
  --json machine-readable output
275
279
 
280
+ holmes-kit scratch [--new <label>]
281
+ print the Holmes scratch root, or make a fresh directory under it; the gate lets
282
+ an agent rm -rf such a directory by its absolute path in every harness
276
283
  holmes-kit attest [flags] say how many source files trace to an APPROVED spec (a statement, not a gate)
277
284
  --target <dir> the project to measure (default: current directory)
278
285
  --exclude <a,b> path prefixes that are not this project's source (vendored trees); echoed in the output
@@ -322,6 +329,10 @@ async function main(argv) {
322
329
  for (const [key, v] of Object.entries(flags)) {
323
330
  // `--target` (true) AND `--target=` ('') both point at nothing — an empty inline value
324
331
  // resolved to CWD and wired it silently (round-5 HIGH).
332
+ // @implements A-SPEC-770.11 — an optional-value flag defaults where it is read (`--refusals` → 20 rows): the
333
+ // `approve --refusals --target <root>` every refusal prints exited 2 here (measured 2026-10-17).
334
+ if (OPTIONAL_VALUE_FLAGS.has(key) && v === true)
335
+ continue;
325
336
  if (!BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
326
337
  process.stderr.write(`--${key} requires a value\n\n${USAGE}`);
327
338
  return 2;
@@ -466,6 +477,11 @@ async function main(argv) {
466
477
  }
467
478
  // @implements A-SPEC-702 — reads one scan and the spec store; writes only the badge and the README's
468
479
  // marker region, and only when asked. The numbers never change the exit code.
480
+ // @implements A-SPEC-773
481
+ if (cmd === 'scratch') {
482
+ const { runScratch } = require('./scratch');
483
+ return runScratch({ label: typeof flags.new === 'string' ? flags.new : undefined }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
484
+ }
469
485
  if (cmd === 'attest') {
470
486
  const { runAttest } = require('./attest');
471
487
  const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runtimePlanDigest = runtimePlanDigest;
37
37
  exports.applyApprovedRuntimePlan = applyApprovedRuntimePlan;
38
- // @implements A-SPEC-752, A-SPEC-752.14
38
+ // @implements A-SPEC-752, A-SPEC-752.14, A-SPEC-770.3, A-SPEC-770.6
39
39
  const path = __importStar(require("node:path"));
40
+ const npx_bin_1 = require("../project/npx-bin");
40
41
  const node_crypto_1 = require("node:crypto");
41
42
  const risk_gate_1 = require("../guardrail/risk-gate");
42
43
  const approval_grants_1 = require("../governance/approval-grants");
@@ -82,7 +83,7 @@ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply, appr
82
83
  const id = (0, approval_queue_1.approvalRequestId)(action.kind, target);
83
84
  if (result.reason !== 'written' && result.reason !== 'duplicate')
84
85
  throw new Error(`Cannot queue governance-wiring approval: ${result.reason}; nothing installed`);
85
- throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In ${approvalRoot === root ? 'this workspace' : `the workspace ${approvalRoot}`} run holmes-kit approve --list, then holmes-kit approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
86
+ throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In ${approvalRoot === root ? 'this workspace' : `the workspace ${approvalRoot}`} run ${(0, npx_bin_1.holmesKitCommand)(approvalRoot)} approve --list, then ${(0, npx_bin_1.holmesKitCommand)(approvalRoot)} approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
86
87
  };
87
88
  check();
88
89
  if (!resolve())
@@ -43,7 +43,7 @@ exports.codexDuplicateRoutes = codexDuplicateRoutes;
43
43
  exports.runtimeBindingStatus = runtimeBindingStatus;
44
44
  exports.runRuntimeBinding = runRuntimeBinding;
45
45
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
46
- // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
46
+ // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-772.12
47
47
  const fs = __importStar(require("node:fs"));
48
48
  const os = __importStar(require("node:os"));
49
49
  const path = __importStar(require("node:path"));
@@ -57,6 +57,7 @@ const codex_toml_1 = require("./codex-toml");
57
57
  const codex_hooks_1 = require("./codex-hooks");
58
58
  const agents_1 = require("./agents");
59
59
  const heartbeat_1 = require("../hooks/heartbeat");
60
+ const root_1 = require("../project/root");
60
61
  const defaultRuntimeRegistry = () => path.join(os.homedir(), '.holmes', 'runtime', 'bindings.json');
61
62
  exports.defaultRuntimeRegistry = defaultRuntimeRegistry;
62
63
  const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
@@ -370,14 +371,25 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
370
371
  // @implements A-SPEC-769.8 — reported beside the receipt verdicts; it changes neither `conflicts` nor `router`.
371
372
  const duplicateRoutes = codexDuplicateRoutes(opts?.codexHome ?? path.join(os.homedir(), '.codex'), workspace);
372
373
  // @implements A-SPEC-772.1 — a hook observed running in the selected workspace is reported, per harness.
373
- const beats = (0, heartbeat_1.readHookHeartbeats)(selection.workspaceRoot);
374
+ // @implements A-SPEC-772.12 — read where the kernel writes: the directory holding `.ax`. The selection stops at a
375
+ // nested `.git` (round 8, L1: doctor said observed while status said unverified for the same run).
376
+ const governedRoot = (() => {
377
+ try {
378
+ const r = (0, root_1.resolveProjectRoot)(selection.workspaceRoot, { includeGit: false }).root;
379
+ return fs.existsSync(path.join(r, '.ax')) ? r : selection.workspaceRoot;
380
+ }
381
+ catch {
382
+ return selection.workspaceRoot;
383
+ }
384
+ })();
385
+ const beats = (0, heartbeat_1.readHookHeartbeats)(governedRoot);
374
386
  const observed = {};
375
387
  const observedUnrouted = {};
376
388
  const observedOther = {};
377
389
  const wiringEnv = { ...process.env, ...(opts?.codexHome ? { CODEX_HOME: opts.codexHome } : {}) };
378
390
  const now = Date.now();
379
391
  for (const harness of agents_1.AGENTS) {
380
- const wiring = (0, heartbeat_1.hookWiringFiles)(selection.workspaceRoot, harness, wiringEnv);
392
+ const wiring = (0, heartbeat_1.hookWiringFiles)(governedRoot, harness, wiringEnv);
381
393
  // @implements A-SPEC-772.7 — each event on its own: a routed PreToolUse is not hidden by a later Stop of another mode.
382
394
  for (const event of ['pre-tool-use', 'stop']) {
383
395
  const beat = beats[harness][event];
@@ -395,8 +407,12 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
395
407
  if (event === 'pre-tool-use' && o.mode === selection.mode && o.buildId === selection.buildId)
396
408
  latest(observed);
397
409
  // @implements A-SPEC-772.7 — a run without routing evidence is reported apart from activation.
398
- else if (o.mode === 'unknown')
399
- latest(observedUnrouted);
410
+ // @implements A-SPEC-772.12 — each such event by name, PreToolUse first (round 8, L2: the latest time alone hid
411
+ // whether the gate itself ran unrouted).
412
+ else if (o.mode === 'unknown') {
413
+ const entry = `${event} at ${o.at} (build ${o.buildId})`;
414
+ observedUnrouted[harness] = observedUnrouted[harness] ? `${observedUnrouted[harness]}; ${entry}` : entry;
415
+ }
400
416
  // @implements A-SPEC-772.10 — every other observation (a Stop of this selection, another build or mode) is named.
401
417
  // @implements A-SPEC-772.11 — each uncounted event, PreToolUse first (events loop in that order); the latest
402
418
  // alone hid an other-build PreToolUse behind the turn-end Stop (round 7).
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
3
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
4
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
5
+ */
6
+ export declare function runScratch(opts: {
7
+ label?: string;
8
+ tmpdir?: string;
9
+ }, io: {
10
+ stdout: (t: string) => void;
11
+ stderr: (t: string) => void;
12
+ }): number;
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.runScratch = runScratch;
4
+ // @implements A-SPEC-773
5
+ const scratch_root_1 = require("../project/scratch-root");
6
+ /**
7
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
8
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
9
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
10
+ */
11
+ function runScratch(opts, io) {
12
+ try {
13
+ io.stdout(`${opts.label === undefined ? (0, scratch_root_1.ensureScratchRoot)(opts.tmpdir) : (0, scratch_root_1.newScratchDir)(opts.label, opts.tmpdir)}\n`);
14
+ return 0;
15
+ }
16
+ catch (e) {
17
+ io.stderr(`holmes-kit scratch: ${e.message}\n`);
18
+ return 1;
19
+ }
20
+ }
@@ -49,7 +49,7 @@ exports.refusalsOutsideInbox = refusalsOutsideInbox;
49
49
  exports.grantableRequests = grantableRequests;
50
50
  exports.openOccurrences = openOccurrences;
51
51
  exports.asPendingRequest = asPendingRequest;
52
- // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754
52
+ // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6
53
53
  const execution_context_1 = require("../project/execution-context");
54
54
  const root_1 = require("../project/root");
55
55
  const node_crypto_1 = require("node:crypto");
@@ -98,7 +98,8 @@ exports.DECISION_KINDS = new Set([
98
98
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
99
99
  */
100
100
  function pendingRequestLine(id, kind, root) {
101
- const command = `${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
101
+ // @implements A-SPEC-770.3 — the version that issued the hint, past any older copy the bare npx command resolves first.
102
+ const command = `${(0, npx_bin_1.holmesKitCommand)(root)} approve`; // A-SPEC-770.6 — the root the request is stored in
102
103
  // @implements A-SPEC-770.2 — the request lives in the refusal log / queue of the workspace whose hook refused, not in
103
104
  // the shell's cwd (measured 2026-10-12: a command run under a worktree filed its request in the development root;
104
105
  // 2026-10-13, Codex X1: the hint carried no `--target` at all). With a root, every command names it; a root with
@@ -527,7 +528,7 @@ function queueHint(root, req, opts) {
527
528
  + `\n운영자 검토: ${opts.reviewCommand}`;
528
529
  }
529
530
  return (0, screen_safe_1.wrapColumns)(question
530
- + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 내립니다.`, 76, ' \u2502 ');
531
+ + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.holmesKitCommand)(root)} approve 에서 내립니다.`, 76, ' \u2502 ');
531
532
  }
532
533
  const decided = state.decisions[id];
533
534
  const denialLine = decided?.event === 'denied'
@@ -39,6 +39,8 @@ export interface EditEvidenceInput {
39
39
  id: string;
40
40
  file: string;
41
41
  }>;
42
+ /** @implements A-SPEC-278.4 — the digest the artifact is stored under, so a verdict can name the analysis it read. */
43
+ artifactDigest?: string | null;
42
44
  }
43
45
  export interface EditEvidenceVerdict {
44
46
  decision: EditDecision;
@@ -37,7 +37,7 @@ exports.isLowRiskTarget = isLowRiskTarget;
37
37
  exports.evaluateEditEvidence = evaluateEditEvidence;
38
38
  exports.preEditEvidenceDecision = preEditEvidenceDecision;
39
39
  exports.loadEditEvidence = loadEditEvidence;
40
- // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3
40
+ // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6
41
41
  // @implements A-SPEC-278
42
42
  // @implements A-SPEC-277
43
43
  // @implements A-SPEC-276
@@ -69,7 +69,8 @@ function isLowRiskTarget(target) {
69
69
  return true;
70
70
  }
71
71
  const REMEDIATION = {
72
- 'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change and retry with the digest it returns.',
72
+ // @implements A-SPEC-278.4 — an Edit or Write call carries no digest, so "retry with the digest" could not be followed.
73
+ 'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change; the gate finds an analysis persisted at this HEAD by itself (impact_gate_check also accepts its digest).',
73
74
  'basis-drift': 'HEAD moved after the analysis was taken — re-run maintenance_analyze so the evidence is computed on the current commit.',
74
75
  // A separate code because it needs a separate sentence: dogfooding 2026-08-28 showed a file-drift
75
76
  // refusal explaining itself as "HEAD moved", which was simply false. Same lesson as A-SPEC-269.
@@ -156,7 +157,7 @@ function evaluateEditEvidence(inputArgs) {
156
157
  code: 'target-out-of-scope',
157
158
  detail: affectedOnly
158
159
  ? `${target} appears only as an impacted file, which is not the same as having been analysed as an edit candidate.`
159
- : `${target} is not among the files this analysis predicted.`,
160
+ : `${target} is not among the files this analysis${inputArgs.artifactDigest ? ` (${inputArgs.artifactDigest})` : ''} predicted.`,
160
161
  });
161
162
  escalate('widen');
162
163
  }
@@ -275,6 +276,11 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
275
276
  }
276
277
  const newer = (a, b) => b === null || String(a.recordedAt ?? '') > String(b.recordedAt ?? '');
277
278
  let best = null;
279
+ let bestDigest = '';
280
+ // @implements A-SPEC-278.4 — the newest analysis at HEAD whether or not it covers the target: when nothing covers it,
281
+ // this analysis's own verdict (target-out-of-scope) is the truth, not "no analysis" (measured 2026-10-17).
282
+ let atHead = null;
283
+ let atHeadDigest = '';
278
284
  const older = [];
279
285
  let targetIsNew;
280
286
  const isNew = () => (targetIsNew ??= !gitOk(projectRoot, ['cat-file', '-e', `${currentHead}:${target}`]));
@@ -288,22 +294,32 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
288
294
  }
289
295
  if (!Array.isArray(candidate?.predicted?.files) || typeof candidate?.graphBasis?.head !== 'string')
290
296
  continue;
297
+ // @implements A-SPEC-278.6 — an older-shape or corrupt artifact made the verdict throw for every target (round 1).
298
+ if (!Array.isArray(candidate?.uncertainty?.impactedFiles) || !Array.isArray(candidate?.uncertainty?.unknowns))
299
+ continue;
300
+ const digest = `sha256:${path.basename(file, '.json')}`;
291
301
  if (candidate.graphBasis.head !== currentHead) {
292
- older.push(candidate);
302
+ older.push({ artifact: candidate, digest });
293
303
  continue;
294
304
  }
305
+ if (newer(candidate, atHead)) {
306
+ atHead = candidate;
307
+ atHeadDigest = digest;
308
+ }
295
309
  if (!coversTarget(candidate, target, isNew))
296
310
  continue;
297
- if (newer(candidate, best))
311
+ if (newer(candidate, best)) {
298
312
  best = candidate;
313
+ bestDigest = digest;
314
+ }
299
315
  }
300
316
  if (best)
301
- return best;
317
+ return { artifact: best, digest: bestDigest };
302
318
  // @implements A-SPEC-278.2 (rule 2) — an analysis at an ancestor ≤ 20 commits back still describes this tree when every
303
319
  // file changed since it was predicted or named by its request (the RED commit adds only the request-named test). The
304
320
  // copy carries the current head so the basis is not reported as drifted; the target's own digest still is.
305
321
  const lineage = new Map();
306
- for (const candidate of older.sort((a, b) => String(b.recordedAt ?? '').localeCompare(String(a.recordedAt ?? '')))) {
322
+ for (const { artifact: candidate, digest } of older.sort((a, b) => String(b.artifact.recordedAt ?? '').localeCompare(String(a.artifact.recordedAt ?? '')))) {
307
323
  const a = candidate.graphBasis.head;
308
324
  if (!coversTarget(candidate, target, isNew))
309
325
  continue;
@@ -313,9 +329,12 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
313
329
  lineage.set(a, unchangedOutside(projectRoot, a, currentHead, candidate));
314
330
  }
315
331
  if (lineage.get(a))
316
- return { ...candidate, graphBasis: { ...candidate.graphBasis, head: currentHead } };
332
+ return { artifact: { ...candidate, graphBasis: { ...candidate.graphBasis, head: currentHead } }, digest };
317
333
  }
318
- return null;
334
+ // @implements A-SPEC-278.4 — this replaces A-SPEC-278.1 #3 for an analysis AT HEAD that does not name the target.
335
+ // @implements A-SPEC-278.6 — not for a low-risk target: its exemption holds only with no artifact, and an unrelated
336
+ // analysis made block mode deny package.json (round 1).
337
+ return atHead && !isLowRiskTarget(target) ? { artifact: atHead, digest: atHeadDigest } : null;
319
338
  }
320
339
  /** @implements A-SPEC-278.2 — distinct ancestor heads examined per judgement (each costs three bounded git calls). */
321
340
  const LINEAGE_HEADS_MAX = 8;
@@ -387,12 +406,14 @@ function gitText(cwd, args) {
387
406
  function loadEditEvidence(projectRoot, target, digest, currentHead) {
388
407
  const rel = target.replace(/\\/g, '/');
389
408
  let artifact = null;
409
+ let artifactDigest = null;
390
410
  if (digest) {
391
411
  const bare = digest.startsWith('sha256:') ? digest.slice(7) : digest;
392
412
  if (/^[a-f0-9]{64}$/.test(bare)) {
393
413
  const file = path.join(projectRoot, '.ax', 'evidence', 'maintenance', `${bare}.json`);
394
414
  try {
395
415
  artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
416
+ artifactDigest = `sha256:${bare}`;
396
417
  }
397
418
  catch {
398
419
  artifact = null;
@@ -400,7 +421,9 @@ function loadEditEvidence(projectRoot, target, digest, currentHead) {
400
421
  }
401
422
  }
402
423
  else {
403
- artifact = newestPersistedAnalysis(projectRoot, rel, currentHead);
424
+ const found = newestPersistedAnalysis(projectRoot, rel, currentHead);
425
+ artifact = found?.artifact ?? null;
426
+ artifactDigest = found?.digest ?? null;
404
427
  }
405
428
  let currentTargetDigest = null;
406
429
  try {
@@ -412,5 +435,5 @@ function loadEditEvidence(projectRoot, target, digest, currentHead) {
412
435
  catch {
413
436
  currentTargetDigest = null;
414
437
  }
415
- return { target: rel, artifact, currentHead, currentTargetDigest };
438
+ return { target: rel, artifact, currentHead, currentTargetDigest, artifactDigest };
416
439
  }
@@ -44,7 +44,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
44
  exports.classifySecret = classifySecret;
45
45
  exports.classifyBlastRadius = classifyBlastRadius;
46
46
  exports.assessRisk = assessRisk;
47
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
47
+ // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
50
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -193,6 +193,14 @@ function isCatastrophicRmFloor(raw) {
193
193
  function rmTargetSafety(raw, sig) {
194
194
  if (isCatastrophicRmFloor(raw))
195
195
  return 'dangerous';
196
+ // @implements A-SPEC-773.1 — tracked source is dangerous even under the scratch root (round 1: a repository inside
197
+ // the root, cwd in it, `rm -rf src` was let through).
198
+ if (sig?.tracked)
199
+ return 'dangerous';
200
+ // @implements A-SPEC-773 — a subdirectory of the trusted Holmes scratch root is the agent's own temporary work
201
+ // (owner decision 2026-10-17). After the floor and the tracked veto, before the out-of-project veto.
202
+ if (sig?.scratch)
203
+ return 'safe';
196
204
  if (sig) {
197
205
  if (sig.tracked)
198
206
  return 'dangerous'; // git-tracked source under VCS
@@ -246,7 +254,11 @@ function rmDangerReason(cmd, signals) {
246
254
  const targets = rmTargets(seg);
247
255
  const safeties = targets.map((t) => rmTargetSafety(t, signals?.[t]));
248
256
  if (safeties.some((s) => s === 'dangerous')) {
249
- return 'recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction';
257
+ // @implements A-SPEC-773.2 — an absolute target is where an agent's temporary work usually is: name the place
258
+ // whose directories it may remove (round 1, quality: nothing told an agent the scratch root exists).
259
+ const hint = targets.some((t) => t.replace(/^["']/, '').startsWith('/'))
260
+ ? '; agent temporary work belongs under `holmes-kit scratch --new <label>` (POSIX), whose directories an agent may remove' : '';
261
+ return `recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction${hint}`;
250
262
  }
251
263
  if (targets.length > 0 && safeties.every((s) => s === 'safe'))
252
264
  continue; // all proven regenerable
@@ -10,6 +10,7 @@ export interface RmSignal {
10
10
  gitIgnored?: boolean;
11
11
  tracked?: boolean;
12
12
  inProject?: boolean;
13
+ scratch?: boolean;
13
14
  }
14
15
  export interface RiskAction {
15
16
  kind: string;