@holmes-lab/holmes-kit 0.33.0 → 0.35.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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,72 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.0] - 2026-10-02
9
+
10
+ ### Changed
11
+
12
+ - **The pre-edit evidence gate follows new files and the RED commit** (A-SPEC-278.2/278.3). Persisted
13
+ `maintenance_analyze` evidence now records the request (up to 4,096 characters) and normalized `changedFiles`
14
+ (up to 512 entries). These explicit paths can cover a file that does not yet exist at HEAD. An analysis from
15
+ an ancestor at most 20 commits back remains usable when every intervening changed file is predicted or
16
+ explicitly named by the analysis. The gate remains advisory and continues to report content drift.
17
+ - **Read-only loops, prose, and commit messages are recognized by the shell gate** (A-SPEC-728.2).
18
+ A read-only `for` loop using only its own variable, a prose literal containing spaces, or a `git commit`
19
+ message mentioning `.ax` no longer counts as a governance-state write.
20
+
21
+ ### Fixed
22
+
23
+ - **File redirects using `>&` or `>|` reach the protected-write classifier** (A-SPEC-728.1). Descriptor
24
+ duplication and closure such as `2>&1`, `>&2`, and `>&-` keep their existing interpretation.
25
+ - **The ART-4 static test counter reads literals, aliases, and suite skips correctly** (A-SPEC-750). A
26
+ single-pass lexer prevents comment-like text inside strings, templates, or regular expressions from erasing
27
+ test declarations. Same-file test aliases are counted, and quoted `describe.skip` text no longer discards a
28
+ file. Across 648 test files the counter matches the TypeScript AST oracle; no file counts fewer than before.
29
+ - **A passing test run records the tree captured before execution** (A-SPEC-128.1). Files added or edited
30
+ during a run remain changes for the next run instead of entering `last-green` as already tested.
31
+ - **Parallel tests avoid three measured sources of interference** (A-SPEC-749/749.1, A-SPEC-162.1,
32
+ A-SPEC-651.6/651.7). All 72 migrated wall-clock bounds scale against reference work measured at the assertion
33
+ (factor 1–8); the supervisor swap test changes a package copy instead of the repository build ID; and test
34
+ Git commands disable detached auto-maintenance that could race fixture cleanup.
35
+
36
+ ## [0.34.0] - 2026-10-01
37
+
38
+ ### Added
39
+
40
+ - **A docs-only commit inherits the release test-lane receipt** (A-SPEC-748). The publish gate binds its test
41
+ receipt to HEAD, so a one-line README fix after the release lane cost a second full serial suite (~35 min).
42
+ `node scripts/verify-release.js --inherit-release-test-lane` records a receipt for HEAD by running only the
43
+ required docs tests, when every change since the last full lane is `README.md` or an unshipped file under
44
+ `docs/`. It names the full receipt it stands on; the publish check re-reads that receipt (24 h limit) and
45
+ recomputes the diff with git — a path list written in the receipt is never trusted. `CHANGELOG.md`, shipped
46
+ docs, `package.json`, source, playbooks — any of them changed means the full lane, as before.
47
+
48
+ ### Changed
49
+
50
+ - **Read-only shell commands over `.ax` are reads** (A-SPEC-747). 28 of 79 refused `.ax` commands in four sessions
51
+ only read, and each filed an approval request no one would decide. The gate now splits a command at operators
52
+ outside quotes and substitutions (`grep "a\|b" F` is one clause), judges every command substitution's body by the
53
+ same rule (so `echo "$(sh -c …)"` over `.ax` is newly refused), and knows `cd` (to a literal target), `pwd`,
54
+ `sleep`, `seq`, `pgrep`, clock-reading `date`, `git -C`/`--no-pager` and `while`/`until` loops of reads. Measured:
55
+ read over-blocks 18/29 → 1/29 (the remaining one is the remote-code rule), write probes still 32/32 refused.
56
+ - **`sed -i` is judged by the files it edits, not by its script** (A-SPEC-747). A `sed -i` over a file outside the
57
+ project was refused as a project code write because its script mentioned a `.ts` name.
58
+ - **`requirement_triage` judges a lineage approved by its documents, not their count** (A-SPEC-713.4). Only
59
+ lineages of exactly four documents counted as approved: 62 of 672 fully approved lineages here (8 of 671 in a
60
+ second corpus) have sub-slices or retired documents and could never be `fulfilled`, and four approved documents
61
+ without a T-SPEC counted as approved.
62
+
63
+ ### Fixed
64
+
65
+ - **The autoreload MCP launcher exits when its client goes away** (A-SPEC-666.1). With `HOLMES_MCP_AUTORELOAD`,
66
+ the supervisor listened to stdin data only; when the client (a restarted Codex app-server daemon, observed) went
67
+ away, the launcher and its server child ran on with PPID 1 for hours. On stdin end or close it now closes the
68
+ child's input (a request forwarded just before is still read) and kills it after a 2 s grace, never restarting it.
69
+ - **A deep-link scan test no longer fails under a loaded parallel run** (A-SPEC-734.2, correcting A-SPEC-734.1, whose
70
+ counted call — `readdirSync` — stayed at 313 with the memo removed and so could not catch it). The 5 s wall-clock bound
71
+ (3.3 s alone, 13.8 s under load) is replaced by the property it guarded — the per-ancestor `.git` probe runs once
72
+ per directory (608–909 calls; 602,608 with the memo removed).
73
+
8
74
  ## [0.33.0] - 2026-10-01
9
75
 
10
76
  ### Changed
package/README.md CHANGED
@@ -23,6 +23,8 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **Maintenance evidence survives the RED commit, and test evidence records what ran** *(new in 0.35.0)*: persisted `maintenance_analyze` evidence includes the request and explicit `changedFiles`, allowing the pre-edit advisory to cover named new files and analyses up to 20 ancestor commits back when every intervening change is covered. A passing `test_run` records the tree captured before execution, so edits made during a run remain unverified changes. The static test counter handles literals and same-file aliases, and recognizes suite skips only in code. The shared shell gate accepts read-only loops, prose literals, and commit messages mentioning `.ax`, and classifies file redirects using `>&` and `>|` as protected writes where applicable.
27
+ - 📖 **Reading `.ax` from the shell is a read, and a docs fix does not re-run the whole release suite** *(new in 0.34.0)*: the gate splits shell commands at operators outside quotes and substitutions, judges every command substitution it would run, and knows literal `cd`, `pwd`, `sleep`, `seq`, `pgrep`, clock-reading `date`, `git -C` and `while`/`until` loops — so `grep "a\|b" .ax/…`, `f=$(find .ax/specs …)` or `until grep -q … .ax/…; do sleep 20; done` no longer file an approval request, while every write form is still refused (and `echo "$(sh -c …)"` now is). `sed -i` is judged by the files it edits, not by the words in its script. After a full release lane, `node scripts/verify-release.js --inherit-release-test-lane` lets a commit that changes only `README.md` or unshipped `docs/` files publish on the full lane's receipt by running just the docs tests; the publish check recomputes that diff with git. `requirement_triage` counts a lineage with sub-slices as approved, and an autoreload MCP launcher exits when its client goes away.
26
28
  - 🗜️ **Large answers are compressed, not cut, and new requirements are not blocked by a guess** *(new in 0.33.0)*: `spec_list`, `review_status` and `reverse_scan` answer by default with a compressed view — duplicates removed, digests dropped, what needs action first, anything left out counted with a note — and `detail: "full"` (or paging, or `spec_list({ ids })` for one spec) gives the complete answer. `requirement_triage` confirms a lineage only when both of its channels agree and the lineage mentions every code identifier the request names, so a requirement next to a finished one, or on an install without a semantic layer, can still be admitted. `maintenance_analyze` judges a Korean or Japanese request against unreadable files by its words and, on the cloud tier, by meaning; the pre-edit gate finds the analysis the session persisted; `spec_approve` names a spec's blockers instead of queueing an approval nobody could use; and `holmes-kit autonomy status`/`off` read the project default in `.mcp.json`, so `off` never claims OFF while autonomous approval is still on.
27
29
  - 🔎 **The analysis tools decide on evidence about the request, and say what they could not decide** *(new in 0.32.0)*: measured on two repositories by point-in-time replay, `maintenance_analyze` had answered `ambiguous` for every request because a shell script anywhere in the tree counted against it — the classification now counts an unreadable language only when the change touches it, while the test scope stays as conservative as before (relaxing it too let narrowed scopes miss the commit's own tests). `confidence` carries `confidenceCalibrated: false`; persisted evidence records why a scope was `full` and `maintenance_calibration` reports how often each cause occurred; candidate specs come in relevance order. `requirement_triage` answers in summaries by default (`detail: "full"` for document text), counts semantic coverage over documents that can have a vector, and gives `existing-change`/`fulfilled` only when its lexical and semantic channels agree on the first-ranked lineage — a lineage the request cites is listed first but a citation is not evidence — otherwise `ambiguous`, which leaves a new requirement possible.
28
30
  - 🚦 **The gate only ever denies** *(changed in 0.31.0)*: an action Holmes does not deny is left to your harness's own permission flow — Claude Code and Codex get no permission decision, Antigravity gets `ask` (or `allow` for a read inside the workspace that git does not ignore). Earlier versions answered `allow`, which Claude Code treats as "bypassing permission prompt", so anything the shell model missed ran unconfirmed. In Claude Code's default mode you now see its confirmations again, as without Holmes.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- cd3e509f-muobw3d9
1
+ 7dd2aa11-muqzdhr1
@@ -37,10 +37,11 @@ exports.isLowRiskTarget = isLowRiskTarget;
37
37
  exports.evaluateEditEvidence = evaluateEditEvidence;
38
38
  exports.preEditEvidenceDecision = preEditEvidenceDecision;
39
39
  exports.loadEditEvidence = loadEditEvidence;
40
- // @implements A-SPEC-279, A-SPEC-278.1
40
+ // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3
41
41
  // @implements A-SPEC-278
42
42
  // @implements A-SPEC-277
43
43
  // @implements A-SPEC-276
44
+ const node_child_process_1 = require("node:child_process");
44
45
  const fs = __importStar(require("node:fs"));
45
46
  const crypto = __importStar(require("node:crypto"));
46
47
  const path = __importStar(require("node:path"));
@@ -272,7 +273,11 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
272
273
  catch {
273
274
  return null;
274
275
  }
276
+ const newer = (a, b) => b === null || String(a.recordedAt ?? '') > String(b.recordedAt ?? '');
275
277
  let best = null;
278
+ const older = [];
279
+ let targetIsNew;
280
+ const isNew = () => (targetIsNew ??= !gitOk(projectRoot, ['cat-file', '-e', `${currentHead}:${target}`]));
276
281
  for (const { file } of entries.sort((a, b) => b.mtime - a.mtime).slice(0, PERSISTED_SCAN_LIMIT)) {
277
282
  let candidate;
278
283
  try {
@@ -281,14 +286,94 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
281
286
  catch {
282
287
  continue;
283
288
  }
284
- if (candidate?.graphBasis?.head !== currentHead)
289
+ if (!Array.isArray(candidate?.predicted?.files) || typeof candidate?.graphBasis?.head !== 'string')
285
290
  continue;
286
- if (!Array.isArray(candidate?.predicted?.files) || !candidate.predicted.files.includes(target))
291
+ if (candidate.graphBasis.head !== currentHead) {
292
+ older.push(candidate);
287
293
  continue;
288
- if (best === null || String(candidate.recordedAt ?? '') > String(best.recordedAt ?? ''))
294
+ }
295
+ if (!coversTarget(candidate, target, isNew))
296
+ continue;
297
+ if (newer(candidate, best))
289
298
  best = candidate;
290
299
  }
291
- return best;
300
+ if (best)
301
+ return best;
302
+ // @implements A-SPEC-278.2 (rule 2) — an analysis at an ancestor ≤ 20 commits back still describes this tree when every
303
+ // file changed since it was predicted or named by its request (the RED commit adds only the request-named test). The
304
+ // copy carries the current head so the basis is not reported as drifted; the target's own digest still is.
305
+ const lineage = new Map();
306
+ for (const candidate of older.sort((a, b) => String(b.recordedAt ?? '').localeCompare(String(a.recordedAt ?? '')))) {
307
+ const a = candidate.graphBasis.head;
308
+ if (!coversTarget(candidate, target, isNew))
309
+ continue;
310
+ if (!lineage.has(a)) {
311
+ if (lineage.size >= LINEAGE_HEADS_MAX)
312
+ break;
313
+ lineage.set(a, unchangedOutside(projectRoot, a, currentHead, candidate));
314
+ }
315
+ if (lineage.get(a))
316
+ return { ...candidate, graphBasis: { ...candidate.graphBasis, head: currentHead } };
317
+ }
318
+ return null;
319
+ }
320
+ /** @implements A-SPEC-278.2 — distinct ancestor heads examined per judgement (each costs three bounded git calls). */
321
+ const LINEAGE_HEADS_MAX = 8;
322
+ const LINEAGE_DEPTH_MAX = 20;
323
+ /** The analysis request names `rel` as a whole path (not as part of a longer one). */
324
+ function requestNames(candidate, rel) {
325
+ // @implements A-SPEC-278.3 — a file the caller listed in changedFiles is named exactly, whatever the request text says.
326
+ const listed = candidate.changedFiles;
327
+ if (rel !== '' && Array.isArray(listed) && listed.includes(rel))
328
+ return true;
329
+ const request = candidate.request;
330
+ if (typeof request !== 'string' || rel === '')
331
+ return false;
332
+ let at = request.indexOf(rel);
333
+ while (at >= 0) {
334
+ const before = at === 0 ? '' : request[at - 1];
335
+ const after = request[at + rel.length] ?? '';
336
+ if (!/[\w./-]/.test(before) && !/[\w/-]/.test(after) && !(after === '.' && /[\w]/.test(request[at + rel.length + 1] ?? '')))
337
+ return true;
338
+ at = request.indexOf(rel, at + 1);
339
+ }
340
+ return false;
341
+ }
342
+ /** @implements A-SPEC-278.2 (rule 1) — predicted, or a file new at HEAD that the request names. */
343
+ function coversTarget(candidate, target, isNew) {
344
+ if (candidate.predicted.files.includes(target))
345
+ return true;
346
+ return requestNames(candidate, target) && isNew();
347
+ }
348
+ function unchangedOutside(projectRoot, ancestor, head, candidate) {
349
+ if (!/^[0-9a-f]{7,64}$/i.test(ancestor) || !gitOk(projectRoot, ['merge-base', '--is-ancestor', ancestor, head]))
350
+ return false;
351
+ const count = Number(gitText(projectRoot, ['rev-list', '--count', `${ancestor}..${head}`]));
352
+ if (!Number.isInteger(count) || count < 1 || count > LINEAGE_DEPTH_MAX)
353
+ return false;
354
+ const changed = gitText(projectRoot, ['diff', '--name-only', '--no-renames', ancestor, head]);
355
+ if (changed === null)
356
+ return false;
357
+ return changed.split('\n').filter(Boolean).every((f) => candidate.predicted.files.includes(f) || requestNames(candidate, f));
358
+ }
359
+ const GIT_TIMEOUT_MS = 5000;
360
+ const GIT_MAX_BUFFER = 1024 * 1024;
361
+ function gitOk(cwd, args) {
362
+ try {
363
+ (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
364
+ return true;
365
+ }
366
+ catch {
367
+ return false;
368
+ }
369
+ }
370
+ function gitText(cwd, args) {
371
+ try {
372
+ return (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
373
+ }
374
+ catch {
375
+ return null;
376
+ }
292
377
  }
293
378
  /**
294
379
  * @implements A-SPEC-278
@@ -154,6 +154,11 @@ function redirectTokenTester(tail) {
154
154
  let i = text.indexOf('>');
155
155
  while (i >= 0) {
156
156
  let j = i + 1;
157
+ // @implements A-SPEC-728.1 — one `&` or `|` right after `>` belongs to the operator (`>&`, `>|`): it ended the
158
+ // target token at once, so `echo x >& .ax/ledger/…` was `confirm` here (measured on 0.33.0 and 0.34.0).
159
+ const dup = text[j] === '&';
160
+ if (dup || text[j] === '|')
161
+ j++;
157
162
  while (j < text.length && /\s/.test(text[j]))
158
163
  j++;
159
164
  if (text[j] === '"' || text[j] === "'")
@@ -161,7 +166,9 @@ function redirectTokenTester(tail) {
161
166
  let k = j;
162
167
  while (k < text.length && !/[\s;&|]/.test(text[k]))
163
168
  k++;
164
- if (t.test(text.slice(j, k)))
169
+ const token = text.slice(j, k);
170
+ // `>&2`, `>& 2`, `>&-` duplicate or close a descriptor; they name no file.
171
+ if (!(dup && /^(?:\d+|-)$/.test(token)) && t.test(token))
165
172
  return true;
166
173
  // A `>` ending the token targets the NEXT token (after blanks); one inside it sees a suffix.
167
174
  i = text.indexOf('>', k > i + 1 && text[k - 1] === '>' ? k - 1 : Math.max(k, i + 1));
@@ -16,6 +16,12 @@ 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-728.2 — the classifier's own read judgement of a whole shell text, loops included, for the identity
21
+ * layer: a `for` loop whose body only reads its variable's files names no mutation target with its word list.
22
+ */
23
+ export declare function shellTextOnlyReads(text: string): boolean;
24
+ export declare function stripCommitMessages(cmd: string): string;
19
25
  /**
20
26
  * @implements A-SPEC-125.1
21
27
  * Reversibility axis: can the action's effect be undone? Conservative default —
@@ -37,12 +37,14 @@ exports.rmCommandTargets = rmCommandTargets;
37
37
  exports.normalizeWindowsPathSpellings = normalizeWindowsPathSpellings;
38
38
  exports.scopeAxToProject = scopeAxToProject;
39
39
  exports.normalizeCommandPaths = normalizeCommandPaths;
40
+ exports.shellTextOnlyReads = shellTextOnlyReads;
41
+ exports.stripCommitMessages = stripCommitMessages;
40
42
  exports.classifyReversibility = classifyReversibility;
41
43
  exports.classifyArchitectureReversal = classifyArchitectureReversal;
42
44
  exports.classifySecret = classifySecret;
43
45
  exports.classifyBlastRadius = classifyBlastRadius;
44
46
  exports.assessRisk = assessRisk;
45
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737
47
+ // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747
46
48
  const fs = __importStar(require("node:fs"));
47
49
  const path = __importStar(require("node:path"));
48
50
  const risk_types_1 = require("./risk-types");
@@ -651,6 +653,8 @@ const READ_ONLY_SHELL = new Set([
651
653
  'cat', 'grep', 'rg', 'ls', 'find', 'head', 'tail', 'wc', 'diff', 'awk', 'sort', 'uniq',
652
654
  'less', 'more', 'file', 'stat', 'du', 'cut', 'tr', 'column', 'jq', 'basename', 'dirname',
653
655
  'realpath', 'echo', 'printf', 'true', 'test',
656
+ // @implements A-SPEC-747 — measured in the refused reads: none of these writes a file.
657
+ 'cd', 'pwd', 'sleep', 'seq', 'pgrep',
654
658
  ]);
655
659
  /** `git` subcommands that only read. `commit`/`checkout`/`add` are not among them. */
656
660
  const READ_ONLY_GIT = new Set([
@@ -692,11 +696,175 @@ function sedInPlaceFlag(t) {
692
696
  * hide behind a pipe (`cat SPEC | tee OTHER`).
693
697
  */
694
698
  function splitShellClauses(cmd) {
695
- return cmd
696
- .split(/\|\||&&|;|\||\n/)
699
+ // @implements A-SPEC-747 — operators inside quotes or a substitution are text, not separators: `grep "a\|b" F`
700
+ // was judged as the clause `b" F`, which is no known read (17 of 28 measured reads refused). An unclosed quote
701
+ // keeps the quote-blind split — when the reader is unsure it cuts more, never less.
702
+ const pieces = splitUnquoted(cmd) ?? cmd.split(/\|\||&&|;|\||\n/);
703
+ return pieces
697
704
  .map((c) => c.replace(/^[\s(]+/, '').trim())
698
705
  .filter((c) => c.length > 0);
699
706
  }
707
+ /**
708
+ * @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
709
+ * escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
710
+ */
711
+ function splitUnquoted(cmd) {
712
+ const out = [];
713
+ let cur = '';
714
+ let quote = null;
715
+ let depth = 0;
716
+ let tick = false;
717
+ for (let i = 0; i < cmd.length; i++) {
718
+ const ch = cmd[i];
719
+ if (quote === "'") {
720
+ cur += ch;
721
+ if (ch === "'")
722
+ quote = null;
723
+ continue;
724
+ }
725
+ if (ch === '\\' && i + 1 < cmd.length) {
726
+ cur += ch + cmd[i + 1];
727
+ i++;
728
+ continue;
729
+ }
730
+ if (ch === '`') {
731
+ tick = !tick;
732
+ cur += ch;
733
+ continue;
734
+ }
735
+ if ((ch === '$' || ch === '<' || ch === '>') && cmd[i + 1] === '(') {
736
+ depth++;
737
+ cur += ch + '(';
738
+ i++;
739
+ continue;
740
+ }
741
+ if (depth > 0 && ch === ')') {
742
+ depth--;
743
+ cur += ch;
744
+ continue;
745
+ }
746
+ if (quote === '"') {
747
+ cur += ch;
748
+ if (ch === '"')
749
+ quote = null;
750
+ continue;
751
+ }
752
+ if (ch === '"' || ch === "'") {
753
+ quote = ch;
754
+ cur += ch;
755
+ continue;
756
+ }
757
+ if (depth === 0 && !tick) {
758
+ if (ch === '\n' || ch === ';') {
759
+ out.push(cur);
760
+ cur = '';
761
+ continue;
762
+ }
763
+ if (ch === '|') {
764
+ if (cmd[i + 1] === '|')
765
+ i++;
766
+ out.push(cur);
767
+ cur = '';
768
+ continue;
769
+ }
770
+ if (ch === '&' && cmd[i + 1] === '&') {
771
+ i++;
772
+ out.push(cur);
773
+ cur = '';
774
+ continue;
775
+ }
776
+ }
777
+ cur += ch;
778
+ }
779
+ if (quote !== null || depth !== 0 || tick)
780
+ return null;
781
+ out.push(cur);
782
+ return out;
783
+ }
784
+ /** @implements A-SPEC-747 — how deep command substitutions are followed before a clause stops counting as a read. */
785
+ const MAX_SUBSTITUTION_DEPTH = 4;
786
+ /**
787
+ * @implements A-SPEC-747 — the command substitutions a clause runs (`$(…)`, backticks, `<(…)`; also inside double
788
+ * quotes, where they still run) and the clause with each replaced by a placeholder word. `null` when one is left
789
+ * open, or for `>(…)` (a process the output is written into).
790
+ */
791
+ function substitutionsOf(clause) {
792
+ const bodies = [];
793
+ let rest = '';
794
+ let single = false;
795
+ for (let i = 0; i < clause.length; i++) {
796
+ const ch = clause[i];
797
+ if (single) {
798
+ rest += ch;
799
+ if (ch === "'")
800
+ single = false;
801
+ continue;
802
+ }
803
+ if (ch === '\\' && i + 1 < clause.length) {
804
+ rest += ch + clause[i + 1];
805
+ i++;
806
+ continue;
807
+ }
808
+ if (ch === "'") {
809
+ single = true;
810
+ rest += ch;
811
+ continue;
812
+ }
813
+ if (ch === '>' && clause[i + 1] === '(')
814
+ return null;
815
+ if ((ch === '$' || ch === '<') && clause[i + 1] === '(') {
816
+ let depth = 1;
817
+ let j = i + 2;
818
+ for (; j < clause.length && depth > 0; j++) {
819
+ if (clause[j] === '(')
820
+ depth++;
821
+ else if (clause[j] === ')')
822
+ depth--;
823
+ }
824
+ if (depth !== 0)
825
+ return null;
826
+ bodies.push(clause.slice(i + 2, j - 1));
827
+ rest += 'x';
828
+ i = j - 1;
829
+ continue;
830
+ }
831
+ if (ch === '`') {
832
+ const end = clause.indexOf('`', i + 1);
833
+ if (end < 0)
834
+ return null;
835
+ bodies.push(clause.slice(i + 1, end));
836
+ rest += 'x';
837
+ i = end;
838
+ continue;
839
+ }
840
+ rest += ch;
841
+ }
842
+ return { bodies, rest };
843
+ }
844
+ /**
845
+ * @implements A-SPEC-747 — a clause is a read when every substitution it runs is all reads (judged by the same rule,
846
+ * at most MAX_SUBSTITUTION_DEPTH deep) and the clause itself, with each substitution a placeholder, is a read. Before
847
+ * this, `echo "$(sh -c …)"` over .ax read as `echo` — the substitution was never judged.
848
+ */
849
+ function clauseIsRead(clause, isRead, depth = 0) {
850
+ // A `cd` whose target is computed (a substitution, variable or glob) is not a read: the rules after it cannot know
851
+ // where relative paths land, and treating it as a read let `cd "$(printf '.%s' ax)"; echo x >& ./ledger/…` through
852
+ // (A-SPEC-728 round 27 pin — measured while building this slice). Only a certain cd moves on as a read.
853
+ if (/^cd(?:\s|$)/.test(clause) && /[$`*?[{]/.test(clause))
854
+ return false;
855
+ const subs = substitutionsOf(clause);
856
+ if (subs === null)
857
+ return false;
858
+ if (subs.bodies.length > 0) {
859
+ if (depth >= MAX_SUBSTITUTION_DEPTH)
860
+ return false;
861
+ for (const body of subs.bodies) {
862
+ if (!clausesAreReads(splitShellClauses(body), (c) => clauseIsRead(c, isRead, depth + 1)))
863
+ return false;
864
+ }
865
+ }
866
+ return isRead(subs.rest.trim());
867
+ }
700
868
  /**
701
869
  * Is this single clause known to only read?
702
870
  *
@@ -717,8 +885,10 @@ function isReadOnlyShellClause(clause) {
717
885
  let assigned = 0;
718
886
  while (assigned < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[assigned]))
719
887
  assigned++;
888
+ // @implements A-SPEC-747 — an assignment-only clause runs nothing itself: `f=$(find …)` is a read when its
889
+ // substitution is (clauseIsRead judges the body and hands this rule the placeholder `f=x`).
720
890
  if (assigned > 0)
721
- return assigned < tokens.length && isReadOnlyShellClause(tokens.slice(assigned).join(' '));
891
+ return assigned === tokens.length || isReadOnlyShellClause(tokens.slice(assigned).join(' '));
722
892
  const name = tokens[0].replace(/^.*\//, ''); // /usr/bin/grep -> grep
723
893
  // @implements A-SPEC-737 — each of these read commands has a form that writes a named file, and
724
894
  // the gate allowed all of them onto .ax/specs (measured through the built hook).
@@ -750,8 +920,29 @@ function isReadOnlyShellClause(clause) {
750
920
  return k < tokens.length && isReadOnlyShellClause(tokens.slice(k).join(' '));
751
921
  }
752
922
  if (name === 'git') {
753
- return tokens.length > 1 && READ_ONLY_GIT.has(tokens[1]) && !rest.some((t) => t.startsWith('--output'));
923
+ // @implements A-SPEC-747 — `-C <dir>` (repeatable) and `--no-pager` come before the sub-command; any other global
924
+ // option is not a read (`-c core.fsmonitor=…` runs a program on `status`, `--git-dir`/`--work-tree` retarget it).
925
+ let k = 1;
926
+ while (k < tokens.length && tokens[k].startsWith('-')) {
927
+ if (tokens[k] === '-C') {
928
+ k += 2;
929
+ continue;
930
+ }
931
+ if (tokens[k] === '--no-pager') {
932
+ k++;
933
+ continue;
934
+ }
935
+ return false;
936
+ }
937
+ // The sub-command is read by its last path part: the per-segment flattening prefixes every word after a moved
938
+ // base (`git status` → `git <dir>/status`), which read as no known sub-command (measured on a census read). A real
939
+ // git given a path-shaped sub-command only fails, and a write sub-command is not a read under any prefix.
940
+ const sub = k < tokens.length ? tokens[k].replace(/^.*\//, '') : '';
941
+ return sub !== '' && READ_ONLY_GIT.has(sub) && !rest.some((t) => t.startsWith('--output'));
754
942
  }
943
+ // @implements A-SPEC-747 — `date` reads unless it sets the clock (`-s`, `--set`, or an operand that is not a `+FORMAT`).
944
+ if (name === 'date')
945
+ return !rest.some((t) => t === '-s' || longOption(t, 'set', 2) || !(t.startsWith('-') || t.startsWith('+')));
755
946
  // @implements A-SPEC-737 (round 2) — sed `w`/`s///w`, awk `> FILENAME`/`-i inplace`, perl open(),
756
947
  // rg --pre and `sort -o<path>` all wrote into .ax/specs while allowed as reads. A programmable
757
948
  // reader is a read only in a recognisable read form, judged on quote-aware words.
@@ -1227,6 +1418,16 @@ function clausesAreReads(clauses, isRead) {
1227
1418
  inLoop = true;
1228
1419
  continue;
1229
1420
  }
1421
+ // @implements A-SPEC-747 — `while COND` / `until COND` open a loop like `for`; the condition must itself be a read
1422
+ // (no substitution, no output redirect) and the body keeps the `for` rules.
1423
+ const loopHead = /^(?:while|until)\s+(.*)$/s.exec(c);
1424
+ if (loopHead) {
1425
+ const cond = loopHead[1].trim();
1426
+ if (inLoop || SUBSTITUTION_RE.test(cond) || OUTPUT_REDIRECT_RE.test(cond) || !isRead(cond))
1427
+ return false;
1428
+ inLoop = true;
1429
+ continue;
1430
+ }
1230
1431
  if (inLoop && /^done$/.test(c)) {
1231
1432
  inLoop = false;
1232
1433
  continue;
@@ -1277,6 +1478,26 @@ function isIndexRestoreClause(clause) {
1277
1478
  }
1278
1479
  return false;
1279
1480
  }
1481
+ /**
1482
+ * @implements A-SPEC-728.2 — the classifier's own read judgement of a whole shell text, loops included, for the identity
1483
+ * layer: a `for` loop whose body only reads its variable's files names no mutation target with its word list.
1484
+ */
1485
+ function shellTextOnlyReads(text) {
1486
+ return clausesAreReads(splitShellClauses(text), (c) => clauseIsRead(c, isReadOnlyShellClause));
1487
+ }
1488
+ /**
1489
+ * @implements A-SPEC-728.2 — a `git commit` message is text, not a path: `git commit -m "… .ax/specs …"` was refused as "not
1490
+ * recognisably read-only" (measured 2026-10-01). The values of `-m`/`--message`/`--message=`/`-F`/`--file` in a `git …
1491
+ * commit` segment are blanked before the `.ax` rules read the command. A double-quoted value holding `$` or a backtick (a
1492
+ * substitution runs), an unquoted value's redirect (`-m x>FILE`), and a pathspec stay as written.
1493
+ */
1494
+ const COMMIT_SEGMENT_RE = /(\bgit\b(?:\s+(?:-C|-c)\s+\S+|\s+--no-pager)*\s+commit\b)([^;&|\n]*)/g;
1495
+ const COMMIT_MESSAGE_RE = /(\s(?:-[a-zA-Z]*[mF]|--message|--file))(=|\s+)("(?:[^"\\$`]|\\[^$`])*"|'[^']*'|[^\s;&|<>()$`"']+)/g;
1496
+ function stripCommitMessages(cmd) {
1497
+ if (!/\bcommit\b/.test(cmd))
1498
+ return cmd;
1499
+ return cmd.replace(COMMIT_SEGMENT_RE, (_, head, rest) => head + rest.replace(COMMIT_MESSAGE_RE, '$1$2""'));
1500
+ }
1280
1501
  /**
1281
1502
  * A shell command that touches a protected governance path and is not recognisably read-only.
1282
1503
  *
@@ -1288,7 +1509,20 @@ function shellWritesProtectedAx(ncmd) {
1288
1509
  // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
1289
1510
  // because it is a property of the TARGET rather than of the command shape.
1290
1511
  const restoreAllowed = !LEDGER_PATH_RE.test(ncmd);
1291
- return !clausesAreReads(splitShellClauses(ncmd), (c) => isReadOnlyShellClause(c) || (restoreAllowed && isIndexRestoreClause(c)));
1512
+ // @implements A-SPEC-747 — each clause's substitutions are judged first (clauseIsRead).
1513
+ const isRead = (c) => isReadOnlyShellClause(c) || (restoreAllowed && isIndexRestoreClause(c));
1514
+ // After a `cd`, an output redirect into a file is not a read: the redirect rule reads a target token that starts right
1515
+ // after `>`, so `>& path` and `>| path` (a `&` or `|` first) are never seen, and `cd .ax; echo x >& ledger/…` passed once
1516
+ // `cd` became a read (measured while building this slice). Before A-SPEC-747 every command with a `cd` was refused, so
1517
+ // this keeps that shape exactly as refused as it was.
1518
+ let sawCd = false;
1519
+ return !clausesAreReads(splitShellClauses(ncmd), (c) => {
1520
+ if (/^cd(?:\s|$)/.test(c))
1521
+ sawCd = true;
1522
+ else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1523
+ return false;
1524
+ return clauseIsRead(c, isRead);
1525
+ });
1292
1526
  }
1293
1527
  /**
1294
1528
  * @implements A-SPEC-125.1
@@ -1330,10 +1564,12 @@ function classifyReversibilityAsWritten(action) {
1330
1564
  // @implements A-SPEC-728 (round 9) — the cd-flattened text AND the text as written: flattening
1331
1565
  // followed a cd the shell never ran (`cd /nonexistent && true; echo x > .ax/ledger/p.jsonl` became an
1332
1566
  // other-project path and was allowed — measured). Judging both only ever adds refusals.
1333
- const flat = scopeAxToProject(normalizeCommandPaths(cmd), action.projectRoot);
1334
- const asWritten = scopeAxToProject(normalizeCommandPaths(cmd, false), action.projectRoot);
1567
+ // 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);
1335
1571
  // Round 10: and with every segment at the base the certain-cd model gives it (a second cd into .ax).
1336
- const bySegment = action.projectRoot ? scopeAxToProject(normalizeCommandPaths(segmentFlattened(cmd, action.projectRoot, action.cwd ?? action.projectRoot), false), action.projectRoot) : asWritten;
1572
+ const bySegment = action.projectRoot ? scopeAxToProject(normalizeCommandPaths(segmentFlattened(axCmd, action.projectRoot, action.cwd ?? action.projectRoot), false), action.projectRoot) : asWritten;
1337
1573
  const ncmd = [...new Set([flat, asWritten, bySegment])].join('\n');
1338
1574
  // @implements A-SPEC-737 — one reason served all four channels, so an interpreter READ was refused as
1339
1575
  // a "removal command" and the author could not tell what to change. Each channel names itself.