@holmes-lab/holmes-kit 0.31.2 → 0.33.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 +104 -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/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 +17 -11
- package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +6 -0
- 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/requirement-triage.d.ts +163 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +26 -18
- 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 +212 -18
- package/dist/holmes/mcp/maintenance-analyze.d.ts +19 -0
- package/dist/holmes/mcp/maintenance-analyze.js +171 -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 +29 -6
- 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 +25 -1
- package/dist/holmes/review/requirement-triage.js +175 -12
- package/dist/holmes/rtm/localize.d.ts +7 -0
- package/dist/holmes/rtm/localize.js +10 -0
- 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
|
@@ -41,8 +41,9 @@ exports.readArtifacts = readArtifacts;
|
|
|
41
41
|
exports.recordOutcome = recordOutcome;
|
|
42
42
|
exports.openArtifacts = openArtifacts;
|
|
43
43
|
exports.closeOpenArtifacts = closeOpenArtifacts;
|
|
44
|
+
exports.scopeCauses = scopeCauses;
|
|
44
45
|
exports.computeCalibration = computeCalibration;
|
|
45
|
-
// @implements A-SPEC-724.1, A-SPEC-271
|
|
46
|
+
// @implements A-SPEC-744, A-SPEC-740, A-SPEC-724.1, A-SPEC-271
|
|
46
47
|
// @implements A-SPEC-268
|
|
47
48
|
const fs = __importStar(require("node:fs"));
|
|
48
49
|
const path = __importStar(require("node:path"));
|
|
@@ -85,6 +86,7 @@ function artifactFrom(analysis, recordedAt, fileDigests = {}) {
|
|
|
85
86
|
extractorVersion: analysis.extractorVersion,
|
|
86
87
|
classification: analysis.classification,
|
|
87
88
|
confidence: analysis.confidence,
|
|
89
|
+
confidenceCalibrated: false,
|
|
88
90
|
graphBasis: analysis.graphBasis,
|
|
89
91
|
predicted: {
|
|
90
92
|
files: sortedUnique(analysis.impacts.files),
|
|
@@ -103,6 +105,8 @@ function artifactFrom(analysis, recordedAt, fileDigests = {}) {
|
|
|
103
105
|
},
|
|
104
106
|
impactTruncated: analysis.impactBounds.stoppedAt.length > 0,
|
|
105
107
|
testScopeTier: analysis.testScope.tier,
|
|
108
|
+
testScopeReason: analysis.testScope.reason,
|
|
109
|
+
testScopeCauses: scopeCauses(analysis.testScope),
|
|
106
110
|
impactedFiles: [...analysis.impacts.impactedFiles],
|
|
107
111
|
securityAssessed: analysis.constraints.security.assessed,
|
|
108
112
|
compatibilityAssessed: analysis.constraints.compatibility.assessed,
|
|
@@ -257,7 +261,53 @@ function closeOpenArtifacts(dir, actual, recordedAt, since) {
|
|
|
257
261
|
}
|
|
258
262
|
return { closed };
|
|
259
263
|
}
|
|
264
|
+
/**
|
|
265
|
+
* @implements A-SPEC-744
|
|
266
|
+
* The named reasons a test scope is `full`, read from its structured fields — never parsed out of the
|
|
267
|
+
* sentence. 455 persisted analyses were all `full` and none said why; the investigation that followed
|
|
268
|
+
* needed a 120-commit replay to answer a question the analysis had already known.
|
|
269
|
+
*/
|
|
270
|
+
function scopeCauses(scope) {
|
|
271
|
+
if (scope.tier !== 'full')
|
|
272
|
+
return [];
|
|
273
|
+
const out = new Set();
|
|
274
|
+
for (const entry of scope.unresolvedFiles ?? []) {
|
|
275
|
+
out.add(entry.startsWith('unsupported:') ? 'unsupported-language'
|
|
276
|
+
: entry.startsWith('impact-truncated:') ? 'impact-truncated' : 'unresolved-file');
|
|
277
|
+
}
|
|
278
|
+
if ((scope.architectureTouched ?? []).length > 0)
|
|
279
|
+
out.add('architecture-document');
|
|
280
|
+
if ((scope.obligationGaps ?? []).length > 0)
|
|
281
|
+
out.add('obligation-gap');
|
|
282
|
+
if (scope.coverageGaps.length > 0)
|
|
283
|
+
out.add('coverage-gap');
|
|
284
|
+
if (scope.hitsFoundational)
|
|
285
|
+
out.add('foundational-requirement');
|
|
286
|
+
// Review round 1: the scope computation's "impacted specs but no anchored tests" branch was being
|
|
287
|
+
// named blast-radius, pointing remediation at the wrong knob.
|
|
288
|
+
if (out.size === 0)
|
|
289
|
+
out.add(scope.impactedTestFiles.length === 0 ? 'no-anchored-tests' : 'blast-radius');
|
|
290
|
+
return [...out].sort();
|
|
291
|
+
}
|
|
260
292
|
const BIN_EDGES = [0, 0.2, 0.4, 0.6, 0.8, 1];
|
|
293
|
+
function scopeCauseTally(artifacts) {
|
|
294
|
+
const tally = { full: 0, narrow: 0, unrecorded: 0, causes: {} };
|
|
295
|
+
for (const artifact of artifacts) {
|
|
296
|
+
const recorded = artifact.uncertainty?.testScopeCauses;
|
|
297
|
+
if (!Array.isArray(recorded)) {
|
|
298
|
+
tally.unrecorded++;
|
|
299
|
+
continue;
|
|
300
|
+
}
|
|
301
|
+
if (artifact.uncertainty.testScopeTier !== 'full') {
|
|
302
|
+
tally.narrow++;
|
|
303
|
+
continue;
|
|
304
|
+
}
|
|
305
|
+
tally.full++;
|
|
306
|
+
for (const cause of new Set(recorded))
|
|
307
|
+
tally.causes[cause] = (tally.causes[cause] ?? 0) + 1;
|
|
308
|
+
}
|
|
309
|
+
return tally;
|
|
310
|
+
}
|
|
261
311
|
/**
|
|
262
312
|
* Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports
|
|
263
313
|
* `insufficient-data` and a null accuracy, because one sample in a bin yields a 0 or a 1 that looks
|
|
@@ -316,5 +366,6 @@ function computeCalibration(artifacts, opts = {}) {
|
|
|
316
366
|
falseNegatives,
|
|
317
367
|
minSamples,
|
|
318
368
|
status: correctness.length >= minSamples ? 'measured' : 'insufficient-data',
|
|
369
|
+
scopeCauses: scopeCauseTally(artifacts),
|
|
319
370
|
};
|
|
320
371
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
|
|
4
|
-
// @implements A-SPEC-736, A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713
|
|
4
|
+
// @implements A-SPEC-743, A-SPEC-736, A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713
|
|
5
5
|
// @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
|
|
6
6
|
// consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
|
|
7
7
|
// @implements A-SPEC-642
|
|
@@ -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: {
|
|
@@ -417,6 +427,8 @@ exports.TOOL_SCHEMAS = {
|
|
|
417
427
|
prompt: str('User requirement or requested behavior to compare with governed requirement lineages.'),
|
|
418
428
|
topK: num('Maximum displayed candidate lineages (default 10, clamped to 1..20).'),
|
|
419
429
|
persist: bool('Write a content-addressed requirement-triage evidence artifact and record its issuance on the provenance ledger (single-use REQ intake evidence). Default false.'),
|
|
430
|
+
// @implements A-SPEC-743
|
|
431
|
+
detail: { type: 'string', enum: ['summary', 'full'], description: 'Default summary: each candidate document is { id, type, title, status, dependsOn }. full adds every document\'s frontmatter and sections (hundreds of KB on a large store). The verdict is the same either way.' },
|
|
420
432
|
},
|
|
421
433
|
required: ['root', 'prompt'],
|
|
422
434
|
},
|
|
@@ -551,21 +563,32 @@ exports.TOOL_SCHEMAS = {
|
|
|
551
563
|
},
|
|
552
564
|
},
|
|
553
565
|
review_status: {
|
|
554
|
-
|
|
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.',
|
|
555
570
|
inputSchema: {
|
|
556
571
|
type: 'object',
|
|
557
|
-
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
|
+
},
|
|
558
576
|
required: ['root'],
|
|
559
577
|
},
|
|
560
578
|
},
|
|
561
579
|
// @implements A-SPEC-126
|
|
562
580
|
reverse_scan: {
|
|
563
|
-
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.',
|
|
564
586
|
inputSchema: {
|
|
565
587
|
type: 'object',
|
|
566
588
|
properties: {
|
|
567
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.'),
|
|
568
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.' },
|
|
569
592
|
},
|
|
570
593
|
required: ['root'],
|
|
571
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),
|
|
@@ -25,9 +25,11 @@ export interface RequirementTriageInput {
|
|
|
25
25
|
semanticCandidates?: readonly RequirementSemanticCandidate[];
|
|
26
26
|
/** Omit for the BM25-only comparison arm; configured cold/unavailable coverage is disclosed. */
|
|
27
27
|
semantic?: {
|
|
28
|
-
state: 'covered' | 'cold' | 'unavailable' | 'not-adopted';
|
|
28
|
+
state: 'covered' | 'partial' | 'cold' | 'unavailable' | 'not-adopted';
|
|
29
29
|
covered: number;
|
|
30
30
|
total: number;
|
|
31
|
+
unlineaged?: number;
|
|
32
|
+
missingLineages?: string[];
|
|
31
33
|
};
|
|
32
34
|
/** The read-only published RTM graph lane. Any unavailable/stale state is disclosed as ambiguity. */
|
|
33
35
|
graph?: {
|
|
@@ -53,9 +55,31 @@ export interface RequirementTriageResult {
|
|
|
53
55
|
reasons: string[];
|
|
54
56
|
uncertainty: string[];
|
|
55
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[];
|
|
56
64
|
/** Re-exported for triage callers; the cache contract belongs to vector coverage. */
|
|
57
65
|
export declare const canonicalRequirementDocument: typeof canonicalRequirementDocumentText;
|
|
58
66
|
/**
|
|
59
67
|
* Retrieval only admits candidates. The verdict requires independent content and operational facts.
|
|
60
68
|
*/
|
|
61
69
|
export declare function triageRequirements(input: RequirementTriageInput): RequirementTriageResult;
|
|
70
|
+
/**
|
|
71
|
+
* @implements A-SPEC-742
|
|
72
|
+
* Requirement-vector coverage over the documents that CAN carry a vector: those with a REQ lineage.
|
|
73
|
+
* A legacy T-SPEC under a C-SPEC has none, is never looked up and never warmed, so counting it in the
|
|
74
|
+
* denominator made `covered` unreachable — every triage in this repository was `ambiguous` (Phase A,
|
|
75
|
+
* 2026-09-30). `partial` is usable evidence: a lexical-only run is already adequate for a verdict,
|
|
76
|
+
* and some vectors are strictly more than none. `cold` — configured, nothing covered — is an inert
|
|
77
|
+
* layer (REQ-682) and stays inadequate.
|
|
78
|
+
*/
|
|
79
|
+
export declare function requirementSemanticCoverage(documents: readonly RequirementDocument[], hasVector: (doc: RequirementDocument, lineageId: string) => boolean): {
|
|
80
|
+
eligible: number;
|
|
81
|
+
covered: number;
|
|
82
|
+
unlineaged: number;
|
|
83
|
+
missingLineages: string[];
|
|
84
|
+
state: 'covered' | 'partial' | 'cold';
|
|
85
|
+
};
|
|
@@ -1,11 +1,55 @@
|
|
|
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;
|
|
7
|
+
// @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-742, A-SPEC-713
|
|
6
8
|
/** Pure, conservative lifecycle triage over governed requirement documents. */
|
|
7
9
|
const semantic_retrieval_1 = require("./semantic-retrieval");
|
|
10
|
+
const localize_1 = require("../rtm/localize");
|
|
8
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
|
+
/**
|
|
14
|
+
* @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
|
|
15
|
+
* paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
|
|
16
|
+
* are not identifiers. Lower-cased, de-duplicated, at most 50.
|
|
17
|
+
*/
|
|
18
|
+
function requestIdentifiers(prompt) {
|
|
19
|
+
const out = [];
|
|
20
|
+
for (const raw of (0, localize_1.withoutCitations)(prompt).split(/\s+/)) {
|
|
21
|
+
const token = raw.replace(/^[`'"([{<]+/, '').replace(/[`'")\]}>.,;:!?]+$/, '');
|
|
22
|
+
if (token === '' || /^[a-z][a-z0-9+.-]*:\/\//i.test(token) || /^www\./i.test(token))
|
|
23
|
+
continue;
|
|
24
|
+
const snake = /^[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+$/.test(token);
|
|
25
|
+
const camel = token.length >= 4 && /^[A-Za-z][A-Za-z0-9]*$/.test(token) && /[a-z][A-Z]/.test(token);
|
|
26
|
+
// A path needs a code extension or two separators: `and/or` and `client/server` are prose.
|
|
27
|
+
const pathLike = token.includes('/') && /[A-Za-z]/.test(token) && (CODE_FILE.test(token) || (token.match(/\//g) ?? []).length >= 2);
|
|
28
|
+
const file = !token.includes('/') && /[A-Za-z]/.test(token.replace(CODE_FILE, '')) && CODE_FILE.test(token);
|
|
29
|
+
if (!snake && !camel && !pathLike && !file)
|
|
30
|
+
continue;
|
|
31
|
+
const id = token.toLowerCase();
|
|
32
|
+
if (!out.includes(id))
|
|
33
|
+
out.push(id);
|
|
34
|
+
if (out.length === 50)
|
|
35
|
+
break;
|
|
36
|
+
}
|
|
37
|
+
return out;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* @implements A-SPEC-713.2 — what a lineage says it covers: titles and section bodies, without a section
|
|
41
|
+
* headed "Out of Scope" and without what follows an `Out of Scope:` line inside a section.
|
|
42
|
+
*/
|
|
43
|
+
function inScopeText(docs) {
|
|
44
|
+
return docs.map((d) => [d.title, ...Object.entries(d.sections ?? {})
|
|
45
|
+
.filter(([heading]) => !/out of scope/i.test(heading))
|
|
46
|
+
.map(([, body]) => body.split(/^\s*Out of Scope\s*:/im)[0])].join('\n')).join('\n').toLowerCase();
|
|
47
|
+
}
|
|
48
|
+
function identifierCovered(id, text) {
|
|
49
|
+
if (text.includes(id))
|
|
50
|
+
return true;
|
|
51
|
+
return id.includes('/') && text.includes(id.slice(id.lastIndexOf('/') + 1));
|
|
52
|
+
}
|
|
9
53
|
/** Re-exported for triage callers; the cache contract belongs to vector coverage. */
|
|
10
54
|
exports.canonicalRequirementDocument = vector_coverage_1.canonicalRequirementDocument;
|
|
11
55
|
function rankLimit(value) {
|
|
@@ -29,6 +73,22 @@ function rootOf(id, byId) {
|
|
|
29
73
|
}
|
|
30
74
|
return null;
|
|
31
75
|
}
|
|
76
|
+
/** @implements A-SPEC-713.1 — what BM25 and content support read: a document's title and sections. */
|
|
77
|
+
function scoringText(doc) {
|
|
78
|
+
// Round 4: bodies only — every spec shares its headings (Objective, Behavior, Files to Touch, …).
|
|
79
|
+
const bodies = Object.entries(doc.sections ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([, body]) => body);
|
|
80
|
+
return [doc.title, ...bodies].join('\n');
|
|
81
|
+
}
|
|
82
|
+
function rankCompare(a, b, cited) {
|
|
83
|
+
const byCitation = Number(cited.has(b.reqId)) - Number(cited.has(a.reqId));
|
|
84
|
+
if (byCitation !== 0)
|
|
85
|
+
return byCitation;
|
|
86
|
+
const sa = a.semanticScore ?? -Infinity;
|
|
87
|
+
const sb = b.semanticScore ?? -Infinity;
|
|
88
|
+
if (sa !== sb)
|
|
89
|
+
return sb > sa ? 1 : -1;
|
|
90
|
+
return b.lexicalScore - a.lexicalScore || a.reqId.localeCompare(b.reqId);
|
|
91
|
+
}
|
|
32
92
|
function bm25(query, docs) {
|
|
33
93
|
const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedTerms)(text));
|
|
34
94
|
const avg = terms.reduce((n, row) => n + row.length, 0) / (terms.length || 1);
|
|
@@ -54,9 +114,43 @@ function bm25(query, docs) {
|
|
|
54
114
|
* Retrieval only admits candidates. The verdict requires independent content and operational facts.
|
|
55
115
|
*/
|
|
56
116
|
function triageRequirements(input) {
|
|
57
|
-
const
|
|
58
|
-
|
|
59
|
-
|
|
117
|
+
const result = triageCore(input);
|
|
118
|
+
// @implements A-SPEC-742 — a partially covered layer decides, and says what it lacked.
|
|
119
|
+
if (input.semantic?.state !== 'partial')
|
|
120
|
+
return result;
|
|
121
|
+
return { ...result, uncertainty: [...result.uncertainty, `semantic-partial:${Math.max(0, input.semantic.total - input.semantic.covered)}`] };
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* @implements A-SPEC-742
|
|
125
|
+
* Requirement-vector coverage over the documents that CAN carry a vector: those with a REQ lineage.
|
|
126
|
+
* A legacy T-SPEC under a C-SPEC has none, is never looked up and never warmed, so counting it in the
|
|
127
|
+
* denominator made `covered` unreachable — every triage in this repository was `ambiguous` (Phase A,
|
|
128
|
+
* 2026-09-30). `partial` is usable evidence: a lexical-only run is already adequate for a verdict,
|
|
129
|
+
* and some vectors are strictly more than none. `cold` — configured, nothing covered — is an inert
|
|
130
|
+
* layer (REQ-682) and stays inadequate.
|
|
131
|
+
*/
|
|
132
|
+
function requirementSemanticCoverage(documents, hasVector) {
|
|
133
|
+
const byId = new Map(documents.map((d) => [d.id, d]));
|
|
134
|
+
let eligible = 0;
|
|
135
|
+
let covered = 0;
|
|
136
|
+
const missing = new Set();
|
|
137
|
+
for (const doc of documents) {
|
|
138
|
+
const lineageId = rootOf(doc.id, byId);
|
|
139
|
+
if (lineageId === null)
|
|
140
|
+
continue;
|
|
141
|
+
eligible++;
|
|
142
|
+
if (hasVector(doc, lineageId))
|
|
143
|
+
covered++;
|
|
144
|
+
else
|
|
145
|
+
missing.add(lineageId);
|
|
146
|
+
}
|
|
147
|
+
// Review round 1: zero eligible is `cold`, never a vacuous `covered` (0 === 0).
|
|
148
|
+
const state = covered === 0 ? 'cold' : covered === eligible ? 'covered' : 'partial';
|
|
149
|
+
return { eligible, covered, unlineaged: documents.length - eligible, missingLineages: [...missing].sort().slice(0, 20), state };
|
|
150
|
+
}
|
|
151
|
+
function triageCore(input) {
|
|
152
|
+
// @implements A-SPEC-713.1 — ids are pointers, not content: they order (citation) but never score.
|
|
153
|
+
const promptTerms = [...new Set((0, semantic_retrieval_1.normalisedTerms)((0, localize_1.withoutCitations)(input.prompt)))];
|
|
60
154
|
const governed = input.documents.filter((d) => d.type === 'REQ' || d.type === 'H-SPEC' || d.type === 'A-SPEC' || d.type === 'T-SPEC');
|
|
61
155
|
if (governed.length === 0)
|
|
62
156
|
return { verdict: 'ambiguous', candidates: [], reasons: ['empty-or-unreadable-corpus'], uncertainty: ['empty-or-unreadable-corpus'] };
|
|
@@ -72,10 +166,18 @@ function triageRequirements(input) {
|
|
|
72
166
|
}
|
|
73
167
|
if (lineages.size === 0)
|
|
74
168
|
return { verdict: 'ambiguous', candidates: [], reasons: ['no-readable-lineage'], uncertainty: ['no-readable-lineage'] };
|
|
169
|
+
// @implements A-SPEC-713.1 — a lineage the request names ranks first (only ORDERS, never scores).
|
|
170
|
+
const citedLineages = new Set((0, localize_1.citationsIn)(input.prompt, new Set(governed.map((d) => d.id))).cited
|
|
171
|
+
.map((id) => rootOf(id, byId)).filter((root) => root !== null));
|
|
172
|
+
// Review round 3: an id-only prompt still lists the lineages it names.
|
|
173
|
+
if (promptTerms.length === 0 && citedLineages.size === 0)
|
|
174
|
+
return { verdict: 'ambiguous', candidates: [], reasons: ['empty-prompt'], uncertainty: ['empty-prompt'] };
|
|
75
175
|
const documents = [...lineages.entries()].map(([reqId, docs]) => ({
|
|
76
176
|
reqId,
|
|
77
177
|
docs: [...docs].sort((a, b) => a.id.localeCompare(b.id)),
|
|
78
|
-
|
|
178
|
+
// Review round 3: titles and sections only — the vector-cache text's `id:`/`lineage:`/`status:`
|
|
179
|
+
// header let "REQ 742", "the 742 rows", "spec" or "status" score (the cache text is unchanged).
|
|
180
|
+
text: docs.map(scoringText).join('\n'),
|
|
79
181
|
})).sort((a, b) => a.reqId.localeCompare(b.reqId));
|
|
80
182
|
const lexical = bm25(promptTerms, documents.map((d) => d.text));
|
|
81
183
|
const semantic = new Map();
|
|
@@ -88,7 +190,8 @@ function triageRequirements(input) {
|
|
|
88
190
|
}
|
|
89
191
|
const allCandidates = documents.map((row, i) => {
|
|
90
192
|
const semanticScore = semantic.get(row.reqId);
|
|
91
|
-
|
|
193
|
+
const cited = citedLineages.has(row.reqId);
|
|
194
|
+
if (lexical[i] <= 0 && semanticScore === undefined && !cited)
|
|
92
195
|
return null;
|
|
93
196
|
const textLower = row.text.toLowerCase();
|
|
94
197
|
const contentTerms = promptTerms.filter((term) => textLower.includes(term));
|
|
@@ -96,6 +199,7 @@ function triageRequirements(input) {
|
|
|
96
199
|
const approved = row.docs.length === 4 && row.docs.every((d) => d.status === 'approved');
|
|
97
200
|
const anchors = [...new Set(operational.implementationAnchors ?? [])].sort();
|
|
98
201
|
const reasons = [
|
|
202
|
+
...(cited ? ['cited'] : []),
|
|
99
203
|
...(lexical[i] > 0 ? ['bm25'] : []),
|
|
100
204
|
...(semanticScore !== undefined ? ['semantic-candidate'] : []),
|
|
101
205
|
...(contentTerms.length > 0 ? ['content-supported'] : ['content-unsupported']),
|
|
@@ -108,11 +212,14 @@ function triageRequirements(input) {
|
|
|
108
212
|
...(semanticScore !== undefined ? { semanticScore } : {}), contentTerms, approved,
|
|
109
213
|
implementationAnchors: anchors, freshGreenTests: operational.freshGreenTests === true, reasons };
|
|
110
214
|
}).filter((candidate) => candidate !== null)
|
|
111
|
-
.
|
|
112
|
-
|
|
215
|
+
// @implements A-SPEC-713.1 — cited, then the semantic channel where the lineage has a vector, then
|
|
216
|
+
// BM25. `max(BM25, cosine)` compared two scales: cosine counted only when BM25 was zero, while on
|
|
217
|
+
// the replay the semantic top was right 2–2.5× as often as the lexical top when they disagreed.
|
|
218
|
+
// With no vector anywhere (a lexical-only run) this is the lexical order it always was.
|
|
219
|
+
.sort((a, b) => rankCompare(a, b, citedLineages));
|
|
113
220
|
const candidates = allCandidates.slice(0, rankLimit(input.topK));
|
|
114
221
|
const semanticInadequate = input.semantic !== undefined
|
|
115
|
-
&& input.semantic.state !== 'covered' && input.semantic.state !== 'not-adopted';
|
|
222
|
+
&& input.semantic.state !== 'covered' && input.semantic.state !== 'partial' && input.semantic.state !== 'not-adopted';
|
|
116
223
|
const graphInadequate = input.graph !== undefined && input.graph.state !== 'current';
|
|
117
224
|
if (graphInadequate)
|
|
118
225
|
return { verdict: 'ambiguous', candidates, reasons: ['graph-coverage-inadequate'], uncertainty: ['graph-coverage-inadequate'] };
|
|
@@ -121,16 +228,72 @@ function triageRequirements(input) {
|
|
|
121
228
|
if (allCandidates.length === 0)
|
|
122
229
|
return { verdict: 'new', candidates, reasons: ['semantic-coverage-not-required-for-bm25-baseline'], uncertainty: ['semantic-coverage-not-required-for-bm25-baseline'] };
|
|
123
230
|
const top = allCandidates[0];
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
231
|
+
// @implements A-SPEC-713.1 — ties are judged on scores alone, whatever is cited, and a lineage with
|
|
232
|
+
// no vector ties on the semantic side (a coverage gap is not evidence against it). Checked first: a
|
|
233
|
+
// tie is the more specific explanation for an ambiguous answer.
|
|
234
|
+
const tied = allCandidates.filter((c) => c.lexicalScore === top.lexicalScore
|
|
235
|
+
&& (c.semanticScore === undefined || top.semanticScore === undefined || c.semanticScore === top.semanticScore));
|
|
236
|
+
// @implements A-SPEC-713.1 — a confident verdict needs two channels on the same lineage. Replay:
|
|
237
|
+
// agreement → right 0.46–0.79; disagreement → the lexical top right 0.12–0.16; every gold-new case
|
|
238
|
+
// disagreed, and an existing-change verdict refuses a new REQ at intake. A channel names a lineage
|
|
239
|
+
// only when its top is unique (and, lexically, above zero). A citation only ORDERS (review round 1:
|
|
240
|
+
// "unlike REQ-2", an id in a URL or `S-1` in prose are mentions, not evidence): it counts only when it
|
|
241
|
+
// is the single cited lineage and a channel also tops it.
|
|
242
|
+
let agreementReason = null;
|
|
243
|
+
if (tied.length <= 1) {
|
|
244
|
+
const uniqueTop = (list, score) => {
|
|
245
|
+
const sorted = [...list].sort((a, b) => score(b) - score(a));
|
|
246
|
+
if (sorted.length === 0 || (sorted.length > 1 && score(sorted[0]) === score(sorted[1])))
|
|
247
|
+
return null;
|
|
248
|
+
return sorted[0];
|
|
249
|
+
};
|
|
250
|
+
// Round 4: a term every lineage contains cannot tell lineages apart — the lexical channel names a
|
|
251
|
+
// lineage only through at least one term that some lineage lacks.
|
|
252
|
+
// With a single lineage there is nothing to tell apart, so the rule does not apply.
|
|
253
|
+
const everywhere = new Set(documents.length < 2 ? [] : promptTerms.filter((term) => documents.every((d) => d.text.toLowerCase().includes(term))));
|
|
254
|
+
const lexicalTop = uniqueTop(allCandidates.filter((c) => c.lexicalScore > 0 && c.contentTerms.some((t) => !everywhere.has(t))), (c) => c.lexicalScore);
|
|
255
|
+
const withVector = allCandidates.filter((c) => c.semanticScore !== undefined);
|
|
256
|
+
const semanticTop = uniqueTop(withVector, (c) => c.semanticScore);
|
|
257
|
+
// Round 3: a citation never counts toward agreement — "(unrelated to REQ-1)" plus one channel on
|
|
258
|
+
// REQ-1 decided REQ-1. Both channels (or, lexical-only, the lexical one) must name a lineage, and it
|
|
259
|
+
// must be the first-ranked one.
|
|
260
|
+
// @implements A-SPEC-713.3 — a single channel never confirms (owner decision 2026-10-01). With no vector on
|
|
261
|
+
// any candidate, the lexical top alone answered existing-change for 47 of 60 requirements that were new at
|
|
262
|
+
// the time, and intake then refused them. The lexical order stays visible; the verdict does not decide.
|
|
263
|
+
if (withVector.length === 0) {
|
|
264
|
+
agreementReason = 'single-channel';
|
|
265
|
+
}
|
|
266
|
+
else {
|
|
267
|
+
const agreed = lexicalTop !== null && semanticTop !== null && lexicalTop.reqId === semanticTop.reqId ? lexicalTop.reqId : null;
|
|
268
|
+
if (agreed === null)
|
|
269
|
+
agreementReason = 'channels-disagree';
|
|
270
|
+
else if (agreed !== top.reqId)
|
|
271
|
+
agreementReason = 'citation-unbacked';
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
if (tied.length > 1 || agreementReason !== null || top.contentTerms.length === 0 || top.reasons.includes('contradictory-evidence')) {
|
|
127
275
|
const uncertainty = [
|
|
128
276
|
...(tied.length > 1 ? ['tied-candidates'] : []),
|
|
277
|
+
...(agreementReason !== null ? [agreementReason] : []),
|
|
129
278
|
...(top.contentTerms.length === 0 ? ['candidate-content-unsupported'] : []),
|
|
130
279
|
...(top.reasons.includes('contradictory-evidence') ? ['contradictory-evidence'] : []),
|
|
131
280
|
];
|
|
132
281
|
return { verdict: 'ambiguous', candidates, reasons: uncertainty, uncertainty };
|
|
133
282
|
}
|
|
283
|
+
// @implements A-SPEC-713.2 — a confident verdict says the request is this lineage's business; a code
|
|
284
|
+
// identifier the lineage never mentions in scope means the rule cannot judge that. Measured: a request
|
|
285
|
+
// about spec_list/review_status was `fulfilled` by the phase_status lineage whose REQ puts other tools
|
|
286
|
+
// out of scope, and intake then refused the new requirement.
|
|
287
|
+
const identifiers = requestIdentifiers(input.prompt);
|
|
288
|
+
if (identifiers.length > 0) {
|
|
289
|
+
const text = inScopeText(top.documents);
|
|
290
|
+
const missing = identifiers.filter((id) => !identifierCovered(id, text)).sort();
|
|
291
|
+
if (missing.length > 0) {
|
|
292
|
+
const named = [...missing.slice(0, 5), ...(missing.length > 5 ? [`+${missing.length - 5}`] : [])];
|
|
293
|
+
const reason = `identifiers-outside-lineage:${named.join(',')}`;
|
|
294
|
+
return { verdict: 'ambiguous', candidates, reasons: [reason], uncertainty: [reason] };
|
|
295
|
+
}
|
|
296
|
+
}
|
|
134
297
|
if (top.approved && top.implementationAnchors.length > 0 && top.freshGreenTests) {
|
|
135
298
|
return { verdict: 'fulfilled', candidates, reasons: ['approved-lineage', 'implementation-anchors', 'fresh-green-execution'], uncertainty: [] };
|
|
136
299
|
}
|
|
@@ -32,6 +32,13 @@ export interface LocalizationReport {
|
|
|
32
32
|
*/
|
|
33
33
|
unknownCitations: string[];
|
|
34
34
|
}
|
|
35
|
+
/**
|
|
36
|
+
* @implements A-SPEC-713.1 — the text with every id spelling this extractor recognises removed. An id
|
|
37
|
+
* is a pointer, not content: scored as words, the number inside `REQ-742` made lineage 742 the lexical
|
|
38
|
+
* top of any prompt that merely mentioned it ("not REQ-742", a ticket URL). Same pattern, so the
|
|
39
|
+
* two cannot drift.
|
|
40
|
+
*/
|
|
41
|
+
export declare function withoutCitations(text: string): string;
|
|
35
42
|
export declare function citationsIn(text: string, known: ReadonlySet<string>): {
|
|
36
43
|
cited: string[];
|
|
37
44
|
unknown: string[];
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.withoutCitations = withoutCitations;
|
|
3
4
|
exports.citationsIn = citationsIn;
|
|
4
5
|
exports.significantTerms = significantTerms;
|
|
5
6
|
exports.bigramUnspaced = bigramUnspaced;
|
|
@@ -14,6 +15,15 @@ exports.localizeIssue = localizeIssue;
|
|
|
14
15
|
// SCORING population stays A-SPEC-limited below, so an ADR never admits or reorders a file).
|
|
15
16
|
const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|ADR|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
|
|
16
17
|
const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC', 'ADR'];
|
|
18
|
+
/**
|
|
19
|
+
* @implements A-SPEC-713.1 — the text with every id spelling this extractor recognises removed. An id
|
|
20
|
+
* is a pointer, not content: scored as words, the number inside `REQ-742` made lineage 742 the lexical
|
|
21
|
+
* top of any prompt that merely mentioned it ("not REQ-742", a ticket URL). Same pattern, so the
|
|
22
|
+
* two cannot drift.
|
|
23
|
+
*/
|
|
24
|
+
function withoutCitations(text) {
|
|
25
|
+
return text.replace(CITATION, ' ');
|
|
26
|
+
}
|
|
17
27
|
/**
|
|
18
28
|
* @implements A-SPEC-273
|
|
19
29
|
* How much a citation is worth, normalized by the file's anchor count exactly as the lexical spec
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cosine at or above which an unreadable file's path words are "about" a non-ASCII request, keyed by
|
|
3
|
+
* the semantic runtime label. Measured 2026-09-30 (docs/goals/EVIDENCE-nonlatin-relevance-2026-09-30.md):
|
|
4
|
+
* on gemini-embedding-001 mixed requests naming the file scored 0.701–0.765 and no unmatched jarvis
|
|
5
|
+
* request exceeded 0.640. On local bge-m3 the populations overlapped (pin 0.486 against 0.489), so it
|
|
6
|
+
* has no entry — a label without a threshold keeps the language relevant.
|
|
7
|
+
*/
|
|
8
|
+
export declare const UNREADABLE_PATH_THRESHOLDS: Readonly<Record<string, number>>;
|
|
9
|
+
/** `scripts/holmes_session_key.sh` -> `scripts holmes session key`: the words of the path, no extension. */
|
|
10
|
+
export declare function unreadablePathText(file: string): string;
|
|
11
|
+
/**
|
|
12
|
+
* Tracked and untracked-not-ignored files whose extension the scanner cannot read. Throws when git
|
|
13
|
+
* fails: the analysis handler turns that into its `not-enumerated(non-git)` gap.
|
|
14
|
+
*/
|
|
15
|
+
export declare function listUnreadableFiles(root: string): {
|
|
16
|
+
languages: string[];
|
|
17
|
+
files: string[];
|
|
18
|
+
truncated: boolean;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Warm the path vectors the analysis compares a non-ASCII request with. Best effort: a tree git cannot
|
|
22
|
+
* list, or an embedder that fails, leaves vectors missing — and a missing vector keeps the language
|
|
23
|
+
* relevant, which is the behavior before this existed.
|
|
24
|
+
*/
|
|
25
|
+
export declare function warmUnreadablePaths(rt: {
|
|
26
|
+
warm(texts: string[]): Promise<{
|
|
27
|
+
computed: number;
|
|
28
|
+
cached: number;
|
|
29
|
+
}>;
|
|
30
|
+
}, root: string): Promise<void>;
|