@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,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-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
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");
@@ -429,6 +432,12 @@ function namesProtectedAx(text) {
429
432
  function prefixBareRelative(text, dir) {
430
433
  return text.replace(/(^|[\s>|])(?![-/~'"])([\w@.][\w@./-]*)/g, (full, pre, p) => /^[A-Za-z0-9_.@-]+$/.test(p) || p.includes('/') ? `${pre}${dir}/${p}` : full);
431
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, '/');
432
441
  /**
433
442
  * The segment with only its redirect targets that name a protected `.ax` child read under the store (`> ledger/x`,
434
443
  * `>> "specs/y"`, `>&state/z`); a `>` inside quotes is not a redirect.
@@ -436,6 +445,7 @@ function prefixBareRelative(text, dir) {
436
445
  * @implements A-SPEC-728 (rule 34)
437
446
  */
438
447
  function redirectTargetsUnder(text, ax) {
448
+ ax = slashed(ax); // A-SPEC-728.3
439
449
  const masked = maskQuoted(text);
440
450
  // Rule 35: the descriptor digits start at a non-digit (a 100 KB digit run took 5 s — measured), and `<>` is a write.
441
451
  if (!text.includes('>'))
@@ -517,7 +527,8 @@ function segmentFlattened(cmd, root, start = root) {
517
527
  // @implements A-SPEC-728 (rule 44) — `only` limits the prefix to the words that match it: at a climb base (`.ax/~/…`, a
518
528
  // placeholder for an unprotected child) only a word that climbs can leave the placeholder, and prefixing all 131,000 words
519
529
  // of a 256 KB segment at each of 8 climb bases built ~60 MB for the path rules (3.7 s — measured).
520
- const rewrite = (text, dir, globs = false, only) => {
530
+ const rewrite = (text, native, globs = false, only) => {
531
+ const dir = slashed(native); // A-SPEC-728.3
521
532
  let first = true;
522
533
  const word = globs ? /(^|[\s>|])(['"]?)(?![-/~'"])([\w@.*?[{][\w@./*?[\]{},-]*)/g : /(^|[\s>|])(['"]?)(?![-/~'"])([\w@.][\w@./-]*)/g;
523
534
  const plain = globs ? /^[A-Za-z0-9_.@*?[\]{},-]+$/ : /^[A-Za-z0-9_.@-]+$/;
@@ -526,7 +537,11 @@ function segmentFlattened(cmd, root, start = root) {
526
537
  first = false;
527
538
  if (skip || (only !== undefined && !only.test(p)))
528
539
  return full;
529
- 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}`;
530
545
  });
531
546
  };
532
547
  // Round 17: from the directory the harness runs the shell in (`start`), not always the root.
@@ -594,7 +609,7 @@ function segmentFlattened(cmd, root, start = root) {
594
609
  // judged by the enumerated channels alone (round 29).
595
610
  // Rule 35 (owner decision 2026-09-26): that channel net is removed — it refused `terraform state rm`, `docker run --rm …
596
611
  // specs/` and `npx jest specs/rm.test.ts` (measured); an unrecognised wrapper or runner is a named residual.
597
- 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}`);
598
613
  // @implements A-SPEC-728 (rule 39) — when the bases are unknown, for any reason, a literal cd may have gone unapplied; if one
599
614
  // of them lands in the store (by identity: `axl -> .ax` counts) from the start or from any base, a segment recognised as
600
615
  // writing is judged at the store and at each protected child too, glob-leading words included. Rule 38 read the whole
@@ -675,6 +690,29 @@ function normalizeCommandPaths(cmd, followCd = true) {
675
690
  // `\b…\b` test stays; `docs/install-guide.md` beside an .ax path is still refused, on purpose, until a rule exists
676
691
  // that the shell cannot split around.
677
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'));
678
716
  // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
679
717
  // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
680
718
  // here, so this is deliberately conservative on the .ax governance surface only.
@@ -754,7 +792,7 @@ function splitShellClauses(cmd) {
754
792
  * @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
755
793
  * escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
756
794
  */
757
- function splitUnquoted(cmd) {
795
+ function splitUnquoted(cmd, atPipe = true) {
758
796
  const out = [];
759
797
  let cur = '';
760
798
  let quote = null;
@@ -806,9 +844,13 @@ function splitUnquoted(cmd) {
806
844
  cur = '';
807
845
  continue;
808
846
  }
809
- if (ch === '|') {
810
- if (cmd[i + 1] === '|')
811
- i++;
847
+ if (ch === '|' && cmd[i + 1] === '|') {
848
+ i++;
849
+ out.push(cur);
850
+ cur = '';
851
+ continue;
852
+ }
853
+ if (ch === '|' && atPipe) {
812
854
  out.push(cur);
813
855
  cur = '';
814
856
  continue;
@@ -966,15 +1008,18 @@ function isReadOnlyShellClause(clause) {
966
1008
  return k < tokens.length && isReadOnlyShellClause(tokens.slice(k).join(' '));
967
1009
  }
968
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);
969
1014
  // @implements A-SPEC-747 — `-C <dir>` (repeatable) and `--no-pager` come before the sub-command; any other global
970
1015
  // option is not a read (`-c core.fsmonitor=…` runs a program on `status`, `--git-dir`/`--work-tree` retarget it).
971
1016
  let k = 1;
972
- while (k < tokens.length && tokens[k].startsWith('-')) {
973
- if (tokens[k] === '-C') {
1017
+ while (k < words.length && words[k].startsWith('-')) {
1018
+ if (words[k] === '-C') {
974
1019
  k += 2;
975
1020
  continue;
976
1021
  }
977
- if (tokens[k] === '--no-pager') {
1022
+ if (words[k] === '--no-pager') {
978
1023
  k++;
979
1024
  continue;
980
1025
  }
@@ -983,8 +1028,8 @@ function isReadOnlyShellClause(clause) {
983
1028
  // The sub-command is read by its last path part: the per-segment flattening prefixes every word after a moved
984
1029
  // base (`git status` → `git <dir>/status`), which read as no known sub-command (measured on a census read). A real
985
1030
  // git given a path-shaped sub-command only fails, and a write sub-command is not a read under any prefix.
986
- const sub = k < tokens.length ? tokens[k].replace(/^.*\//, '') : '';
987
- 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'));
988
1033
  }
989
1034
  // @implements A-SPEC-747 — `date` reads unless it sets the clock (`-s`, `--set`, or an operand that is not a `+FORMAT`).
990
1035
  if (name === 'date')
@@ -1563,18 +1608,181 @@ function shellWritesProtectedAx(ncmd) {
1563
1608
  // after `>`, so `>& path` and `>| path` (a `&` or `|` first) are never seen, and `cd .ax; echo x >& ledger/…` passed once
1564
1609
  // `cd` became a read (measured while building this slice). Before A-SPEC-747 every command with a `cd` was refused, so
1565
1610
  // this keeps that shape exactly as refused as it was.
1566
- let sawCd = false;
1567
- return !clausesAreReads(splitShellClauses(ncmd), (c) => {
1568
- if (/^cd(?:\s|$)/.test(c))
1569
- sawCd = true;
1570
- else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1571
- return false;
1572
- // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1573
- // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1574
- if (COMPUTED_REDIRECT_RE.test(c))
1575
- return false;
1576
- return clauseIsRead(c, isRead);
1577
- });
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;
1578
1786
  }
1579
1787
  /**
1580
1788
  * @implements A-SPEC-125.1
@@ -1638,7 +1846,7 @@ function classifyReversibilityAsWritten(action) {
1638
1846
  const axChannel = REMOVAL_VERB_RE.test(ncmd) && namesProtectedAx(ncmd)
1639
1847
  ? 'removal, move or copy command targets a protected .ax governance path'
1640
1848
  : CLOBBER_AX_RE.test(ncmd) ? 'output redirection writes into a protected .ax governance path'
1641
- : 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'
1642
1850
  : INTERPRETER_AX_RE.test(ncmd)
1643
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'
1644
1852
  : undefined;
@@ -1655,6 +1863,14 @@ function classifyReversibilityAsWritten(action) {
1655
1863
  reasons: ['shell command over a protected .ax governance path is not recognisably read-only'],
1656
1864
  };
1657
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
+ }
1658
1874
  // A destructive recursive `rm` — either `-rf` on a non-safe target, or a recursive delete of
1659
1875
  // a catastrophic root (/, ~, $HOME, ., .., glob) even WITHOUT `-f` — is whole-tree destruction,
1660
1876
  // unconditionally hard-hitl regardless of `tracked`. The single-file `tracked===true` auto
@@ -42,7 +42,22 @@ export interface RiskAction {
42
42
  * starts from; defaults to `projectRoot`.
43
43
  */
44
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;
45
52
  }
53
+ export type StagedStoreSignal = {
54
+ specsDir: string;
55
+ tracked: boolean;
56
+ untracked: boolean;
57
+ } | {
58
+ specsDir: string;
59
+ unanswered: true;
60
+ };
46
61
  export interface RiskThresholds {
47
62
  blastRadiusConfirm?: number;
48
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 {};