@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 +66 -0
- package/README.md +2 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/guardrail/impact-gate.js +90 -5
- package/dist/holmes/guardrail/linear-match.js +8 -1
- package/dist/holmes/guardrail/risk-classifier.d.ts +6 -0
- package/dist/holmes/guardrail/risk-classifier.js +245 -9
- package/dist/holmes/guardrail/shell-words.js +52 -1
- package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
- package/dist/holmes/hooks/pre-tool-use.js +55 -2
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +4 -2
- package/dist/holmes/mcp/handlers/test-execution.js +6 -2
- package/dist/holmes/mcp/maintenance-evidence.d.ts +16 -1
- package/dist/holmes/mcp/maintenance-evidence.js +29 -3
- package/dist/holmes/mcp/supervisor.d.ts +8 -0
- package/dist/holmes/mcp/supervisor.js +32 -2
- package/dist/holmes/review/requirement-triage.js +9 -2
- package/dist/holmes/review/test-outcomes.d.ts +53 -1
- package/dist/holmes/review/test-outcomes.js +156 -8
- package/dist/holmes/rtm/test-scope.d.ts +9 -0
- package/dist/holmes/rtm/test-scope.js +284 -14
- package/package.json +1 -1
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
|
-
|
|
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 !==
|
|
289
|
+
if (!Array.isArray(candidate?.predicted?.files) || typeof candidate?.graphBasis?.head !== 'string')
|
|
285
290
|
continue;
|
|
286
|
-
if (
|
|
291
|
+
if (candidate.graphBasis.head !== currentHead) {
|
|
292
|
+
older.push(candidate);
|
|
287
293
|
continue;
|
|
288
|
-
|
|
294
|
+
}
|
|
295
|
+
if (!coversTarget(candidate, target, isNew))
|
|
296
|
+
continue;
|
|
297
|
+
if (newer(candidate, best))
|
|
289
298
|
best = candidate;
|
|
290
299
|
}
|
|
291
|
-
|
|
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
|
-
|
|
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
|
-
|
|
696
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1334
|
-
const
|
|
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(
|
|
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.
|