@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.
Files changed (37) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +3 -1
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/autonomy.js +15 -1
  5. package/dist/holmes/guardrail/impact-gate.js +50 -1
  6. package/dist/holmes/mcp/handlers/adoption.d.ts +17 -3
  7. package/dist/holmes/mcp/handlers/adoption.js +70 -2
  8. package/dist/holmes/mcp/handlers/graph-operations.js +6 -1
  9. package/dist/holmes/mcp/handlers/maintenance-analysis.js +17 -11
  10. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +6 -0
  11. package/dist/holmes/mcp/handlers/phase-queries.d.ts +30 -2
  12. package/dist/holmes/mcp/handlers/phase-queries.js +5 -1
  13. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +163 -4
  14. package/dist/holmes/mcp/handlers/requirement-triage.js +26 -18
  15. package/dist/holmes/mcp/handlers/review-evidence.d.ts +44 -1
  16. package/dist/holmes/mcp/handlers/review-evidence.js +48 -2
  17. package/dist/holmes/mcp/handlers/spec-approval.d.ts +10 -0
  18. package/dist/holmes/mcp/handlers/spec-approval.js +16 -1
  19. package/dist/holmes/mcp/handlers/spec-queries.d.ts +1 -9
  20. package/dist/holmes/mcp/handlers/spec-queries.js +40 -15
  21. package/dist/holmes/mcp/handlers.d.ts +212 -18
  22. package/dist/holmes/mcp/maintenance-analyze.d.ts +19 -0
  23. package/dist/holmes/mcp/maintenance-analyze.js +171 -7
  24. package/dist/holmes/mcp/maintenance-evidence.d.ts +25 -0
  25. package/dist/holmes/mcp/maintenance-evidence.js +52 -1
  26. package/dist/holmes/mcp/tool-schemas.js +29 -6
  27. package/dist/holmes/reverse/scan.d.ts +6 -0
  28. package/dist/holmes/reverse/scan.js +4 -2
  29. package/dist/holmes/review/requirement-triage.d.ts +25 -1
  30. package/dist/holmes/review/requirement-triage.js +175 -12
  31. package/dist/holmes/rtm/localize.d.ts +7 -0
  32. package/dist/holmes/rtm/localize.js +10 -0
  33. package/dist/holmes/semantic/unreadable-paths.d.ts +30 -0
  34. package/dist/holmes/semantic/unreadable-paths.js +104 -0
  35. package/package.json +1 -1
  36. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  37. 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
- description: `List all 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), optionally filtered to a single kind.`,
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: { type: str('Optional spec kind to filter by (e.g. A-SPEC).') },
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
- description: 'Summarize open findings by severity and whether the review is blocked ({ blocked, open }).',
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: { root: ROOT },
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 anchored = files.filter((f) => f.implementsSpecs.length > 0).length;
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
- // @implements A-SPEC-713
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 promptTerms = [...new Set((0, semantic_retrieval_1.normalisedTerms)(input.prompt))];
58
- if (promptTerms.length === 0)
59
- return { verdict: 'ambiguous', candidates: [], reasons: ['empty-prompt'], uncertainty: ['empty-prompt'] };
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
- text: docs.map((d) => (0, exports.canonicalRequirementDocument)(d, reqId)).join('\n'),
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
- if (lexical[i] <= 0 && semanticScore === undefined)
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
- .sort((a, b) => Math.max(b.lexicalScore, b.semanticScore ?? 0) - Math.max(a.lexicalScore, a.semanticScore ?? 0)
112
- || a.reqId.localeCompare(b.reqId));
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
- const topScore = Math.max(top.lexicalScore, top.semanticScore ?? 0);
125
- const tied = allCandidates.filter((c) => Math.max(c.lexicalScore, c.semanticScore ?? 0) === topScore);
126
- if (tied.length > 1 || top.contentTerms.length === 0 || top.reasons.includes('contradictory-evidence')) {
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>;