@holmes-lab/holmes-kit 0.35.25 → 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 (125) hide show
  1. package/CHANGELOG.md +298 -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 +140 -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/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
@@ -0,0 +1,177 @@
1
+ "use strict";
2
+ // @implements A-SPEC-774.11, A-SPEC-774.26, A-SPEC-774.27, A-SPEC-774.28
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.gateOffMarker = gateOffMarker;
5
+ exports.launchView = launchView;
6
+ exports.launchOptionWords = launchOptionWords;
7
+ exports.interactiveLaunchIssue = interactiveLaunchIssue;
8
+ const any = 'any';
9
+ const oneOf = (...vs) => (v) => vs.includes(v);
10
+ // @implements A-SPEC-774.26 — the autonomy keys: they set the child's own approvals and sandbox, not what it loads.
11
+ const CODEX_CONFIG_KEYS = ['model', 'model_reasoning_effort', 'model_reasoning_summary', 'model_verbosity', 'approval_policy', 'sandbox_mode'];
12
+ /**
13
+ * @implements A-SPEC-774.26 — autonomy options skip the child harness's OWN permission prompts. Measured 2026-10-18 (owner
14
+ * grants): a child started with `claude --dangerously-skip-permissions`, `codex exec
15
+ * --dangerously-bypass-approvals-and-sandbox` or `agy --dangerously-skip-permissions` still had a shell write into a code
16
+ * file refused by the Holmes PreToolUse hook. Owner decision the same day: a person's session runs other agents with
17
+ * full autonomous approval; only Holmes governance must stay on. What changes what the child LOADS stays refused
18
+ * (GATE_OFF_MARKERS).
19
+ */
20
+ const CLAUDE = {
21
+ flags: new Set(['-p', '--print', '--verbose', '-c', '--continue', '--version', '-v', '--help', '-h', '--dangerously-skip-permissions']),
22
+ values: new Map([
23
+ ['--model', any], ['--output-format', any], ['--input-format', any], ['--max-turns', any],
24
+ ['--append-system-prompt', any], ['--system-prompt', any], ['-r', any], ['--resume', any], ['--add-dir', any],
25
+ ['--allowedTools', any], ['--disallowedTools', any],
26
+ ['--permission-mode', oneOf('default', 'acceptEdits', 'plan', 'bypassPermissions')],
27
+ ]),
28
+ };
29
+ const CODEX = {
30
+ flags: new Set(['--json', '--skip-git-repo-check', '--full-auto', '--version', '--help', '-h', '-V', '--dangerously-bypass-approvals-and-sandbox']),
31
+ values: new Map([
32
+ ['-m', any], ['--model', any], ['-C', any], ['--cd', any], ['-o', any], ['--output-last-message', any],
33
+ ['--color', any], ['-i', any], ['--image', any],
34
+ ['-s', oneOf('read-only', 'workspace-write', 'danger-full-access')], ['--sandbox', oneOf('read-only', 'workspace-write', 'danger-full-access')],
35
+ ['-a', oneOf('untrusted', 'on-request', 'on-failure', 'never')], ['--ask-for-approval', oneOf('untrusted', 'on-request', 'on-failure', 'never')],
36
+ ['-c', (v) => CODEX_CONFIG_KEYS.includes(v.split('=')[0])], ['--config', (v) => CODEX_CONFIG_KEYS.includes(v.split('=')[0])],
37
+ ]),
38
+ subcommands: new Set(['exec', 'e', 'review']),
39
+ };
40
+ /**
41
+ * @implements A-SPEC-774.26 — agy is its own CLI (`agy --help`, 2026-10-18), not gemini's. `--remote-control` hands the
42
+ * session to another party and stays off the list.
43
+ * @implements A-SPEC-774.28 — `--mode auto`, unmeasured when 774.26 shipped, was measured and allowed by A-SPEC-774.27.
44
+ */
45
+ const AGY = {
46
+ flags: new Set(['-c', '--continue', '--new-project', '--sandbox', '--disable-slash-commands', '--dangerously-skip-permissions', '--version', '--help', '-h']),
47
+ values: new Map([
48
+ ['-p', any], ['--print', any], ['--prompt', any], ['-i', any], ['--prompt-interactive', any], ['--model', any], ['--effort', any],
49
+ ['--output-format', any], ['--input-format', any], ['--print-timeout', any], ['--add-dir', any], ['--project', any],
50
+ ['--conversation', any], ['--agent', any], ['--json-schema', any], ['--log-file', any],
51
+ // @implements A-SPEC-774.27 — `auto` measured by the operator in the agy TUI (2026-10-19): the Holmes hook still refused.
52
+ ['--mode', oneOf('accept-edits', 'plan', 'auto')],
53
+ ]),
54
+ };
55
+ const GEMINI = {
56
+ flags: new Set(['--version', '--help', '-h']),
57
+ values: new Map([
58
+ ['-p', any], ['--prompt', any], ['-m', any], ['--model', any], ['--output-format', any],
59
+ ['--approval-mode', oneOf('default', 'auto_edit')],
60
+ ]),
61
+ };
62
+ const NONE = { flags: new Set(), values: new Map() };
63
+ const BY_NAME = {
64
+ claude: CLAUDE, '@anthropic-ai/claude-code': CLAUDE,
65
+ codex: CODEX, '@openai/codex': CODEX,
66
+ gemini: GEMINI, agy: AGY, '@google/gemini-cli': GEMINI,
67
+ };
68
+ const AGENT_WORD = /^(?:claude|codex|gemini|agy|aider|cursor-agent|opencode|goose|qwen)$/;
69
+ const SAFE_ENV = /^(?:LANG|LC_[A-Z_]+|TZ|TERM|NO_COLOR|FORCE_COLOR|COLUMNS|LINES)$/;
70
+ const agentOf = (word) => {
71
+ const base = (word.split(/[\\/]/).pop() ?? word).replace(/\.(?:exe|cmd)$/i, '').toLowerCase();
72
+ if (AGENT_WORD.test(base))
73
+ return base;
74
+ const pkg = (/^(@?[^@]+)/.exec(word) ?? ['', ''])[1];
75
+ return BY_NAME[pkg] ? pkg : null;
76
+ };
77
+ /**
78
+ * @implements A-SPEC-774.12 — the gate-off markers, read anywhere in a launch's text. Shell and interpreter launches use
79
+ * this one list: an interpreter spawn cannot be read option by option, and it read only the flag strings, so
80
+ * `spawnSync('codex',['exec','-c','approval_policy=never'])` passed while the same shell form was refused.
81
+ */
82
+ // @implements A-SPEC-774.26 — only what changes what the child LOADS (settings, hooks, MCP, its config directory), and the
83
+ // unmeasured `--yolo`. The autonomy options measured to keep the gate on left this list for the allowlists above.
84
+ const GATE_OFF_MARKERS = [
85
+ [/--safe-mode\b/, '--safe-mode'],
86
+ [/(?<![\w-])--yolo\b/, '--yolo'],
87
+ [/--approval-mode['",\s=]+yolo\b/, '--approval-mode yolo'],
88
+ [/\bdisableAllHooks\b/, 'disableAllHooks'],
89
+ // @implements A-SPEC-774.26 — a codex hooks key in an interpreter spawn (`['exec','-c','hooks.enabled=false']`), which is
90
+ // read as text, not option by option; it passed before this slice too (measured on the built probe).
91
+ [/\bhooks\.[\w.]*['"]?\s*[:=]/, 'hooks config key'],
92
+ [/--setting-sources\b/, '--setting-sources'],
93
+ [/--settings\b/, '--settings'],
94
+ [/--strict-mcp-config\b/, '--strict-mcp-config'],
95
+ [/--mcp-config\b/, '--mcp-config'],
96
+ [/\b(?:CODEX_HOME|CLAUDE_CONFIG_DIR|XDG_CONFIG_HOME|GEMINI_CONFIG_DIR)\b/, 'settings-directory environment'],
97
+ [/(?<![\w.])['"]?HOME['"]?\s*[:=]/, 'HOME'],
98
+ ];
99
+ function gateOffMarker(text) {
100
+ for (const [re, name] of GATE_OFF_MARKERS) {
101
+ const m = re.exec(text);
102
+ if (m)
103
+ return name === 'settings-directory environment' ? m[0] : name;
104
+ }
105
+ return null;
106
+ }
107
+ /**
108
+ * @implements A-SPEC-774.26 — the words the option check reads. When the agent word is unquoted, each quoted span is one
109
+ * value or prompt (a `-d=` inside `-p "…"` is text) and is kept as a single word marked quoted. When the agent word is
110
+ * itself inside a quoted span (`tmux new -d 'claude --settings x'`), that span's words are the agent's options.
111
+ * Without spans (callers before 774.26) every word is an option word, as before.
112
+ */
113
+ function launchView(words, spans) {
114
+ if (!spans || spans.length !== words.length)
115
+ return { words: [...words], quoted: words.map(() => false) };
116
+ const at = words.findIndex((w) => agentOf(w) !== null);
117
+ const own = at < 0 ? -1 : spans[at];
118
+ // A quoted PROGRAM is a span holding the agent and more words; `'claude' --settings x` quotes only the name, and the
119
+ // words after it are still its options.
120
+ if (own >= 0 && spans.filter((s) => s === own).length > 1) {
121
+ const kept = words.filter((_, i) => spans[i] === own);
122
+ return { words: kept, quoted: kept.map(() => false) };
123
+ }
124
+ const out = [];
125
+ const quoted = [];
126
+ for (let i = 0; i < words.length; i++) {
127
+ if (spans[i] >= 0 && i !== at && i > 0 && spans[i - 1] === spans[i]) {
128
+ out[out.length - 1] += ` ${words[i]}`;
129
+ continue;
130
+ }
131
+ out.push(words[i]);
132
+ // A quoted word that is one argument starting with `-` reaches the agent as an option (`'--settings'`); only text
133
+ // (a prompt, a value) is exempt.
134
+ quoted.push(spans[i] >= 0 && i !== at && !words[i].startsWith('-'));
135
+ }
136
+ return { words: out, quoted };
137
+ }
138
+ /** @implements A-SPEC-774.26 — the option words alone (no quoted prompt text), for the marker check. */
139
+ function launchOptionWords(words, spans) {
140
+ const v = launchView(words, spans);
141
+ return v.words.filter((_, i) => !v.quoted[i]);
142
+ }
143
+ /** The refusal for an interactive launch, or null. `words` is one launching segment (A-SPEC-774.5), quoting removed. */
144
+ function interactiveLaunchIssue(rawWords, spans) {
145
+ const { words, quoted } = launchView(rawWords, spans);
146
+ const at = words.findIndex((w) => agentOf(w) !== null);
147
+ if (at < 0)
148
+ return null;
149
+ for (const w of words.slice(0, at)) {
150
+ const m = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(w);
151
+ if (m && !SAFE_ENV.test(m[1]))
152
+ return `environment prefix ${m[1]} — it can change where the agent loads its settings or hooks`;
153
+ }
154
+ const opts = BY_NAME[agentOf(words[at])] ?? NONE;
155
+ let sawSubcommand = false;
156
+ for (let i = at + 1; i < words.length; i++) {
157
+ const w = words[i];
158
+ if (quoted[i] || !w.startsWith('-') || w === '-') {
159
+ if (!sawSubcommand && opts.subcommands?.has(w))
160
+ sawSubcommand = true;
161
+ continue; // a prompt or subcommand
162
+ }
163
+ const eq = w.indexOf('=');
164
+ const name = eq > 0 && w.startsWith('--') ? w.slice(0, eq) : w;
165
+ if (opts.flags.has(name) && eq < 0)
166
+ continue;
167
+ const rule = opts.values.get(name);
168
+ if (rule === undefined)
169
+ return `option ${w} — not on the list of options known to leave the agent's gate on`;
170
+ const value = eq > 0 && w.startsWith('--') ? w.slice(eq + 1) : words[++i];
171
+ if (value === undefined)
172
+ return `option ${w} without a value`;
173
+ if (rule !== any && !rule(value))
174
+ return `option ${name} ${value} — that value is not known to leave the agent's gate on`;
175
+ }
176
+ return null;
177
+ }
@@ -0,0 +1,17 @@
1
+ export interface ClassifyOptions {
2
+ strict: boolean;
3
+ /** Project-relative POSIX folders the owner declared as test folders (`classification.testDirs`). */
4
+ declaredTestDirs: readonly string[];
5
+ /** True when the project-relative folder holds a gated build manifest. */
6
+ isPackageRoot: (dirRel: string) => boolean;
7
+ }
8
+ export declare function underDeclared(rel: string, declared: readonly string[]): boolean;
9
+ /**
10
+ * The shared table's answer, with the folder rules narrowed under strict: a match that rests only on a `tests?/` folder
11
+ * counts when one such segment's parent is the project root, a package root, or lies under a declared folder.
12
+ */
13
+ export declare function scopedTestFile(rel: string, opts: ClassifyOptions): boolean;
14
+ /** Under strict, the unclassified writes that stay free: documents, assets, data under a test folder, the `.ax/` store. */
15
+ export declare function safeUnclassified(rel: string, opts: ClassifyOptions): boolean;
16
+ /** The options for one judgement: strict in a run or under the owner's opt-in; declared folders in every mode. */
17
+ export declare function classifyOptionsFor(projectRoot: string, run: boolean): ClassifyOptions;
@@ -0,0 +1,135 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.underDeclared = underDeclared;
37
+ exports.scopedTestFile = scopedTestFile;
38
+ exports.safeUnclassified = safeUnclassified;
39
+ exports.classifyOptionsFor = classifyOptionsFor;
40
+ // @implements A-SPEC-775.1
41
+ // What the classifier is told about the mode it judges in. Without options `classifyAction` gives the 0.35.25
42
+ // verdicts; a run (A-SPEC-774.9) or the owner's `classification.strict` opt-in narrows test folders (I1) and makes an
43
+ // unclassified write off the safe list code (I2). The scanner's test table is read, never changed, so the North Star
44
+ // measurement base does not move with the gate.
45
+ const fs = __importStar(require("node:fs"));
46
+ const path = __importStar(require("node:path"));
47
+ const config_1 = require("../config/config");
48
+ const test_files_1 = require("../cpg/test-files");
49
+ /**
50
+ * Manifests that make a folder a package root. Each is an executable artifact (A-SPEC-167), so creating one to fake a
51
+ * package root is itself a WRITE_CODE write. `CMakeLists.txt` and `go.mod` are not gated and do not count.
52
+ */
53
+ const PACKAGE_MANIFESTS = ['package.json', 'Cargo.toml', 'pyproject.toml', 'setup.py', 'pom.xml', 'build.gradle', 'build.gradle.kts'];
54
+ /** The folder-only rules of the shared table: the ones that match on a `tests?/` segment at any depth. */
55
+ const FOLDER_RULES = new Set(['python-dir', 'rust-dir', 'cpp-dir', 'js-test-dir']);
56
+ const cleanDir = (d) => d.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
57
+ function underDeclared(rel, declared) {
58
+ return declared.some((raw) => {
59
+ const d = cleanDir(raw);
60
+ return d !== '' && (rel === d || rel.startsWith(`${d}/`));
61
+ });
62
+ }
63
+ /**
64
+ * The shared table's answer, with the folder rules narrowed under strict: a match that rests only on a `tests?/` folder
65
+ * counts when one such segment's parent is the project root, a package root, or lies under a declared folder.
66
+ */
67
+ function scopedTestFile(rel, opts) {
68
+ const hits = test_files_1.TEST_FILE_PATTERNS.filter(([, re]) => re.test(rel)).map(([name]) => name);
69
+ if (hits.length === 0)
70
+ return false;
71
+ if (!opts.strict || hits.some((h) => !FOLDER_RULES.has(h)))
72
+ return true;
73
+ const segment = hits.every((h) => h === 'rust-dir') ? /^tests$/ : /^tests?$/;
74
+ const segs = rel.split('/');
75
+ for (let i = 0; i < segs.length - 1; i++) {
76
+ if (!segment.test(segs[i]))
77
+ continue;
78
+ const parent = segs.slice(0, i).join('/');
79
+ if (parent === '' || opts.isPackageRoot(parent) || underDeclared(parent, opts.declaredTestDirs))
80
+ return true;
81
+ }
82
+ return false;
83
+ }
84
+ const SAFE_EXT = /\.(?:md|mdx|rst|adoc|txt|png|jpe?g|gif|svg|ico|webp|bmp|pdf|lock)$/i;
85
+ const SAFE_BASE = new Set(['LICENSE', 'NOTICE', 'AUTHORS', 'COPYING']);
86
+ const TEST_DATA_SEGMENT = /^(?:tests?|__tests__|fixtures|__fixtures__|testdata|__snapshots__)$/;
87
+ /** Under strict, the unclassified writes that stay free: documents, assets, data under a test folder, the `.ax/` store. */
88
+ function safeUnclassified(rel, opts) {
89
+ // Outside the project is not this classifier's to promote (the shell gate passes absolute paths through).
90
+ if (rel.startsWith('/') || rel.startsWith('~') || /^[A-Za-z]:\//.test(rel) || rel === '..' || rel.startsWith('../'))
91
+ return true;
92
+ if (rel.startsWith('.ax/'))
93
+ return true;
94
+ const segs = rel.split('/');
95
+ const base = segs[segs.length - 1];
96
+ // Runtime prompts are what the agent executes; never safe, even as markdown.
97
+ if (segs.slice(0, -1).some((s) => /^prompts?$/i.test(s)) || /\.prompt\.md$/i.test(base))
98
+ return false;
99
+ if (/^requirements[^/]*\.txt$/i.test(base))
100
+ return false;
101
+ if (SAFE_EXT.test(base) || SAFE_BASE.has(base))
102
+ return true;
103
+ if (segs.slice(0, -1).some((s) => TEST_DATA_SEGMENT.test(s)))
104
+ return true;
105
+ if (rel.startsWith('src/test/') || rel.includes('/src/test/'))
106
+ return true;
107
+ return underDeclared(rel, opts.declaredTestDirs);
108
+ }
109
+ /** The options for one judgement: strict in a run or under the owner's opt-in; declared folders in every mode. */
110
+ function classifyOptionsFor(projectRoot, run) {
111
+ const cfg = (0, config_1.loadConfig)(projectRoot).classification;
112
+ const memo = new Map();
113
+ return {
114
+ strict: run || cfg.strict,
115
+ declaredTestDirs: cfg.testDirs.map(cleanDir).filter((d) => d !== ''),
116
+ isPackageRoot: (dirRel) => {
117
+ const d = cleanDir(dirRel);
118
+ if (d === '' || d.startsWith('/') || d.split('/').includes('..'))
119
+ return false;
120
+ let hit = memo.get(d);
121
+ if (hit === undefined) {
122
+ hit = PACKAGE_MANIFESTS.some((m) => {
123
+ try {
124
+ return fs.statSync(path.join(projectRoot, d, m)).isFile();
125
+ }
126
+ catch {
127
+ return false;
128
+ }
129
+ });
130
+ memo.set(d, hit);
131
+ }
132
+ return hit;
133
+ },
134
+ };
135
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Shell writes whose target or command is computed at run time. A census of 29 forms (2026-10-19, built hook and
3
+ * 0.35.25) found 19 writes to code files allowed by both: the code-write rule reads a literal destination, so a
4
+ * destination that xargs appends, that find substitutes for `{}`, that a variable holds, or a command word that a
5
+ * variable or an IFS join spells, never reached it. Pure: the hook places the tokens (inside or outside the project).
6
+ */
7
+ export interface DynamicWrites {
8
+ /** Literal destinations named by a runner's sub-command (`find … -exec cp {} src/x.ts \;`). */
9
+ statics: string[];
10
+ /** A write the gate cannot place, with every literal path-like token of the segment. */
11
+ dynamic: {
12
+ why: string;
13
+ tokens: string[];
14
+ } | null;
15
+ }
16
+ /**
17
+ * A variable the command assigned a literal value is that value: `S=/abs/scratch; sed -i … $S/x` writes `/abs/scratch/x`.
18
+ * Measured on this project's own sessions (2026-10-19): without it, 0.4% of 15,798 commands were refused, most of them
19
+ * scratchpad writes through such a variable. A word that still holds `$` or a backtick after expansion stays computed.
20
+ */
21
+ export declare function expandAssigned(text: string, assigned: Map<string, string>): string | null;
22
+ /**
23
+ * Every literal path-like token of a text: words and assignment values, split at an IFS join. The hook reads it over
24
+ * 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
25
+ * another segment than the write (measured on the first build of this slice).
26
+ */
27
+ export declare function pathTokensOf(text: string): string[];
28
+ /**
29
+ * What the whole command says once: the literal assignments, and whether a write verb appears anywhere (a computed
30
+ * command word's verb may sit in an earlier segment — `c=cp; $c …`). Read once per command, not per segment: per segment
31
+ * it was quadratic and a 4,000-segment command passed the 2 s bound (A-SPEC-728 round 38 — measured).
32
+ */
33
+ /**
34
+ * `computed`: a clause of the whole command, split quote-aware, has a command word computed at run time and a write
35
+ * verb appears anywhere. Judged on the whole command, not on the hook's segments: those cut inside quotes and heredoc
36
+ * bodies, and a fragment opening on a quote read as a computed command (4 of 12 refusals in this project's sessions).
37
+ */
38
+ export interface CommandContext {
39
+ assigned: Map<string, string>;
40
+ computed: boolean;
41
+ }
42
+ export declare function commandContext(commandText: string): CommandContext;
43
+ export declare function dynamicWrites(segmentText: string, context?: CommandContext): DynamicWrites;