@holmes-lab/holmes-kit 0.35.0 → 0.35.2

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 (50) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +7 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve.js +9 -2
  5. package/dist/holmes/cli/codex-oracle.js +36 -2
  6. package/dist/holmes/cli/doctor.d.ts +14 -1
  7. package/dist/holmes/cli/doctor.js +355 -72
  8. package/dist/holmes/cli/index.d.ts +1 -1
  9. package/dist/holmes/cli/index.js +38 -5
  10. package/dist/holmes/cli/init.d.ts +2 -0
  11. package/dist/holmes/cli/init.js +37 -1
  12. package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
  13. package/dist/holmes/cli/runtime-binding-approval.js +102 -0
  14. package/dist/holmes/cli/runtime-binding.d.ts +45 -0
  15. package/dist/holmes/cli/runtime-binding.js +630 -0
  16. package/dist/holmes/governance/approval-grants.d.ts +7 -0
  17. package/dist/holmes/governance/approval-grants.js +8 -2
  18. package/dist/holmes/governance/approval-queue.d.ts +2 -0
  19. package/dist/holmes/governance/approval-queue.js +11 -4
  20. package/dist/holmes/governance/autonomy.d.ts +9 -0
  21. package/dist/holmes/governance/autonomy.js +65 -13
  22. package/dist/holmes/guardrail/risk-classifier.js +76 -26
  23. package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
  24. package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
  25. package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
  26. package/dist/holmes/guardrail/shell-syntax.js +489 -0
  27. package/dist/holmes/guardrail/shell-words.d.ts +2 -18
  28. package/dist/holmes/guardrail/shell-words.js +15 -441
  29. package/dist/holmes/guardrail/write-target.d.ts +54 -0
  30. package/dist/holmes/guardrail/write-target.js +327 -1
  31. package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
  32. package/dist/holmes/guardrail/write-verb-word.js +55 -0
  33. package/dist/holmes/hooks/pre-tool-use.d.ts +14 -0
  34. package/dist/holmes/hooks/pre-tool-use.js +391 -66
  35. package/dist/holmes/mcp/handlers/spec-approval.js +14 -2
  36. package/dist/holmes/mcp/handlers.d.ts +9 -1
  37. package/dist/holmes/mcp/handlers.js +6 -4
  38. package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
  39. package/dist/holmes/mcp/harness-attestation.js +70 -3
  40. package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
  41. package/dist/holmes/mcp/operator-recovery.js +66 -0
  42. package/dist/holmes/mcp/server.js +6 -3
  43. package/dist/holmes/runtime/binding.d.ts +30 -0
  44. package/dist/holmes/runtime/binding.js +164 -0
  45. package/dist/holmes/runtime/dispatch.d.ts +9 -0
  46. package/dist/holmes/runtime/dispatch.js +169 -0
  47. package/dist/holmes/runtime/hook-process.d.ts +11 -0
  48. package/dist/holmes/runtime/hook-process.js +130 -0
  49. package/docs/install-guide.md +65 -0
  50. package/package.json +1 -1
@@ -33,13 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.GRANTS_RELDIR = void 0;
36
+ exports.GRANT_NO_EXPIRY = exports.GRANTS_RELDIR = void 0;
37
37
  exports.readGrants = readGrants;
38
38
  exports.refusedGrantReasons = refusedGrantReasons;
39
39
  exports.pickCoveringGrant = pickCoveringGrant;
40
40
  exports.resolveApproval = resolveApproval;
41
41
  exports.consumeGrantFile = consumeGrantFile;
42
- // @implements A-SPEC-245
42
+ // @implements A-SPEC-245, A-SPEC-532.5
43
43
  const fs = __importStar(require("node:fs"));
44
44
  const path = __importStar(require("node:path"));
45
45
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -105,6 +105,12 @@ function readGrants(root) {
105
105
  }
106
106
  return { grants, ignored };
107
107
  }
108
+ /**
109
+ * @implements A-SPEC-532.5 — the `expires` a subject-bound grant carries: it keeps the field every grant must have
110
+ * (a grant is narrow: scope, expires, nonce) and the comparison every consumer already makes, while the grant's
111
+ * `lifetime: 'until-used'` says in words that no time limit was meant.
112
+ */
113
+ exports.GRANT_NO_EXPIRY = '9999-12-31T23:59:59.999Z';
108
114
  /** The current workspace id, or undefined for a legacy workspace / an unreadable identity. */
109
115
  function currentWorkspaceId(root) {
110
116
  try {
@@ -201,6 +201,8 @@ export declare function queueHint(root: string, req: {
201
201
  why: string;
202
202
  } & RequestDetails, opts?: {
203
203
  baseReasonBytes?: number;
204
+ reviewCommand?: string;
205
+ pendingHint?: (id: string) => string;
204
206
  }): string;
205
207
  /**
206
208
  * @implements A-SPEC-690
@@ -47,7 +47,7 @@ exports.queueHint = queueHint;
47
47
  exports.grantableRequests = grantableRequests;
48
48
  exports.openOccurrences = openOccurrences;
49
49
  exports.asPendingRequest = asPendingRequest;
50
- // @implements A-SPEC-244, A-SPEC-626
50
+ // @implements A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754
51
51
  const execution_context_1 = require("../project/execution-context");
52
52
  const root_1 = require("../project/root");
53
53
  const node_crypto_1 = require("node:crypto");
@@ -86,7 +86,7 @@ exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
86
86
  // request went to the refusal log so the inbox stayed empty (measured 2026-09-14 on Windows: two
87
87
  // expired session dialogs, then `approve --list` answered "No requests awaiting approval").
88
88
  exports.DECISION_KINDS = new Set([
89
- 'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal', 'review-resolve',
89
+ 'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal', 'review-resolve', 'governance-wiring',
90
90
  ]);
91
91
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
92
92
  function refusalsFilename(replica) {
@@ -491,7 +491,14 @@ function queueHint(root, req, opts) {
491
491
  // Round-6 established that flattening is not enough once text is folded, and gave `[v]` a
492
492
  // template-owned margin; this producer, read by the operator AND relayed by the agent, never got
493
493
  // one. The first row keeps the template's own opening; the rest sit under the margin.
494
- return (0, screen_safe_1.wrapColumns)(`\n[보류 — 운영자 질문: ${(0, screen_safe_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`
494
+ const question = `\n[보류 — 운영자 질문: ${(0, screen_safe_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`;
495
+ if (opts?.reviewCommand) {
496
+ // Fold only prose: inserted newlines/margins inside literal shell paths
497
+ // would change the command the operator is being asked to execute.
498
+ return (0, screen_safe_1.wrapColumns)(question + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자 승인 UI에서 내립니다.', 76, ' \u2502 ')
499
+ + `\n운영자 검토: ${opts.reviewCommand}`;
500
+ }
501
+ return (0, screen_safe_1.wrapColumns)(question
495
502
  + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 내립니다.`, 76, ' \u2502 ');
496
503
  }
497
504
  const decided = state.decisions[id];
@@ -501,7 +508,7 @@ function queueHint(root, req, opts) {
501
508
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
502
509
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
503
510
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
504
- const hint = `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
511
+ const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : `\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`);
505
512
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
506
513
  ? hint
507
514
  : denialLine;
@@ -26,6 +26,15 @@ export declare function descendantAspecs(spec: Spec, all: Spec[]): Spec[];
26
26
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
27
27
  */
28
28
  export declare function specApprovalAutonomy(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): ApprovalAutonomy;
29
+ export declare function declaredGateDirection(spec: Spec): 'tightens' | 'wording' | null;
30
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
31
+ export declare function autonomyRuleMeaning(rule: string): string;
32
+ /**
33
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
34
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
35
+ * could tell which rule had fired.
36
+ */
37
+ export declare function specApprovalAutonomyReason(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): string | null;
29
38
  /**
30
39
  * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
31
40
  * presented in-session while autonomous mode is enabled. This is intentionally narrower than
@@ -37,6 +37,9 @@ exports.SESSION_AUTONOMY_MARKER = exports.AUTONOMY_ENV = void 0;
37
37
  exports.isHighRiskPath = isHighRiskPath;
38
38
  exports.descendantAspecs = descendantAspecs;
39
39
  exports.specApprovalAutonomy = specApprovalAutonomy;
40
+ exports.declaredGateDirection = declaredGateDirection;
41
+ exports.autonomyRuleMeaning = autonomyRuleMeaning;
42
+ exports.specApprovalAutonomyReason = specApprovalAutonomyReason;
40
43
  exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
41
44
  exports.sessionAutonomyActive = sessionAutonomyActive;
42
45
  exports.projectDefaultAutonomy = projectDefaultAutonomy;
@@ -45,7 +48,7 @@ exports.autonomyBanner = autonomyBanner;
45
48
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
46
49
  exports.versionBumpKind = versionBumpKind;
47
50
  exports.releaseAutonomy = releaseAutonomy;
48
- // @implements A-SPEC-532.1, A-SPEC-718
51
+ // @implements A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4
49
52
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
50
53
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
51
54
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -155,40 +158,89 @@ function descendantAspecs(spec, all) {
155
158
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
156
159
  */
157
160
  function specApprovalAutonomy(spec, resolveParent, descendants) {
161
+ // @implements A-SPEC-532.3 — one walk: the verdict is "no rule fired", so it cannot disagree with the rule's name.
162
+ return specApprovalAutonomyReason(spec, resolveParent, descendants) === null ? 'auto' : 'hitl';
163
+ }
164
+ /**
165
+ * @implements A-SPEC-532.4 — the declared direction of a gate change: `gate-behavior: tightens — …` (nothing refused
166
+ * before passes after) or `gate-behavior: wording — …` (no input changes side). Owner decision 2026-10-05: these are
167
+ * sealed autonomously; any other gate change asks the owner. The word is the first of the reason, read
168
+ * case-sensitively, and must be followed by white space or a dash.
169
+ */
170
+ function gateDirection(spec) {
171
+ const raw = spec.frontmatter?.breaking_change;
172
+ if (typeof raw !== 'string')
173
+ return null;
174
+ const m = /^\s*gate-behavior\s*:\s*(tightens|wording)(?=[\s—–-])/.exec(raw);
175
+ return m ? m[1] : null;
176
+ }
177
+ function declaredGateDirection(spec) {
178
+ return spec.type === 'A-SPEC' ? gateDirection(spec) : null;
179
+ }
180
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
181
+ function autonomyRuleMeaning(rule) {
182
+ if (rule.startsWith('files-to-touch-gate-file'))
183
+ return 'Files to Touch names a gate or governance file and the spec declares no tightening-only or wording-only gate change';
184
+ if (rule === 'breaking-change-gate-behavior')
185
+ return 'the gate change does not declare its direction as tightens or wording';
186
+ if (rule.startsWith('breaking-change-'))
187
+ return rule === 'breaking-change-undeclared' ? 'breaking_change is not declared' : 'the breaking_change grade is not one the grader knows';
188
+ switch (rule) {
189
+ case 'upstream-without-aspec': return 'no A-SPEC exists beneath it yet, so its scope is unknown';
190
+ case 'upstream-has-human-aspec': return 'an A-SPEC beneath it is the operator\'s to seal';
191
+ case 'architecture-document': return 'a C-SPEC or ADR is a decision';
192
+ case 'files-to-touch-empty': return 'Files to Touch names no path, so its scope is unbounded';
193
+ case 'files-to-touch-root-only': return 'Files to Touch names only root-level files';
194
+ case 'requirement-without-intake': return 'the requirement was never admitted through requirement_triage';
195
+ default: return 'the spec kind is not one the grader knows';
196
+ }
197
+ }
198
+ /**
199
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
200
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
201
+ * could tell which rule had fired.
202
+ */
203
+ function specApprovalAutonomyReason(spec, resolveParent, descendants) {
158
204
  switch (spec.type) {
159
205
  case 'T-SPEC':
160
- return 'auto'; // tests are low risk
206
+ return null; // tests are low risk
161
207
  case 'REQ':
162
208
  case 'H-SPEC': {
163
209
  const below = (descendants ?? []).filter((s) => s.type === 'A-SPEC');
164
210
  if (below.length === 0)
165
- return 'hitl'; // unknown scope stays human
166
- return below.every((a) => specApprovalAutonomy(a, resolveParent) === 'auto') ? 'auto' : 'hitl';
211
+ return 'upstream-without-aspec'; // unknown scope stays human
212
+ return below.every((a) => specApprovalAutonomyReason(a, resolveParent) === null) ? null : 'upstream-has-human-aspec';
167
213
  }
168
214
  case 'C-SPEC':
169
215
  case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
170
- return 'hitl'; // architecture / structural constraint — the owner's exception
216
+ return 'architecture-document'; // architecture / structural constraint — the owner's exception
171
217
  case 'A-SPEC': {
172
218
  const grade = breakingGrade(spec);
173
- if (grade === null || !AUTO_GRADES.has(grade))
174
- return 'hitl'; // undeclared or gate-behavior
219
+ if (grade === null)
220
+ return 'breaking-change-undeclared';
221
+ // @implements A-SPEC-532.4 — a gate change that declares tightening or wording passes the grade rule and the
222
+ // gate-file rule; an undirected one, and a gate file under any other grade, do not.
223
+ const directed = grade === 'gate-behavior' && gateDirection(spec) !== null;
224
+ if (!directed && !AUTO_GRADES.has(grade))
225
+ return `breaking-change-${grade}`; // gate-behavior, or unrecognised
175
226
  const paths = (0, scope_judgment_1.fttPathTokens)(spec.sections['Files to Touch'] ?? '');
176
227
  // @implements A-SPEC-556.1 — no path tokens (prose-only / empty FtT) is an UNCONSTRAINED scope:
177
228
  // the enforcer imposes nothing, so the spec can write ANYWHERE incl. the gate. Never self-approve.
178
229
  if (paths.length === 0)
179
- return 'hitl';
180
- if (paths.some(isHighRiskPath))
181
- return 'hitl'; // gate/governance/taint file
230
+ return 'files-to-touch-empty';
231
+ const gateFile = paths.find(isHighRiskPath);
232
+ if (gateFile !== undefined && !directed)
233
+ return `files-to-touch-gate-file: ${gateFile}`; // gate/governance/taint file
182
234
  // @implements A-SPEC-654 — a ROOT-level file is project-wide configuration (the test runner, the
183
235
  // manifest, the ignore policy): admitting it at the gate was the point of that slice, but grading
184
236
  // it auto would be a widening nobody asked for. A spec earns self-approval only when it also names
185
237
  // a directory-scoped surface — the same doubt `paths.length === 0` already encodes.
186
238
  if (!paths.some((p) => p.includes('/')))
187
- return 'hitl';
188
- return 'auto';
239
+ return 'files-to-touch-root-only';
240
+ return null;
189
241
  }
190
242
  default:
191
- return 'hitl'; // unknown kind: fail-safe to human
243
+ return 'unknown-kind'; // unknown kind: fail-safe to human
192
244
  }
193
245
  }
194
246
  /**
@@ -44,12 +44,14 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
44
  exports.classifySecret = classifySecret;
45
45
  exports.classifyBlastRadius = classifyBlastRadius;
46
46
  exports.assessRisk = assessRisk;
47
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747
47
+ // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
+ const shell_argument_roles_1 = require("./shell-argument-roles");
51
+ const write_target_1 = require("./write-target");
50
52
  const risk_types_1 = require("./risk-types");
51
53
  const linear_match_1 = require("./linear-match");
52
- const write_target_1 = require("./write-target");
54
+ const write_target_2 = require("./write-target");
53
55
  const AWS_KEY_RE = /AKIA[0-9A-Z]{16}/;
54
56
  const PEM_KEY_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
55
57
  const SECRET_KV_RE = /(password|passwd|secret|token|api[_-]?key)\s*[:=]\s*\S{6,}/i;
@@ -313,6 +315,12 @@ function normalizeWindowsPathSpellings(cmd) {
313
315
  .replace(/(^|[\s'"=(])\/([A-Za-z])\/(?=[^\s'"()/])/g, (_m, pre, d) => `${pre}${d.toLowerCase()}:/`);
314
316
  }
315
317
  function scopeAxToProject(cmd, projectRoot) {
318
+ return scopeAxWithPlaceholder(cmd, projectRoot, false);
319
+ }
320
+ // Keep the diagnostic representation stable, but never introduce shell operators into text
321
+ // that will be classified again: a synthetic `>` can target the next real governance path.
322
+ function scopeAxWithPlaceholder(cmd, projectRoot, forClassification) {
323
+ const placeholder = forClassification ? '__other_project_path__' : '<other-project-path>';
316
324
  const spelled = normalizeWindowsPathSpellings(cmd);
317
325
  if (!projectRoot)
318
326
  return spelled;
@@ -329,7 +337,10 @@ function scopeAxToProject(cmd, projectRoot) {
329
337
  // time: the regex rescanned each run of path characters from every `=` (256 KB of `=/` met the hook's 20 s wall —
330
338
  // measured). A match lies inside one maximal run of `[^\s'"()]` and extends to its end, so each run needs only its last
331
339
  // `/.ax/` and its leftmost start: the run's first character after a boundary other than `)`, or one after an `=` inside it.
332
- const RUN = /[^\s'"()]+/g;
340
+ // Preserve shell syntax attached to a masked path: redirects, control operators,
341
+ // substitution delimiters and escapes must reach the downstream shell checks intact.
342
+ // The public diagnostic rendering retains its historical contract.
343
+ const RUN = forClassification ? /[^\s'"();&|<>`$\\]+/g : /[^\s'"()]+/g;
333
344
  let out = '';
334
345
  let last = 0;
335
346
  for (let m = RUN.exec(spelled); m !== null; m = RUN.exec(spelled)) {
@@ -353,7 +364,7 @@ function scopeAxToProject(cmd, projectRoot) {
353
364
  continue;
354
365
  const pre = start === 0 ? '' : spelled[start - 1];
355
366
  const abs = spelled.slice(start, b);
356
- out += spelled.slice(last, start === 0 ? 0 : start - 1) + (inside(abs) ? pre + abs : `${pre}<other-project-path>`);
367
+ out += spelled.slice(last, start === 0 ? 0 : start - 1) + (inside(abs) ? pre + abs : pre + placeholder);
357
368
  last = b;
358
369
  }
359
370
  return out + spelled.slice(last);
@@ -380,6 +391,22 @@ const REMOVAL_VERB_RE = /\b(rm|rmdir|unlink|git\s+rm|git\s+mv|mv|cp)\b/i;
380
391
  // 240 000 of them). A later `>` inside an already-scanned token can only see a suffix of it.
381
392
  const CLOBBER_AX_RE = (0, linear_match_1.redirectTokenTester)(new RegExp(String.raw `\.ax/(${PROTECTED_AX_ALT})\b`, 'i'));
382
393
  const CMD_PROTECTED_AX_RE = new RegExp(String.raw `(^|[\s'"=(/])\.ax/(${PROTECTED_AX_ALT})(/|\b)`, 'i');
394
+ // No boundary after the child either: under a separator the text does not show, `mvq.ax/specsq/tmp/z` is `mv .ax/specs /tmp/z`.
395
+ const PROTECTED_AX_ANYWHERE_RE = new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})`, 'i');
396
+ /**
397
+ * @implements A-SPEC-226.1 — does the text name a protected .ax path. The pattern above asks for white space, a quote,
398
+ * `=`, `(` or `/` before `.ax/`, so a path glued to an expansion was not one: `rm${IFS}-rf${IFS}.ax/specs/…` and
399
+ * `rm$IFS-rf$IFS.ax/specs` were allowed while `rm -rf .ax/specs/…` was refused (shipped through 0.35.1; measured
400
+ * 2026-10-05). Only tightens: everything the old pattern matched still matches. One linear pattern test.
401
+ */
402
+ function namesProtectedAx(text) {
403
+ // @implements A-SPEC-226.2 — the spelling counts wherever it appears. A-SPEC-226.1 kept "a spelling that continues a
404
+ // longer file name" out, and its re-review (2026-10-05) passed removals through exactly that door: `rm -f $-.ax/specs/…`
405
+ // (dash), `rm -f $X:t.ax/specs/…` (zsh), `P=q.ax/specs; mv ${P#q} /tmp/gone`, `echo mvq.ax/specsq/tmp/z | tr q ' ' | sh`,
406
+ // `sed -n w.ax/ledger/p.jsonl /dev/null`. The text cannot tell a longer file name from a prefix the shell removes, so
407
+ // it no longer tries; 226.1's three rules are subsumed. Cost, stated: `backup.ax/specs` is judged as the store.
408
+ return CMD_PROTECTED_AX_RE.test(text) || PROTECTED_AX_ANYWHERE_RE.test(text);
409
+ }
383
410
  /**
384
411
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
385
412
  * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
@@ -403,7 +430,7 @@ function redirectTargetsUnder(text, ax) {
403
430
  return text;
404
431
  // Rule 36: the digits have their own lookbehind; the operator only must not follow `<`/`>` (`2>&1>ledger/x` matched no
405
432
  // start and passed — measured).
406
- const re = new RegExp(`((?:(?<![0-9&<>])(?:[0-9]+|&))?(?<![<>])(?:>{1,2}[|!&]?|<>)[ \\t]*)(['"]?)(?:\\./)*((?:${write_target_1.AX_PROTECTED_CHILDREN.join('|')})(?:/[^\\s'"<>|;&()]*)?)(?=[\\s'"<>|;&()]|$)`, 'g');
433
+ const re = new RegExp(`((?:(?<![0-9&<>])(?:[0-9]+|&))?(?<![<>])(?:>{1,2}[|!&]?|<>)[ \\t]*)(['"]?)(?:\\./)*((?:${write_target_2.AX_PROTECTED_CHILDREN.join('|')})(?:/[^\\s'"<>|;&()]*)?)(?=[\\s'"<>|;&()]|$)`, 'g');
407
434
  return text.replace(re, (whole, op, q, p, at) => (masked[at + op.indexOf('>')] === '>' ? `${op}${q}${ax}/${p}` : whole));
408
435
  }
409
436
  /**
@@ -426,8 +453,8 @@ function cdReachesStore(cb, start, rootAx) {
426
453
  const realAx = real(rootAx);
427
454
  const seen = new Set();
428
455
  for (const arg of cb.literal) {
429
- for (const b of (0, write_target_1.absoluteKindOf)(arg) !== null ? [arg] : bases) {
430
- const to = (0, write_target_1.absoluteKindOf)(arg) !== null ? (0, write_target_1.pathFlavorFor)(arg, arg).resolve(arg) : (0, write_target_1.pathFlavorFor)(b, arg).resolve(b, arg);
456
+ for (const b of (0, write_target_2.absoluteKindOf)(arg) !== null ? [arg] : bases) {
457
+ const to = (0, write_target_2.absoluteKindOf)(arg) !== null ? (0, write_target_2.pathFlavorFor)(arg, arg).resolve(arg) : (0, write_target_2.pathFlavorFor)(b, arg).resolve(b, arg);
431
458
  if (seen.has(to))
432
459
  continue;
433
460
  seen.add(to);
@@ -491,7 +518,7 @@ function segmentFlattened(cmd, root, start = root) {
491
518
  });
492
519
  };
493
520
  // Round 17: from the directory the harness runs the shell in (`start`), not always the root.
494
- const segments = (0, write_target_1.shellSegments)(cmd, start);
521
+ const segments = (0, write_target_2.shellSegments)(cmd, start);
495
522
  // @implements A-SPEC-728 (round 11) — a null-base segment MAY run in any base the command produced
496
523
  // (`maybe`); the ones under `.ax` matter, keyed by the top-level `.ax` child so the rewrite count is
497
524
  // bounded by the store's layout, not the command's length (measured: `git log; cd sub; cd ../.ax;
@@ -509,12 +536,12 @@ function segmentFlattened(cmd, root, start = root) {
509
536
  // @implements A-SPEC-728 (round 23) — every segment is also judged from every directory under `.ax` the command may
510
537
  // run ANY part in (flow-insensitive): a loop, a function or a trap runs text after a later `cd .ax` (measured: `for …;
511
538
  // do rm ledger/provenance.jsonl; cd .ax; done` deleted the ledger). An unknown set on a `.ax` mention adds `.ax`.
512
- const cb = (0, write_target_1.commandBases)(cmd, start, segments);
539
+ const cb = (0, write_target_2.commandBases)(cmd, start, segments);
513
540
  for (const b of cb.bases)
514
541
  candidates.add(b);
515
- if (cb.unknown !== null && (0, write_target_1.mentionsAxSpelling)(cmd)) {
542
+ if (cb.unknown !== null && (0, write_target_2.mentionsAxSpelling)(cmd)) {
516
543
  candidates.add(path.join(start, '.ax'));
517
- for (const c of write_target_1.AX_PROTECTED_CHILDREN)
544
+ for (const c of write_target_2.AX_PROTECTED_CHILDREN)
518
545
  candidates.add(path.join(start, '.ax', c));
519
546
  }
520
547
  // @implements A-SPEC-728 (rule 39) — a store key is only as deep as the command's longest `../` climb needs (a `cd` 1,000
@@ -522,7 +549,7 @@ function segmentFlattened(cmd, root, start = root) {
522
549
  let climb = 0;
523
550
  for (const m of cmd.matchAll(/(?:\.\.[\\/])+/g))
524
551
  climb = Math.max(climb, m[0].length / 3);
525
- const keys = (0, write_target_1.axCandidateKeys)(root, candidates, climb + 1);
552
+ const keys = (0, write_target_2.axCandidateKeys)(root, candidates, climb + 1);
526
553
  const forms = [];
527
554
  // @implements A-SPEC-728 (rule 44) — every form is kept within one budget: past FORMS_MAX characters the command is too large
528
555
  // to judge (after `cd .ax; cd "$X"`, `sed -i` over 131,000 words was rewritten at the store and each protected child, ~150 MB
@@ -537,10 +564,10 @@ function segmentFlattened(cmd, root, start = root) {
537
564
  // @implements A-SPEC-728 (round 24) — an unknown set on a command that never spells `.ax`: a path whose first component is a
538
565
  // protected `.ax` child is judged under the store too (`cd "$(printf '.%s' ax)" && echo x > ledger/provenance.jsonl` was
539
566
  // allowed — measured). Only those paths, so an ordinary relative write is not read as a store write.
540
- const axChildren = cb.unknown !== null && !(0, write_target_1.mentionsAxSpelling)(cmd) ? path.join(root, '.ax') : null;
567
+ const axChildren = cb.unknown !== null && !(0, write_target_2.mentionsAxSpelling)(cmd) ? path.join(root, '.ax') : null;
541
568
  // Round 25: `./ledger/…` too. Round 28: after `=` and `(`, before `)`/`>`/`;`/`&`/`|`, with glob and brace characters
542
569
  // (`cp a --target-directory=ledger`, `rm ledger/*` — measured).
543
- const childRe = new RegExp(`(^|[\\s>|=(])(['"]?)(?:\\./)*((?:${write_target_1.AX_PROTECTED_CHILDREN.join('|')})(?:/[^\\s'"<>|;&()]*)?)(?=[\\s'"<>|;&()]|$)`, 'g');
570
+ const childRe = new RegExp(`(^|[\\s>|=(])(['"]?)(?:\\./)*((?:${write_target_2.AX_PROTECTED_CHILDREN.join('|')})(?:/[^\\s'"<>|;&()]*)?)(?=[\\s'"<>|;&()]|$)`, 'g');
544
571
  // Round 26: only a segment that writes or removes (reads of an ordinary top-level `specs/` after a computed cd were
545
572
  // denied — measured).
546
573
  // Round 27: inverted — a segment skips this reading only when it is recognisably read-only and redirects nothing into a
@@ -563,7 +590,7 @@ function segmentFlattened(cmd, root, start = root) {
563
590
  // regression); rule 37 read it never, which let 64 no-op cds before `eval 'cd axl/specs/01_req'` carry `sed -i` into the
564
591
  // store. Past 16,384 argument-base pairs the store is read without looking.
565
592
  const rootAx = path.join(root, '.ax');
566
- const storeBases = cb.unknown !== null && cdReachesStore(cb, start, rootAx) ? [rootAx, ...write_target_1.AX_PROTECTED_CHILDREN.map((c) => path.join(rootAx, c))] : [];
593
+ const storeBases = cb.unknown !== null && cdReachesStore(cb, start, rootAx) ? [rootAx, ...write_target_2.AX_PROTECTED_CHILDREN.map((c) => path.join(rootAx, c))] : [];
567
594
  const fed = axChildren === null && storeBases.length === 0 ? new Set() : feedsAShell(segments);
568
595
  for (const [i, s] of segments.entries()) {
569
596
  if ((axChildren !== null || storeBases.length > 0) && !s.data) {
@@ -584,9 +611,9 @@ function segmentFlattened(cmd, root, start = root) {
584
611
  add(s.text);
585
612
  if (s.maybe || keys.bases.length > 0) {
586
613
  // @implements A-SPEC-728 (rule 44) — past 8 climb bases the command is too large to judge (60 rewrites of 256 KB — measured).
587
- const climbs = (0, write_target_1.axClimbBases)(root, keys, s.text);
588
- if (climbs.length > write_target_1.AX_CLIMB_BASES_MAX)
589
- throw new RangeError(`a command too large to judge at every directory it may run in under .ax (more than ${write_target_1.AX_CLIMB_BASES_MAX} climbs)`);
614
+ const climbs = (0, write_target_2.axClimbBases)(root, keys, s.text);
615
+ if (climbs.length > write_target_2.AX_CLIMB_BASES_MAX)
616
+ throw new RangeError(`a command too large to judge at every directory it may run in under .ax (more than ${write_target_2.AX_CLIMB_BASES_MAX} climbs)`);
590
617
  for (const k of keys.bases)
591
618
  add(rewrite(s.text, k));
592
619
  for (const k of climbs)
@@ -630,6 +657,11 @@ function normalizeCommandPaths(cmd, followCd = true) {
630
657
  }
631
658
  // File-mutating shell verbs beyond redirect/removal: these WRITE a target path, so a protected path
632
659
  // as their argument is the same governance breach as `>` or `rm` (probe: tee/cp/install slipped).
660
+ // A-SPEC-747.1 rules 1–5 (count a verb only as a shell word) are NOT implemented: the independent review of the first
661
+ // build (2026-10-04) showed the exemption for a verb inside a longer file name passes real writes whenever the shell
662
+ // splits a word the text does not (`cp${IFS}a${IFS}.ax/specs/x.md`, a custom IFS, text re-parsed by `sh -c`). The
663
+ // `\b…\b` test stays; `docs/install-guide.md` beside an .ax path is still refused, on purpose, until a rule exists
664
+ // that the shell cannot split around.
633
665
  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'));
634
666
  // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
635
667
  // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
@@ -660,6 +692,8 @@ const READ_ONLY_SHELL = new Set([
660
692
  const READ_ONLY_GIT = new Set([
661
693
  'show', 'log', 'status', 'diff', 'ls-tree', 'ls-files', 'blame', 'cat-file', 'rev-parse',
662
694
  'merge-base', 'describe',
695
+ // @implements A-SPEC-747.1 — `git check-ignore -v .ax/state/…` was refused (measured); it only reads.
696
+ 'check-ignore',
663
697
  ]);
664
698
  /** Is `t` a spelling of the long option `--<full>` that getopt_long accepts (an unambiguous prefix of `min`+ letters)? */
665
699
  function longOption(t, full, min) {
@@ -1408,6 +1442,8 @@ function awkIsRead(clause, args) {
1408
1442
  const FOR_HEAD_RE = /^for\s+[A-Za-z_][A-Za-z0-9_]*\s+in\b/;
1409
1443
  const SUBSTITUTION_RE = /\$\(|`|<\(|>\(/;
1410
1444
  const OUTPUT_REDIRECT_RE = />(?!\s*(?:\/dev\/null\b|&\d))/;
1445
+ /** An output redirect whose target word holds an expansion (`> ${P#q}`, `>> "$f"`, `` > `x` ``). Linear: one word after `>`. */
1446
+ const COMPUTED_REDIRECT_RE = />[>|&]?[ \t]*[^\s;|&<>$`]*[$`]/;
1411
1447
  function clausesAreReads(clauses, isRead) {
1412
1448
  let inLoop = false;
1413
1449
  for (const raw of clauses) {
@@ -1504,7 +1540,7 @@ function stripCommitMessages(cmd) {
1504
1540
  * @implements A-SPEC-226
1505
1541
  */
1506
1542
  function shellWritesProtectedAx(ncmd) {
1507
- if (!CMD_PROTECTED_AX_RE.test(ncmd))
1543
+ if (!namesProtectedAx(ncmd))
1508
1544
  return false;
1509
1545
  // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
1510
1546
  // because it is a property of the TARGET rather than of the command shape.
@@ -1521,6 +1557,10 @@ function shellWritesProtectedAx(ncmd) {
1521
1557
  sawCd = true;
1522
1558
  else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1523
1559
  return false;
1560
+ // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1561
+ // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1562
+ if (COMPUTED_REDIRECT_RE.test(c))
1563
+ return false;
1524
1564
  return clauseIsRead(c, isRead);
1525
1565
  });
1526
1566
  }
@@ -1536,7 +1576,7 @@ function shellWritesProtectedAx(ncmd) {
1536
1576
  */
1537
1577
  function classifyReversibility(action) {
1538
1578
  const raw = action.command ?? '';
1539
- const joined = raw === '' ? raw : (0, write_target_1.joinShellText)(raw);
1579
+ const joined = raw === '' ? raw : (0, write_target_2.joinShellText)(raw);
1540
1580
  if (joined === raw)
1541
1581
  return classifyReversibilityAsWritten(action);
1542
1582
  const a = classifyReversibilityAsWritten(action);
@@ -1565,15 +1605,25 @@ function classifyReversibilityAsWritten(action) {
1565
1605
  // followed a cd the shell never ran (`cd /nonexistent && true; echo x > .ax/ledger/p.jsonl` became an
1566
1606
  // other-project path and was allowed — measured). Judging both only ever adds refusals.
1567
1607
  // A-SPEC-728.2 — a commit message is text the `.ax` rules do not read.
1568
- const axCmd = stripCommitMessages(cmd);
1569
- const flat = scopeAxToProject(normalizeCommandPaths(axCmd), action.projectRoot);
1570
- const asWritten = scopeAxToProject(normalizeCommandPaths(axCmd, false), action.projectRoot);
1608
+ const roles = (0, shell_argument_roles_1.shellArgumentRoles)(cmd, action.cwd ?? action.projectRoot ?? null);
1609
+ if (action.projectRoot) {
1610
+ for (const output of roles.outputPaths) {
1611
+ const kind = (0, write_target_1.wiringWriteKindOf)(action.projectRoot, action.cwd ?? action.projectRoot, output);
1612
+ if (kind)
1613
+ return { axis, level: 'hard-hitl', reasons: [`CLI output option writes protected ${kind}`] };
1614
+ }
1615
+ }
1616
+ const axCmd = stripCommitMessages(roles.governanceText);
1617
+ const scopeForClassification = (text) => scopeAxWithPlaceholder(text, action.projectRoot, true);
1618
+ const flat = scopeForClassification(normalizeCommandPaths(axCmd));
1619
+ const asWritten = scopeForClassification(normalizeCommandPaths(axCmd, false));
1571
1620
  // Round 10: and with every segment at the base the certain-cd model gives it (a second cd into .ax).
1572
- const bySegment = action.projectRoot ? scopeAxToProject(normalizeCommandPaths(segmentFlattened(axCmd, action.projectRoot, action.cwd ?? action.projectRoot), false), action.projectRoot) : asWritten;
1573
- const ncmd = [...new Set([flat, asWritten, bySegment])].join('\n');
1621
+ const bySegment = action.projectRoot ? scopeForClassification(normalizeCommandPaths(segmentFlattened(axCmd, action.projectRoot, action.cwd ?? action.projectRoot), false)) : asWritten;
1622
+ const outputTargets = roles.outputPaths.map(p => scopeForClassification(normalizeCommandPaths(p, false)));
1623
+ const ncmd = [...new Set([flat, asWritten, bySegment, ...outputTargets])].join('\n');
1574
1624
  // @implements A-SPEC-737 — one reason served all four channels, so an interpreter READ was refused as
1575
1625
  // a "removal command" and the author could not tell what to change. Each channel names itself.
1576
- const axChannel = REMOVAL_VERB_RE.test(ncmd) && CMD_PROTECTED_AX_RE.test(ncmd)
1626
+ const axChannel = REMOVAL_VERB_RE.test(ncmd) && namesProtectedAx(ncmd)
1577
1627
  ? 'removal, move or copy command targets a protected .ax governance path'
1578
1628
  : CLOBBER_AX_RE.test(ncmd) ? 'output redirection writes into a protected .ax governance path'
1579
1629
  : WRITE_VERB_AX_RE.test(ncmd) ? 'file-writing command (tee/cp/install/dd/ln/mv/rsync) targets a protected .ax governance path'
@@ -0,0 +1,15 @@
1
+ export interface ArgumentRoles {
2
+ /** Original syntax, except proven literal prompt operands; never a permission decision. */
3
+ governanceText: string;
4
+ /** Original executable syntax, with proven script/search data operands neutralized. */
5
+ serverText: string;
6
+ /** Potential output identities at each plausible CLI base; shell redirects remain in source. */
7
+ outputPaths: string[];
8
+ }
9
+ /**
10
+ * @implements A-SPEC-753.1 — whether a command is the documented installer, and whether it applies or only previews.
11
+ * Measured 2026-10-04: the apply form was refused as a server start (A-SPEC-732), which it is not; the caller needs to
12
+ * know the act to name it. One command, every word certain, no substitution and no redirect — anything else is null.
13
+ */
14
+ export declare function installerInvocationOf(command: string, cwd?: string | null): 'preview' | 'apply' | null;
15
+ export declare function shellArgumentRoles(command: string, cwd?: string | null): ArgumentRoles;