@holmes-lab/holmes-kit 0.31.2 → 0.32.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 +54 -0
- package/README.md +1 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +16 -3
- package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +6 -0
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +163 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +26 -18
- package/dist/holmes/mcp/handlers.d.ts +169 -4
- package/dist/holmes/mcp/maintenance-analyze.d.ts +19 -0
- package/dist/holmes/mcp/maintenance-analyze.js +113 -7
- package/dist/holmes/mcp/maintenance-evidence.d.ts +25 -0
- package/dist/holmes/mcp/maintenance-evidence.js +52 -1
- package/dist/holmes/mcp/tool-schemas.js +3 -1
- package/dist/holmes/review/requirement-triage.d.ts +19 -1
- package/dist/holmes/review/requirement-triage.js +113 -12
- package/dist/holmes/rtm/localize.d.ts +7 -0
- package/dist/holmes/rtm/localize.js +10 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,60 @@ 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.32.0] - 2026-09-30
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- **`maintenance_analyze` says its confidence is uncalibrated where the number is read** (A-SPEC-740). Every result
|
|
13
|
+
carries `confidenceCalibrated: false` and a `confidenceNote` (the value counts which kinds of evidence were present,
|
|
14
|
+
does not predict accuracy, and must not weight answers or narrow a test scope); every persisted evidence artifact
|
|
15
|
+
carries `confidenceCalibrated: false`. The value and formula are unchanged and the artifact schema stays
|
|
16
|
+
`maintenance-evidence/1.4`, so recorded artifacts still feed calibration. It ships before the classification gates
|
|
17
|
+
are relaxed: with them lifted, 120 of 120 replay cases would report 0.95 at 0.467/0.383 top-1 accuracy.
|
|
18
|
+
- **`requirement_triage` answers in summaries by default** (A-SPEC-743). Each candidate document is
|
|
19
|
+
`{ id, type, title, status, dependsOn }`; `detail: "full"` adds frontmatter and sections. The bodies were 72% of a
|
|
20
|
+
201 KB median answer (holmes; 107 KB on a second corpus) — past the tool-result limit, so the mandated intake step
|
|
21
|
+
was read back from a file in slices. Verdict, reasons, candidate order and scores are identical either way.
|
|
22
|
+
- **`maintenance_analyze` lists candidate specs in relevance order** (A-SPEC-745): specs the request cites, then the
|
|
23
|
+
specs anchored by the top-ranked candidate files, then the rest. The response keeps ten, and id order made those
|
|
24
|
+
ten A-SPEC-100 and its neighbours for every request. The set and every computation over it are unchanged.
|
|
25
|
+
- **`requirement_triage` gives a confident verdict only when its channels agree** (A-SPEC-713.1). A lineage the
|
|
26
|
+
request cites ranks first; lineages with a requirement vector are ordered by semantic score before BM25 (the old
|
|
27
|
+
`max(BM25, cosine)` let cosine count only when BM25 was zero); `existing-change`/`fulfilled` need the lexical and
|
|
28
|
+
semantic top lineages to agree — each top unique, the lexical one above zero — and that lineage to be the first
|
|
29
|
+
ranked, otherwise `ambiguous` (`channels-disagree` / `citation-unbacked`). A citation only orders and never counts
|
|
30
|
+
toward agreement: "(unrelated to REQ-1)" or an id inside a URL is a mention, not evidence. BM25 now scores each
|
|
31
|
+
lineage's titles and sections only — id spellings are removed from the prompt, and the `id:`/`lineage:`/`status:`
|
|
32
|
+
header is not scored — so "REQ 742", "the 742 rows" or the word "spec" no longer pick a lineage. Ties are judged on
|
|
33
|
+
scores alone, and a lineage without a vector ties on the semantic side. On replay the
|
|
34
|
+
lexical top was the right lineage in 0.20–0.32 of cases and a second corpus already answered `existing-change`
|
|
35
|
+
wrongly four times in five; an `existing-change` answer also stops the intake from creating a new REQ.
|
|
36
|
+
|
|
37
|
+
### Added
|
|
38
|
+
|
|
39
|
+
- **Persisted maintenance evidence says why its test scope was full** (A-SPEC-744): `uncertainty.testScopeReason` and
|
|
40
|
+
structured `testScopeCauses` (unsupported-language, impact-truncated, coverage-gap, no-anchored-tests, …), and `maintenance_calibration`
|
|
41
|
+
reports `scopeCauses` — how often each cause occurred, older artifacts counted as `unrecorded`. 455 persisted
|
|
42
|
+
analyses here were all `full` and none said why.
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
|
|
46
|
+
- **`maintenance_analyze` is no longer `ambiguous` for every request** (A-SPEC-741). Since four CI `.sh` scripts
|
|
47
|
+
landed on 2026-09-03, every analysis in this repository (455 of 455) and every replay case on two corpora (120 of
|
|
48
|
+
120) was `ambiguous`, because a language the scanner cannot read anywhere in the tree counted against every request,
|
|
49
|
+
and a truncated impact walk decided the classification too. The classification now counts an unsupported language
|
|
50
|
+
only when the change touches it — a changed file with that extension, a path in the request (`ci.sh.` included), or
|
|
51
|
+
an unreadable file whose path — folders included — shares a word or a five-letter stem with the request
|
|
52
|
+
(`app/session/store.rb` for "the sessions", `lib/isolate.rb` for "isolation"), or a request that names the language
|
|
53
|
+
("the shell script", "Kotlin") — and leans to "about the change" wherever it cannot judge: a request in a non-Latin
|
|
54
|
+
script, or a list of unreadable files that hit its 5,000-path cap. Truncation no longer decides it. The **test scope is unchanged**: a first version also relaxed it, and on replay 10 of the 12
|
|
55
|
+
scopes that then narrowed missed a test the commit changed, so every language and every depth stop still widen it.
|
|
56
|
+
- **`requirement_triage` no longer discards its semantic layer in this repository** (A-SPEC-742). Coverage was compared
|
|
57
|
+
against every requirement document, including 24 legacy T-SPECs under C-SPECs that have no REQ lineage and can never
|
|
58
|
+
have a vector, so triage here was `ambiguous` on every call. Coverage now counts documents that can carry a vector
|
|
59
|
+
(`unlineaged` reported separately); a partially covered layer decides with `semantic-partial:<n>` and
|
|
60
|
+
`missingLineages` disclosed; a configured layer that covers nothing still forces `ambiguous`.
|
|
61
|
+
|
|
8
62
|
## [0.31.2] - 2026-09-30
|
|
9
63
|
|
|
10
64
|
### Fixed
|
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
|
+
- 🔎 **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.
|
|
26
27
|
- 🚦 **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.
|
|
27
28
|
- 🪝 **The Codex gate loads again on codex-cli 0.155** *(new in 0.31.0)*: plugin hooks were removed upstream, so `init --agent codex` wires the Holmes PreToolUse and Stop kernels into the user-level `$CODEX_HOME/hooks.json`, keeps every hook it does not own, and `--remove` takes away only its own groups. Codex runs a user hook only after you trust it once with `/hooks`; Holmes never forges that trust, and `doctor` says so instead of claiming enforcement.
|
|
28
29
|
- 🧭 **The shell gate judges by identity, from where the command really runs** *(new in 0.31.0)*: wiring files, the whole `.ax` store and the files inside it are protected as shell WORDS resolved against each segment's real base — a `cd` moves the base only when it is certain to have run, an uncertain or expanded one (`cd .a?`, a link made in the same command, `cd "$X"`) leaves it unknown and the command is judged at every base it could have produced, and the base starts at the harness's own working directory (the payload `cwd`, a Codex `workdir`), not the project root. Every evaluation runs under a fail-closed deadline wall. The Codex oracle asks the installed Codex whether your config loads — locally, over copies, with plugins and every proxy closed, `sqlite_home`/`analytics`/`otel` isolated from the user copy alone, and a verdict it could not obtain labelled `approximate`. Source walkers skip nested git working trees only when git says the tree is not the project's, read regular files only, and ask git once per scan; every reader on a gate path is linear in its input.
|
package/dist/.build-id
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
8f0f2af0-munbbu91
|
|
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
|
|
37
|
-
// @implements A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734
|
|
37
|
+
// @implements A-SPEC-745, A-SPEC-741, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734
|
|
38
38
|
const fs = __importStar(require("node:fs"));
|
|
39
39
|
const path = __importStar(require("node:path"));
|
|
40
40
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -78,6 +78,10 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
78
78
|
const supportedExtensions = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
|
|
79
79
|
const knownCodeExtensions = new Set(['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r']);
|
|
80
80
|
const unsupportedLanguages = new Set();
|
|
81
|
+
// @implements A-SPEC-741 — the paths too, so the analysis can tell an unreadable file that may
|
|
82
|
+
// be this request's target from one that is unrelated. Bounded: a vendored tree must not grow it.
|
|
83
|
+
const unsupportedFiles = [];
|
|
84
|
+
let unsupportedFilesTruncated = false;
|
|
81
85
|
try {
|
|
82
86
|
// A-SPEC-734 (round 12): a root whose git timed out is not asked again (the shared memory).
|
|
83
87
|
if ((0, bounded_io_1.gitRootBlocked)(root))
|
|
@@ -86,8 +90,13 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
86
90
|
const files = (0, node_child_process_1.execFileSync)('git', ['-c', 'core.fsmonitor=false', '-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: bounded_io_1.GIT_MAX_BUFFER }).split('\0'); // round 16: the shared bound
|
|
87
91
|
for (const file of files) {
|
|
88
92
|
const ext = path.extname(file).toLowerCase();
|
|
89
|
-
if (knownCodeExtensions.has(ext) && !supportedExtensions.has(ext))
|
|
93
|
+
if (knownCodeExtensions.has(ext) && !supportedExtensions.has(ext)) {
|
|
90
94
|
unsupportedLanguages.add(ext);
|
|
95
|
+
if (unsupportedFiles.length < 5000)
|
|
96
|
+
unsupportedFiles.push(file);
|
|
97
|
+
else
|
|
98
|
+
unsupportedFilesTruncated = true;
|
|
99
|
+
}
|
|
91
100
|
}
|
|
92
101
|
}
|
|
93
102
|
catch (e) {
|
|
@@ -125,6 +134,8 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
125
134
|
scannedFiles: scanned.length,
|
|
126
135
|
skippedFiles: skipped.map((entry) => entry.file),
|
|
127
136
|
unsupportedLanguages: [...unsupportedLanguages],
|
|
137
|
+
unsupportedFiles,
|
|
138
|
+
...(unsupportedFilesTruncated ? { unsupportedFilesTruncated: true } : {}),
|
|
128
139
|
historyStatus: 'not-requested',
|
|
129
140
|
},
|
|
130
141
|
};
|
|
@@ -172,7 +183,9 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
172
183
|
const directSeed = preliminary.candidates
|
|
173
184
|
.flatMap((candidate) => candidate.symbols)
|
|
174
185
|
.flatMap((qualifiedName) => graph.codeNodeIds(qualifiedName))[0];
|
|
175
|
-
|
|
186
|
+
// A-SPEC-745 keeps every computation over the candidate specs as it was: the emitted list is now
|
|
187
|
+
// in relevance order, so the seed is taken from the id-sorted set exactly as before.
|
|
188
|
+
const specSeed = [...preliminary.candidateSpecs].sort((a, b) => a.localeCompare(b)).find((id) => id.startsWith('A-SPEC-'));
|
|
176
189
|
const seedId = directSeed ?? (specSeed ? `SPEC:${specSeed}` : undefined);
|
|
177
190
|
const budget = Math.max(100, Math.min(10_000, Math.floor(a.contextBudget ?? 2_000)));
|
|
178
191
|
const contextBundle = seedId
|
|
@@ -39,6 +39,12 @@ export declare function createMaintenanceEvidenceHandlers(context: MaintenanceEv
|
|
|
39
39
|
falseNegatives: number;
|
|
40
40
|
minSamples: number;
|
|
41
41
|
status: "measured" | "insufficient-data";
|
|
42
|
+
scopeCauses: {
|
|
43
|
+
full: number;
|
|
44
|
+
narrow: number;
|
|
45
|
+
unrecorded: number;
|
|
46
|
+
causes: Record<string, number>;
|
|
47
|
+
};
|
|
42
48
|
}>;
|
|
43
49
|
};
|
|
44
50
|
export {};
|
|
@@ -19,17 +19,20 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
|
|
|
19
19
|
prompt: string;
|
|
20
20
|
topK?: number;
|
|
21
21
|
persist?: boolean;
|
|
22
|
+
detail?: string;
|
|
22
23
|
}): Promise<{
|
|
23
24
|
promptDigest: string;
|
|
24
25
|
semantic: {
|
|
25
26
|
localState?: import("../../semantic/model-cache").LocalModelState | undefined;
|
|
26
27
|
recovery?: string | undefined;
|
|
27
28
|
suppressed?: true | undefined;
|
|
29
|
+
availability: string;
|
|
30
|
+
missingLineages?: string[] | undefined;
|
|
28
31
|
tier: "local" | "none" | "cloud";
|
|
29
32
|
covered: number;
|
|
30
33
|
total: number;
|
|
31
|
-
|
|
32
|
-
|
|
34
|
+
unlineaged: number;
|
|
35
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
33
36
|
};
|
|
34
37
|
provenance: {
|
|
35
38
|
reqId: string;
|
|
@@ -75,6 +78,80 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
|
|
|
75
78
|
reasons: string[];
|
|
76
79
|
uncertainty: string[];
|
|
77
80
|
schema: "requirement-triage/1";
|
|
81
|
+
} | {
|
|
82
|
+
promptDigest: string;
|
|
83
|
+
semantic: {
|
|
84
|
+
localState?: import("../../semantic/model-cache").LocalModelState | undefined;
|
|
85
|
+
recovery?: string | undefined;
|
|
86
|
+
suppressed?: true | undefined;
|
|
87
|
+
availability: string;
|
|
88
|
+
missingLineages?: string[] | undefined;
|
|
89
|
+
tier: "local" | "none" | "cloud";
|
|
90
|
+
covered: number;
|
|
91
|
+
total: number;
|
|
92
|
+
unlineaged: number;
|
|
93
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
94
|
+
};
|
|
95
|
+
provenance: {
|
|
96
|
+
reqId: string;
|
|
97
|
+
documents: {
|
|
98
|
+
id: string;
|
|
99
|
+
type: import("../../review/requirement-triage").RequirementDocumentKind;
|
|
100
|
+
status: string;
|
|
101
|
+
dependsOn: readonly string[];
|
|
102
|
+
}[];
|
|
103
|
+
implementationAnchors: string[];
|
|
104
|
+
graphProvenance: {
|
|
105
|
+
[k: string]: {} | null;
|
|
106
|
+
};
|
|
107
|
+
executionEvidence: {
|
|
108
|
+
state: string;
|
|
109
|
+
recordedHead: string | null;
|
|
110
|
+
currentHead: string;
|
|
111
|
+
};
|
|
112
|
+
}[];
|
|
113
|
+
graph: {
|
|
114
|
+
status: GraphStatus;
|
|
115
|
+
sourceCommit: string | null;
|
|
116
|
+
graphAsOf: string | null;
|
|
117
|
+
resolutionLimits: string[];
|
|
118
|
+
};
|
|
119
|
+
graphBasis: {
|
|
120
|
+
head: string;
|
|
121
|
+
governedDocumentCount: number;
|
|
122
|
+
scannedSourceCount: number;
|
|
123
|
+
};
|
|
124
|
+
freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
|
|
125
|
+
state: string;
|
|
126
|
+
};
|
|
127
|
+
refresh: {
|
|
128
|
+
status: "spawned" | "coalesced" | "failed";
|
|
129
|
+
generation?: string;
|
|
130
|
+
} | {
|
|
131
|
+
status: "unavailable" | "not-needed";
|
|
132
|
+
};
|
|
133
|
+
lexicalOnly?: true | undefined;
|
|
134
|
+
candidates: {
|
|
135
|
+
documents: {
|
|
136
|
+
id: string;
|
|
137
|
+
type: import("../../review/requirement-triage").RequirementDocumentKind;
|
|
138
|
+
title: string;
|
|
139
|
+
status: string;
|
|
140
|
+
dependsOn: readonly string[];
|
|
141
|
+
}[];
|
|
142
|
+
reqId: string;
|
|
143
|
+
lexicalScore: number;
|
|
144
|
+
semanticScore?: number;
|
|
145
|
+
contentTerms: string[];
|
|
146
|
+
approved: boolean;
|
|
147
|
+
implementationAnchors: string[];
|
|
148
|
+
freshGreenTests: boolean;
|
|
149
|
+
reasons: string[];
|
|
150
|
+
}[];
|
|
151
|
+
verdict: import("../../review/requirement-triage").RequirementVerdict;
|
|
152
|
+
reasons: string[];
|
|
153
|
+
uncertainty: string[];
|
|
154
|
+
schema: "requirement-triage/1";
|
|
78
155
|
} | {
|
|
79
156
|
evidenceDigest: string;
|
|
80
157
|
persistedTo: string;
|
|
@@ -87,11 +164,13 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
|
|
|
87
164
|
localState?: import("../../semantic/model-cache").LocalModelState | undefined;
|
|
88
165
|
recovery?: string | undefined;
|
|
89
166
|
suppressed?: true | undefined;
|
|
167
|
+
availability: string;
|
|
168
|
+
missingLineages?: string[] | undefined;
|
|
90
169
|
tier: "local" | "none" | "cloud";
|
|
91
170
|
covered: number;
|
|
92
171
|
total: number;
|
|
93
|
-
|
|
94
|
-
|
|
172
|
+
unlineaged: number;
|
|
173
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
95
174
|
};
|
|
96
175
|
provenance: {
|
|
97
176
|
reqId: string;
|
|
@@ -137,6 +216,86 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
|
|
|
137
216
|
reasons: string[];
|
|
138
217
|
uncertainty: string[];
|
|
139
218
|
schema: "requirement-triage/1";
|
|
219
|
+
} | {
|
|
220
|
+
evidenceDigest: string;
|
|
221
|
+
persistedTo: string;
|
|
222
|
+
artifact: {
|
|
223
|
+
digest: string;
|
|
224
|
+
path: string;
|
|
225
|
+
};
|
|
226
|
+
promptDigest: string;
|
|
227
|
+
semantic: {
|
|
228
|
+
localState?: import("../../semantic/model-cache").LocalModelState | undefined;
|
|
229
|
+
recovery?: string | undefined;
|
|
230
|
+
suppressed?: true | undefined;
|
|
231
|
+
availability: string;
|
|
232
|
+
missingLineages?: string[] | undefined;
|
|
233
|
+
tier: "local" | "none" | "cloud";
|
|
234
|
+
covered: number;
|
|
235
|
+
total: number;
|
|
236
|
+
unlineaged: number;
|
|
237
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
238
|
+
};
|
|
239
|
+
provenance: {
|
|
240
|
+
reqId: string;
|
|
241
|
+
documents: {
|
|
242
|
+
id: string;
|
|
243
|
+
type: import("../../review/requirement-triage").RequirementDocumentKind;
|
|
244
|
+
status: string;
|
|
245
|
+
dependsOn: readonly string[];
|
|
246
|
+
}[];
|
|
247
|
+
implementationAnchors: string[];
|
|
248
|
+
graphProvenance: {
|
|
249
|
+
[k: string]: {} | null;
|
|
250
|
+
};
|
|
251
|
+
executionEvidence: {
|
|
252
|
+
state: string;
|
|
253
|
+
recordedHead: string | null;
|
|
254
|
+
currentHead: string;
|
|
255
|
+
};
|
|
256
|
+
}[];
|
|
257
|
+
graph: {
|
|
258
|
+
status: GraphStatus;
|
|
259
|
+
sourceCommit: string | null;
|
|
260
|
+
graphAsOf: string | null;
|
|
261
|
+
resolutionLimits: string[];
|
|
262
|
+
};
|
|
263
|
+
graphBasis: {
|
|
264
|
+
head: string;
|
|
265
|
+
governedDocumentCount: number;
|
|
266
|
+
scannedSourceCount: number;
|
|
267
|
+
};
|
|
268
|
+
freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
|
|
269
|
+
state: string;
|
|
270
|
+
};
|
|
271
|
+
refresh: {
|
|
272
|
+
status: "spawned" | "coalesced" | "failed";
|
|
273
|
+
generation?: string;
|
|
274
|
+
} | {
|
|
275
|
+
status: "unavailable" | "not-needed";
|
|
276
|
+
};
|
|
277
|
+
lexicalOnly?: true | undefined;
|
|
278
|
+
candidates: {
|
|
279
|
+
documents: {
|
|
280
|
+
id: string;
|
|
281
|
+
type: import("../../review/requirement-triage").RequirementDocumentKind;
|
|
282
|
+
title: string;
|
|
283
|
+
status: string;
|
|
284
|
+
dependsOn: readonly string[];
|
|
285
|
+
}[];
|
|
286
|
+
reqId: string;
|
|
287
|
+
lexicalScore: number;
|
|
288
|
+
semanticScore?: number;
|
|
289
|
+
contentTerms: string[];
|
|
290
|
+
approved: boolean;
|
|
291
|
+
implementationAnchors: string[];
|
|
292
|
+
freshGreenTests: boolean;
|
|
293
|
+
reasons: string[];
|
|
294
|
+
}[];
|
|
295
|
+
verdict: import("../../review/requirement-triage").RequirementVerdict;
|
|
296
|
+
reasons: string[];
|
|
297
|
+
uncertainty: string[];
|
|
298
|
+
schema: "requirement-triage/1";
|
|
140
299
|
}>;
|
|
141
300
|
};
|
|
142
301
|
export {};
|
|
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
|
|
37
|
-
// @implements A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734
|
|
37
|
+
// @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734
|
|
38
38
|
// @implements A-SPEC-713
|
|
39
39
|
/** Read-only MCP projection of the pure requirement lifecycle triage model. */
|
|
40
40
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -163,31 +163,32 @@ function createRequirementTriageHandlers(context) {
|
|
|
163
163
|
const runtime = suppressed ? null : (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
|
|
164
164
|
const query = runtime ? await runtime.embedQuery(a.prompt) : null;
|
|
165
165
|
const semanticCandidates = [];
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
}
|
|
166
|
+
// @implements A-SPEC-742 — counted over documents that can carry a vector (a REQ lineage);
|
|
167
|
+
// the unlineaged are reported, not counted against the layer.
|
|
168
|
+
const coverage = (0, requirement_triage_1.requirementSemanticCoverage)(documents, (doc, reqId) => {
|
|
169
|
+
if (!runtime || !query)
|
|
170
|
+
return false;
|
|
171
|
+
const vector = runtime.cachedDocVector((0, requirement_triage_1.canonicalRequirementDocument)(doc, reqId));
|
|
172
|
+
if (vector)
|
|
173
|
+
semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
|
|
174
|
+
return vector !== null && vector !== undefined;
|
|
175
|
+
});
|
|
176
|
+
const covered = coverage.covered;
|
|
178
177
|
const semanticState = suppressed ? 'not-adopted'
|
|
179
178
|
: runtime === null || query === null
|
|
180
179
|
? (tier.tier === 'none' && !tier.localRuntimePresent ? 'not-adopted' : 'unavailable')
|
|
181
|
-
:
|
|
180
|
+
: coverage.state;
|
|
182
181
|
const readiness = tier.tier === 'none' && tier.localRuntimePresent ? (0, model_cache_1.readLocalModelReadiness)() : null;
|
|
183
182
|
const availability = semanticState === 'covered' ? 'available'
|
|
184
|
-
: semanticState === 'cold' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
|
|
183
|
+
: semanticState === 'cold' || semanticState === 'partial' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
|
|
185
184
|
: 'unavailable';
|
|
186
|
-
const semantic = { tier: tier.tier, covered, total:
|
|
185
|
+
const semantic = { tier: tier.tier, covered, total: coverage.eligible, unlineaged: coverage.unlineaged, state: semanticState,
|
|
186
|
+
...(semanticState === 'partial' ? { missingLineages: coverage.missingLineages } : {}),
|
|
187
187
|
availability, ...(suppressed ? { suppressed: true } : {}),
|
|
188
188
|
...(readiness ? { localState: readiness.state, recovery: readiness.recovery } : {}) };
|
|
189
189
|
// lexicalOnly describes THIS run: no semantic score contributed to its ranking.
|
|
190
|
-
|
|
190
|
+
// A-SPEC-742 review round 1: a vector whose cosine was filtered out (<= 0) ranked nothing.
|
|
191
|
+
const lexical = !semanticCandidates.some((c) => Number.isFinite(c.score) && c.score > 0);
|
|
191
192
|
const ranked = (0, requirement_triage_1.triageRequirements)({ prompt: a.prompt, documents, evidence: lineageEvidence,
|
|
192
193
|
semanticCandidates, semantic, graph: { state: graph.status }, topK: a.topK });
|
|
193
194
|
const result = freshnessCurrent ? ranked : {
|
|
@@ -206,7 +207,14 @@ function createRequirementTriageHandlers(context) {
|
|
|
206
207
|
graphProvenance: Object.fromEntries(candidate.documents.map((document) => [document.id, graph.provenanceBySpec[document.id] ?? null])),
|
|
207
208
|
executionEvidence: { state: executionState, recordedHead: evidence?.head ?? null, currentHead },
|
|
208
209
|
}));
|
|
209
|
-
|
|
210
|
+
// @implements A-SPEC-743 — documents as summaries unless the caller asks for their text: the
|
|
211
|
+
// bodies were 72% of a 201 KB median answer, past the harness tool-result limit. Every decision
|
|
212
|
+
// field (verdict, reasons, uncertainty, candidate order and scores) is the same either way.
|
|
213
|
+
const shown = a.detail === 'full' ? result : { ...result, candidates: result.candidates.map((candidate) => ({
|
|
214
|
+
...candidate,
|
|
215
|
+
documents: candidate.documents.map((d) => ({ id: d.id, type: d.type, title: d.title, status: d.status, dependsOn: d.dependsOn ?? [] })),
|
|
216
|
+
})) };
|
|
217
|
+
const answer = { schema: 'requirement-triage/1', ...shown, ...(lexical ? { lexicalOnly: true } : {}), promptDigest, semantic, provenance,
|
|
210
218
|
graph: { status: graph.status, sourceCommit: graph.sourceCommit, graphAsOf: graph.graphAsOf, resolutionLimits: graph.resolutionLimits },
|
|
211
219
|
graphBasis: { head: currentHead, governedDocumentCount: documents.length, scannedSourceCount: scanned.length },
|
|
212
220
|
freshness: freshness === null ? { state: 'absent' } : freshness,
|
|
@@ -634,17 +634,20 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
634
634
|
prompt: string;
|
|
635
635
|
topK?: number;
|
|
636
636
|
persist?: boolean;
|
|
637
|
+
detail?: string;
|
|
637
638
|
}) => Promise<{
|
|
638
639
|
promptDigest: string;
|
|
639
640
|
semantic: {
|
|
640
641
|
localState?: import("../semantic/model-cache").LocalModelState | undefined;
|
|
641
642
|
recovery?: string | undefined;
|
|
642
643
|
suppressed?: true | undefined;
|
|
644
|
+
availability: string;
|
|
645
|
+
missingLineages?: string[] | undefined;
|
|
643
646
|
tier: "local" | "none" | "cloud";
|
|
644
647
|
covered: number;
|
|
645
648
|
total: number;
|
|
646
|
-
|
|
647
|
-
|
|
649
|
+
unlineaged: number;
|
|
650
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
648
651
|
};
|
|
649
652
|
provenance: {
|
|
650
653
|
reqId: string;
|
|
@@ -690,6 +693,80 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
690
693
|
reasons: string[];
|
|
691
694
|
uncertainty: string[];
|
|
692
695
|
schema: "requirement-triage/1";
|
|
696
|
+
} | {
|
|
697
|
+
promptDigest: string;
|
|
698
|
+
semantic: {
|
|
699
|
+
localState?: import("../semantic/model-cache").LocalModelState | undefined;
|
|
700
|
+
recovery?: string | undefined;
|
|
701
|
+
suppressed?: true | undefined;
|
|
702
|
+
availability: string;
|
|
703
|
+
missingLineages?: string[] | undefined;
|
|
704
|
+
tier: "local" | "none" | "cloud";
|
|
705
|
+
covered: number;
|
|
706
|
+
total: number;
|
|
707
|
+
unlineaged: number;
|
|
708
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
709
|
+
};
|
|
710
|
+
provenance: {
|
|
711
|
+
reqId: string;
|
|
712
|
+
documents: {
|
|
713
|
+
id: string;
|
|
714
|
+
type: import("../review/requirement-triage").RequirementDocumentKind;
|
|
715
|
+
status: string;
|
|
716
|
+
dependsOn: readonly string[];
|
|
717
|
+
}[];
|
|
718
|
+
implementationAnchors: string[];
|
|
719
|
+
graphProvenance: {
|
|
720
|
+
[k: string]: {} | null;
|
|
721
|
+
};
|
|
722
|
+
executionEvidence: {
|
|
723
|
+
state: string;
|
|
724
|
+
recordedHead: string | null;
|
|
725
|
+
currentHead: string;
|
|
726
|
+
};
|
|
727
|
+
}[];
|
|
728
|
+
graph: {
|
|
729
|
+
status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
|
|
730
|
+
sourceCommit: string | null;
|
|
731
|
+
graphAsOf: string | null;
|
|
732
|
+
resolutionLimits: string[];
|
|
733
|
+
};
|
|
734
|
+
graphBasis: {
|
|
735
|
+
head: string;
|
|
736
|
+
governedDocumentCount: number;
|
|
737
|
+
scannedSourceCount: number;
|
|
738
|
+
};
|
|
739
|
+
freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
|
|
740
|
+
state: string;
|
|
741
|
+
};
|
|
742
|
+
refresh: {
|
|
743
|
+
status: "spawned" | "coalesced" | "failed";
|
|
744
|
+
generation?: string;
|
|
745
|
+
} | {
|
|
746
|
+
status: "unavailable" | "not-needed";
|
|
747
|
+
};
|
|
748
|
+
lexicalOnly?: true | undefined;
|
|
749
|
+
candidates: {
|
|
750
|
+
documents: {
|
|
751
|
+
id: string;
|
|
752
|
+
type: import("../review/requirement-triage").RequirementDocumentKind;
|
|
753
|
+
title: string;
|
|
754
|
+
status: string;
|
|
755
|
+
dependsOn: readonly string[];
|
|
756
|
+
}[];
|
|
757
|
+
reqId: string;
|
|
758
|
+
lexicalScore: number;
|
|
759
|
+
semanticScore?: number;
|
|
760
|
+
contentTerms: string[];
|
|
761
|
+
approved: boolean;
|
|
762
|
+
implementationAnchors: string[];
|
|
763
|
+
freshGreenTests: boolean;
|
|
764
|
+
reasons: string[];
|
|
765
|
+
}[];
|
|
766
|
+
verdict: import("../review/requirement-triage").RequirementVerdict;
|
|
767
|
+
reasons: string[];
|
|
768
|
+
uncertainty: string[];
|
|
769
|
+
schema: "requirement-triage/1";
|
|
693
770
|
} | {
|
|
694
771
|
evidenceDigest: string;
|
|
695
772
|
persistedTo: string;
|
|
@@ -702,11 +779,13 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
702
779
|
localState?: import("../semantic/model-cache").LocalModelState | undefined;
|
|
703
780
|
recovery?: string | undefined;
|
|
704
781
|
suppressed?: true | undefined;
|
|
782
|
+
availability: string;
|
|
783
|
+
missingLineages?: string[] | undefined;
|
|
705
784
|
tier: "local" | "none" | "cloud";
|
|
706
785
|
covered: number;
|
|
707
786
|
total: number;
|
|
708
|
-
|
|
709
|
-
|
|
787
|
+
unlineaged: number;
|
|
788
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
710
789
|
};
|
|
711
790
|
provenance: {
|
|
712
791
|
reqId: string;
|
|
@@ -752,6 +831,86 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
752
831
|
reasons: string[];
|
|
753
832
|
uncertainty: string[];
|
|
754
833
|
schema: "requirement-triage/1";
|
|
834
|
+
} | {
|
|
835
|
+
evidenceDigest: string;
|
|
836
|
+
persistedTo: string;
|
|
837
|
+
artifact: {
|
|
838
|
+
digest: string;
|
|
839
|
+
path: string;
|
|
840
|
+
};
|
|
841
|
+
promptDigest: string;
|
|
842
|
+
semantic: {
|
|
843
|
+
localState?: import("../semantic/model-cache").LocalModelState | undefined;
|
|
844
|
+
recovery?: string | undefined;
|
|
845
|
+
suppressed?: true | undefined;
|
|
846
|
+
availability: string;
|
|
847
|
+
missingLineages?: string[] | undefined;
|
|
848
|
+
tier: "local" | "none" | "cloud";
|
|
849
|
+
covered: number;
|
|
850
|
+
total: number;
|
|
851
|
+
unlineaged: number;
|
|
852
|
+
state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
|
|
853
|
+
};
|
|
854
|
+
provenance: {
|
|
855
|
+
reqId: string;
|
|
856
|
+
documents: {
|
|
857
|
+
id: string;
|
|
858
|
+
type: import("../review/requirement-triage").RequirementDocumentKind;
|
|
859
|
+
status: string;
|
|
860
|
+
dependsOn: readonly string[];
|
|
861
|
+
}[];
|
|
862
|
+
implementationAnchors: string[];
|
|
863
|
+
graphProvenance: {
|
|
864
|
+
[k: string]: {} | null;
|
|
865
|
+
};
|
|
866
|
+
executionEvidence: {
|
|
867
|
+
state: string;
|
|
868
|
+
recordedHead: string | null;
|
|
869
|
+
currentHead: string;
|
|
870
|
+
};
|
|
871
|
+
}[];
|
|
872
|
+
graph: {
|
|
873
|
+
status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
|
|
874
|
+
sourceCommit: string | null;
|
|
875
|
+
graphAsOf: string | null;
|
|
876
|
+
resolutionLimits: string[];
|
|
877
|
+
};
|
|
878
|
+
graphBasis: {
|
|
879
|
+
head: string;
|
|
880
|
+
governedDocumentCount: number;
|
|
881
|
+
scannedSourceCount: number;
|
|
882
|
+
};
|
|
883
|
+
freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
|
|
884
|
+
state: string;
|
|
885
|
+
};
|
|
886
|
+
refresh: {
|
|
887
|
+
status: "spawned" | "coalesced" | "failed";
|
|
888
|
+
generation?: string;
|
|
889
|
+
} | {
|
|
890
|
+
status: "unavailable" | "not-needed";
|
|
891
|
+
};
|
|
892
|
+
lexicalOnly?: true | undefined;
|
|
893
|
+
candidates: {
|
|
894
|
+
documents: {
|
|
895
|
+
id: string;
|
|
896
|
+
type: import("../review/requirement-triage").RequirementDocumentKind;
|
|
897
|
+
title: string;
|
|
898
|
+
status: string;
|
|
899
|
+
dependsOn: readonly string[];
|
|
900
|
+
}[];
|
|
901
|
+
reqId: string;
|
|
902
|
+
lexicalScore: number;
|
|
903
|
+
semanticScore?: number;
|
|
904
|
+
contentTerms: string[];
|
|
905
|
+
approved: boolean;
|
|
906
|
+
implementationAnchors: string[];
|
|
907
|
+
freshGreenTests: boolean;
|
|
908
|
+
reasons: string[];
|
|
909
|
+
}[];
|
|
910
|
+
verdict: import("../review/requirement-triage").RequirementVerdict;
|
|
911
|
+
reasons: string[];
|
|
912
|
+
uncertainty: string[];
|
|
913
|
+
schema: "requirement-triage/1";
|
|
755
914
|
}>;
|
|
756
915
|
ledger_reconcile: (a: {
|
|
757
916
|
root?: string;
|
|
@@ -828,6 +987,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
828
987
|
falseNegatives: number;
|
|
829
988
|
minSamples: number;
|
|
830
989
|
status: "measured" | "insufficient-data";
|
|
990
|
+
scopeCauses: {
|
|
991
|
+
full: number;
|
|
992
|
+
narrow: number;
|
|
993
|
+
unrecorded: number;
|
|
994
|
+
causes: Record<string, number>;
|
|
995
|
+
};
|
|
831
996
|
}>;
|
|
832
997
|
spec_create: (a: any) => Promise<{
|
|
833
998
|
ok: boolean;
|