@holmes-lab/holmes-kit 0.33.0 → 0.34.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 +38 -0
- package/README.md +1 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/guardrail/risk-classifier.js +218 -6
- 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/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/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,44 @@ 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.34.0] - 2026-10-01
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **A docs-only commit inherits the release test-lane receipt** (A-SPEC-748). The publish gate binds its test
|
|
13
|
+
receipt to HEAD, so a one-line README fix after the release lane cost a second full serial suite (~35 min).
|
|
14
|
+
`node scripts/verify-release.js --inherit-release-test-lane` records a receipt for HEAD by running only the
|
|
15
|
+
required docs tests, when every change since the last full lane is `README.md` or an unshipped file under
|
|
16
|
+
`docs/`. It names the full receipt it stands on; the publish check re-reads that receipt (24 h limit) and
|
|
17
|
+
recomputes the diff with git — a path list written in the receipt is never trusted. `CHANGELOG.md`, shipped
|
|
18
|
+
docs, `package.json`, source, playbooks — any of them changed means the full lane, as before.
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
|
|
22
|
+
- **Read-only shell commands over `.ax` are reads** (A-SPEC-747). 28 of 79 refused `.ax` commands in four sessions
|
|
23
|
+
only read, and each filed an approval request no one would decide. The gate now splits a command at operators
|
|
24
|
+
outside quotes and substitutions (`grep "a\|b" F` is one clause), judges every command substitution's body by the
|
|
25
|
+
same rule (so `echo "$(sh -c …)"` over `.ax` is newly refused), and knows `cd` (to a literal target), `pwd`,
|
|
26
|
+
`sleep`, `seq`, `pgrep`, clock-reading `date`, `git -C`/`--no-pager` and `while`/`until` loops of reads. Measured:
|
|
27
|
+
read over-blocks 18/29 → 1/29 (the remaining one is the remote-code rule), write probes still 32/32 refused.
|
|
28
|
+
- **`sed -i` is judged by the files it edits, not by its script** (A-SPEC-747). A `sed -i` over a file outside the
|
|
29
|
+
project was refused as a project code write because its script mentioned a `.ts` name.
|
|
30
|
+
- **`requirement_triage` judges a lineage approved by its documents, not their count** (A-SPEC-713.4). Only
|
|
31
|
+
lineages of exactly four documents counted as approved: 62 of 672 fully approved lineages here (8 of 671 in a
|
|
32
|
+
second corpus) have sub-slices or retired documents and could never be `fulfilled`, and four approved documents
|
|
33
|
+
without a T-SPEC counted as approved.
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- **The autoreload MCP launcher exits when its client goes away** (A-SPEC-666.1). With `HOLMES_MCP_AUTORELOAD`,
|
|
38
|
+
the supervisor listened to stdin data only; when the client (a restarted Codex app-server daemon, observed) went
|
|
39
|
+
away, the launcher and its server child ran on with PPID 1 for hours. On stdin end or close it now closes the
|
|
40
|
+
child's input (a request forwarded just before is still read) and kills it after a 2 s grace, never restarting it.
|
|
41
|
+
- **A deep-link scan test no longer fails under a loaded parallel run** (A-SPEC-734.2, correcting A-SPEC-734.1, whose
|
|
42
|
+
counted call — `readdirSync` — stayed at 313 with the memo removed and so could not catch it). The 5 s wall-clock bound
|
|
43
|
+
(3.3 s alone, 13.8 s under load) is replaced by the property it guarded — the per-ancestor `.git` probe runs once
|
|
44
|
+
per directory (608–909 calls; 602,608 with the memo removed).
|
|
45
|
+
|
|
8
46
|
## [0.33.0] - 2026-10-01
|
|
9
47
|
|
|
10
48
|
### Changed
|
package/README.md
CHANGED
|
@@ -23,6 +23,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
|
|
|
23
23
|
|
|
24
24
|
### 🛡️ Currently Supported Features (Production Features)
|
|
25
25
|
|
|
26
|
+
- 📖 **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
27
|
- 🗜️ **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
28
|
- 🔎 **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
29
|
- 🚦 **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
|
+
d1018322-muosc0k6
|
|
@@ -42,7 +42,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
|
|
|
42
42
|
exports.classifySecret = classifySecret;
|
|
43
43
|
exports.classifyBlastRadius = classifyBlastRadius;
|
|
44
44
|
exports.assessRisk = assessRisk;
|
|
45
|
-
// @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737
|
|
45
|
+
// @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747
|
|
46
46
|
const fs = __importStar(require("node:fs"));
|
|
47
47
|
const path = __importStar(require("node:path"));
|
|
48
48
|
const risk_types_1 = require("./risk-types");
|
|
@@ -651,6 +651,8 @@ const READ_ONLY_SHELL = new Set([
|
|
|
651
651
|
'cat', 'grep', 'rg', 'ls', 'find', 'head', 'tail', 'wc', 'diff', 'awk', 'sort', 'uniq',
|
|
652
652
|
'less', 'more', 'file', 'stat', 'du', 'cut', 'tr', 'column', 'jq', 'basename', 'dirname',
|
|
653
653
|
'realpath', 'echo', 'printf', 'true', 'test',
|
|
654
|
+
// @implements A-SPEC-747 — measured in the refused reads: none of these writes a file.
|
|
655
|
+
'cd', 'pwd', 'sleep', 'seq', 'pgrep',
|
|
654
656
|
]);
|
|
655
657
|
/** `git` subcommands that only read. `commit`/`checkout`/`add` are not among them. */
|
|
656
658
|
const READ_ONLY_GIT = new Set([
|
|
@@ -692,11 +694,175 @@ function sedInPlaceFlag(t) {
|
|
|
692
694
|
* hide behind a pipe (`cat SPEC | tee OTHER`).
|
|
693
695
|
*/
|
|
694
696
|
function splitShellClauses(cmd) {
|
|
695
|
-
|
|
696
|
-
|
|
697
|
+
// @implements A-SPEC-747 — operators inside quotes or a substitution are text, not separators: `grep "a\|b" F`
|
|
698
|
+
// was judged as the clause `b" F`, which is no known read (17 of 28 measured reads refused). An unclosed quote
|
|
699
|
+
// keeps the quote-blind split — when the reader is unsure it cuts more, never less.
|
|
700
|
+
const pieces = splitUnquoted(cmd) ?? cmd.split(/\|\||&&|;|\||\n/);
|
|
701
|
+
return pieces
|
|
697
702
|
.map((c) => c.replace(/^[\s(]+/, '').trim())
|
|
698
703
|
.filter((c) => c.length > 0);
|
|
699
704
|
}
|
|
705
|
+
/**
|
|
706
|
+
* @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
|
|
707
|
+
* escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
|
|
708
|
+
*/
|
|
709
|
+
function splitUnquoted(cmd) {
|
|
710
|
+
const out = [];
|
|
711
|
+
let cur = '';
|
|
712
|
+
let quote = null;
|
|
713
|
+
let depth = 0;
|
|
714
|
+
let tick = false;
|
|
715
|
+
for (let i = 0; i < cmd.length; i++) {
|
|
716
|
+
const ch = cmd[i];
|
|
717
|
+
if (quote === "'") {
|
|
718
|
+
cur += ch;
|
|
719
|
+
if (ch === "'")
|
|
720
|
+
quote = null;
|
|
721
|
+
continue;
|
|
722
|
+
}
|
|
723
|
+
if (ch === '\\' && i + 1 < cmd.length) {
|
|
724
|
+
cur += ch + cmd[i + 1];
|
|
725
|
+
i++;
|
|
726
|
+
continue;
|
|
727
|
+
}
|
|
728
|
+
if (ch === '`') {
|
|
729
|
+
tick = !tick;
|
|
730
|
+
cur += ch;
|
|
731
|
+
continue;
|
|
732
|
+
}
|
|
733
|
+
if ((ch === '$' || ch === '<' || ch === '>') && cmd[i + 1] === '(') {
|
|
734
|
+
depth++;
|
|
735
|
+
cur += ch + '(';
|
|
736
|
+
i++;
|
|
737
|
+
continue;
|
|
738
|
+
}
|
|
739
|
+
if (depth > 0 && ch === ')') {
|
|
740
|
+
depth--;
|
|
741
|
+
cur += ch;
|
|
742
|
+
continue;
|
|
743
|
+
}
|
|
744
|
+
if (quote === '"') {
|
|
745
|
+
cur += ch;
|
|
746
|
+
if (ch === '"')
|
|
747
|
+
quote = null;
|
|
748
|
+
continue;
|
|
749
|
+
}
|
|
750
|
+
if (ch === '"' || ch === "'") {
|
|
751
|
+
quote = ch;
|
|
752
|
+
cur += ch;
|
|
753
|
+
continue;
|
|
754
|
+
}
|
|
755
|
+
if (depth === 0 && !tick) {
|
|
756
|
+
if (ch === '\n' || ch === ';') {
|
|
757
|
+
out.push(cur);
|
|
758
|
+
cur = '';
|
|
759
|
+
continue;
|
|
760
|
+
}
|
|
761
|
+
if (ch === '|') {
|
|
762
|
+
if (cmd[i + 1] === '|')
|
|
763
|
+
i++;
|
|
764
|
+
out.push(cur);
|
|
765
|
+
cur = '';
|
|
766
|
+
continue;
|
|
767
|
+
}
|
|
768
|
+
if (ch === '&' && cmd[i + 1] === '&') {
|
|
769
|
+
i++;
|
|
770
|
+
out.push(cur);
|
|
771
|
+
cur = '';
|
|
772
|
+
continue;
|
|
773
|
+
}
|
|
774
|
+
}
|
|
775
|
+
cur += ch;
|
|
776
|
+
}
|
|
777
|
+
if (quote !== null || depth !== 0 || tick)
|
|
778
|
+
return null;
|
|
779
|
+
out.push(cur);
|
|
780
|
+
return out;
|
|
781
|
+
}
|
|
782
|
+
/** @implements A-SPEC-747 — how deep command substitutions are followed before a clause stops counting as a read. */
|
|
783
|
+
const MAX_SUBSTITUTION_DEPTH = 4;
|
|
784
|
+
/**
|
|
785
|
+
* @implements A-SPEC-747 — the command substitutions a clause runs (`$(…)`, backticks, `<(…)`; also inside double
|
|
786
|
+
* quotes, where they still run) and the clause with each replaced by a placeholder word. `null` when one is left
|
|
787
|
+
* open, or for `>(…)` (a process the output is written into).
|
|
788
|
+
*/
|
|
789
|
+
function substitutionsOf(clause) {
|
|
790
|
+
const bodies = [];
|
|
791
|
+
let rest = '';
|
|
792
|
+
let single = false;
|
|
793
|
+
for (let i = 0; i < clause.length; i++) {
|
|
794
|
+
const ch = clause[i];
|
|
795
|
+
if (single) {
|
|
796
|
+
rest += ch;
|
|
797
|
+
if (ch === "'")
|
|
798
|
+
single = false;
|
|
799
|
+
continue;
|
|
800
|
+
}
|
|
801
|
+
if (ch === '\\' && i + 1 < clause.length) {
|
|
802
|
+
rest += ch + clause[i + 1];
|
|
803
|
+
i++;
|
|
804
|
+
continue;
|
|
805
|
+
}
|
|
806
|
+
if (ch === "'") {
|
|
807
|
+
single = true;
|
|
808
|
+
rest += ch;
|
|
809
|
+
continue;
|
|
810
|
+
}
|
|
811
|
+
if (ch === '>' && clause[i + 1] === '(')
|
|
812
|
+
return null;
|
|
813
|
+
if ((ch === '$' || ch === '<') && clause[i + 1] === '(') {
|
|
814
|
+
let depth = 1;
|
|
815
|
+
let j = i + 2;
|
|
816
|
+
for (; j < clause.length && depth > 0; j++) {
|
|
817
|
+
if (clause[j] === '(')
|
|
818
|
+
depth++;
|
|
819
|
+
else if (clause[j] === ')')
|
|
820
|
+
depth--;
|
|
821
|
+
}
|
|
822
|
+
if (depth !== 0)
|
|
823
|
+
return null;
|
|
824
|
+
bodies.push(clause.slice(i + 2, j - 1));
|
|
825
|
+
rest += 'x';
|
|
826
|
+
i = j - 1;
|
|
827
|
+
continue;
|
|
828
|
+
}
|
|
829
|
+
if (ch === '`') {
|
|
830
|
+
const end = clause.indexOf('`', i + 1);
|
|
831
|
+
if (end < 0)
|
|
832
|
+
return null;
|
|
833
|
+
bodies.push(clause.slice(i + 1, end));
|
|
834
|
+
rest += 'x';
|
|
835
|
+
i = end;
|
|
836
|
+
continue;
|
|
837
|
+
}
|
|
838
|
+
rest += ch;
|
|
839
|
+
}
|
|
840
|
+
return { bodies, rest };
|
|
841
|
+
}
|
|
842
|
+
/**
|
|
843
|
+
* @implements A-SPEC-747 — a clause is a read when every substitution it runs is all reads (judged by the same rule,
|
|
844
|
+
* at most MAX_SUBSTITUTION_DEPTH deep) and the clause itself, with each substitution a placeholder, is a read. Before
|
|
845
|
+
* this, `echo "$(sh -c …)"` over .ax read as `echo` — the substitution was never judged.
|
|
846
|
+
*/
|
|
847
|
+
function clauseIsRead(clause, isRead, depth = 0) {
|
|
848
|
+
// A `cd` whose target is computed (a substitution, variable or glob) is not a read: the rules after it cannot know
|
|
849
|
+
// where relative paths land, and treating it as a read let `cd "$(printf '.%s' ax)"; echo x >& ./ledger/…` through
|
|
850
|
+
// (A-SPEC-728 round 27 pin — measured while building this slice). Only a certain cd moves on as a read.
|
|
851
|
+
if (/^cd(?:\s|$)/.test(clause) && /[$`*?[{]/.test(clause))
|
|
852
|
+
return false;
|
|
853
|
+
const subs = substitutionsOf(clause);
|
|
854
|
+
if (subs === null)
|
|
855
|
+
return false;
|
|
856
|
+
if (subs.bodies.length > 0) {
|
|
857
|
+
if (depth >= MAX_SUBSTITUTION_DEPTH)
|
|
858
|
+
return false;
|
|
859
|
+
for (const body of subs.bodies) {
|
|
860
|
+
if (!clausesAreReads(splitShellClauses(body), (c) => clauseIsRead(c, isRead, depth + 1)))
|
|
861
|
+
return false;
|
|
862
|
+
}
|
|
863
|
+
}
|
|
864
|
+
return isRead(subs.rest.trim());
|
|
865
|
+
}
|
|
700
866
|
/**
|
|
701
867
|
* Is this single clause known to only read?
|
|
702
868
|
*
|
|
@@ -717,8 +883,10 @@ function isReadOnlyShellClause(clause) {
|
|
|
717
883
|
let assigned = 0;
|
|
718
884
|
while (assigned < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[assigned]))
|
|
719
885
|
assigned++;
|
|
886
|
+
// @implements A-SPEC-747 — an assignment-only clause runs nothing itself: `f=$(find …)` is a read when its
|
|
887
|
+
// substitution is (clauseIsRead judges the body and hands this rule the placeholder `f=x`).
|
|
720
888
|
if (assigned > 0)
|
|
721
|
-
return assigned
|
|
889
|
+
return assigned === tokens.length || isReadOnlyShellClause(tokens.slice(assigned).join(' '));
|
|
722
890
|
const name = tokens[0].replace(/^.*\//, ''); // /usr/bin/grep -> grep
|
|
723
891
|
// @implements A-SPEC-737 — each of these read commands has a form that writes a named file, and
|
|
724
892
|
// the gate allowed all of them onto .ax/specs (measured through the built hook).
|
|
@@ -750,8 +918,29 @@ function isReadOnlyShellClause(clause) {
|
|
|
750
918
|
return k < tokens.length && isReadOnlyShellClause(tokens.slice(k).join(' '));
|
|
751
919
|
}
|
|
752
920
|
if (name === 'git') {
|
|
753
|
-
|
|
921
|
+
// @implements A-SPEC-747 — `-C <dir>` (repeatable) and `--no-pager` come before the sub-command; any other global
|
|
922
|
+
// option is not a read (`-c core.fsmonitor=…` runs a program on `status`, `--git-dir`/`--work-tree` retarget it).
|
|
923
|
+
let k = 1;
|
|
924
|
+
while (k < tokens.length && tokens[k].startsWith('-')) {
|
|
925
|
+
if (tokens[k] === '-C') {
|
|
926
|
+
k += 2;
|
|
927
|
+
continue;
|
|
928
|
+
}
|
|
929
|
+
if (tokens[k] === '--no-pager') {
|
|
930
|
+
k++;
|
|
931
|
+
continue;
|
|
932
|
+
}
|
|
933
|
+
return false;
|
|
934
|
+
}
|
|
935
|
+
// The sub-command is read by its last path part: the per-segment flattening prefixes every word after a moved
|
|
936
|
+
// base (`git status` → `git <dir>/status`), which read as no known sub-command (measured on a census read). A real
|
|
937
|
+
// git given a path-shaped sub-command only fails, and a write sub-command is not a read under any prefix.
|
|
938
|
+
const sub = k < tokens.length ? tokens[k].replace(/^.*\//, '') : '';
|
|
939
|
+
return sub !== '' && READ_ONLY_GIT.has(sub) && !rest.some((t) => t.startsWith('--output'));
|
|
754
940
|
}
|
|
941
|
+
// @implements A-SPEC-747 — `date` reads unless it sets the clock (`-s`, `--set`, or an operand that is not a `+FORMAT`).
|
|
942
|
+
if (name === 'date')
|
|
943
|
+
return !rest.some((t) => t === '-s' || longOption(t, 'set', 2) || !(t.startsWith('-') || t.startsWith('+')));
|
|
755
944
|
// @implements A-SPEC-737 (round 2) — sed `w`/`s///w`, awk `> FILENAME`/`-i inplace`, perl open(),
|
|
756
945
|
// rg --pre and `sort -o<path>` all wrote into .ax/specs while allowed as reads. A programmable
|
|
757
946
|
// reader is a read only in a recognisable read form, judged on quote-aware words.
|
|
@@ -1227,6 +1416,16 @@ function clausesAreReads(clauses, isRead) {
|
|
|
1227
1416
|
inLoop = true;
|
|
1228
1417
|
continue;
|
|
1229
1418
|
}
|
|
1419
|
+
// @implements A-SPEC-747 — `while COND` / `until COND` open a loop like `for`; the condition must itself be a read
|
|
1420
|
+
// (no substitution, no output redirect) and the body keeps the `for` rules.
|
|
1421
|
+
const loopHead = /^(?:while|until)\s+(.*)$/s.exec(c);
|
|
1422
|
+
if (loopHead) {
|
|
1423
|
+
const cond = loopHead[1].trim();
|
|
1424
|
+
if (inLoop || SUBSTITUTION_RE.test(cond) || OUTPUT_REDIRECT_RE.test(cond) || !isRead(cond))
|
|
1425
|
+
return false;
|
|
1426
|
+
inLoop = true;
|
|
1427
|
+
continue;
|
|
1428
|
+
}
|
|
1230
1429
|
if (inLoop && /^done$/.test(c)) {
|
|
1231
1430
|
inLoop = false;
|
|
1232
1431
|
continue;
|
|
@@ -1288,7 +1487,20 @@ function shellWritesProtectedAx(ncmd) {
|
|
|
1288
1487
|
// @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
|
|
1289
1488
|
// because it is a property of the TARGET rather than of the command shape.
|
|
1290
1489
|
const restoreAllowed = !LEDGER_PATH_RE.test(ncmd);
|
|
1291
|
-
|
|
1490
|
+
// @implements A-SPEC-747 — each clause's substitutions are judged first (clauseIsRead).
|
|
1491
|
+
const isRead = (c) => isReadOnlyShellClause(c) || (restoreAllowed && isIndexRestoreClause(c));
|
|
1492
|
+
// After a `cd`, an output redirect into a file is not a read: the redirect rule reads a target token that starts right
|
|
1493
|
+
// after `>`, so `>& path` and `>| path` (a `&` or `|` first) are never seen, and `cd .ax; echo x >& ledger/…` passed once
|
|
1494
|
+
// `cd` became a read (measured while building this slice). Before A-SPEC-747 every command with a `cd` was refused, so
|
|
1495
|
+
// this keeps that shape exactly as refused as it was.
|
|
1496
|
+
let sawCd = false;
|
|
1497
|
+
return !clausesAreReads(splitShellClauses(ncmd), (c) => {
|
|
1498
|
+
if (/^cd(?:\s|$)/.test(c))
|
|
1499
|
+
sawCd = true;
|
|
1500
|
+
else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
|
|
1501
|
+
return false;
|
|
1502
|
+
return clauseIsRead(c, isRead);
|
|
1503
|
+
});
|
|
1292
1504
|
}
|
|
1293
1505
|
/**
|
|
1294
1506
|
* @implements A-SPEC-125.1
|
|
@@ -11,6 +11,18 @@ export declare function resolveRmSignals(command: string, cwd: string, projectRo
|
|
|
11
11
|
* malformed input as absent) is testable at the layer that owns it.
|
|
12
12
|
*/
|
|
13
13
|
export declare function readApprovalFromEnv(): Approval | undefined;
|
|
14
|
+
/**
|
|
15
|
+
* @implements A-SPEC-732 (round 5) — the command as a shell would resolve its words: quotes and
|
|
16
|
+
* backslash escapes removed, `.`/`..` path segments resolved, case folded (macOS paths are
|
|
17
|
+
* case-insensitive). Measured allowed before: `dist/holmes/mcp/./server.js`, `dist/holmes/../holmes/
|
|
18
|
+
* mcp/server.js`, `DIST/…`, a quoted command word, `holmes\-mcp`. Linear: one pass per word.
|
|
19
|
+
*/
|
|
20
|
+
/**
|
|
21
|
+
* @implements A-SPEC-747 — the files a `sed` with an in-place flag writes: its non-option operands, minus the script.
|
|
22
|
+
* The script is the first non-option operand unless `-e`/`--expression`/`-f`/`--file` supplied it; BSD's `-i ''` takes
|
|
23
|
+
* the empty word as its suffix. Words are read quote-aware; an operand that is only a glob or a variable still counts.
|
|
24
|
+
*/
|
|
25
|
+
export declare function sedInPlaceFiles(text: string): string[];
|
|
14
26
|
/**
|
|
15
27
|
* @implements A-SPEC-732 (round 2) — the PreToolUse output. For `approval_commit` an unobjected call
|
|
16
28
|
* carries no decision: an `allow` would pre-empt the harness's own sensitive-tool confirmation, the
|
|
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.DEFAULT_SPECS_DIR = void 0;
|
|
37
37
|
exports.resolveRmSignals = resolveRmSignals;
|
|
38
38
|
exports.readApprovalFromEnv = readApprovalFromEnv;
|
|
39
|
+
exports.sedInPlaceFiles = sedInPlaceFiles;
|
|
39
40
|
exports.hookOutputFor = hookOutputFor;
|
|
40
41
|
exports.dumpsEnvInCommandPosition = dumpsEnvInCommandPosition;
|
|
41
42
|
exports.normalizeHookInput = normalizeHookInput;
|
|
@@ -46,7 +47,7 @@ exports.gateErrorDecision = gateErrorDecision;
|
|
|
46
47
|
exports.wiredSpecsDir = wiredSpecsDir;
|
|
47
48
|
exports.evaluateHook = evaluateHook;
|
|
48
49
|
exports.readSpecsSync = readSpecsSync;
|
|
49
|
-
// @implements A-SPEC-278, A-SPEC-733, A-SPEC-734
|
|
50
|
+
// @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747
|
|
50
51
|
// @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
|
|
51
52
|
// evaluateHook in this file to prove it.
|
|
52
53
|
// @implements A-SPEC-643
|
|
@@ -386,6 +387,52 @@ const LOCAL_SERVER_RUN = /(?:^|[\s;&|(])(?:exec\s+)?(?:node|nodejs|bun|deno|tsx|
|
|
|
386
387
|
* case-insensitive). Measured allowed before: `dist/holmes/mcp/./server.js`, `dist/holmes/../holmes/
|
|
387
388
|
* mcp/server.js`, `DIST/…`, a quoted command word, `holmes\-mcp`. Linear: one pass per word.
|
|
388
389
|
*/
|
|
390
|
+
/**
|
|
391
|
+
* @implements A-SPEC-747 — the files a `sed` with an in-place flag writes: its non-option operands, minus the script.
|
|
392
|
+
* The script is the first non-option operand unless `-e`/`--expression`/`-f`/`--file` supplied it; BSD's `-i ''` takes
|
|
393
|
+
* the empty word as its suffix. Words are read quote-aware; an operand that is only a glob or a variable still counts.
|
|
394
|
+
*/
|
|
395
|
+
function sedInPlaceFiles(text) {
|
|
396
|
+
const toks = text.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
|
|
397
|
+
const unq = (t) => t.replace(/^(['"])(.*)\1$/s, '$2');
|
|
398
|
+
const files = [];
|
|
399
|
+
for (let i = 0; i < toks.length; i++) {
|
|
400
|
+
if (!/(^|\/)g?sed$/.test(unq(toks[i])))
|
|
401
|
+
continue;
|
|
402
|
+
const args = [];
|
|
403
|
+
let j = i + 1;
|
|
404
|
+
for (; j < toks.length && !/^(?:\|\|?|&&?|;)$/.test(toks[j]) && !/^[0-9]*[<>]/.test(toks[j]); j++)
|
|
405
|
+
args.push(toks[j]);
|
|
406
|
+
i = j - 1;
|
|
407
|
+
const inPlace = args.some((a) => /^--in-place(=|$)/.test(unq(a)) || /^-[^-]*[iI]/.test(unq(a)));
|
|
408
|
+
if (!inPlace)
|
|
409
|
+
continue;
|
|
410
|
+
let scriptGiven = false;
|
|
411
|
+
const operands = [];
|
|
412
|
+
for (let k = 0; k < args.length; k++) {
|
|
413
|
+
const a = args[k];
|
|
414
|
+
const u = unq(a);
|
|
415
|
+
if (u === '-e' || u === '--expression' || u === '-f' || u === '--file') {
|
|
416
|
+
scriptGiven = true;
|
|
417
|
+
k++;
|
|
418
|
+
continue;
|
|
419
|
+
}
|
|
420
|
+
if (/^--(?:expression|file)=/.test(u)) {
|
|
421
|
+
scriptGiven = true;
|
|
422
|
+
continue;
|
|
423
|
+
}
|
|
424
|
+
if ((u === '-i' || u === '-I') && (args[k + 1] === "''" || args[k + 1] === '""')) {
|
|
425
|
+
k++;
|
|
426
|
+
continue;
|
|
427
|
+
}
|
|
428
|
+
if (u.startsWith('-') && u.length > 1)
|
|
429
|
+
continue;
|
|
430
|
+
operands.push(u);
|
|
431
|
+
}
|
|
432
|
+
files.push(...(scriptGiven ? operands : operands.slice(1)));
|
|
433
|
+
}
|
|
434
|
+
return files;
|
|
435
|
+
}
|
|
389
436
|
function normalizedCommand(command) {
|
|
390
437
|
return command.replace(/\\(.)/g, '$1').replace(/["']/g, '').toLowerCase().split(/(\s+)/).map((word) => {
|
|
391
438
|
if (!word.includes('/'))
|
|
@@ -1415,12 +1462,18 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1415
1462
|
// @implements A-SPEC-463 — same quoted-space fix as the config rule; `EXT_TAIL` is the
|
|
1416
1463
|
// extension part and `pathAlt` supplies the prefix and the quoting alternatives.
|
|
1417
1464
|
const EXT_TAIL = `\\.${CODE_EXT}`;
|
|
1465
|
+
const CODE_TAIL_RE_SED = new RegExp(`${EXT_TAIL}$`);
|
|
1418
1466
|
const candidates = [];
|
|
1419
1467
|
const CODE_REDIRECT = new RegExp(`(?:>{1,2}|\\btee\\b(?:\\s+-a)?\\s)\\s*${pathAlt(EXT_TAIL)}`, 'g');
|
|
1420
1468
|
for (const seg of segments) {
|
|
1421
1469
|
collectSeg(seg, CODE_REDIRECT, candidates);
|
|
1422
1470
|
collectPaths(seg, /\btouch\s+/, EXT_TAIL, candidates);
|
|
1423
|
-
|
|
1471
|
+
// @implements A-SPEC-747 — only sed's FILE operands are written; its script is not. Every code-named word of a
|
|
1472
|
+
// `sed -i` segment was a candidate, so `sed -i '' 's#a.test.ts#src/x.ts#' <outside>/notes.md` was denied as a
|
|
1473
|
+
// project code write (measured 2026-10-01).
|
|
1474
|
+
for (const raw of sedInPlaceFiles(seg.text))
|
|
1475
|
+
if (CODE_TAIL_RE_SED.test(raw))
|
|
1476
|
+
candidates.push({ raw, base: seg.base });
|
|
1424
1477
|
}
|
|
1425
1478
|
// @implements A-SPEC-449 — the copy/move family. The CONFIG rule has carried it since
|
|
1426
1479
|
// A-SPEC-191 §28 ("a gate that names one syntax for an act is a gate over that syntax, not
|
|
@@ -7,6 +7,8 @@ export declare const AUTORELOAD_ENV = "HOLMES_MCP_AUTORELOAD";
|
|
|
7
7
|
* spawn" stops quickly while "one OOM under load" restarts freely.
|
|
8
8
|
*/
|
|
9
9
|
export declare const MAX_CONSECUTIVE_SILENT_DEATHS = 5;
|
|
10
|
+
/** @implements A-SPEC-666.1 — how long a child may take to leave after its input closes before it is killed. */
|
|
11
|
+
export declare const INPUT_END_GRACE_MS = 2000;
|
|
10
12
|
export declare function autoreloadEnabled(env: NodeJS.ProcessEnv): boolean;
|
|
11
13
|
/**
|
|
12
14
|
* Whether the child may be replaced right now.
|
|
@@ -85,6 +87,12 @@ export declare class Supervisor {
|
|
|
85
87
|
private givenUp;
|
|
86
88
|
constructor(repoRoot: string, onSwap?: ((from: string, to: string, replayed: number) => void) | undefined);
|
|
87
89
|
start(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): void;
|
|
90
|
+
/**
|
|
91
|
+
* @implements A-SPEC-666.1 — close the child's input rather than kill it, so a request forwarded just before the
|
|
92
|
+
* end is still read (killing at once dropped it — measured by the corner case); a child that does not leave on its
|
|
93
|
+
* own within the grace period is killed. Never restarted afterwards (`givenUp`).
|
|
94
|
+
*/
|
|
95
|
+
private endInput;
|
|
88
96
|
private forward;
|
|
89
97
|
private swap;
|
|
90
98
|
private spawnChild;
|
|
@@ -33,11 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.Supervisor = exports.MAX_CONSECUTIVE_SILENT_DEATHS = exports.AUTORELOAD_ENV = void 0;
|
|
36
|
+
exports.Supervisor = exports.INPUT_END_GRACE_MS = exports.MAX_CONSECUTIVE_SILENT_DEATHS = exports.AUTORELOAD_ENV = void 0;
|
|
37
37
|
exports.autoreloadEnabled = autoreloadEnabled;
|
|
38
38
|
exports.shouldSwap = shouldSwap;
|
|
39
39
|
exports.createResponseCounter = createResponseCounter;
|
|
40
|
-
// @implements A-SPEC-721, A-SPEC-162
|
|
40
|
+
// @implements A-SPEC-721, A-SPEC-162, A-SPEC-666.1
|
|
41
41
|
const node_child_process_1 = require("node:child_process");
|
|
42
42
|
const path = __importStar(require("node:path"));
|
|
43
43
|
const basis_1 = require("./basis");
|
|
@@ -50,6 +50,8 @@ exports.AUTORELOAD_ENV = 'HOLMES_MCP_AUTORELOAD';
|
|
|
50
50
|
* spawn" stops quickly while "one OOM under load" restarts freely.
|
|
51
51
|
*/
|
|
52
52
|
exports.MAX_CONSECUTIVE_SILENT_DEATHS = 5;
|
|
53
|
+
/** @implements A-SPEC-666.1 — how long a child may take to leave after its input closes before it is killed. */
|
|
54
|
+
exports.INPUT_END_GRACE_MS = 2000;
|
|
53
55
|
function autoreloadEnabled(env) {
|
|
54
56
|
const v = env[exports.AUTORELOAD_ENV];
|
|
55
57
|
return typeof v === 'string' && v.trim() !== '';
|
|
@@ -181,6 +183,34 @@ class Supervisor {
|
|
|
181
183
|
this.forward(line, stdout);
|
|
182
184
|
}
|
|
183
185
|
});
|
|
186
|
+
// @implements A-SPEC-666.1 — the client is gone when its input ends. Listening for `data` only, the launcher
|
|
187
|
+
// ran on as an orphan (PPID 1, four hours, observed 2026-10-01): the pipe to the live child kept the event loop
|
|
188
|
+
// alive. Complete lines were already forwarded above; a partial trailing line has no one to answer it.
|
|
189
|
+
stdin.on('end', () => this.endInput());
|
|
190
|
+
stdin.on('close', () => this.endInput());
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* @implements A-SPEC-666.1 — close the child's input rather than kill it, so a request forwarded just before the
|
|
194
|
+
* end is still read (killing at once dropped it — measured by the corner case); a child that does not leave on its
|
|
195
|
+
* own within the grace period is killed. Never restarted afterwards (`givenUp`).
|
|
196
|
+
*/
|
|
197
|
+
endInput() {
|
|
198
|
+
if (this.givenUp)
|
|
199
|
+
return;
|
|
200
|
+
this.expectedExit = true;
|
|
201
|
+
this.givenUp = true;
|
|
202
|
+
const child = this.child;
|
|
203
|
+
if (child === undefined)
|
|
204
|
+
return;
|
|
205
|
+
try {
|
|
206
|
+
child.stdin.end();
|
|
207
|
+
}
|
|
208
|
+
catch { /* already closed */ }
|
|
209
|
+
const timer = setTimeout(() => { try {
|
|
210
|
+
child.kill();
|
|
211
|
+
}
|
|
212
|
+
catch { /* already gone */ } }, exports.INPUT_END_GRACE_MS);
|
|
213
|
+
timer.unref();
|
|
184
214
|
}
|
|
185
215
|
forward(line, stdout) {
|
|
186
216
|
const trimmed = line.trim();
|
|
@@ -4,12 +4,14 @@ exports.canonicalRequirementDocument = void 0;
|
|
|
4
4
|
exports.requestIdentifiers = requestIdentifiers;
|
|
5
5
|
exports.triageRequirements = triageRequirements;
|
|
6
6
|
exports.requirementSemanticCoverage = requirementSemanticCoverage;
|
|
7
|
-
// @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-742, A-SPEC-713
|
|
7
|
+
// @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-713.4, A-SPEC-742, A-SPEC-713
|
|
8
8
|
/** Pure, conservative lifecycle triage over governed requirement documents. */
|
|
9
9
|
const semantic_retrieval_1 = require("./semantic-retrieval");
|
|
10
10
|
const localize_1 = require("../rtm/localize");
|
|
11
11
|
const vector_coverage_1 = require("../semantic/vector-coverage");
|
|
12
12
|
const CODE_FILE = /\.(ts|tsx|js|mjs|cjs|py|go|rs|java|cs|rb|sh|json|ya?ml|toml|md)$/i;
|
|
13
|
+
/** @implements A-SPEC-713.4 — the kinds an approved lineage has among its live documents. */
|
|
14
|
+
const LINEAGE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC'];
|
|
13
15
|
/**
|
|
14
16
|
* @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
|
|
15
17
|
* paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
|
|
@@ -196,7 +198,12 @@ function triageCore(input) {
|
|
|
196
198
|
const textLower = row.text.toLowerCase();
|
|
197
199
|
const contentTerms = promptTerms.filter((term) => textLower.includes(term));
|
|
198
200
|
const operational = input.evidence?.[row.reqId] ?? {};
|
|
199
|
-
|
|
201
|
+
// @implements A-SPEC-713.4 — judged by the documents, not their count: `length === 4` left 62 of 672 fully
|
|
202
|
+
// approved lineages here (8 of 671 in jarvis) unapproved because they carry sub-slices or retired documents,
|
|
203
|
+
// and counted REQ, H-SPEC and two A-SPECs without any T-SPEC as approved.
|
|
204
|
+
const live = row.docs.filter((d) => d.status !== 'outdated');
|
|
205
|
+
const kinds = new Set(live.map((d) => d.type));
|
|
206
|
+
const approved = live.every((d) => d.status === 'approved') && LINEAGE_KINDS.every((kind) => kinds.has(kind));
|
|
200
207
|
const anchors = [...new Set(operational.implementationAnchors ?? [])].sort();
|
|
201
208
|
const reasons = [
|
|
202
209
|
...(cited ? ['cited'] : []),
|
|
@@ -16,6 +16,12 @@ export interface ReleaseTestLaneReceipt {
|
|
|
16
16
|
pattern: string;
|
|
17
17
|
reason: string;
|
|
18
18
|
}>;
|
|
19
|
+
/** @implements A-SPEC-748 — present only on a receipt a docs-only commit inherited from a FULL lane receipt. */
|
|
20
|
+
inheritedFrom?: {
|
|
21
|
+
head: string;
|
|
22
|
+
completedAt: string;
|
|
23
|
+
digest: string;
|
|
24
|
+
};
|
|
19
25
|
digest: string;
|
|
20
26
|
}
|
|
21
27
|
export type ReleaseTestLaneValidation = {
|
|
@@ -27,8 +33,54 @@ export type ReleaseTestLaneValidation = {
|
|
|
27
33
|
};
|
|
28
34
|
/** Persist only evidence whose scope is explicit and bounded; callers cannot choose its path. */
|
|
29
35
|
export declare function writeReleaseTestLaneReceipt(root: string, input: Omit<ReleaseTestLaneReceipt, 'schema' | 'digest'>): ReleaseTestLaneReceipt | null;
|
|
36
|
+
/** @implements A-SPEC-748 — the last FULL lane receipt, kept beside the current one (git-ignored like it). */
|
|
37
|
+
export declare const RELEASE_TEST_LANE_FULL_FILE: string;
|
|
38
|
+
/**
|
|
39
|
+
* @implements A-SPEC-748 — the tests an inherited receipt runs: every test that reads the repository's own README or
|
|
40
|
+
* docs/, plus the docs-currency, publish-docs-gate and packaging tests. A ratchet test fails when a new reader is missing.
|
|
41
|
+
*/
|
|
42
|
+
export declare const REQUIRED_DOCS_TESTS: readonly string[];
|
|
43
|
+
export interface LaneChange {
|
|
44
|
+
status: string;
|
|
45
|
+
paths: string[];
|
|
46
|
+
}
|
|
47
|
+
export interface LaneGit {
|
|
48
|
+
isAncestor(base: string, head: string): boolean;
|
|
49
|
+
changes(base: string, head: string): LaneChange[] | null;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* @implements A-SPEC-748 — every path of every change (both sides of a rename or copy) must be `README.md` or under
|
|
53
|
+
* `docs/`, and none may be shipped (equal to, or under a directory entry of, package.json `files`).
|
|
54
|
+
*/
|
|
55
|
+
export declare function inheritablePaths(changes: readonly LaneChange[], shipped: readonly string[]): {
|
|
56
|
+
ok: true;
|
|
57
|
+
} | {
|
|
58
|
+
ok: false;
|
|
59
|
+
path: string;
|
|
60
|
+
};
|
|
61
|
+
/** @implements A-SPEC-748 — the two git questions inheritance asks, answered by git in `root`; `null`/false when git cannot. */
|
|
62
|
+
export declare function laneGit(root: string): LaneGit;
|
|
63
|
+
/**
|
|
64
|
+
* @implements A-SPEC-748 — record a receipt for HEAD by inheriting the kept full lane receipt: refused unless the full
|
|
65
|
+
* receipt is valid, fresh and an ancestor, every change since it is inheritable, and the required docs tests pass.
|
|
66
|
+
*/
|
|
67
|
+
export declare function inheritReleaseTestLane(root: string, head: string, opts: {
|
|
68
|
+
git: LaneGit;
|
|
69
|
+
shipped: readonly string[];
|
|
70
|
+
runDocsTests: (files: readonly string[]) => boolean;
|
|
71
|
+
now?: number;
|
|
72
|
+
}): {
|
|
73
|
+
ok: true;
|
|
74
|
+
receipt: ReleaseTestLaneReceipt;
|
|
75
|
+
} | {
|
|
76
|
+
ok: false;
|
|
77
|
+
reason: string;
|
|
78
|
+
};
|
|
30
79
|
/** Read the sole project-local receipt and fail closed for every missing or unprovable condition. */
|
|
31
|
-
export declare function validateReleaseTestLaneReceipt(root: string, head: string, now?: number
|
|
80
|
+
export declare function validateReleaseTestLaneReceipt(root: string, head: string, now?: number, inherit?: {
|
|
81
|
+
git: LaneGit;
|
|
82
|
+
shipped: readonly string[];
|
|
83
|
+
}): ReleaseTestLaneValidation;
|
|
32
84
|
export declare function outcomesFilename(replica: string): string;
|
|
33
85
|
export declare function isOutcomesFilename(name: string): boolean;
|
|
34
86
|
/**
|
|
@@ -33,8 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.RELEASE_TEST_LANE_SCHEMA = exports.RELEASE_TEST_LANE_FILE = exports.OUTCOMES_FILE = void 0;
|
|
36
|
+
exports.REQUIRED_DOCS_TESTS = exports.RELEASE_TEST_LANE_FULL_FILE = exports.RELEASE_TEST_LANE_SCHEMA = exports.RELEASE_TEST_LANE_FILE = exports.OUTCOMES_FILE = void 0;
|
|
37
37
|
exports.writeReleaseTestLaneReceipt = writeReleaseTestLaneReceipt;
|
|
38
|
+
exports.inheritablePaths = inheritablePaths;
|
|
39
|
+
exports.laneGit = laneGit;
|
|
40
|
+
exports.inheritReleaseTestLane = inheritReleaseTestLane;
|
|
38
41
|
exports.validateReleaseTestLaneReceipt = validateReleaseTestLaneReceipt;
|
|
39
42
|
exports.outcomesFilename = outcomesFilename;
|
|
40
43
|
exports.isOutcomesFilename = isOutcomesFilename;
|
|
@@ -42,10 +45,11 @@ exports.appendOutcomes = appendOutcomes;
|
|
|
42
45
|
exports.readOutcomes = readOutcomes;
|
|
43
46
|
exports.buildOutcomeRecords = buildOutcomeRecords;
|
|
44
47
|
exports.groupOutcomesByAspec = groupOutcomesByAspec;
|
|
45
|
-
// @implements A-SPEC-724.1, A-SPEC-714, A-SPEC-734
|
|
48
|
+
// @implements A-SPEC-724.1, A-SPEC-714, A-SPEC-734, A-SPEC-748
|
|
46
49
|
// @implements A-SPEC-534.3, A-SPEC-625
|
|
47
50
|
// @implements A-SPEC-645
|
|
48
51
|
const node_crypto_1 = require("node:crypto");
|
|
52
|
+
const node_child_process_1 = require("node:child_process");
|
|
49
53
|
const execution_context_1 = require("../project/execution-context");
|
|
50
54
|
const fs = __importStar(require("node:fs"));
|
|
51
55
|
const path = __importStar(require("node:path"));
|
|
@@ -55,10 +59,12 @@ exports.OUTCOMES_FILE = path.join('.ax', 'ledger', 'test-outcomes.jsonl');
|
|
|
55
59
|
exports.RELEASE_TEST_LANE_FILE = path.join('.ax', 'evidence', 'release-test-lane.json');
|
|
56
60
|
exports.RELEASE_TEST_LANE_SCHEMA = 'release-test-lane/1';
|
|
57
61
|
const RELEASE_TEST_LANE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
|
|
62
|
+
// A full receipt signs exactly what it always signed; `inheritedFrom` is signed only where it exists.
|
|
58
63
|
const stableReceipt = (receipt) => JSON.stringify({
|
|
59
64
|
schema: receipt.schema, root: receipt.root, head: receipt.head, completedAt: receipt.completedAt,
|
|
60
65
|
passed: receipt.passed, externalAccess: receipt.externalAccess, command: receipt.command,
|
|
61
66
|
include: receipt.include, exclusions: receipt.exclusions,
|
|
67
|
+
...(receipt.inheritedFrom ? { inheritedFrom: receipt.inheritedFrom } : {}),
|
|
62
68
|
});
|
|
63
69
|
const releaseReceiptDigest = (receipt) => `sha256:${(0, node_crypto_1.createHash)('sha256').update(stableReceipt(receipt)).digest('hex')}`;
|
|
64
70
|
/** Persist only evidence whose scope is explicit and bounded; callers cannot choose its path. */
|
|
@@ -68,24 +74,142 @@ function writeReleaseTestLaneReceipt(root, input) {
|
|
|
68
74
|
const receipt = normalizeReleaseTestLaneReceipt(root, { ...input, schema: exports.RELEASE_TEST_LANE_SCHEMA });
|
|
69
75
|
if (receipt === null)
|
|
70
76
|
return null;
|
|
71
|
-
|
|
77
|
+
if (!writeAtomic(path.join(path.resolve(root), exports.RELEASE_TEST_LANE_FILE), receipt))
|
|
78
|
+
return null;
|
|
79
|
+
// @implements A-SPEC-748 — a FULL lane is also kept as the base later docs-only commits inherit from.
|
|
80
|
+
if (!receipt.inheritedFrom && !writeAtomic(path.join(path.resolve(root), exports.RELEASE_TEST_LANE_FULL_FILE), receipt))
|
|
81
|
+
return null;
|
|
82
|
+
return receipt;
|
|
83
|
+
}
|
|
84
|
+
function writeAtomic(file, receipt) {
|
|
72
85
|
const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
|
|
73
86
|
try {
|
|
74
87
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
75
88
|
fs.writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { encoding: 'utf8', mode: 0o600 });
|
|
76
89
|
fs.renameSync(tmp, file);
|
|
77
|
-
return
|
|
90
|
+
return true;
|
|
78
91
|
}
|
|
79
92
|
catch {
|
|
80
93
|
try {
|
|
81
94
|
fs.unlinkSync(tmp);
|
|
82
95
|
}
|
|
83
96
|
catch { /* no partial receipt is valid */ }
|
|
84
|
-
return
|
|
97
|
+
return false;
|
|
85
98
|
}
|
|
86
99
|
}
|
|
100
|
+
/** @implements A-SPEC-748 — the last FULL lane receipt, kept beside the current one (git-ignored like it). */
|
|
101
|
+
exports.RELEASE_TEST_LANE_FULL_FILE = path.join('.ax', 'evidence', 'release-test-lane.full.json');
|
|
102
|
+
/**
|
|
103
|
+
* @implements A-SPEC-748 — the tests an inherited receipt runs: every test that reads the repository's own README or
|
|
104
|
+
* docs/, plus the docs-currency, publish-docs-gate and packaging tests. A ratchet test fails when a new reader is missing.
|
|
105
|
+
*/
|
|
106
|
+
exports.REQUIRED_DOCS_TESTS = [
|
|
107
|
+
'src/holmes/project/docs-currency.test.ts',
|
|
108
|
+
'src/holmes/playbooks/publish-docs-gate.test.ts',
|
|
109
|
+
'src/holmes/playbooks/packaging.test.ts',
|
|
110
|
+
'src/holmes/cpg/foundation/language-matrix.test.ts',
|
|
111
|
+
'src/holmes/project/dependency-overrides.test.ts',
|
|
112
|
+
];
|
|
113
|
+
/**
|
|
114
|
+
* @implements A-SPEC-748 — every path of every change (both sides of a rename or copy) must be `README.md` or under
|
|
115
|
+
* `docs/`, and none may be shipped (equal to, or under a directory entry of, package.json `files`).
|
|
116
|
+
*/
|
|
117
|
+
function inheritablePaths(changes, shipped) {
|
|
118
|
+
const isShipped = (p) => shipped.some((raw) => {
|
|
119
|
+
const e = raw.replace(/\\/g, '/').replace(/^\.\//, '');
|
|
120
|
+
return e.endsWith('/') ? p.startsWith(e) : p === e || p.startsWith(`${e}/`);
|
|
121
|
+
});
|
|
122
|
+
for (const change of changes) {
|
|
123
|
+
for (const raw of change.paths) {
|
|
124
|
+
const p = raw.replace(/\\/g, '/');
|
|
125
|
+
if (!(p === 'README.md' || p.startsWith('docs/')) || isShipped(p))
|
|
126
|
+
return { ok: false, path: p };
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return { ok: true };
|
|
130
|
+
}
|
|
131
|
+
/** @implements A-SPEC-748 — the two git questions inheritance asks, answered by git in `root`; `null`/false when git cannot. */
|
|
132
|
+
function laneGit(root) {
|
|
133
|
+
const run = (args) => {
|
|
134
|
+
const r = (0, node_child_process_1.spawnSync)('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 64 * 1024 * 1024 });
|
|
135
|
+
return { status: r.status, stdout: typeof r.stdout === 'string' ? r.stdout : '' };
|
|
136
|
+
};
|
|
137
|
+
return {
|
|
138
|
+
isAncestor: (base, head) => run(['merge-base', '--is-ancestor', base, head]).status === 0,
|
|
139
|
+
changes: (base, head) => {
|
|
140
|
+
const r = run(['diff', '--name-status', '-M', '-z', base, head]);
|
|
141
|
+
if (r.status !== 0)
|
|
142
|
+
return null;
|
|
143
|
+
const parts = r.stdout.split('\0').filter((s) => s !== '');
|
|
144
|
+
const out = [];
|
|
145
|
+
for (let i = 0; i < parts.length;) {
|
|
146
|
+
const status = parts[i++];
|
|
147
|
+
const n = /^[RC]/.test(status) ? 2 : 1;
|
|
148
|
+
out.push({ status, paths: parts.slice(i, i + n) });
|
|
149
|
+
i += n;
|
|
150
|
+
}
|
|
151
|
+
return out;
|
|
152
|
+
},
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
/** @implements A-SPEC-748 — the kept FULL receipt, valid for its own head and not older than the lane's limit. */
|
|
156
|
+
function readFullReceipt(root, now) {
|
|
157
|
+
let parsed;
|
|
158
|
+
try {
|
|
159
|
+
parsed = JSON.parse(fs.readFileSync(path.join(path.resolve(root), exports.RELEASE_TEST_LANE_FULL_FILE), 'utf8'));
|
|
160
|
+
}
|
|
161
|
+
catch {
|
|
162
|
+
return { ok: false, reason: 'no full release test-lane receipt to inherit from — run the full lane (--record-release-test-lane)' };
|
|
163
|
+
}
|
|
164
|
+
const receipt = normalizeReleaseTestLaneReceipt(root, parsed);
|
|
165
|
+
if (receipt === null || receipt.digest !== parsed.digest) {
|
|
166
|
+
return { ok: false, reason: 'the kept full release test-lane receipt is malformed or its digest is invalid' };
|
|
167
|
+
}
|
|
168
|
+
if (receipt.inheritedFrom)
|
|
169
|
+
return { ok: false, reason: 'the kept full receipt is itself inherited — only a full lane can be inherited from' };
|
|
170
|
+
const completedMs = Date.parse(receipt.completedAt);
|
|
171
|
+
if (completedMs > now || now - completedMs > RELEASE_TEST_LANE_MAX_AGE_MS) {
|
|
172
|
+
return { ok: false, reason: 'the kept full release test-lane receipt is older than 24 hours (or in the future)' };
|
|
173
|
+
}
|
|
174
|
+
return { ok: true, receipt };
|
|
175
|
+
}
|
|
176
|
+
/** @implements A-SPEC-748 — whether HEAD may stand on the full receipt: an ancestor, and only inheritable changes since it. */
|
|
177
|
+
function inheritableSince(full, head, git, shipped) {
|
|
178
|
+
if (!git.isAncestor(full.head, head))
|
|
179
|
+
return `the full lane's HEAD ${full.head.slice(0, 12)} is not an ancestor of ${head.slice(0, 12)}`;
|
|
180
|
+
const changes = git.changes(full.head, head);
|
|
181
|
+
if (changes === null)
|
|
182
|
+
return 'git could not list the changes since the full lane';
|
|
183
|
+
const verdict = inheritablePaths(changes, shipped);
|
|
184
|
+
return verdict.ok ? null : `${verdict.path} changed since the full lane — only README.md and unshipped docs/ files may be inherited; run the full lane`;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* @implements A-SPEC-748 — record a receipt for HEAD by inheriting the kept full lane receipt: refused unless the full
|
|
188
|
+
* receipt is valid, fresh and an ancestor, every change since it is inheritable, and the required docs tests pass.
|
|
189
|
+
*/
|
|
190
|
+
function inheritReleaseTestLane(root, head, opts) {
|
|
191
|
+
const now = opts.now ?? Date.now();
|
|
192
|
+
const full = readFullReceipt(root, now);
|
|
193
|
+
if (!full.ok)
|
|
194
|
+
return full;
|
|
195
|
+
if (full.receipt.head === head)
|
|
196
|
+
return { ok: false, reason: 'HEAD already has the full release test-lane receipt — nothing to inherit' };
|
|
197
|
+
const blocked = inheritableSince(full.receipt, head, opts.git, opts.shipped);
|
|
198
|
+
if (blocked !== null)
|
|
199
|
+
return { ok: false, reason: blocked };
|
|
200
|
+
if (!opts.runDocsTests(exports.REQUIRED_DOCS_TESTS))
|
|
201
|
+
return { ok: false, reason: 'the required docs tests failed — this commit is not published on an inherited receipt' };
|
|
202
|
+
const receipt = writeReleaseTestLaneReceipt(root, {
|
|
203
|
+
root: path.resolve(root), head, completedAt: new Date(now).toISOString(), passed: true, externalAccess: 'forbidden',
|
|
204
|
+
command: ['npm', 'test', '--', '--runInBand', ...exports.REQUIRED_DOCS_TESTS],
|
|
205
|
+
include: ['required docs tests on a docs-only commit, inheriting the full lane'],
|
|
206
|
+
exclusions: full.receipt.exclusions,
|
|
207
|
+
inheritedFrom: { head: full.receipt.head, completedAt: full.receipt.completedAt, digest: full.receipt.digest },
|
|
208
|
+
});
|
|
209
|
+
return receipt === null ? { ok: false, reason: 'the inherited release test-lane receipt could not be written' } : { ok: true, receipt };
|
|
210
|
+
}
|
|
87
211
|
/** Read the sole project-local receipt and fail closed for every missing or unprovable condition. */
|
|
88
|
-
function validateReleaseTestLaneReceipt(root, head, now = Date.now()) {
|
|
212
|
+
function validateReleaseTestLaneReceipt(root, head, now = Date.now(), inherit) {
|
|
89
213
|
const expectedRoot = path.resolve(root);
|
|
90
214
|
if (typeof head !== 'string' || head === '' || head.includes('/') || head.includes('\\'))
|
|
91
215
|
return { valid: false, reason: 'invalid current HEAD' };
|
|
@@ -105,6 +229,22 @@ function validateReleaseTestLaneReceipt(root, head, now = Date.now()) {
|
|
|
105
229
|
return { valid: false, reason: 'release test-lane receipt belongs to a different root' };
|
|
106
230
|
if (receipt.head !== head)
|
|
107
231
|
return { valid: false, reason: 'release test-lane receipt HEAD does not match' };
|
|
232
|
+
// @implements A-SPEC-748 — an inherited receipt stands only on the kept full receipt it names, and on a diff
|
|
233
|
+
// recomputed now: a path list written into the receipt is never trusted.
|
|
234
|
+
if (receipt.inheritedFrom) {
|
|
235
|
+
if (!inherit)
|
|
236
|
+
return { valid: false, reason: 'an inherited release test-lane receipt needs the publish-time diff to be checked' };
|
|
237
|
+
const full = readFullReceipt(root, now);
|
|
238
|
+
if (!full.ok)
|
|
239
|
+
return { valid: false, reason: full.reason };
|
|
240
|
+
const f = full.receipt;
|
|
241
|
+
if (f.head !== receipt.inheritedFrom.head || f.completedAt !== receipt.inheritedFrom.completedAt || f.digest !== receipt.inheritedFrom.digest) {
|
|
242
|
+
return { valid: false, reason: 'the inherited receipt does not name the kept full release test-lane receipt' };
|
|
243
|
+
}
|
|
244
|
+
const blocked = inheritableSince(f, head, inherit.git, inherit.shipped);
|
|
245
|
+
if (blocked !== null)
|
|
246
|
+
return { valid: false, reason: blocked };
|
|
247
|
+
}
|
|
108
248
|
const completedMs = Date.parse(receipt.completedAt);
|
|
109
249
|
if (!Number.isFinite(completedMs) || completedMs > now || now - completedMs > RELEASE_TEST_LANE_MAX_AGE_MS) {
|
|
110
250
|
return { valid: false, reason: 'release test-lane receipt is stale or has an invalid timestamp' };
|
|
@@ -122,10 +262,17 @@ function normalizeReleaseTestLaneReceipt(root, input) {
|
|
|
122
262
|
|| typeof value.completedAt !== 'string' || !Number.isFinite(Date.parse(value.completedAt))
|
|
123
263
|
|| value.passed !== true || value.externalAccess !== 'forbidden')
|
|
124
264
|
return null;
|
|
265
|
+
// @implements A-SPEC-748 — an inherited receipt names its full receipt and ran named docs tests; a full one keeps
|
|
266
|
+
// today's command requirements.
|
|
267
|
+
const from = value.inheritedFrom;
|
|
268
|
+
if (from !== undefined && (!from || typeof from.head !== 'string' || from.head === '' || /[\\/]/.test(from.head)
|
|
269
|
+
|| typeof from.completedAt !== 'string' || !Number.isFinite(Date.parse(from.completedAt))
|
|
270
|
+
|| typeof from.digest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(from.digest)))
|
|
271
|
+
return null;
|
|
125
272
|
if (!Array.isArray(value.command) || value.command.some((part) => typeof part !== 'string' || part === '')
|
|
126
273
|
|| value.command.length < 5 || value.command[0] !== 'npm' || value.command[1] !== 'test'
|
|
127
274
|
|| value.command[2] !== '--' || !value.command.includes('--runInBand')
|
|
128
|
-
|| !value.command.some((part) => part.startsWith('--testPathIgnorePatterns=')))
|
|
275
|
+
|| (from === undefined && !value.command.some((part) => part.startsWith('--testPathIgnorePatterns='))))
|
|
129
276
|
return null;
|
|
130
277
|
if (!Array.isArray(value.include) || value.include.length === 0 || value.include.some((part) => typeof part !== 'string' || part.trim() === ''))
|
|
131
278
|
return null;
|
|
@@ -134,7 +281,8 @@ function normalizeReleaseTestLaneReceipt(root, input) {
|
|
|
134
281
|
return null;
|
|
135
282
|
const unsigned = { schema: exports.RELEASE_TEST_LANE_SCHEMA, root: rootPath, head: value.head, completedAt: value.completedAt,
|
|
136
283
|
passed: true, externalAccess: 'forbidden', command: [...value.command], include: [...value.include],
|
|
137
|
-
exclusions: value.exclusions.map((entry) => ({ pattern: entry.pattern, reason: entry.reason }))
|
|
284
|
+
exclusions: value.exclusions.map((entry) => ({ pattern: entry.pattern, reason: entry.reason })),
|
|
285
|
+
...(from !== undefined ? { inheritedFrom: { head: from.head, completedAt: from.completedAt, digest: from.digest } } : {}) };
|
|
138
286
|
return { ...unsigned, digest: releaseReceiptDigest(unsigned) };
|
|
139
287
|
}
|
|
140
288
|
// @implements A-SPEC-562.1 — outcomes join the ledger's REPLICA convention (A-SPEC-148): one file per
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "@implements A-SPEC-209",
|
|
3
3
|
"name": "@holmes-lab/holmes-kit",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.34.0",
|
|
5
5
|
"description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
|
|
6
6
|
"main": "dist/holmes/mcp/server.js",
|
|
7
7
|
"types": "dist/holmes/mcp/server.d.ts",
|