@holmes-lab/holmes-kit 0.35.24 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +34 -4
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -0,0 +1,24 @@
1
+ /**
2
+ * @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
3
+ * pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
4
+ * `[holmes-refusal] {json}` appended to every PreToolUse deny carries the same refusal as a stable code. Pure: no I/O.
5
+ */
6
+ export type RefusalClass = 'retryable' | 'needs_hitl' | 'permanent';
7
+ export interface RefusalCode {
8
+ code: string;
9
+ class: RefusalClass;
10
+ remediation: string[];
11
+ }
12
+ export declare const REFUSAL_LINE_PREFIX = "[holmes-refusal] ";
13
+ interface Row {
14
+ code: string;
15
+ class: RefusalClass;
16
+ remediation: string[];
17
+ test: RegExp;
18
+ }
19
+ export declare const REFUSAL_CODES: readonly Row[];
20
+ export declare function refusalCode(reason: string): RefusalCode;
21
+ export declare function refusalLine(reason: string): string;
22
+ /** The deny reason with its refusal line appended once. */
23
+ export declare function withRefusalLine(reason: string | undefined): string;
24
+ export {};
@@ -0,0 +1,140 @@
1
+ "use strict";
2
+ // @implements A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4
3
+ /**
4
+ * @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
5
+ * pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
6
+ * `[holmes-refusal] {json}` appended to every PreToolUse deny carries the same refusal as a stable code. Pure: no I/O.
7
+ */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.REFUSAL_CODES = exports.REFUSAL_LINE_PREFIX = void 0;
10
+ exports.refusalCode = refusalCode;
11
+ exports.refusalLine = refusalLine;
12
+ exports.withRefusalLine = withRefusalLine;
13
+ exports.REFUSAL_LINE_PREFIX = '[holmes-refusal] ';
14
+ // First match wins. Patterns name the refusal's own words; a new refusal that none of them names fails the census in
15
+ // refusal-codes.test.ts.
16
+ exports.REFUSAL_CODES = [
17
+ {
18
+ // @implements A-SPEC-779 — a run waiting for the operator's decision: retry after it, never around it.
19
+ code: 'run.awaiting-approval', class: 'retryable',
20
+ remediation: ['wait: the operator decides the request in a terminal', 'retry after the decision; do not work around it'],
21
+ test: /this run is awaiting approval/i,
22
+ },
23
+ {
24
+ // @implements A-SPEC-778 — first: a stopped run's refusal names the code that stopped it.
25
+ code: 'run.stopped', class: 'needs_hitl',
26
+ remediation: ['stop working in this run', 'the operator ends it with holmes-kit run stop and starts a new run'],
27
+ test: /this run stopped|this run is now stopped|this run stalled|was not decided within|the Holmes install changed since run start/i, // A-SPEC-778.1/778.2: stalled
28
+ },
29
+ {
30
+ code: 'gate.unjudgeable', class: 'retryable',
31
+ remediation: ['split the command or edit into smaller parts', 'retry; if it repeats, ask the operator'],
32
+ // A-SPEC-790.3: a PowerShell command the translator cannot read is retried in plainer parts.
33
+ test: /too large to judge|internal error|deadline|timed out|risk classification failed|PreToolUse Hook\] Error|result of this write to|a shell command (?:of|with more than)|a PowerShell command that cannot be judged/i,
34
+ },
35
+ {
36
+ code: 'launch.refused', class: 'needs_hitl',
37
+ remediation: ['do not launch the agent or server from this session', 'ask the operator to run it from their own terminal'],
38
+ test: /launches an agent CLI|agent this command launches|starts the Holmes MCP server|runtime-binding setup/i,
39
+ },
40
+ {
41
+ code: 'secret.access', class: 'needs_hitl',
42
+ remediation: ['do not read the environment, credentials or authority configuration', 'ask the operator if the access is needed'],
43
+ test: /process environment|credential|authority or semantic-egress/i,
44
+ },
45
+ {
46
+ code: 'role.refused', class: 'needs_hitl',
47
+ remediation: ['the session role does not permit this action', 'ask the operator to assign a role or approve a role-override'],
48
+ test: /role policy|역할|may not act in stage/i, // A-SPEC-774.19 — the role's stages
49
+ },
50
+ {
51
+ code: 'spec.protected', class: 'needs_hitl',
52
+ remediation: ['seal through spec_approve, never by editing status', 'an approved spec changes only after spec_unseal by the operator'],
53
+ test: /Self-Approval|Approved Specification Modification|blast-radius/i,
54
+ },
55
+ {
56
+ // @implements A-SPEC-779.1 — a grant refused because it is not the operator's, or a run may await it.
57
+ code: 'grant.operator-only', class: 'needs_hitl',
58
+ remediation: ['the operator grants the request from their own terminal'],
59
+ test: /a grant is the operator's|is awaited by run|cannot tell whether a run awaits/i,
60
+ },
61
+ {
62
+ // @implements A-SPEC-476.4 — a run cannot change an owner cap in ax.config.json (A-SPEC-476.3).
63
+ code: 'cap.run-fixed', class: 'permanent',
64
+ remediation: ['leave ax.config.json as it is in the run', 'the owner changes a cap outside a run'],
65
+ test: /a run cannot change a project cap/i,
66
+ },
67
+ {
68
+ code: 'approval.required', class: 'needs_hitl',
69
+ remediation: ['the act needs an operator approval', 'run the approve command the refusal names, or ask the operator'],
70
+ // @implements A-SPEC-476.4 — and raising an owner cap, or a shell write over one (A-SPEC-476.3).
71
+ test: /hard-hitl|Integrity\]|Governance Path Destruction|requires operator|raises or removes a project cap|sets a project cap/i,
72
+ },
73
+ {
74
+ code: 'governance.path', class: 'needs_hitl',
75
+ remediation: ['governance files change only through the Holmes tools', 'ask the operator if a direct change is needed'],
76
+ test: /\.ax\/|governance (?:store|ledger)/i,
77
+ },
78
+ {
79
+ code: 'scope.outside', class: 'permanent',
80
+ remediation: ["extend the anchored spec's Files to Touch first", 'or anchor the file to the spec whose scope covers it'],
81
+ test: /Files to Touch|refused admitting|self-selection/i,
82
+ },
83
+ {
84
+ // @implements A-SPEC-781.1 — the run's stage does not allow this kind of write.
85
+ code: 'stage.refused', class: 'permanent',
86
+ remediation: ['do the work the current stage allows', 'the orchestrator moves the run to the stage that allows it'],
87
+ test: /the run is in stage/i,
88
+ },
89
+ {
90
+ code: 'spec.not-approved', class: 'permanent',
91
+ remediation: ['create and approve the REQ -> H-SPEC -> A-SPEC -> T-SPEC chain', 'call spec_next for the next step'],
92
+ test: /not approved|Gate Refusal\] Target specification|Missing Specification Anchor|approved A-SPEC|approved T-SPEC|no T-SPEC/i,
93
+ },
94
+ {
95
+ code: 'architecture.violation', class: 'permanent',
96
+ remediation: ['change the code so it no longer has the shape the C-SPEC forbids'],
97
+ test: /structural-constraint|C-SPEC forbids/i,
98
+ },
99
+ {
100
+ code: 'constitution.debt', class: 'permanent',
101
+ remediation: ['settle the outstanding constitution debt first'],
102
+ test: /constitution-debt/i,
103
+ },
104
+ {
105
+ code: 'patch.unreadable', class: 'permanent',
106
+ remediation: ['write a patch that applies to the file as it stands, with at least one + or - line', 'or use the Edit tool'],
107
+ test: /the patch (?:does not apply|to\b)|patch tool or a patch marker/i,
108
+ },
109
+ {
110
+ code: 'shell.code-write', class: 'permanent',
111
+ remediation: ['write project code through the Edit or Write tool, not the shell'],
112
+ test: /shell write to a project code file/i,
113
+ },
114
+ {
115
+ code: 'target.unresolvable', class: 'permanent',
116
+ remediation: ['name the target by a readable absolute or project-relative path'],
117
+ test: /cannot read|NUL byte|\(UNC\)|cannot be located|cannot be resolved/i,
118
+ },
119
+ ];
120
+ const UNCLASSIFIED = {
121
+ code: 'gate.unclassified', class: 'needs_hitl', remediation: ['read the refusal; ask the operator if unsure'],
122
+ };
123
+ function refusalCode(reason) {
124
+ for (const r of exports.REFUSAL_CODES) {
125
+ if (r.test.test(reason))
126
+ return { code: r.code, class: r.class, remediation: [...r.remediation] };
127
+ }
128
+ return { ...UNCLASSIFIED, remediation: [...UNCLASSIFIED.remediation] };
129
+ }
130
+ function refusalLine(reason) {
131
+ return exports.REFUSAL_LINE_PREFIX + JSON.stringify(refusalCode(reason));
132
+ }
133
+ /** The deny reason with its refusal line appended once. */
134
+ function withRefusalLine(reason) {
135
+ const text = reason ?? '';
136
+ const last = text.split('\n').pop() ?? '';
137
+ if (last.startsWith(exports.REFUSAL_LINE_PREFIX))
138
+ return text;
139
+ return text === '' ? refusalLine(text) : `${text}\n${refusalLine(text)}`;
140
+ }
@@ -16,6 +16,23 @@ export declare function rmCommandTargets(cmd: string): string[];
16
16
  export declare function normalizeWindowsPathSpellings(cmd: string): string;
17
17
  export declare function scopeAxToProject(cmd: string, projectRoot?: string): string;
18
18
  export declare function normalizeCommandPaths(cmd: string, followCd?: boolean): string;
19
+ /**
20
+ * @implements A-SPEC-747.3 — a verb counts only as a shell word: a word whose last path segment is the verb (`cp`,
21
+ * `/bin/cp`, `\cp`, `"cp"`, `x;cp`, `$(cp`, `cp${IFS}`), never one inside an option or a longer name (`grep -ln`,
22
+ * `java -cp`, `a.ln`, `bin/cp-helper`, `run-install-change.test.ts`). It is used only for PLAIN text (see
23
+ * `plainShellText`); every other command keeps the `\b…\b` test, which the 747.1 review showed is the only one a
24
+ * field-splitting shell cannot get around.
25
+ */
26
+ export declare function verbWordRe(alt: string, flags?: string): RegExp;
27
+ export declare function plainShellText(cmd: string): boolean;
28
+ /**
29
+ * Split a command into the clauses that run separately.
30
+ *
31
+ * @implements A-SPEC-226
32
+ * One clause being a write makes the whole command a write: judging only the first word lets a write
33
+ * hide behind a pipe (`cat SPEC | tee OTHER`).
34
+ */
35
+ export declare function splitShellClauses(cmd: string): string[];
19
36
  /**
20
37
  * @implements A-SPEC-728.2 — the classifier's own read judgement of a whole shell text, loops included, for the identity
21
38
  * layer: a `for` loop whose body only reads its variable's files names no mutation target with its word list.
@@ -37,6 +37,9 @@ exports.rmCommandTargets = rmCommandTargets;
37
37
  exports.normalizeWindowsPathSpellings = normalizeWindowsPathSpellings;
38
38
  exports.scopeAxToProject = scopeAxToProject;
39
39
  exports.normalizeCommandPaths = normalizeCommandPaths;
40
+ exports.verbWordRe = verbWordRe;
41
+ exports.plainShellText = plainShellText;
42
+ exports.splitShellClauses = splitShellClauses;
40
43
  exports.shellTextOnlyReads = shellTextOnlyReads;
41
44
  exports.stripCommitMessages = stripCommitMessages;
42
45
  exports.classifyReversibility = classifyReversibility;
@@ -44,7 +47,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
47
  exports.classifySecret = classifySecret;
45
48
  exports.classifyBlastRadius = classifyBlastRadius;
46
49
  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
50
+ // @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, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3
48
51
  const fs = __importStar(require("node:fs"));
49
52
  const path = __importStar(require("node:path"));
50
53
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -193,6 +196,14 @@ function isCatastrophicRmFloor(raw) {
193
196
  function rmTargetSafety(raw, sig) {
194
197
  if (isCatastrophicRmFloor(raw))
195
198
  return 'dangerous';
199
+ // @implements A-SPEC-773.1 — tracked source is dangerous even under the scratch root (round 1: a repository inside
200
+ // the root, cwd in it, `rm -rf src` was let through).
201
+ if (sig?.tracked)
202
+ return 'dangerous';
203
+ // @implements A-SPEC-773 — a subdirectory of the trusted Holmes scratch root is the agent's own temporary work
204
+ // (owner decision 2026-10-17). After the floor and the tracked veto, before the out-of-project veto.
205
+ if (sig?.scratch)
206
+ return 'safe';
196
207
  if (sig) {
197
208
  if (sig.tracked)
198
209
  return 'dangerous'; // git-tracked source under VCS
@@ -246,7 +257,11 @@ function rmDangerReason(cmd, signals) {
246
257
  const targets = rmTargets(seg);
247
258
  const safeties = targets.map((t) => rmTargetSafety(t, signals?.[t]));
248
259
  if (safeties.some((s) => s === 'dangerous')) {
249
- return 'recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction';
260
+ // @implements A-SPEC-773.2 — an absolute target is where an agent's temporary work usually is: name the place
261
+ // whose directories it may remove (round 1, quality: nothing told an agent the scratch root exists).
262
+ const hint = targets.some((t) => t.replace(/^["']/, '').startsWith('/'))
263
+ ? '; agent temporary work belongs under `holmes-kit scratch --new <label>` (POSIX), whose directories an agent may remove' : '';
264
+ return `recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction${hint}`;
250
265
  }
251
266
  if (targets.length > 0 && safeties.every((s) => s === 'safe'))
252
267
  continue; // all proven regenerable
@@ -417,6 +432,12 @@ function namesProtectedAx(text) {
417
432
  function prefixBareRelative(text, dir) {
418
433
  return text.replace(/(^|[\s>|])(?![-/~'"])([\w@.][\w@./-]*)/g, (full, pre, p) => /^[A-Za-z0-9_.@-]+$/.test(p) || p.includes('/') ? `${pre}${dir}/${p}` : full);
419
434
  }
435
+ /**
436
+ * @implements A-SPEC-728.3 — a directory spliced into shell text is spelled with `/`. A native Windows base under a root whose
437
+ * path holds a space (`C:\Users\First Last\…\.ax\specs`) was normalised only up to the space, so the rewritten word named no
438
+ * `.ax/<child>` and `echo .* && sh -c 'cat "$0"'` read confirm/allow (measured 2026-10-19). POSIX bases are unchanged.
439
+ */
440
+ const slashed = (dir) => dir.replace(/\\/g, '/');
420
441
  /**
421
442
  * The segment with only its redirect targets that name a protected `.ax` child read under the store (`> ledger/x`,
422
443
  * `>> "specs/y"`, `>&state/z`); a `>` inside quotes is not a redirect.
@@ -424,6 +445,7 @@ function prefixBareRelative(text, dir) {
424
445
  * @implements A-SPEC-728 (rule 34)
425
446
  */
426
447
  function redirectTargetsUnder(text, ax) {
448
+ ax = slashed(ax); // A-SPEC-728.3
427
449
  const masked = maskQuoted(text);
428
450
  // Rule 35: the descriptor digits start at a non-digit (a 100 KB digit run took 5 s — measured), and `<>` is a write.
429
451
  if (!text.includes('>'))
@@ -505,7 +527,8 @@ function segmentFlattened(cmd, root, start = root) {
505
527
  // @implements A-SPEC-728 (rule 44) — `only` limits the prefix to the words that match it: at a climb base (`.ax/~/…`, a
506
528
  // placeholder for an unprotected child) only a word that climbs can leave the placeholder, and prefixing all 131,000 words
507
529
  // of a 256 KB segment at each of 8 climb bases built ~60 MB for the path rules (3.7 s — measured).
508
- const rewrite = (text, dir, globs = false, only) => {
530
+ const rewrite = (text, native, globs = false, only) => {
531
+ const dir = slashed(native); // A-SPEC-728.3
509
532
  let first = true;
510
533
  const word = globs ? /(^|[\s>|])(['"]?)(?![-/~'"])([\w@.*?[{][\w@./*?[\]{},-]*)/g : /(^|[\s>|])(['"]?)(?![-/~'"])([\w@.][\w@./-]*)/g;
511
534
  const plain = globs ? /^[A-Za-z0-9_.@*?[\]{},-]+$/ : /^[A-Za-z0-9_.@-]+$/;
@@ -514,7 +537,11 @@ function segmentFlattened(cmd, root, start = root) {
514
537
  first = false;
515
538
  if (skip || (only !== undefined && !only.test(p)))
516
539
  return full;
517
- return plain.test(p) || p.includes('/') ? `${pre}${q}${dir}/${p}` : full;
540
+ if (!(plain.test(p) || p.includes('/')))
541
+ return full;
542
+ // @implements A-SPEC-747.9 — a base that holds whitespace keeps the word one word (`git status` after `cd "/a b"` read
543
+ // as `git /a b/status`: no sub-command, so a read was refused). A space-free base is spelled as before.
544
+ return q === '' && /\s/.test(dir) ? `${pre}"${dir}/${p}"` : `${pre}${q}${dir}/${p}`;
518
545
  });
519
546
  };
520
547
  // Round 17: from the directory the harness runs the shell in (`start`), not always the root.
@@ -582,7 +609,7 @@ function segmentFlattened(cmd, root, start = root) {
582
609
  // judged by the enumerated channels alone (round 29).
583
610
  // Rule 35 (owner decision 2026-09-26): that channel net is removed — it refused `terraform state rm`, `docker run --rm …
584
611
  // specs/` and `npx jest specs/rm.test.ts` (measured); an unrecognised wrapper or runner is a named residual.
585
- const underStore = (text) => text.replace(childRe, (_f, pre, q, p) => `${pre}${q}${axChildren}/${p}`);
612
+ const underStore = (text) => text.replace(childRe, (_f, pre, q, p) => `${pre}${q}${slashed(axChildren ?? '')}/${p}`);
586
613
  // @implements A-SPEC-728 (rule 39) — when the bases are unknown, for any reason, a literal cd may have gone unapplied; if one
587
614
  // of them lands in the store (by identity: `axl -> .ax` counts) from the start or from any base, a segment recognised as
588
615
  // writing is judged at the store and at each protected child too, glob-leading words included. Rule 38 read the whole
@@ -663,6 +690,29 @@ function normalizeCommandPaths(cmd, followCd = true) {
663
690
  // `\b…\b` test stays; `docs/install-guide.md` beside an .ax path is still refused, on purpose, until a rule exists
664
691
  // that the shell cannot split around.
665
692
  const WRITE_VERB_AX_RE = (0, linear_match_1.headThenTail)(/\b(?:tee|cp|install|dd|ln|mv|rsync)\b/i, SEG, new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i'));
693
+ /**
694
+ * @implements A-SPEC-747.3 — a verb counts only as a shell word: a word whose last path segment is the verb (`cp`,
695
+ * `/bin/cp`, `\cp`, `"cp"`, `x;cp`, `$(cp`, `cp${IFS}`), never one inside an option or a longer name (`grep -ln`,
696
+ * `java -cp`, `a.ln`, `bin/cp-helper`, `run-install-change.test.ts`). It is used only for PLAIN text (see
697
+ * `plainShellText`); every other command keeps the `\b…\b` test, which the 747.1 review showed is the only one a
698
+ * field-splitting shell cannot get around.
699
+ */
700
+ function verbWordRe(alt, flags = '') {
701
+ // A Windows executable suffix (`cp.bat`, `cp.exe`) is still the verb.
702
+ return new RegExp(String.raw `(?<![^\s;&|()\x60'"\\])(?:[^\s;&|()\x60'"<>\\]*/)?(?:${alt})(?:\.(?:exe|bat|cmd|com|ps1))?(?![^\s;&|()\x60'"<>$\\])`, flags);
703
+ }
704
+ /**
705
+ * @implements A-SPEC-747.3 — text the shell runs as written: no expansion, substitution, eval or IFS, and no program that
706
+ * runs text as a command (`… | tr , ' ' | sh` re-parses `dd,if=…` into a write — the 747.1 review's case).
707
+ */
708
+ const TEXT_RUNNER_RE = /(?:^|[^\w.-])(?:sh|bash|zsh|dash|ksh|fish|csh|tcsh|source|eval|exec|xargs|env|node|nodejs|python[0-9.]*|perl|ruby|php|deno|bun|awk|gawk|osascript|pwsh|powershell)(?![\w.-])/;
709
+ function plainShellText(cmd) {
710
+ // A `$` inside single quotes is text (`grep -e '^a.md$'`); IFS and a text runner count anywhere, quoted or not, so a
711
+ // quoted `'sh' -c '…$X'` is never plain.
712
+ return !/[$\x60]/.test(cmd.replace(/'[^']*'/g, "''")) && !/\bIFS\b/.test(cmd) && !TEXT_RUNNER_RE.test(cmd)
713
+ && !/(?:^|[;&|(]\s*)\.\s/.test(cmd);
714
+ }
715
+ const WRITE_VERB_AX_WORD_RE = (0, linear_match_1.headThenTail)(verbWordRe('tee|cp|install|dd|ln|mv|rsync', 'i'), SEG, new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i'));
666
716
  // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
667
717
  // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
668
718
  // here, so this is deliberately conservative on the .ax governance surface only.
@@ -742,7 +792,7 @@ function splitShellClauses(cmd) {
742
792
  * @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
743
793
  * escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
744
794
  */
745
- function splitUnquoted(cmd) {
795
+ function splitUnquoted(cmd, atPipe = true) {
746
796
  const out = [];
747
797
  let cur = '';
748
798
  let quote = null;
@@ -794,9 +844,13 @@ function splitUnquoted(cmd) {
794
844
  cur = '';
795
845
  continue;
796
846
  }
797
- if (ch === '|') {
798
- if (cmd[i + 1] === '|')
799
- i++;
847
+ if (ch === '|' && cmd[i + 1] === '|') {
848
+ i++;
849
+ out.push(cur);
850
+ cur = '';
851
+ continue;
852
+ }
853
+ if (ch === '|' && atPipe) {
800
854
  out.push(cur);
801
855
  cur = '';
802
856
  continue;
@@ -954,15 +1008,18 @@ function isReadOnlyShellClause(clause) {
954
1008
  return k < tokens.length && isReadOnlyShellClause(tokens.slice(k).join(' '));
955
1009
  }
956
1010
  if (name === 'git') {
1011
+ // @implements A-SPEC-747.9 — quote-aware words: `-C "<dir with a space>"` is one value (split on blanks, the dir's
1012
+ // second half was read as the sub-command and a read under such a root was refused), and `"--output=…"` is seen.
1013
+ const words = clauseWords(clause);
957
1014
  // @implements A-SPEC-747 — `-C <dir>` (repeatable) and `--no-pager` come before the sub-command; any other global
958
1015
  // option is not a read (`-c core.fsmonitor=…` runs a program on `status`, `--git-dir`/`--work-tree` retarget it).
959
1016
  let k = 1;
960
- while (k < tokens.length && tokens[k].startsWith('-')) {
961
- if (tokens[k] === '-C') {
1017
+ while (k < words.length && words[k].startsWith('-')) {
1018
+ if (words[k] === '-C') {
962
1019
  k += 2;
963
1020
  continue;
964
1021
  }
965
- if (tokens[k] === '--no-pager') {
1022
+ if (words[k] === '--no-pager') {
966
1023
  k++;
967
1024
  continue;
968
1025
  }
@@ -971,8 +1028,8 @@ function isReadOnlyShellClause(clause) {
971
1028
  // The sub-command is read by its last path part: the per-segment flattening prefixes every word after a moved
972
1029
  // base (`git status` → `git <dir>/status`), which read as no known sub-command (measured on a census read). A real
973
1030
  // git given a path-shaped sub-command only fails, and a write sub-command is not a read under any prefix.
974
- const sub = k < tokens.length ? tokens[k].replace(/^.*\//, '') : '';
975
- return sub !== '' && READ_ONLY_GIT.has(sub) && !rest.some((t) => t.startsWith('--output'));
1031
+ const sub = k < words.length ? words[k].replace(/^.*\//, '') : '';
1032
+ return sub !== '' && READ_ONLY_GIT.has(sub) && !words.slice(1).some((t) => t.startsWith('--output'));
976
1033
  }
977
1034
  // @implements A-SPEC-747 — `date` reads unless it sets the clock (`-s`, `--set`, or an operand that is not a `+FORMAT`).
978
1035
  if (name === 'date')
@@ -1551,18 +1608,181 @@ function shellWritesProtectedAx(ncmd) {
1551
1608
  // after `>`, so `>& path` and `>| path` (a `&` or `|` first) are never seen, and `cd .ax; echo x >& ledger/…` passed once
1552
1609
  // `cd` became a read (measured while building this slice). Before A-SPEC-747 every command with a `cd` was refused, so
1553
1610
  // this keeps that shape exactly as refused as it was.
1554
- let sawCd = false;
1555
- return !clausesAreReads(splitShellClauses(ncmd), (c) => {
1556
- if (/^cd(?:\s|$)/.test(c))
1557
- sawCd = true;
1558
- else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1559
- return false;
1560
- // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1561
- // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1562
- if (COMPUTED_REDIRECT_RE.test(c))
1563
- return false;
1564
- return clauseIsRead(c, isRead);
1565
- });
1611
+ const writes = (text) => {
1612
+ let sawCd = false;
1613
+ return !clausesAreReads(splitShellClauses(text), (c) => {
1614
+ if (/^cd(?:\s|$)/.test(c))
1615
+ sawCd = true;
1616
+ else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1617
+ return false;
1618
+ // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1619
+ // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1620
+ if (COMPUTED_REDIRECT_RE.test(c))
1621
+ return false;
1622
+ return clauseIsRead(c, isRead);
1623
+ });
1624
+ };
1625
+ const pipelines = independentPipelines(ncmd);
1626
+ return pipelines === null ? writes(ncmd) : pipelines.filter((p) => namesProtectedAx(p)).some(writes);
1627
+ }
1628
+ /**
1629
+ * @implements A-SPEC-226.3 — A-SPEC-226 reads the path a command names, so `git add -A`, `git add .ax` and `git commit -a`
1630
+ * staged the spec changes `git add .ax/specs` asks an approval for (28 forms measured 2026-10-19, identical on 0.35.25).
1631
+ * A staging clause reaches the store when what it would stage (the hook's `git status` of the store) includes a change.
1632
+ */
1633
+ const GIT_PLAIN_GLOBAL = new Set(['--no-pager', '-P', '--no-optional-locks', '--literal-pathspecs', '--no-replace-objects']);
1634
+ const COMMIT_VALUE_SHORT = new Set(['m', 'F', 'C', 'c', 't']);
1635
+ const COMMIT_VALUE_LONG = /^--(?:message|file|reuse-message|reedit-message|author|date|template|cleanup|fixup|squash|trailer|gpg-sign)$/;
1636
+ function stageClauseOf(words) {
1637
+ if (words[0] !== 'git')
1638
+ return null;
1639
+ let i = 1;
1640
+ let unknownBase = false;
1641
+ while (i < words.length && words[i].startsWith('-')) {
1642
+ const w = words[i];
1643
+ if (!GIT_PLAIN_GLOBAL.has(w))
1644
+ unknownBase = true;
1645
+ i += /^(?:-C|-c|--git-dir|--work-tree|--exec-path|--namespace)$/.test(w) ? 2 : 1;
1646
+ }
1647
+ const verb = words[i];
1648
+ if (verb !== 'add' && verb !== 'stage' && verb !== 'commit')
1649
+ return null;
1650
+ const pathspecs = [];
1651
+ let all = false;
1652
+ let update = false;
1653
+ let commitAll = false;
1654
+ let dryRun = false;
1655
+ let ended = false;
1656
+ for (let j = i + 1; j < words.length; j++) {
1657
+ const w = words[j];
1658
+ if (ended || !w.startsWith('-') || w === '-') {
1659
+ pathspecs.push(w);
1660
+ continue;
1661
+ }
1662
+ if (w === '--') {
1663
+ ended = true;
1664
+ continue;
1665
+ }
1666
+ if (w.startsWith('--pathspec-from-file')) {
1667
+ unknownBase = true;
1668
+ continue;
1669
+ }
1670
+ if (verb === 'commit') {
1671
+ if (w === '--all') {
1672
+ commitAll = true;
1673
+ continue;
1674
+ }
1675
+ if (w === '--dry-run') {
1676
+ dryRun = true;
1677
+ continue;
1678
+ }
1679
+ if (w.startsWith('--')) {
1680
+ if (COMMIT_VALUE_LONG.test(w))
1681
+ j++;
1682
+ continue;
1683
+ }
1684
+ // A short-option bundle: `-am x` is `-a -m x`; a value option takes the rest of the bundle or the next word.
1685
+ for (let k = 1; k < w.length; k++) {
1686
+ if (w[k] === 'a')
1687
+ commitAll = true;
1688
+ if (COMMIT_VALUE_SHORT.has(w[k])) {
1689
+ if (k === w.length - 1)
1690
+ j++;
1691
+ break;
1692
+ }
1693
+ }
1694
+ continue;
1695
+ }
1696
+ if (w === '--all' || w === '--no-ignore-removal') {
1697
+ all = true;
1698
+ continue;
1699
+ }
1700
+ if (w === '--update') {
1701
+ update = true;
1702
+ continue;
1703
+ }
1704
+ if (w === '--dry-run') {
1705
+ dryRun = true;
1706
+ continue;
1707
+ }
1708
+ if (w.startsWith('--'))
1709
+ continue;
1710
+ for (let k = 1; k < w.length; k++) {
1711
+ if (w[k] === 'A')
1712
+ all = true;
1713
+ else if (w[k] === 'u')
1714
+ update = true;
1715
+ else if (w[k] === 'n')
1716
+ dryRun = true;
1717
+ }
1718
+ }
1719
+ if (dryRun)
1720
+ return null;
1721
+ if (verb === 'commit')
1722
+ return commitAll || pathspecs.length > 0 ? { mode: 'tracked', pathspecs, unknownBase } : null;
1723
+ if (pathspecs.length > 0 || all)
1724
+ return { mode: update && !all ? 'tracked' : 'all', pathspecs, unknownBase };
1725
+ return update ? { mode: 'tracked', pathspecs, unknownBase } : null;
1726
+ }
1727
+ function stagingReachesSpecs(cmd, action) {
1728
+ const signal = action.stagedStore;
1729
+ if (signal === undefined || !/\bgit\b/.test(cmd))
1730
+ return false;
1731
+ const fold = (p) => { const s = (0, linear_match_1.trimTrailing)(path.posix.normalize(p.replace(/\\/g, '/')), '/'); return process.platform === 'win32' ? s.toLowerCase() : s; };
1732
+ const inside = (t, r) => t === r || t.startsWith(r + '/');
1733
+ const specs = fold(signal.specsDir);
1734
+ const root = action.projectRoot ? fold(action.projectRoot) : null;
1735
+ const base0 = action.cwd ?? action.projectRoot;
1736
+ const changed = (mode) => 'unanswered' in signal || signal.tracked || (mode === 'all' && signal.untracked);
1737
+ let movedBase = false;
1738
+ for (const clause of splitShellClauses(stripCommitMessages(cmd))) {
1739
+ const words = clauseWords(clause);
1740
+ if (/^(?:cd|pushd|popd)$/.test(words[0] ?? '')) {
1741
+ movedBase = true;
1742
+ continue;
1743
+ }
1744
+ const st = stageClauseOf(words);
1745
+ if (st === null || !changed(st.mode))
1746
+ continue;
1747
+ const base = movedBase || st.unknownBase || !base0 ? null : fold(base0);
1748
+ if (st.pathspecs.length === 0) {
1749
+ if (base === null || root === null || inside(base, root) || inside(root, base))
1750
+ return true;
1751
+ continue;
1752
+ }
1753
+ for (const p of st.pathspecs) {
1754
+ if (base === null || /[*?[$`~]/.test(p) || p.startsWith(':'))
1755
+ return true;
1756
+ const abs = fold(path.posix.resolve(base, p.replace(/\\/g, '/')));
1757
+ if (inside(specs, abs) || inside(abs, specs))
1758
+ return true;
1759
+ }
1760
+ }
1761
+ return false;
1762
+ }
1763
+ /**
1764
+ * @implements A-SPEC-747.3 (D) — the pipelines of a command (split at `;`, `&&`, `||` and newline, never at `|`) when
1765
+ * one that does not name `.ax` cannot reach a pipeline that does; `null` means "judge the whole command as before".
1766
+ * They cannot reach each other when: no clause is `cd`/`pushd` or a compound keyword (a loop or a branch spans
1767
+ * pipelines), no pipeline without `.ax` holds an expansion or substitution, and no pipeline with `.ax` assigns, exports
1768
+ * or reads a variable.
1769
+ */
1770
+ const COMPOUND_RE = /^(?:cd|pushd|popd|for|while|until|do|done|if|then|elif|else|fi|case|esac|select|function)(?:\s|$)|^[{}]/;
1771
+ const ASSIGNS_RE = /(?:^|[\s;&|(])(?:[A-Za-z_]\w*(?:\[[^\]]*\])?\+?=|(?:export|declare|typeset|local|readonly|read|mapfile|readarray|unset)\b|printf\s+-v\b)/;
1772
+ function independentPipelines(ncmd) {
1773
+ const pipelines = splitUnquoted(ncmd, false);
1774
+ if (pipelines === null)
1775
+ return null;
1776
+ const parts = pipelines.map((p) => p.trim()).filter((p) => p !== '');
1777
+ if (parts.length < 2)
1778
+ return null;
1779
+ if (splitShellClauses(ncmd).some((c) => COMPOUND_RE.test(c)))
1780
+ return null;
1781
+ for (const p of parts) {
1782
+ if (namesProtectedAx(p) ? ASSIGNS_RE.test(p) : SUBSTITUTION_RE.test(p) || /\$/.test(p))
1783
+ return null;
1784
+ }
1785
+ return parts;
1566
1786
  }
1567
1787
  /**
1568
1788
  * @implements A-SPEC-125.1
@@ -1626,7 +1846,7 @@ function classifyReversibilityAsWritten(action) {
1626
1846
  const axChannel = REMOVAL_VERB_RE.test(ncmd) && namesProtectedAx(ncmd)
1627
1847
  ? 'removal, move or copy command targets a protected .ax governance path'
1628
1848
  : CLOBBER_AX_RE.test(ncmd) ? 'output redirection writes into a protected .ax governance path'
1629
- : WRITE_VERB_AX_RE.test(ncmd) ? 'file-writing command (tee/cp/install/dd/ln/mv/rsync) targets a protected .ax governance path'
1849
+ : (plainShellText(ncmd) ? WRITE_VERB_AX_WORD_RE : WRITE_VERB_AX_RE).test(ncmd) ? 'file-writing command (tee/cp/install/dd/ln/mv/rsync) targets a protected .ax governance path'
1630
1850
  : INTERPRETER_AX_RE.test(ncmd)
1631
1851
  ? 'interpreter one-liner names a protected .ax governance path — a read cannot be told from a write here; read with cat, head, grep or sed -n instead'
1632
1852
  : undefined;
@@ -1643,6 +1863,14 @@ function classifyReversibilityAsWritten(action) {
1643
1863
  reasons: ['shell command over a protected .ax governance path is not recognisably read-only'],
1644
1864
  };
1645
1865
  }
1866
+ // @implements A-SPEC-226.3 — the same act without the spelling.
1867
+ if (stagingReachesSpecs(cmd, action)) {
1868
+ return {
1869
+ axis,
1870
+ level: 'hard-hitl',
1871
+ reasons: ['staging command reaches changed files in the protected .ax spec store without naming it (the same act as staging them by name)'],
1872
+ };
1873
+ }
1646
1874
  // A destructive recursive `rm` — either `-rf` on a non-safe target, or a recursive delete of
1647
1875
  // a catastrophic root (/, ~, $HOME, ., .., glob) even WITHOUT `-f` — is whole-tree destruction,
1648
1876
  // unconditionally hard-hitl regardless of `tracked`. The single-file `tracked===true` auto
@@ -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;
@@ -41,7 +42,22 @@ export interface RiskAction {
41
42
  * starts from; defaults to `projectRoot`.
42
43
  */
43
44
  cwd?: string;
45
+ /**
46
+ * @implements A-SPEC-226.3
47
+ * What `git status` says about the spec store, resolved by the hook only for a command that holds a staging verb.
48
+ * `tracked`: a tracked file there differs between the index and the work tree; `untracked`: an untracked, not-ignored
49
+ * file exists there; `unanswered`: git was asked and did not answer. Absent: not asked (no verdict changes).
50
+ */
51
+ stagedStore?: StagedStoreSignal;
44
52
  }
53
+ export type StagedStoreSignal = {
54
+ specsDir: string;
55
+ tracked: boolean;
56
+ untracked: boolean;
57
+ } | {
58
+ specsDir: string;
59
+ unanswered: true;
60
+ };
45
61
  export interface RiskThresholds {
46
62
  blastRadiusConfirm?: number;
47
63
  blastRadiusHardHitl?: number;
@@ -0,0 +1,23 @@
1
+ type Decision = {
2
+ permissionDecision: string;
3
+ permissionDecisionReason?: string;
4
+ } & Record<string, unknown>;
5
+ export interface PlanScopeContext {
6
+ projectRoot: string;
7
+ specsDir: string;
8
+ env: NodeJS.ProcessEnv;
9
+ cwd?: string;
10
+ sessionId?: string;
11
+ tool: string;
12
+ toolInput: Record<string, unknown>;
13
+ }
14
+ /** The paths a file tool writes; for apply_patch, every target the patch names. */
15
+ export declare function planTargets(tool: string, input: Record<string, unknown>): string[];
16
+ export declare function applyPlanScope(out: Decision, ctx: PlanScopeContext): Decision;
17
+ /**
18
+ * @implements A-SPEC-774.23 — the plan-scope judgement for any writer (file tools, apply_patch, the shell): null when
19
+ * the run is unscoped or every target lies in the plan, otherwise the refusal. A plan that cannot be read refuses,
20
+ * naming what could not be read — a malformed scope, a spec not found or unparseable, an unreadable or empty FtT.
21
+ */
22
+ export declare function planScopeRefusal(ctx: Omit<PlanScopeContext, 'tool' | 'toolInput'>, targets: readonly string[]): string | null;
23
+ export {};