@holmes-lab/holmes-kit 0.32.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 +88 -0
- package/README.md +3 -1
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/autonomy.js +15 -1
- package/dist/holmes/guardrail/impact-gate.js +50 -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/handlers/adoption.d.ts +17 -3
- package/dist/holmes/mcp/handlers/adoption.js +70 -2
- package/dist/holmes/mcp/handlers/graph-operations.js +6 -1
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +9 -16
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +30 -2
- package/dist/holmes/mcp/handlers/phase-queries.js +5 -1
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +44 -1
- package/dist/holmes/mcp/handlers/review-evidence.js +48 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +10 -0
- package/dist/holmes/mcp/handlers/spec-approval.js +16 -1
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +1 -9
- package/dist/holmes/mcp/handlers/spec-queries.js +40 -15
- package/dist/holmes/mcp/handlers.d.ts +43 -14
- package/dist/holmes/mcp/maintenance-analyze.js +64 -6
- package/dist/holmes/mcp/supervisor.d.ts +8 -0
- package/dist/holmes/mcp/supervisor.js +32 -2
- package/dist/holmes/mcp/tool-schemas.js +26 -5
- package/dist/holmes/reverse/scan.d.ts +6 -0
- package/dist/holmes/reverse/scan.js +4 -2
- package/dist/holmes/review/requirement-triage.d.ts +6 -0
- package/dist/holmes/review/requirement-triage.js +78 -9
- package/dist/holmes/review/test-outcomes.d.ts +53 -1
- package/dist/holmes/review/test-outcomes.js +156 -8
- package/dist/holmes/semantic/unreadable-paths.d.ts +30 -0
- package/dist/holmes/semantic/unreadable-paths.js +104 -0
- package/package.json +1 -1
- package/playbooks/author-slice/PLAYBOOK.md +1 -1
- package/playbooks/promote-slice/PLAYBOOK.md +1 -1
|
@@ -469,7 +469,14 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
469
469
|
}>;
|
|
470
470
|
review_status: (a: {
|
|
471
471
|
root: string;
|
|
472
|
+
detail?: unknown;
|
|
472
473
|
}) => Promise<{
|
|
474
|
+
ok: boolean;
|
|
475
|
+
reason: string;
|
|
476
|
+
blocked?: undefined;
|
|
477
|
+
open?: undefined;
|
|
478
|
+
reviewNeeded?: undefined;
|
|
479
|
+
} | {
|
|
473
480
|
blocked: boolean;
|
|
474
481
|
open: {
|
|
475
482
|
critical: number;
|
|
@@ -477,6 +484,25 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
477
484
|
minor: number;
|
|
478
485
|
};
|
|
479
486
|
reviewNeeded: import("../review/review-targets").ReviewNeeded[];
|
|
487
|
+
ok?: undefined;
|
|
488
|
+
reason?: undefined;
|
|
489
|
+
} | {
|
|
490
|
+
reviewNeeded: Array<{
|
|
491
|
+
spec: string;
|
|
492
|
+
files: string[];
|
|
493
|
+
signals: number;
|
|
494
|
+
}>;
|
|
495
|
+
reviewNeededTotal: number;
|
|
496
|
+
reviewNeededOmitted?: number;
|
|
497
|
+
note?: string;
|
|
498
|
+
blocked: boolean;
|
|
499
|
+
open: {
|
|
500
|
+
critical: number;
|
|
501
|
+
important: number;
|
|
502
|
+
minor: number;
|
|
503
|
+
};
|
|
504
|
+
ok?: undefined;
|
|
505
|
+
reason?: undefined;
|
|
480
506
|
}>;
|
|
481
507
|
risk_check: (a: {
|
|
482
508
|
root?: string;
|
|
@@ -494,7 +520,8 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
494
520
|
reverse_scan: (a: {
|
|
495
521
|
root: string;
|
|
496
522
|
maxFlagged?: number;
|
|
497
|
-
|
|
523
|
+
detail?: unknown;
|
|
524
|
+
}) => Promise<Record<string, unknown> | {
|
|
498
525
|
root: string;
|
|
499
526
|
isGit: boolean;
|
|
500
527
|
scanned: number;
|
|
@@ -1203,17 +1230,26 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
1203
1230
|
} | {
|
|
1204
1231
|
ok: boolean;
|
|
1205
1232
|
reason: string;
|
|
1233
|
+
blockers: string[];
|
|
1234
|
+
approvalIntent?: undefined;
|
|
1235
|
+
conflict?: undefined;
|
|
1236
|
+
} | {
|
|
1237
|
+
ok: boolean;
|
|
1238
|
+
reason: string;
|
|
1239
|
+
blockers?: undefined;
|
|
1206
1240
|
approvalIntent?: undefined;
|
|
1207
1241
|
conflict?: undefined;
|
|
1208
1242
|
} | {
|
|
1209
1243
|
ok: boolean;
|
|
1210
1244
|
reason: string;
|
|
1211
1245
|
approvalIntent: ApprovalIntent;
|
|
1246
|
+
blockers?: undefined;
|
|
1212
1247
|
conflict?: undefined;
|
|
1213
1248
|
} | {
|
|
1214
1249
|
ok: boolean;
|
|
1215
1250
|
reason: string;
|
|
1216
1251
|
conflict: import("../spec/version-conflict").ConflictDetail;
|
|
1252
|
+
blockers?: undefined;
|
|
1217
1253
|
approvalIntent?: undefined;
|
|
1218
1254
|
} | {
|
|
1219
1255
|
dismissUnknown?: string[] | undefined;
|
|
@@ -1234,18 +1270,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
1234
1270
|
digest: string;
|
|
1235
1271
|
ok?: undefined;
|
|
1236
1272
|
reason?: undefined;
|
|
1273
|
+
blockers?: undefined;
|
|
1237
1274
|
approvalIntent?: undefined;
|
|
1238
1275
|
conflict?: undefined;
|
|
1239
1276
|
}>;
|
|
1240
|
-
spec_list: (a: any) => Promise<
|
|
1241
|
-
specs: {
|
|
1242
|
-
legacy?: boolean | undefined;
|
|
1243
|
-
parent?: string | undefined;
|
|
1244
|
-
id: string;
|
|
1245
|
-
type: import("../spec/spec-types").SpecType;
|
|
1246
|
-
status: "draft" | "review" | "approved" | "outdated";
|
|
1247
|
-
}[];
|
|
1248
|
-
}>;
|
|
1277
|
+
spec_list: (a: any) => Promise<Record<string, any>>;
|
|
1249
1278
|
spec_next: (a?: {
|
|
1250
1279
|
id?: string;
|
|
1251
1280
|
}) => Promise<{
|
|
@@ -1351,15 +1380,15 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
1351
1380
|
counts: Record<string, Record<string, number>>;
|
|
1352
1381
|
notApproved: {
|
|
1353
1382
|
id: string;
|
|
1354
|
-
type:
|
|
1355
|
-
status:
|
|
1383
|
+
type: import("../spec/spec-types").SpecType;
|
|
1384
|
+
status: "draft" | "review" | "approved" | "outdated";
|
|
1356
1385
|
}[];
|
|
1357
1386
|
notApprovedTotal: number;
|
|
1358
1387
|
};
|
|
1359
1388
|
specs: {
|
|
1360
1389
|
id: string;
|
|
1361
|
-
type:
|
|
1362
|
-
status:
|
|
1390
|
+
type: import("../spec/spec-types").SpecType;
|
|
1391
|
+
status: "draft" | "review" | "approved" | "outdated";
|
|
1363
1392
|
}[];
|
|
1364
1393
|
matched: number;
|
|
1365
1394
|
ok?: undefined;
|
|
@@ -4,7 +4,7 @@ exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH
|
|
|
4
4
|
exports.unquoteGitPath = unquoteGitPath;
|
|
5
5
|
exports.analyzeMaintenance = analyzeMaintenance;
|
|
6
6
|
exports.boundAnalysis = boundAnalysis;
|
|
7
|
-
// @implements A-SPEC-745, A-SPEC-741, A-SPEC-740, A-SPEC-725, A-SPEC-310
|
|
7
|
+
// @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
|
|
8
8
|
// @implements A-SPEC-295
|
|
9
9
|
// @implements A-SPEC-294
|
|
10
10
|
// @implements A-SPEC-293
|
|
@@ -25,6 +25,7 @@ const localize_1 = require("../rtm/localize");
|
|
|
25
25
|
// lookups must key identically or the coverage reported is about nothing.
|
|
26
26
|
const vector_coverage_1 = require("../semantic/vector-coverage");
|
|
27
27
|
const admission_1 = require("../semantic/admission");
|
|
28
|
+
const unreadable_paths_1 = require("../semantic/unreadable-paths");
|
|
28
29
|
const dense_retrieval_1 = require("../review/dense-retrieval");
|
|
29
30
|
const test_scope_1 = require("../rtm/test-scope");
|
|
30
31
|
const scope_1 = require("../review/scope");
|
|
@@ -58,6 +59,26 @@ const LANGUAGE_NAMES = {
|
|
|
58
59
|
'.sh': ['shell', 'bash', 'sh'], '.rb': ['ruby', 'rails'], '.php': ['php'], '.kt': ['kotlin'], '.kts': ['kotlin'],
|
|
59
60
|
'.swift': ['swift'], '.scala': ['scala'], '.ex': ['elixir'], '.exs': ['elixir'], '.lua': ['lua'],
|
|
60
61
|
};
|
|
62
|
+
/** @implements A-SPEC-741.1 — the same names as a Korean or Japanese request writes them (substring match). */
|
|
63
|
+
const LANGUAGE_NAMES_CJK = {
|
|
64
|
+
'.sh': ['셸', '쉘', '배시', '스크립트', 'シェル', 'スクリプト'], '.rb': ['루비', '레일즈', 'ルビー'],
|
|
65
|
+
'.kt': ['코틀린', 'コトリン'], '.kts': ['코틀린', 'コトリン'], '.swift': ['스위프트', 'スウィフト'], '.scala': ['스칼라'],
|
|
66
|
+
'.ex': ['엘릭서'], '.exs': ['엘릭서'], '.lua': ['루아'],
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* @implements A-SPEC-741.1 — a leading conventional-commit type word is not about any file: `feat`
|
|
70
|
+
* met `create-new-feature.sh` through the 4-letter prefix rule in 28 of 60 replayed Korean requests.
|
|
71
|
+
* The scope that may follow it (`fix(holmes):`) stays — it names the area the author meant.
|
|
72
|
+
*/
|
|
73
|
+
const COMMIT_TYPE_WORD = /^\s*(feat|fix|chore|docs|refactor|perf|style|revert|harden)(?=(\([^)]*\))?!?:)/i;
|
|
74
|
+
/**
|
|
75
|
+
* @implements A-SPEC-741.1 — an ASCII token that can be compared with a path: 3+ characters with a
|
|
76
|
+
* letter, not a spec-id fragment (`req`, `spec`, `adr`, `goal`) nor an id-shaped token (`f079`, `516`).
|
|
77
|
+
*/
|
|
78
|
+
function isComparableWord(token) {
|
|
79
|
+
return token.length >= 3 && /[a-z]/.test(token) && !/^(req|spec|aspec|hspec|tspec|cspec|adr|goal)$/.test(token)
|
|
80
|
+
&& !/^[a-z]{0,2}\d+$/.test(token);
|
|
81
|
+
}
|
|
61
82
|
// @implements A-SPEC-740
|
|
62
83
|
exports.CONFIDENCE_NOTE = 'confidence is not calibrated: it counts which kinds of evidence were present, '
|
|
63
84
|
+ 'does not predict accuracy, and must not be used to weight answers or to narrow a test scope.';
|
|
@@ -767,15 +788,17 @@ function analyzeMaintenance(input) {
|
|
|
767
788
|
// Review round 1 (2026-09-30): where the rule cannot judge it leans to "relevant" — a false
|
|
768
789
|
// "unrelated" is false confidence. Raw tokens (length >= 2, no stop list: `ci`, `db`, `test` are
|
|
769
790
|
// names), a prefix match from 4 characters (`session`/`sessions`), trailing punctuation stripped
|
|
770
|
-
// from request paths (`ci.sh.`),
|
|
771
|
-
//
|
|
791
|
+
// from request paths (`ci.sh.`), and a capped path list all count as "about the change". A non-ASCII
|
|
792
|
+
// request used to count too; A-SPEC-741.1 judges its non-ASCII part by meaning instead (below).
|
|
772
793
|
const requestLower = input.request.toLowerCase();
|
|
773
794
|
// Review round 2: a Set, capped — a 500 KB request cost 2.9 s against 5,000 paths when the tokens were
|
|
774
795
|
// an array compared inside the per-file loop.
|
|
775
796
|
// Round 3: de-duplicate FIRST, then cap — a pasted log of repeated lines pushed the file's name past
|
|
776
797
|
// a cap taken over raw tokens.
|
|
777
798
|
// Round 4: tokens over 64 characters (a pasted hex blob, a minified line) are not words.
|
|
778
|
-
|
|
799
|
+
// A-SPEC-741.1: a leading commit type word (`feat:`, `fix(scope):`) is not compared; the scope is.
|
|
800
|
+
const comparableRequest = input.request.replace(COMMIT_TYPE_WORD, '');
|
|
801
|
+
const requestTokens = new Set([...new Set(rawTokens(comparableRequest).filter((t) => t.length <= 64))].slice(0, 4096));
|
|
779
802
|
const requestStems = new Set([...requestTokens].filter((t) => t.length >= 5).map((t) => t.slice(0, 5)));
|
|
780
803
|
// Every prefix (>= 4 chars) of every request token, so "a path token is a prefix of a request word"
|
|
781
804
|
// (`auth` / `authentication`) is one lookup instead of a scan.
|
|
@@ -803,6 +826,35 @@ function analyzeMaintenance(input) {
|
|
|
803
826
|
// A LETTER outside ASCII (Hangul, Kana, …) — not an em dash or a curly quote, which every commit subject here uses.
|
|
804
827
|
const requestIsNonAscii = /(?![\x00-\x7f])\p{L}/u.test(input.request);
|
|
805
828
|
const pathsCapped = input.coverage.unsupportedFilesTruncated === true;
|
|
829
|
+
// @implements A-SPEC-741.1 — a non-ASCII request is no longer relevant to every unreadable language.
|
|
830
|
+
// Its ASCII words are compared like any request's; what they cannot reach, the Korean or Japanese
|
|
831
|
+
// part may still name (`세션 격리 isolate` for `app/session_store.rb`), so that part is judged by
|
|
832
|
+
// meaning against the warmed path vectors. It is "outside the change" only when every file of the
|
|
833
|
+
// language has a vector and all sit below the model's measured threshold — anything the rule cannot
|
|
834
|
+
// judge (no comparable word, no tier, no threshold, a missing vector) stays relevant.
|
|
835
|
+
const hasComparableWord = [...requestTokens].some(isComparableWord);
|
|
836
|
+
const judgedByMeaning = [];
|
|
837
|
+
const outsideByMeaning = (ext, files) => {
|
|
838
|
+
const sem = input.semantic;
|
|
839
|
+
if (!hasComparableWord || !sem || sem.queryVector === null)
|
|
840
|
+
return false;
|
|
841
|
+
const threshold = unreadable_paths_1.UNREADABLE_PATH_THRESHOLDS[sem.label];
|
|
842
|
+
if (threshold === undefined)
|
|
843
|
+
return false;
|
|
844
|
+
let max = -1;
|
|
845
|
+
for (const file of files) {
|
|
846
|
+
const vector = sem.cachedDocVector((0, unreadable_paths_1.unreadablePathText)(file));
|
|
847
|
+
if (vector === null)
|
|
848
|
+
return false;
|
|
849
|
+
const c = (0, dense_retrieval_1.cosine)(sem.queryVector, vector);
|
|
850
|
+
if (c >= threshold)
|
|
851
|
+
return false;
|
|
852
|
+
if (c > max)
|
|
853
|
+
max = c;
|
|
854
|
+
}
|
|
855
|
+
judgedByMeaning.push({ ext, label: sem.label, max, threshold });
|
|
856
|
+
return true;
|
|
857
|
+
};
|
|
806
858
|
const relevantUnsupported = input.coverage.unsupportedLanguages.filter((language) => {
|
|
807
859
|
if (!language.startsWith('.'))
|
|
808
860
|
return true;
|
|
@@ -816,11 +868,15 @@ function analyzeMaintenance(input) {
|
|
|
816
868
|
// Review round 2: a request that names the language itself (`.sh`, `shell`, `kotlin`) is about it.
|
|
817
869
|
if (requestTokens.has(ext.slice(1)) || (LANGUAGE_NAMES[ext] ?? []).some((name) => requestTokens.has(name)))
|
|
818
870
|
return true;
|
|
871
|
+
if ((LANGUAGE_NAMES_CJK[ext] ?? []).some((name) => input.request.includes(name)))
|
|
872
|
+
return true;
|
|
819
873
|
const files = (input.coverage.unsupportedFiles ?? []).filter((file) => file.toLowerCase().endsWith(ext));
|
|
820
|
-
if (pathsCapped
|
|
874
|
+
if (pathsCapped)
|
|
821
875
|
return true;
|
|
822
876
|
// Every token of the path — folders too (`app/session/store.rb`) — exact, or sharing a 5-letter stem.
|
|
823
|
-
|
|
877
|
+
if (files.some((file) => rawTokens(file.slice(0, -ext.length)).some(tokenMeetsRequest)))
|
|
878
|
+
return true;
|
|
879
|
+
return requestIsNonAscii && files.length > 0 && !outsideByMeaning(ext, files);
|
|
824
880
|
});
|
|
825
881
|
// The TEST SCOPE keeps every language (A-SPEC-741 revision): relevance decides the classification
|
|
826
882
|
// only. Dropping the unrelated ones from the scope let anchor-based narrowing miss tests on replay.
|
|
@@ -858,6 +914,8 @@ function analyzeMaintenance(input) {
|
|
|
858
914
|
const outside = unsupportedLanguages.filter((language) => !relevantUnsupported.includes(language));
|
|
859
915
|
unknowns.push(`Unsupported languages are outside the evidence basis: ${unsupportedLanguages.join(', ')}`
|
|
860
916
|
+ (outside.length > 0 ? ` (${outside.join(', ')} judged outside this change for the classification: no changed file, request path or path-sharing file names it; the test scope still counts it)` : '')
|
|
917
|
+
// @implements A-SPEC-741.1 — say which languages a non-ASCII request was judged against by meaning.
|
|
918
|
+
+ judgedByMeaning.map((j) => ` (${j.ext} judged outside this change by meaning (${j.label}: max ${j.max.toFixed(2)} < ${j.threshold.toFixed(2)}))`).join('')
|
|
861
919
|
+ (pathsCapped ? ' (the list of unreadable files was capped, so every language counts as about this change)' : ''));
|
|
862
920
|
}
|
|
863
921
|
if (truncationMarkers.length > 0) {
|
|
@@ -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();
|
|
@@ -255,10 +255,20 @@ exports.TOOL_SCHEMAS = {
|
|
|
255
255
|
},
|
|
256
256
|
},
|
|
257
257
|
spec_list: {
|
|
258
|
-
|
|
258
|
+
// @implements A-SPEC-746 — the whole corpus in one answer was 202,608 characters here.
|
|
259
|
+
description: `List specs (id, type, status; plus parent when depends_on names one, and legacy: true when the status is outside the canonical ${spec_types_1.SPEC_STATUSES.join('|')} union — absence of legacy speaks only to the STATUS being canonical, not to governance). `
|
|
260
|
+
+ 'Answers with `summary` { total, counts[type][status] }, `pending` (first 100 specs that are not approved — what needs action) with `pendingTotal`, '
|
|
261
|
+
+ 'and one page of `specs` in id order (default 100, `limit` 1..500) with `total` and `nextCursor` while rows remain — pass it back as `cursor`. '
|
|
262
|
+
+ 'To ask whether a spec exists, pass `ids`: only those rows come back, and missing ids are named in `unknownIds`.',
|
|
259
263
|
inputSchema: {
|
|
260
264
|
type: 'object',
|
|
261
|
-
properties: {
|
|
265
|
+
properties: {
|
|
266
|
+
type: str('Optional spec kind to filter by (e.g. A-SPEC).'),
|
|
267
|
+
ids: strArray('Only these spec ids; ids that do not exist are listed in `unknownIds`.'),
|
|
268
|
+
status: str('Only this status, e.g. draft | approved | outdated.'),
|
|
269
|
+
limit: num('Rows per page: an integer 1..500 (default 100).'),
|
|
270
|
+
cursor: str('The `nextCursor` of the previous page; rows after it are returned.'),
|
|
271
|
+
},
|
|
262
272
|
},
|
|
263
273
|
},
|
|
264
274
|
spec_next: {
|
|
@@ -553,21 +563,32 @@ exports.TOOL_SCHEMAS = {
|
|
|
553
563
|
},
|
|
554
564
|
},
|
|
555
565
|
review_status: {
|
|
556
|
-
|
|
566
|
+
// @implements A-SPEC-746
|
|
567
|
+
description: 'Summarize open findings by severity and whether the review is blocked ({ blocked, open }), and the specs whose approved content moved and await review: '
|
|
568
|
+
+ 'by default one row per spec { spec, files, signals } newest first with `reviewNeededTotal` (signals); if they would not fit, the rest are counted in `reviewNeededOmitted`. '
|
|
569
|
+
+ '`detail: "full"` returns every raw signal with its from/to digests.',
|
|
557
570
|
inputSchema: {
|
|
558
571
|
type: 'object',
|
|
559
|
-
properties: {
|
|
572
|
+
properties: {
|
|
573
|
+
root: ROOT,
|
|
574
|
+
detail: { type: 'string', enum: ['summary', 'full'], description: 'summary (default): merged per spec, no digests. full: every raw review-needed signal.' },
|
|
575
|
+
},
|
|
560
576
|
required: ['root'],
|
|
561
577
|
},
|
|
562
578
|
},
|
|
563
579
|
// @implements A-SPEC-126
|
|
564
580
|
reverse_scan: {
|
|
565
|
-
description: 'Brownfield inventory: scan a legacy target read-only and return candidate A-SPEC clusters, cohesion evidence, and an honest coverage report (unresolved wiring, uncalibrated languages). Writes nothing.'
|
|
581
|
+
description: 'Brownfield inventory: scan a legacy target read-only and return candidate A-SPEC clusters, cohesion evidence, and an honest coverage report (unresolved wiring, uncalibrated languages). Writes nothing. '
|
|
582
|
+
// @implements A-SPEC-746
|
|
583
|
+
+ 'By default a compressed view: unanchored clusters first with paths relative to their dir, clusters already fully anchored folded to { dir, fileCount, anchored }, '
|
|
584
|
+
+ 'test matches counted (matchedTotal, matchedVia) and unmatched tests grouped by directory; anything reduced further is counted in clustersReduced with a note. '
|
|
585
|
+
+ '`detail: "full"` returns every row.',
|
|
566
586
|
inputSchema: {
|
|
567
587
|
type: 'object',
|
|
568
588
|
properties: {
|
|
569
589
|
root: str('Absolute path to the target repository root. Unlike the other tools this need not be a git repository — a non-git tree is scanned whole and reported as isGit:false.'),
|
|
570
590
|
maxFlagged: num('Cap on the listed dynamic-wiring files (default 50). Counts stay complete.'),
|
|
591
|
+
detail: { type: 'string', enum: ['summary', 'full'], description: 'summary (default): the compressed view. full: every cluster file and test-match row.' },
|
|
571
592
|
},
|
|
572
593
|
required: ['root'],
|
|
573
594
|
},
|
|
@@ -67,6 +67,12 @@ export interface ReverseScanReport {
|
|
|
67
67
|
* call, and the surface measures ~5KB per cluster on the calibration target. The handler strips it.
|
|
68
68
|
*/
|
|
69
69
|
surfaceByCluster: Record<string, SurfaceSymbol[]>;
|
|
70
|
+
/**
|
|
71
|
+
* @implements A-SPEC-746 — candidate files that already carry an `@implements` anchor, so the tool
|
|
72
|
+
* handler can fold clusters that are no longer adoption candidates. Stripped from every response,
|
|
73
|
+
* like `surfaceByCluster`.
|
|
74
|
+
*/
|
|
75
|
+
anchoredFiles: string[];
|
|
70
76
|
coverage: {
|
|
71
77
|
/** Candidate files placed in a production cluster by directory evidence. */
|
|
72
78
|
structurallyResolved: number;
|
|
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.candidates = candidates;
|
|
37
37
|
exports.reverseScan = reverseScan;
|
|
38
|
-
// @implements A-SPEC-126, A-SPEC-734
|
|
38
|
+
// @implements A-SPEC-126, A-SPEC-734, A-SPEC-746
|
|
39
39
|
const fs = __importStar(require("node:fs"));
|
|
40
40
|
const path = __importStar(require("node:path"));
|
|
41
41
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -175,7 +175,8 @@ function reverseScan(root, opts = {}) {
|
|
|
175
175
|
flagged.push({ file: f.sourcePath, indicators: hits });
|
|
176
176
|
}
|
|
177
177
|
flagged.sort((a, b) => cmp(a.file, b.file));
|
|
178
|
-
const
|
|
178
|
+
const anchoredFiles = files.filter((f) => f.implementsSpecs.length > 0).map((f) => f.sourcePath).sort(cmp);
|
|
179
|
+
const anchored = anchoredFiles.length;
|
|
179
180
|
const countFiles = (cs) => cs.reduce((n, c) => n + c.files.length, 0);
|
|
180
181
|
return {
|
|
181
182
|
root,
|
|
@@ -188,6 +189,7 @@ function reverseScan(root, opts = {}) {
|
|
|
188
189
|
clusters: production,
|
|
189
190
|
testClusters,
|
|
190
191
|
surfaceByCluster,
|
|
192
|
+
anchoredFiles,
|
|
191
193
|
coverage: {
|
|
192
194
|
structurallyResolved: countFiles(production),
|
|
193
195
|
inTestClusters: countFiles(testClusters),
|
|
@@ -55,6 +55,12 @@ export interface RequirementTriageResult {
|
|
|
55
55
|
reasons: string[];
|
|
56
56
|
uncertainty: string[];
|
|
57
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
|
|
60
|
+
* paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
|
|
61
|
+
* are not identifiers. Lower-cased, de-duplicated, at most 50.
|
|
62
|
+
*/
|
|
63
|
+
export declare function requestIdentifiers(prompt: string): string[];
|
|
58
64
|
/** Re-exported for triage callers; the cache contract belongs to vector coverage. */
|
|
59
65
|
export declare const canonicalRequirementDocument: typeof canonicalRequirementDocumentText;
|
|
60
66
|
/**
|
|
@@ -1,13 +1,57 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.canonicalRequirementDocument = void 0;
|
|
4
|
+
exports.requestIdentifiers = requestIdentifiers;
|
|
4
5
|
exports.triageRequirements = triageRequirements;
|
|
5
6
|
exports.requirementSemanticCoverage = requirementSemanticCoverage;
|
|
6
|
-
// @implements A-SPEC-713.1, 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
|
|
7
8
|
/** Pure, conservative lifecycle triage over governed requirement documents. */
|
|
8
9
|
const semantic_retrieval_1 = require("./semantic-retrieval");
|
|
9
10
|
const localize_1 = require("../rtm/localize");
|
|
10
11
|
const vector_coverage_1 = require("../semantic/vector-coverage");
|
|
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'];
|
|
15
|
+
/**
|
|
16
|
+
* @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
|
|
17
|
+
* paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
|
|
18
|
+
* are not identifiers. Lower-cased, de-duplicated, at most 50.
|
|
19
|
+
*/
|
|
20
|
+
function requestIdentifiers(prompt) {
|
|
21
|
+
const out = [];
|
|
22
|
+
for (const raw of (0, localize_1.withoutCitations)(prompt).split(/\s+/)) {
|
|
23
|
+
const token = raw.replace(/^[`'"([{<]+/, '').replace(/[`'")\]}>.,;:!?]+$/, '');
|
|
24
|
+
if (token === '' || /^[a-z][a-z0-9+.-]*:\/\//i.test(token) || /^www\./i.test(token))
|
|
25
|
+
continue;
|
|
26
|
+
const snake = /^[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+$/.test(token);
|
|
27
|
+
const camel = token.length >= 4 && /^[A-Za-z][A-Za-z0-9]*$/.test(token) && /[a-z][A-Z]/.test(token);
|
|
28
|
+
// A path needs a code extension or two separators: `and/or` and `client/server` are prose.
|
|
29
|
+
const pathLike = token.includes('/') && /[A-Za-z]/.test(token) && (CODE_FILE.test(token) || (token.match(/\//g) ?? []).length >= 2);
|
|
30
|
+
const file = !token.includes('/') && /[A-Za-z]/.test(token.replace(CODE_FILE, '')) && CODE_FILE.test(token);
|
|
31
|
+
if (!snake && !camel && !pathLike && !file)
|
|
32
|
+
continue;
|
|
33
|
+
const id = token.toLowerCase();
|
|
34
|
+
if (!out.includes(id))
|
|
35
|
+
out.push(id);
|
|
36
|
+
if (out.length === 50)
|
|
37
|
+
break;
|
|
38
|
+
}
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* @implements A-SPEC-713.2 — what a lineage says it covers: titles and section bodies, without a section
|
|
43
|
+
* headed "Out of Scope" and without what follows an `Out of Scope:` line inside a section.
|
|
44
|
+
*/
|
|
45
|
+
function inScopeText(docs) {
|
|
46
|
+
return docs.map((d) => [d.title, ...Object.entries(d.sections ?? {})
|
|
47
|
+
.filter(([heading]) => !/out of scope/i.test(heading))
|
|
48
|
+
.map(([, body]) => body.split(/^\s*Out of Scope\s*:/im)[0])].join('\n')).join('\n').toLowerCase();
|
|
49
|
+
}
|
|
50
|
+
function identifierCovered(id, text) {
|
|
51
|
+
if (text.includes(id))
|
|
52
|
+
return true;
|
|
53
|
+
return id.includes('/') && text.includes(id.slice(id.lastIndexOf('/') + 1));
|
|
54
|
+
}
|
|
11
55
|
/** Re-exported for triage callers; the cache contract belongs to vector coverage. */
|
|
12
56
|
exports.canonicalRequirementDocument = vector_coverage_1.canonicalRequirementDocument;
|
|
13
57
|
function rankLimit(value) {
|
|
@@ -154,7 +198,12 @@ function triageCore(input) {
|
|
|
154
198
|
const textLower = row.text.toLowerCase();
|
|
155
199
|
const contentTerms = promptTerms.filter((term) => textLower.includes(term));
|
|
156
200
|
const operational = input.evidence?.[row.reqId] ?? {};
|
|
157
|
-
|
|
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));
|
|
158
207
|
const anchors = [...new Set(operational.implementationAnchors ?? [])].sort();
|
|
159
208
|
const reasons = [
|
|
160
209
|
...(cited ? ['cited'] : []),
|
|
@@ -215,13 +264,19 @@ function triageCore(input) {
|
|
|
215
264
|
// Round 3: a citation never counts toward agreement — "(unrelated to REQ-1)" plus one channel on
|
|
216
265
|
// REQ-1 decided REQ-1. Both channels (or, lexical-only, the lexical one) must name a lineage, and it
|
|
217
266
|
// must be the first-ranked one.
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
if (
|
|
222
|
-
agreementReason =
|
|
223
|
-
|
|
224
|
-
|
|
267
|
+
// @implements A-SPEC-713.3 — a single channel never confirms (owner decision 2026-10-01). With no vector on
|
|
268
|
+
// any candidate, the lexical top alone answered existing-change for 47 of 60 requirements that were new at
|
|
269
|
+
// the time, and intake then refused them. The lexical order stays visible; the verdict does not decide.
|
|
270
|
+
if (withVector.length === 0) {
|
|
271
|
+
agreementReason = 'single-channel';
|
|
272
|
+
}
|
|
273
|
+
else {
|
|
274
|
+
const agreed = lexicalTop !== null && semanticTop !== null && lexicalTop.reqId === semanticTop.reqId ? lexicalTop.reqId : null;
|
|
275
|
+
if (agreed === null)
|
|
276
|
+
agreementReason = 'channels-disagree';
|
|
277
|
+
else if (agreed !== top.reqId)
|
|
278
|
+
agreementReason = 'citation-unbacked';
|
|
279
|
+
}
|
|
225
280
|
}
|
|
226
281
|
if (tied.length > 1 || agreementReason !== null || top.contentTerms.length === 0 || top.reasons.includes('contradictory-evidence')) {
|
|
227
282
|
const uncertainty = [
|
|
@@ -232,6 +287,20 @@ function triageCore(input) {
|
|
|
232
287
|
];
|
|
233
288
|
return { verdict: 'ambiguous', candidates, reasons: uncertainty, uncertainty };
|
|
234
289
|
}
|
|
290
|
+
// @implements A-SPEC-713.2 — a confident verdict says the request is this lineage's business; a code
|
|
291
|
+
// identifier the lineage never mentions in scope means the rule cannot judge that. Measured: a request
|
|
292
|
+
// about spec_list/review_status was `fulfilled` by the phase_status lineage whose REQ puts other tools
|
|
293
|
+
// out of scope, and intake then refused the new requirement.
|
|
294
|
+
const identifiers = requestIdentifiers(input.prompt);
|
|
295
|
+
if (identifiers.length > 0) {
|
|
296
|
+
const text = inScopeText(top.documents);
|
|
297
|
+
const missing = identifiers.filter((id) => !identifierCovered(id, text)).sort();
|
|
298
|
+
if (missing.length > 0) {
|
|
299
|
+
const named = [...missing.slice(0, 5), ...(missing.length > 5 ? [`+${missing.length - 5}`] : [])];
|
|
300
|
+
const reason = `identifiers-outside-lineage:${named.join(',')}`;
|
|
301
|
+
return { verdict: 'ambiguous', candidates, reasons: [reason], uncertainty: [reason] };
|
|
302
|
+
}
|
|
303
|
+
}
|
|
235
304
|
if (top.approved && top.implementationAnchors.length > 0 && top.freshGreenTests) {
|
|
236
305
|
return { verdict: 'fulfilled', candidates, reasons: ['approved-lineage', 'implementation-anchors', 'fresh-green-execution'], uncertainty: [] };
|
|
237
306
|
}
|
|
@@ -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
|
/**
|