@holmes-lab/holmes-kit 0.35.25 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +346 -0
  2. package/README.md +3 -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 +31 -1
  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 +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -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.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +141 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/adapters/antigravity.d.ts +1 -1
  77. package/dist/holmes/hooks/adapters/antigravity.js +6 -2
  78. package/dist/holmes/hooks/pre-tool-use.d.ts +55 -2
  79. package/dist/holmes/hooks/pre-tool-use.js +749 -89
  80. package/dist/holmes/hooks/session-start.js +5 -3
  81. package/dist/holmes/hooks/stop.d.ts +32 -0
  82. package/dist/holmes/hooks/stop.js +129 -4
  83. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  84. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  85. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  86. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  87. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  88. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  89. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  90. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  91. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  92. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  93. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  94. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  95. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  96. package/dist/holmes/mcp/handlers.d.ts +2 -3
  97. package/dist/holmes/mcp/handlers.js +22 -2
  98. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  99. package/dist/holmes/mcp/harness-attestation.js +3 -1
  100. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  101. package/dist/holmes/mcp/operator-recovery.js +4 -3
  102. package/dist/holmes/mcp/server.js +9 -0
  103. package/dist/holmes/mcp/tool-schemas.js +6 -3
  104. package/dist/holmes/project/root.js +6 -1
  105. package/dist/holmes/project/run-records.d.ts +17 -0
  106. package/dist/holmes/project/run-records.js +126 -0
  107. package/dist/holmes/review/mrp.d.ts +35 -0
  108. package/dist/holmes/review/mrp.js +119 -0
  109. package/dist/holmes/review/verdicts.d.ts +117 -0
  110. package/dist/holmes/review/verdicts.js +345 -0
  111. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  112. package/dist/holmes/semantic/cloud-usage.js +106 -0
  113. package/dist/holmes/semantic/embedder.d.ts +15 -6
  114. package/dist/holmes/semantic/embedder.js +84 -3
  115. package/dist/holmes/semantic/local-model.d.ts +21 -2
  116. package/dist/holmes/semantic/local-model.js +14 -3
  117. package/dist/holmes/semantic/tier.d.ts +25 -0
  118. package/dist/holmes/semantic/tier.js +86 -1
  119. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  120. package/dist/holmes/semantic/vector-cache.js +4 -1
  121. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  122. package/dist/holmes/spec/approval-blockers.js +70 -2
  123. package/dist/holmes/spec/renumber.d.ts +1 -1
  124. package/dist/holmes/spec/renumber.js +5 -2
  125. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  126. package/dist/holmes/spec/transition-policy.js +17 -2
  127. 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
+ }
@@ -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;