@holmes-lab/holmes-kit 0.31.1 → 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.
@@ -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
@@ -417,6 +417,8 @@ exports.TOOL_SCHEMAS = {
417
417
  prompt: str('User requirement or requested behavior to compare with governed requirement lineages.'),
418
418
  topK: num('Maximum displayed candidate lineages (default 10, clamped to 1..20).'),
419
419
  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.'),
420
+ // @implements A-SPEC-743
421
+ 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
422
  },
421
423
  required: ['root', 'prompt'],
422
424
  },
@@ -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?: {
@@ -59,3 +61,19 @@ export declare const canonicalRequirementDocument: typeof canonicalRequirementDo
59
61
  * Retrieval only admits candidates. The verdict requires independent content and operational facts.
60
62
  */
61
63
  export declare function triageRequirements(input: RequirementTriageInput): RequirementTriageResult;
64
+ /**
65
+ * @implements A-SPEC-742
66
+ * Requirement-vector coverage over the documents that CAN carry a vector: those with a REQ lineage.
67
+ * A legacy T-SPEC under a C-SPEC has none, is never looked up and never warmed, so counting it in the
68
+ * denominator made `covered` unreachable — every triage in this repository was `ambiguous` (Phase A,
69
+ * 2026-09-30). `partial` is usable evidence: a lexical-only run is already adequate for a verdict,
70
+ * and some vectors are strictly more than none. `cold` — configured, nothing covered — is an inert
71
+ * layer (REQ-682) and stays inadequate.
72
+ */
73
+ export declare function requirementSemanticCoverage(documents: readonly RequirementDocument[], hasVector: (doc: RequirementDocument, lineageId: string) => boolean): {
74
+ eligible: number;
75
+ covered: number;
76
+ unlineaged: number;
77
+ missingLineages: string[];
78
+ state: 'covered' | 'partial' | 'cold';
79
+ };
@@ -2,9 +2,11 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.canonicalRequirementDocument = void 0;
4
4
  exports.triageRequirements = triageRequirements;
5
- // @implements A-SPEC-713
5
+ exports.requirementSemanticCoverage = requirementSemanticCoverage;
6
+ // @implements A-SPEC-713.1, A-SPEC-742, A-SPEC-713
6
7
  /** Pure, conservative lifecycle triage over governed requirement documents. */
7
8
  const semantic_retrieval_1 = require("./semantic-retrieval");
9
+ const localize_1 = require("../rtm/localize");
8
10
  const vector_coverage_1 = require("../semantic/vector-coverage");
9
11
  /** Re-exported for triage callers; the cache contract belongs to vector coverage. */
10
12
  exports.canonicalRequirementDocument = vector_coverage_1.canonicalRequirementDocument;
@@ -29,6 +31,22 @@ function rootOf(id, byId) {
29
31
  }
30
32
  return null;
31
33
  }
34
+ /** @implements A-SPEC-713.1 — what BM25 and content support read: a document's title and sections. */
35
+ function scoringText(doc) {
36
+ // Round 4: bodies only — every spec shares its headings (Objective, Behavior, Files to Touch, …).
37
+ const bodies = Object.entries(doc.sections ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([, body]) => body);
38
+ return [doc.title, ...bodies].join('\n');
39
+ }
40
+ function rankCompare(a, b, cited) {
41
+ const byCitation = Number(cited.has(b.reqId)) - Number(cited.has(a.reqId));
42
+ if (byCitation !== 0)
43
+ return byCitation;
44
+ const sa = a.semanticScore ?? -Infinity;
45
+ const sb = b.semanticScore ?? -Infinity;
46
+ if (sa !== sb)
47
+ return sb > sa ? 1 : -1;
48
+ return b.lexicalScore - a.lexicalScore || a.reqId.localeCompare(b.reqId);
49
+ }
32
50
  function bm25(query, docs) {
33
51
  const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedTerms)(text));
34
52
  const avg = terms.reduce((n, row) => n + row.length, 0) / (terms.length || 1);
@@ -54,9 +72,43 @@ function bm25(query, docs) {
54
72
  * Retrieval only admits candidates. The verdict requires independent content and operational facts.
55
73
  */
56
74
  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'] };
75
+ const result = triageCore(input);
76
+ // @implements A-SPEC-742 — a partially covered layer decides, and says what it lacked.
77
+ if (input.semantic?.state !== 'partial')
78
+ return result;
79
+ return { ...result, uncertainty: [...result.uncertainty, `semantic-partial:${Math.max(0, input.semantic.total - input.semantic.covered)}`] };
80
+ }
81
+ /**
82
+ * @implements A-SPEC-742
83
+ * Requirement-vector coverage over the documents that CAN carry a vector: those with a REQ lineage.
84
+ * A legacy T-SPEC under a C-SPEC has none, is never looked up and never warmed, so counting it in the
85
+ * denominator made `covered` unreachable — every triage in this repository was `ambiguous` (Phase A,
86
+ * 2026-09-30). `partial` is usable evidence: a lexical-only run is already adequate for a verdict,
87
+ * and some vectors are strictly more than none. `cold` — configured, nothing covered — is an inert
88
+ * layer (REQ-682) and stays inadequate.
89
+ */
90
+ function requirementSemanticCoverage(documents, hasVector) {
91
+ const byId = new Map(documents.map((d) => [d.id, d]));
92
+ let eligible = 0;
93
+ let covered = 0;
94
+ const missing = new Set();
95
+ for (const doc of documents) {
96
+ const lineageId = rootOf(doc.id, byId);
97
+ if (lineageId === null)
98
+ continue;
99
+ eligible++;
100
+ if (hasVector(doc, lineageId))
101
+ covered++;
102
+ else
103
+ missing.add(lineageId);
104
+ }
105
+ // Review round 1: zero eligible is `cold`, never a vacuous `covered` (0 === 0).
106
+ const state = covered === 0 ? 'cold' : covered === eligible ? 'covered' : 'partial';
107
+ return { eligible, covered, unlineaged: documents.length - eligible, missingLineages: [...missing].sort().slice(0, 20), state };
108
+ }
109
+ function triageCore(input) {
110
+ // @implements A-SPEC-713.1 — ids are pointers, not content: they order (citation) but never score.
111
+ const promptTerms = [...new Set((0, semantic_retrieval_1.normalisedTerms)((0, localize_1.withoutCitations)(input.prompt)))];
60
112
  const governed = input.documents.filter((d) => d.type === 'REQ' || d.type === 'H-SPEC' || d.type === 'A-SPEC' || d.type === 'T-SPEC');
61
113
  if (governed.length === 0)
62
114
  return { verdict: 'ambiguous', candidates: [], reasons: ['empty-or-unreadable-corpus'], uncertainty: ['empty-or-unreadable-corpus'] };
@@ -72,10 +124,18 @@ function triageRequirements(input) {
72
124
  }
73
125
  if (lineages.size === 0)
74
126
  return { verdict: 'ambiguous', candidates: [], reasons: ['no-readable-lineage'], uncertainty: ['no-readable-lineage'] };
127
+ // @implements A-SPEC-713.1 — a lineage the request names ranks first (only ORDERS, never scores).
128
+ const citedLineages = new Set((0, localize_1.citationsIn)(input.prompt, new Set(governed.map((d) => d.id))).cited
129
+ .map((id) => rootOf(id, byId)).filter((root) => root !== null));
130
+ // Review round 3: an id-only prompt still lists the lineages it names.
131
+ if (promptTerms.length === 0 && citedLineages.size === 0)
132
+ return { verdict: 'ambiguous', candidates: [], reasons: ['empty-prompt'], uncertainty: ['empty-prompt'] };
75
133
  const documents = [...lineages.entries()].map(([reqId, docs]) => ({
76
134
  reqId,
77
135
  docs: [...docs].sort((a, b) => a.id.localeCompare(b.id)),
78
- text: docs.map((d) => (0, exports.canonicalRequirementDocument)(d, reqId)).join('\n'),
136
+ // Review round 3: titles and sections only — the vector-cache text's `id:`/`lineage:`/`status:`
137
+ // header let "REQ 742", "the 742 rows", "spec" or "status" score (the cache text is unchanged).
138
+ text: docs.map(scoringText).join('\n'),
79
139
  })).sort((a, b) => a.reqId.localeCompare(b.reqId));
80
140
  const lexical = bm25(promptTerms, documents.map((d) => d.text));
81
141
  const semantic = new Map();
@@ -88,7 +148,8 @@ function triageRequirements(input) {
88
148
  }
89
149
  const allCandidates = documents.map((row, i) => {
90
150
  const semanticScore = semantic.get(row.reqId);
91
- if (lexical[i] <= 0 && semanticScore === undefined)
151
+ const cited = citedLineages.has(row.reqId);
152
+ if (lexical[i] <= 0 && semanticScore === undefined && !cited)
92
153
  return null;
93
154
  const textLower = row.text.toLowerCase();
94
155
  const contentTerms = promptTerms.filter((term) => textLower.includes(term));
@@ -96,6 +157,7 @@ function triageRequirements(input) {
96
157
  const approved = row.docs.length === 4 && row.docs.every((d) => d.status === 'approved');
97
158
  const anchors = [...new Set(operational.implementationAnchors ?? [])].sort();
98
159
  const reasons = [
160
+ ...(cited ? ['cited'] : []),
99
161
  ...(lexical[i] > 0 ? ['bm25'] : []),
100
162
  ...(semanticScore !== undefined ? ['semantic-candidate'] : []),
101
163
  ...(contentTerms.length > 0 ? ['content-supported'] : ['content-unsupported']),
@@ -108,11 +170,14 @@ function triageRequirements(input) {
108
170
  ...(semanticScore !== undefined ? { semanticScore } : {}), contentTerms, approved,
109
171
  implementationAnchors: anchors, freshGreenTests: operational.freshGreenTests === true, reasons };
110
172
  }).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));
173
+ // @implements A-SPEC-713.1 — cited, then the semantic channel where the lineage has a vector, then
174
+ // BM25. `max(BM25, cosine)` compared two scales: cosine counted only when BM25 was zero, while on
175
+ // the replay the semantic top was right 2–2.5× as often as the lexical top when they disagreed.
176
+ // With no vector anywhere (a lexical-only run) this is the lexical order it always was.
177
+ .sort((a, b) => rankCompare(a, b, citedLineages));
113
178
  const candidates = allCandidates.slice(0, rankLimit(input.topK));
114
179
  const semanticInadequate = input.semantic !== undefined
115
- && input.semantic.state !== 'covered' && input.semantic.state !== 'not-adopted';
180
+ && input.semantic.state !== 'covered' && input.semantic.state !== 'partial' && input.semantic.state !== 'not-adopted';
116
181
  const graphInadequate = input.graph !== undefined && input.graph.state !== 'current';
117
182
  if (graphInadequate)
118
183
  return { verdict: 'ambiguous', candidates, reasons: ['graph-coverage-inadequate'], uncertainty: ['graph-coverage-inadequate'] };
@@ -121,11 +186,47 @@ function triageRequirements(input) {
121
186
  if (allCandidates.length === 0)
122
187
  return { verdict: 'new', candidates, reasons: ['semantic-coverage-not-required-for-bm25-baseline'], uncertainty: ['semantic-coverage-not-required-for-bm25-baseline'] };
123
188
  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')) {
189
+ // @implements A-SPEC-713.1 — ties are judged on scores alone, whatever is cited, and a lineage with
190
+ // no vector ties on the semantic side (a coverage gap is not evidence against it). Checked first: a
191
+ // tie is the more specific explanation for an ambiguous answer.
192
+ const tied = allCandidates.filter((c) => c.lexicalScore === top.lexicalScore
193
+ && (c.semanticScore === undefined || top.semanticScore === undefined || c.semanticScore === top.semanticScore));
194
+ // @implements A-SPEC-713.1 — a confident verdict needs two channels on the same lineage. Replay:
195
+ // agreement → right 0.46–0.79; disagreement → the lexical top right 0.12–0.16; every gold-new case
196
+ // disagreed, and an existing-change verdict refuses a new REQ at intake. A channel names a lineage
197
+ // only when its top is unique (and, lexically, above zero). A citation only ORDERS (review round 1:
198
+ // "unlike REQ-2", an id in a URL or `S-1` in prose are mentions, not evidence): it counts only when it
199
+ // is the single cited lineage and a channel also tops it.
200
+ let agreementReason = null;
201
+ if (tied.length <= 1) {
202
+ const uniqueTop = (list, score) => {
203
+ const sorted = [...list].sort((a, b) => score(b) - score(a));
204
+ if (sorted.length === 0 || (sorted.length > 1 && score(sorted[0]) === score(sorted[1])))
205
+ return null;
206
+ return sorted[0];
207
+ };
208
+ // Round 4: a term every lineage contains cannot tell lineages apart — the lexical channel names a
209
+ // lineage only through at least one term that some lineage lacks.
210
+ // With a single lineage there is nothing to tell apart, so the rule does not apply.
211
+ const everywhere = new Set(documents.length < 2 ? [] : promptTerms.filter((term) => documents.every((d) => d.text.toLowerCase().includes(term))));
212
+ const lexicalTop = uniqueTop(allCandidates.filter((c) => c.lexicalScore > 0 && c.contentTerms.some((t) => !everywhere.has(t))), (c) => c.lexicalScore);
213
+ const withVector = allCandidates.filter((c) => c.semanticScore !== undefined);
214
+ const semanticTop = uniqueTop(withVector, (c) => c.semanticScore);
215
+ // Round 3: a citation never counts toward agreement — "(unrelated to REQ-1)" plus one channel on
216
+ // REQ-1 decided REQ-1. Both channels (or, lexical-only, the lexical one) must name a lineage, and it
217
+ // must be the first-ranked one.
218
+ const agreed = withVector.length > 0
219
+ ? (lexicalTop !== null && semanticTop !== null && lexicalTop.reqId === semanticTop.reqId ? lexicalTop.reqId : null)
220
+ : (lexicalTop?.reqId ?? null);
221
+ if (agreed === null)
222
+ agreementReason = withVector.length > 0 || !citedLineages.has(top.reqId) ? 'channels-disagree' : 'citation-unbacked';
223
+ else if (agreed !== top.reqId)
224
+ agreementReason = 'citation-unbacked';
225
+ }
226
+ if (tied.length > 1 || agreementReason !== null || top.contentTerms.length === 0 || top.reasons.includes('contradictory-evidence')) {
127
227
  const uncertainty = [
128
228
  ...(tied.length > 1 ? ['tied-candidates'] : []),
229
+ ...(agreementReason !== null ? [agreementReason] : []),
129
230
  ...(top.contentTerms.length === 0 ? ['candidate-content-unsupported'] : []),
130
231
  ...(top.reasons.includes('contradictory-evidence') ? ['contradictory-evidence'] : []),
131
232
  ];
@@ -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
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.31.1",
4
+ "version": "0.32.0",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",