@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,304 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.expandAssigned = expandAssigned;
4
+ exports.pathTokensOf = pathTokensOf;
5
+ exports.commandContext = commandContext;
6
+ exports.dynamicWrites = dynamicWrites;
7
+ // @implements A-SPEC-747.4, A-SPEC-747.7, A-SPEC-747.10
8
+ const risk_classifier_1 = require("./risk-classifier");
9
+ /** Words a clause may open with before its assignments and command word. */
10
+ const LEAD_KEYWORDS = new Set(['do', 'then', 'else', 'elif', 'if', 'while', 'until', '!', '{', '(', 'time']);
11
+ /** Builtins whose `NAME=value` operands are executed assignments. */
12
+ const DECLARATIONS = new Set(['export', 'declare', 'typeset', 'local', 'readonly']);
13
+ /** Words with quotes removed; `dyn` when a `$` or a backtick sat outside single quotes. */
14
+ function words(clause) {
15
+ const out = [];
16
+ let cur = '', dyn = false, inWord = false, quote = '';
17
+ const push = () => { if (inWord)
18
+ out.push({ text: cur, dyn }); cur = ''; dyn = false; inWord = false; };
19
+ for (let i = 0; i < clause.length; i++) {
20
+ const ch = clause[i];
21
+ if (quote === "'") {
22
+ if (ch === "'")
23
+ quote = '';
24
+ else
25
+ cur += ch;
26
+ continue;
27
+ }
28
+ if (quote === '"') {
29
+ if (ch === '"')
30
+ quote = '';
31
+ else if (ch === '\\' && i + 1 < clause.length)
32
+ cur += clause[++i];
33
+ else {
34
+ if (ch === '$' || ch === '`')
35
+ dyn = true;
36
+ cur += ch;
37
+ }
38
+ continue;
39
+ }
40
+ if (/\s/.test(ch)) {
41
+ push();
42
+ continue;
43
+ }
44
+ inWord = true;
45
+ if (ch === "'" || ch === '"')
46
+ quote = ch;
47
+ else if (ch === '\\' && i + 1 < clause.length)
48
+ cur += clause[++i];
49
+ else {
50
+ if (ch === '$' || ch === '`')
51
+ dyn = true;
52
+ cur += ch;
53
+ }
54
+ }
55
+ push();
56
+ return out;
57
+ }
58
+ const COPY = new Set(['cp', 'mv', 'install', 'ln', 'rsync']);
59
+ const ALL_TARGETS = new Set(['tee', 'touch', 'truncate']);
60
+ const PREFIX = new Set(['env', 'sudo', 'nohup', 'time', 'command', 'nice']);
61
+ const VERB_ANYWHERE = /(?:^|[^A-Za-z0-9_./-])(?:cp|mv|install|ln|rsync|tee|touch|truncate|dd|sed|perl)(?![A-Za-z0-9_])/;
62
+ const XARGS_VALUE = /^(?:-[aEdIiLlnPs]|--arg-file|--delimiter|--eof|--replace|--max-lines|--max-args|--max-procs|--max-chars)$/;
63
+ const progName = (w) => (w.split(/[\\/]/).pop() ?? w).replace(/\.(?:exe|cmd|bat)$/i, '').toLowerCase();
64
+ /**
65
+ * A variable the command assigned a literal value is that value: `S=/abs/scratch; sed -i … $S/x` writes `/abs/scratch/x`.
66
+ * Measured on this project's own sessions (2026-10-19): without it, 0.4% of 15,798 commands were refused, most of them
67
+ * scratchpad writes through such a variable. A word that still holds `$` or a backtick after expansion stays computed.
68
+ */
69
+ function expandAssigned(text, assigned) {
70
+ const out = text.replace(/\$\{([A-Za-z_]\w*)\}|\$([A-Za-z_]\w*)/g, (m, a, b) => assigned.get((a ?? b)) ?? m);
71
+ return /[$`]/.test(out) ? null : out;
72
+ }
73
+ function whyOf(ctx) {
74
+ return ctx.runner === 'find' ? 'find -exec {}' : ctx.runner === 'xargs' ? 'xargs input' : 'variable destination';
75
+ }
76
+ /** Runners nested deeper than this are not read (`xargs xargs …` repeated to 120 KB overflowed the stack — measured). */
77
+ const RUNNER_DEPTH_MAX = 8;
78
+ function judgeCommand(ws, ctx, found, depth = 0) {
79
+ if (depth > RUNNER_DEPTH_MAX) {
80
+ found.why ??= 'runners nested too deep to read';
81
+ return;
82
+ }
83
+ let i = 0;
84
+ while (i < ws.length && (/^[A-Za-z_]\w*=/.test(ws[i].text) || PREFIX.has(progName(ws[i].text)) || (i > 0 && ws[i].text.startsWith('-') && PREFIX.has(progName(ws[i - 1].text)))))
85
+ i++;
86
+ const prog = ws[i];
87
+ if (prog === undefined)
88
+ return;
89
+ // A word that opens a command substitution is not read as the command (the clause split cuts `$(…)` bodies apart:
90
+ // 3 of the 8 false refusals in this project's sessions, 2026-10-19). Residual, recorded: `$(echo cp) a src/x.ts`.
91
+ if (/^(?:\$\(|`)/.test(prog.text))
92
+ return;
93
+ // A command word a literal assignment spelled is that command, unless IFS was reassigned or the value would split.
94
+ const progText = prog.dyn && !found.assigned.has('IFS') ? expandAssigned(prog.text, found.assigned) : prog.dyn ? null : prog.text;
95
+ if (progText === null || (prog.dyn && /\s/.test(progText)) || progText === 'eval') {
96
+ // Only the shapes measured to carry a write: a bare variable (`$c`, `${c}`) unexpanded or expanding to several words,
97
+ // an IFS join, eval. A fragment the quote-aware split could not follow (`$((n-10))…`, nested `"$(…"…")"`, a quoted
98
+ // string read as one word) is not a command word (5 false refusals in this project's sessions, 2026-10-19).
99
+ if (progText === 'eval' || /^\$\{?[A-Za-z_]\w*\}?$/.test(prog.text) || /\$\{?IFS\}?/.test(prog.text))
100
+ found.computed = true;
101
+ return;
102
+ }
103
+ const name = progName(progText);
104
+ const args = ws.slice(i + 1);
105
+ const hasPlaceholder = (w) => ctx.placeholder !== null && w.text.includes(ctx.placeholder);
106
+ const isDyn = (w) => hasPlaceholder(w) || (w.dyn && expandAssigned(w.text, found.assigned) === null);
107
+ const dynamic = () => { found.why ??= whyOf(ctx); };
108
+ // A runner's literal destination, and any destination a literal assignment spelled, go to the code-write rule.
109
+ const literal = (w) => {
110
+ if (w.dyn)
111
+ found.statics.push(expandAssigned(w.text, found.assigned));
112
+ else if (ctx.runner !== null || prog.dyn)
113
+ found.statics.push(w.text); // the literal rule never saw this verb
114
+ };
115
+ if (name === 'xargs' || name === 'parallel') {
116
+ let j = 0;
117
+ let replace = null;
118
+ for (; j < args.length; j++) {
119
+ const t = args[j].text;
120
+ if (!t.startsWith('-') || name === 'parallel' && t === ':::')
121
+ break;
122
+ const r = /^(?:-I|--replace=?)(.*)$/.exec(t) ?? /^-i(.*)$/.exec(t);
123
+ if (r) {
124
+ replace = r[1] !== '' ? r[1] : t === '-I' ? args[j + 1]?.text ?? '{}' : '{}';
125
+ if (t === '-I')
126
+ j++;
127
+ continue;
128
+ }
129
+ if (XARGS_VALUE.test(t))
130
+ j++;
131
+ }
132
+ judgeCommand(args.slice(j), { placeholder: replace ?? (name === 'parallel' ? '{}' : null), appended: replace === null, runner: 'xargs' }, found, depth + 1);
133
+ return;
134
+ }
135
+ if (name === 'find') {
136
+ for (let j = 0; j < args.length; j++) {
137
+ if (!/^-(?:exec|execdir|ok|okdir)$/.test(args[j].text))
138
+ continue;
139
+ const sub = [];
140
+ let k = j + 1;
141
+ for (; k < args.length && args[k].text !== ';' && args[k].text !== '+'; k++)
142
+ sub.push(args[k]);
143
+ judgeCommand(sub, { placeholder: '{}', appended: false, runner: 'find' }, found, depth + 1);
144
+ j = k;
145
+ }
146
+ return;
147
+ }
148
+ if (COPY.has(name)) {
149
+ let target;
150
+ const positional = [];
151
+ for (let j = 0; j < args.length; j++) {
152
+ const t = args[j].text;
153
+ const eq = /^--target-directory=(.*)$/.exec(t);
154
+ if (eq) {
155
+ target = { text: eq[1], dyn: args[j].dyn };
156
+ continue;
157
+ }
158
+ if (t === '-t' || t === '--target-directory') {
159
+ target = args[j + 1];
160
+ j++;
161
+ continue;
162
+ }
163
+ if (t.startsWith('-'))
164
+ continue;
165
+ positional.push(args[j]);
166
+ }
167
+ const dest = target ?? (ctx.appended ? undefined : positional[positional.length - 1]);
168
+ if (dest === undefined) {
169
+ if (ctx.appended)
170
+ dynamic();
171
+ return;
172
+ }
173
+ if (isDyn(dest))
174
+ dynamic();
175
+ else
176
+ literal(dest);
177
+ return;
178
+ }
179
+ const operands = (list, skipFirst, valueFlags) => {
180
+ const out = [];
181
+ let script = !skipFirst;
182
+ for (let j = 0; j < list.length; j++) {
183
+ const t = list[j].text;
184
+ if (t.startsWith('-') && t !== '-') {
185
+ if (valueFlags.test(t))
186
+ j++;
187
+ continue;
188
+ }
189
+ if (!script) {
190
+ script = true;
191
+ continue;
192
+ }
193
+ out.push(list[j]);
194
+ }
195
+ return out;
196
+ };
197
+ const targets = (ts) => {
198
+ if (ctx.appended) {
199
+ dynamic();
200
+ return;
201
+ }
202
+ for (const w of ts) {
203
+ if (isDyn(w))
204
+ dynamic();
205
+ else
206
+ literal(w);
207
+ }
208
+ };
209
+ if (name === 'sed') {
210
+ if (!args.some((a) => /^(?:-[A-Za-z]*i|--in-place)/.test(a.text)))
211
+ return;
212
+ // BSD `sed -i ''`: the empty word after `-i` is the suffix, not the script.
213
+ const kept = args.filter((a, j) => !(a.text === '' && args[j - 1]?.text === '-i'));
214
+ const hasScriptFlag = kept.some((a) => /^(?:-e|-f|--expression|--file)/.test(a.text));
215
+ targets(operands(kept, !hasScriptFlag, /^(?:-e|-f|--expression|--file)$/));
216
+ return;
217
+ }
218
+ if (name === 'perl') {
219
+ if (!args.some((a) => /^-[A-Za-z]*i/.test(a.text)))
220
+ return;
221
+ targets(operands(args, false, /^-[A-Za-z]*[eE]$/));
222
+ return;
223
+ }
224
+ if (ALL_TARGETS.has(name)) {
225
+ targets(operands(args, false, /^(?:-s|--size|-r|--reference)$/));
226
+ return;
227
+ }
228
+ if (name === 'dd') {
229
+ const of = args.find((a) => a.text.startsWith('of='));
230
+ if (of) {
231
+ if (isDyn(of))
232
+ dynamic();
233
+ else
234
+ literal({ text: of.text.slice(3), dyn: false });
235
+ }
236
+ }
237
+ }
238
+ /**
239
+ * Every literal path-like token of a text: words and assignment values, split at an IFS join. The hook reads it over
240
+ * every segment of the command — `X=src/x.ts; cp /tmp/a $X` and `echo src/x.ts | xargs cp /tmp/a` name the target in
241
+ * another segment than the write (measured on the first build of this slice).
242
+ */
243
+ function pathTokensOf(text) {
244
+ const out = [];
245
+ for (const ws of (0, risk_classifier_1.splitShellClauses)(text).map(words))
246
+ for (const w of ws) {
247
+ const value = /^[A-Za-z_]\w*=(.*)$/.exec(w.text)?.[1] ?? w.text;
248
+ for (const part of value.split(/\$\{IFS\}|\$IFS/)) {
249
+ if (part === '' || part.startsWith('-') || /[$`]/.test(part) || part === '{}')
250
+ continue;
251
+ if (/[/.*]/.test(part))
252
+ out.push(part);
253
+ }
254
+ }
255
+ return out;
256
+ }
257
+ function commandContext(commandText) {
258
+ const assigned = new Map();
259
+ // @implements A-SPEC-747.10 — a variable places a write only when every executed assignment of it gives one readable
260
+ // value: keeping the last value let `F=src/x.ts; cp /dev/null "$F"; F=/tmp/x.ts` through (independent review, 2026-10-19).
261
+ const ambiguous = new Set();
262
+ const assign = (w) => {
263
+ const m = /^([A-Za-z_]\w*)=(.*)$/.exec(w.text);
264
+ if (m === null)
265
+ return false;
266
+ if (ambiguous.has(m[1]))
267
+ return true;
268
+ // A chain (`S=/abs; F=$S/x`) is expanded in order; a value that still holds `$` or a backtick is not readable.
269
+ const value = w.dyn ? expandAssigned(m[2], assigned) : m[2];
270
+ const prev = assigned.get(m[1]);
271
+ if (value === null || (prev !== undefined && prev !== value)) {
272
+ assigned.delete(m[1]);
273
+ ambiguous.add(m[1]);
274
+ }
275
+ else
276
+ assigned.set(m[1], value);
277
+ return true;
278
+ };
279
+ const clauses = (0, risk_classifier_1.splitShellClauses)(commandText).map(words);
280
+ for (const ws of clauses) {
281
+ // Only executed assignments count: the words before the command word (after a keyword such as `do`), and those
282
+ // after a declaration builtin. `echo F=x` assigns nothing.
283
+ let i = 0;
284
+ while (i < ws.length && LEAD_KEYWORDS.has(ws[i].text))
285
+ i++;
286
+ while (i < ws.length && assign(ws[i]))
287
+ i++;
288
+ if (i < ws.length && DECLARATIONS.has(ws[i].text))
289
+ for (const w of ws.slice(i + 1))
290
+ assign(w);
291
+ }
292
+ const found = { statics: [], why: null, computed: false, assigned };
293
+ for (const ws of clauses)
294
+ judgeCommand(ws, { placeholder: null, appended: false, runner: null }, found);
295
+ return { assigned, computed: found.computed && VERB_ANYWHERE.test(commandText) };
296
+ }
297
+ function dynamicWrites(segmentText, context = commandContext(segmentText)) {
298
+ const clauses = (0, risk_classifier_1.splitShellClauses)(segmentText).map(words);
299
+ const found = { statics: [], why: null, computed: false, assigned: context.assigned };
300
+ for (const ws of clauses)
301
+ judgeCommand(ws, { placeholder: null, appended: false, runner: null }, found);
302
+ // A computed command word is the whole command's verdict (`CommandContext.computed`), not a segment's.
303
+ return { statics: found.statics, dynamic: found.why === null ? null : { why: found.why, tokens: pathTokensOf(segmentText) } };
304
+ }
@@ -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
  }
@@ -1,4 +1,5 @@
1
1
  import { Spec } from '../spec/spec-parser';
2
+ import { type ClassifyOptions } from './classification-mode';
2
3
  export declare const ACTIONS: readonly ["AUTHOR_REQ", "AUTHOR_HSPEC", "AUTHOR_ASPEC", "AUTHOR_CSPEC", "AUTHOR_TSPEC", "WRITE_TEST", "WRITE_CODE"];
3
4
  export type Action = (typeof ACTIONS)[number];
4
5
  export interface CheckResult {
@@ -19,7 +20,7 @@ export interface CheckResult {
19
20
  * DOWNGRADING the gate, since WRITE_TEST does not require an approved T-SPEC. Callers that hold an
20
21
  * absolute path make it relative first (see evaluateHook).
21
22
  */
22
- export declare function classifyAction(p: string, content?: string): Action | null;
23
+ export declare function classifyAction(p: string, content?: string, opts?: ClassifyOptions): Action | null;
23
24
  export declare function phaseCheck(action: Action, ctx: {
24
25
  specs: Spec[];
25
26
  targetParentReqId?: string;
@@ -5,6 +5,7 @@ exports.classifyAction = classifyAction;
5
5
  exports.phaseCheck = phaseCheck;
6
6
  const executable_artifact_1 = require("./executable-artifact");
7
7
  const test_files_1 = require("../cpg/test-files");
8
+ const classification_mode_1 = require("./classification-mode");
8
9
  const approval_blockers_1 = require("../spec/approval-blockers");
9
10
  const tspec_state_1 = require("./tspec-state");
10
11
  // @implements A-SPEC-100.2
@@ -32,7 +33,7 @@ const CODE_EXT_RE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|scala
32
33
  * DOWNGRADING the gate, since WRITE_TEST does not require an approved T-SPEC. Callers that hold an
33
34
  * absolute path make it relative first (see evaluateHook).
34
35
  */
35
- function classifyAction(p, content) {
36
+ function classifyAction(p, content, opts) {
36
37
  const norm = p.replace(/\\/g, '/');
37
38
  // Spec authoring is a MARKDOWN file under a spec folder. A code file merely PLACED at such a path
38
39
  // (e.g. src/x/.ax/specs/01_req/evil.ts) must NOT be downgraded to the permissive author gate —
@@ -55,19 +56,32 @@ function classifyAction(p, content) {
55
56
  // suite MORE strictly than the code it tests (WRITE_CODE additionally demands an approved T-SPEC),
56
57
  // which no Python or Go project can satisfy for its tests. Measured on a real Python target. One
57
58
  // table means the gate and the graph cannot disagree about what a test is.
58
- if ((0, test_files_1.isTestFile)(norm))
59
- return 'WRITE_TEST';
60
- if (/\.(test|spec)\.[a-z]+$/i.test(norm))
61
- return 'WRITE_TEST';
62
- if (CODE_EXT_RE.test(norm))
63
- return 'WRITE_CODE';
64
59
  // @implements A-SPEC-167
65
- // What EXECUTES is code. The extension list above is the compiler's view, and it missed
60
+ // What EXECUTES is code. The extension list below is the compiler's view, and it missed
66
61
  // package.json, Makefile, Dockerfile, CI workflows and shell scripts — each an execution path,
67
62
  // each previously unclassified and therefore ungated. Folding into WRITE_CODE rather than adding
68
63
  // an action kind means the role policy, the phase gate and the playbooks all already know it.
64
+ // @implements A-SPEC-775 — asked BEFORE "is it a test": a test is dispensed from the T-SPEC and a
65
+ // WRITE_TEST-only role may write one, and `deploy.test.sh` / `.github/workflows/ci.test.yml` were
66
+ // both answered "test" (measured 2026-10-17).
69
67
  if ((0, executable_artifact_1.isExecutableArtifact)(norm, content))
70
68
  return 'WRITE_CODE';
69
+ // @implements A-SPEC-775.1 — a declared test folder holds tests in every mode; under strict the folder-only
70
+ // rules count at the root, a package root or a declared folder. Without options this is the plain table.
71
+ if (opts && (0, classification_mode_1.underDeclared)(norm, opts.declaredTestDirs) && CODE_EXT_RE.test(norm))
72
+ return 'WRITE_TEST';
73
+ if (opts ? (0, classification_mode_1.scopedTestFile)(norm, opts) : (0, test_files_1.isTestFile)(norm))
74
+ return 'WRITE_TEST';
75
+ // A test-NAMED file the shared table does not recognise is a name, not a test any runner collects:
76
+ // it is not dispensed (it was WRITE_TEST by a second, private table; never looser than that).
77
+ if (/\.(test|spec)\.[a-z]+$/i.test(norm))
78
+ return 'WRITE_CODE';
79
+ if (CODE_EXT_RE.test(norm))
80
+ return 'WRITE_CODE';
81
+ // @implements A-SPEC-775.1 — I2: in a run or under strict, a write the classifier does not name is code unless
82
+ // it is on the safe list.
83
+ if (opts?.strict && !(0, classification_mode_1.safeUnclassified)(norm, opts))
84
+ return 'WRITE_CODE';
71
85
  return null;
72
86
  }
73
87
  function deny(phase, missing, message, next, discipline = NO_SPEC_NO_CODE) {
@@ -0,0 +1,21 @@
1
+ /**
2
+ * PowerShell text, read as the shell acts it performs.
3
+ *
4
+ * Measured 2026-10-18 (dist a998bea8, Windows 11): the PreToolUse shell branch ran only for tool_name 'bash', so
5
+ * Claude Code's PowerShell tool passed `Remove-Item -Recurse -Force .ax/specs`, `Set-Content src/...ts` and
6
+ * `git push --force` with no decision. Rather than a second rule set per shell, a PowerShell command is translated into
7
+ * the shell text that does the same thing, and the existing Bash rules judge that text — so every later rule protects
8
+ * both tools at once.
9
+ *
10
+ * PowerShell's own syntax decides: a backslash is a literal path separator (emitted as `/`), a backtick is the escape,
11
+ * single quotes are literal, `$env:NAME` is an environment variable, and cmdlets and their aliases do what PowerShell
12
+ * does. A command the Bash rules would not recognise passes through as its own words, so native tools (git, npm, node)
13
+ * are judged exactly as under Bash. Text that cannot be read is `unjudgeable`; the hook refuses it. Pure.
14
+ */
15
+ export type PowerShellReading = {
16
+ shell: string;
17
+ } | {
18
+ unjudgeable: string;
19
+ };
20
+ /** PowerShell text as the shell text whose acts it performs, or why it cannot be read. */
21
+ export declare function powershellAsShell(command: string): PowerShellReading;