@holmes-lab/holmes-kit 0.27.0 → 0.29.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 (62) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +21 -17
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-command.d.ts +9 -0
  5. package/dist/holmes/cli/agents-guidance-command.js +61 -0
  6. package/dist/holmes/cli/agents-guidance-file.d.ts +7 -0
  7. package/dist/holmes/cli/agents-guidance-file.js +86 -0
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +10 -0
  9. package/dist/holmes/cli/agents-guidance-history.js +35 -0
  10. package/dist/holmes/cli/agents-guidance-plan.d.ts +11 -0
  11. package/dist/holmes/cli/agents-guidance-plan.js +81 -0
  12. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  13. package/dist/holmes/cli/agents-guidance.js +40 -0
  14. package/dist/holmes/cli/agents.d.ts +3 -19
  15. package/dist/holmes/cli/agents.js +12 -108
  16. package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
  17. package/dist/holmes/cli/doctor-guidance.js +61 -0
  18. package/dist/holmes/cli/doctor.d.ts +2 -0
  19. package/dist/holmes/cli/doctor.js +29 -1
  20. package/dist/holmes/cli/index.js +31 -3
  21. package/dist/holmes/cli/init.js +32 -5
  22. package/dist/holmes/cli/upgrade.js +23 -26
  23. package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
  24. package/dist/holmes/cli/worktree-readiness.js +81 -0
  25. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  26. package/dist/holmes/cpg/ast-mutation.js +4 -2
  27. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  28. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  29. package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
  30. package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
  31. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
  32. package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
  33. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  34. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  35. package/dist/holmes/mcp/handlers.d.ts +157 -46
  36. package/dist/holmes/mcp/handlers.js +16 -3
  37. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
  38. package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
  39. package/dist/holmes/mcp/tool-schemas.js +19 -1
  40. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  41. package/dist/holmes/project/workspace-checkout.js +74 -0
  42. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  43. package/dist/holmes/project/workspace-preflight.js +99 -0
  44. package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
  45. package/dist/holmes/review/condition-hunk-replay.js +112 -0
  46. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  47. package/dist/holmes/review/condition-hunk-resolution.js +207 -0
  48. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  49. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  50. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  51. package/dist/holmes/review/requirement-triage.js +143 -0
  52. package/dist/holmes/semantic/local-model.d.ts +3 -3
  53. package/dist/holmes/semantic/local-model.js +10 -12
  54. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  55. package/dist/holmes/semantic/model-cache.js +77 -21
  56. package/dist/holmes/semantic/tier.d.ts +5 -1
  57. package/dist/holmes/semantic/tier.js +7 -6
  58. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  59. package/dist/holmes/semantic/vector-coverage.js +37 -0
  60. package/docs/install-guide.md +73 -24
  61. package/package.json +1 -1
  62. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
@@ -0,0 +1,207 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.parseUnifiedZeroDiff = parseUnifiedZeroDiff;
4
+ exports.classifyConditionDirection = classifyConditionDirection;
5
+ exports.resolveConditionHunks = resolveConditionHunks;
6
+ exports.resolveConditionHunksFromSources = resolveConditionHunksFromSources;
7
+ // @implements A-SPEC-661
8
+ /** Pure, advisory-only resolution from a supplied zero-context diff to declared source spans. */
9
+ const ast_store_1 = require("../cpg/foundation/ast-store");
10
+ const cfg_1 = require("../cpg/foundation/cfg");
11
+ const ast_mutation_1 = require("../cpg/ast-mutation");
12
+ const normalPath = (raw) => raw.replace(/\\/g, '/').replace(/^[ab]\//, '');
13
+ const contains = (start, end, lineStart, lineEnd) => start <= lineStart && end >= lineEnd;
14
+ const overlaps = (start, end, lineStart, lineEnd) => start <= lineEnd && end >= lineStart;
15
+ /** Parse file headers, @@ ranges, and exact changed lines; body text never widens the changed region. */
16
+ function parseUnifiedZeroDiff(diff) {
17
+ if (typeof diff !== 'string')
18
+ return [];
19
+ let file = null;
20
+ let current = null;
21
+ const hunks = [];
22
+ for (const line of diff.split(/\r?\n/)) {
23
+ if (line.startsWith('+++ ')) {
24
+ const next = line.slice(4).trim();
25
+ file = next === '/dev/null' ? null : normalPath(next);
26
+ current = null;
27
+ continue;
28
+ }
29
+ const match = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
30
+ if (match && file !== null) {
31
+ const start = Number(match[2]), added = match[3] === undefined ? 1 : Number(match[3]);
32
+ current = { file, startLine: start, endLine: start + Math.max(added, 1) - 1, ...(added === 0 ? { deletionOnly: true } : {}),
33
+ removedLines: [], addedLines: [] };
34
+ hunks.push(current);
35
+ continue;
36
+ }
37
+ if (current === null)
38
+ continue;
39
+ if (line.startsWith('-') && !line.startsWith('--- '))
40
+ current.removedLines.push(line.slice(1));
41
+ if (line.startsWith('+') && !line.startsWith('+++ '))
42
+ current.addedLines.push(line.slice(1));
43
+ }
44
+ return hunks;
45
+ }
46
+ const compact = (value) => value.replace(/\s+/g, ' ').trim();
47
+ const count = (value, token) => value.split(token).length - 1;
48
+ /** Remove only parentheses which enclose the whole expression, preserving all inner grouping. */
49
+ function unwrapOuterParens(value) {
50
+ let text = compact(value);
51
+ while (text.startsWith('(') && text.endsWith(')')) {
52
+ let depth = 0;
53
+ let encloses = true;
54
+ for (let index = 0; index < text.length; index++) {
55
+ if (text[index] === '(')
56
+ depth++;
57
+ if (text[index] === ')')
58
+ depth--;
59
+ if (depth === 0 && index < text.length - 1) {
60
+ encloses = false;
61
+ break;
62
+ }
63
+ }
64
+ if (!encloses || depth !== 0)
65
+ break;
66
+ text = compact(text.slice(1, -1));
67
+ }
68
+ return text;
69
+ }
70
+ /** Extract a control-flow predicate from one changed line without attempting expression parsing. */
71
+ function predicateInChangedLine(line) {
72
+ const keyword = /\b(?:if|while|switch)\s*\(/.exec(line);
73
+ if (keyword === null)
74
+ return undefined;
75
+ const open = keyword.index + keyword[0].lastIndexOf('(');
76
+ let depth = 0;
77
+ for (let index = open; index < line.length; index++) {
78
+ if (line[index] === '(')
79
+ depth++;
80
+ if (line[index] === ')')
81
+ depth--;
82
+ if (depth === 0)
83
+ return line.slice(open + 1, index);
84
+ }
85
+ return undefined;
86
+ }
87
+ /**
88
+ * Match a changed after-predicate to the CFG span, then take only the same-position removed
89
+ * predicate. Multiple matches, line-count changes, and non-control statements deliberately stay
90
+ * unknown: a zero-context diff cannot establish their correspondence.
91
+ */
92
+ function beforeConditionFromHunk(hunk, afterCondition) {
93
+ if (afterCondition === undefined || hunk.addedLines === undefined || hunk.removedLines === undefined
94
+ || hunk.addedLines.length !== hunk.removedLines.length)
95
+ return undefined;
96
+ const expected = unwrapOuterParens(afterCondition);
97
+ const matches = hunk.addedLines.map(predicateInChangedLine)
98
+ .map((predicate, index) => ({ predicate, index }))
99
+ .filter(({ predicate }) => predicate !== undefined && unwrapOuterParens(predicate) === expected);
100
+ if (matches.length !== 1)
101
+ return undefined;
102
+ return predicateInChangedLine(hunk.removedLines[matches[0].index]);
103
+ }
104
+ /** Classifies only syntactic changes with a local, monotonic meaning; all other changes are unknown. */
105
+ function classifyConditionDirection(before, after) {
106
+ if (typeof before !== 'string' || typeof after !== 'string')
107
+ return 'unknown';
108
+ const left = unwrapOuterParens(before), right = unwrapOuterParens(after);
109
+ if (left === '' || right === '' || left === right)
110
+ return 'unknown';
111
+ const logicalWidening = ast_mutation_1.MUTATION_MAP.logical['&&']?.includes('||') === true;
112
+ const unaryRemoval = ast_mutation_1.MUTATION_MAP.unary['!']?.includes('EMPTY') === true;
113
+ if (logicalWidening && (count(right, '||') > count(left, '||') || count(right, '&&') < count(left, '&&')))
114
+ return 'relaxed';
115
+ if (unaryRemoval && count(right, '!') < count(left, '!'))
116
+ return 'relaxed';
117
+ const relation = /^(.+?)\s*(<=|<|>=|>)\s*(-?\d+(?:\.\d+)?)$/.exec(left);
118
+ const next = /^(.+?)\s*(<=|<|>=|>)\s*(-?\d+(?:\.\d+)?)$/.exec(right);
119
+ if (!relation || !next || compact(relation[1]) !== compact(next[1]))
120
+ return 'unknown';
121
+ const oldValue = Number(relation[3]), newValue = Number(next[3]);
122
+ // The mutation generator stores forward replacement choices only. Direction comparison needs
123
+ // both sides of that vocabulary (for example, `<=` → `<`) plus a same-operator threshold move.
124
+ const relationMutation = relation[2] === next[2]
125
+ || ast_mutation_1.MUTATION_MAP.relational[relation[2]]?.includes(next[2]) === true
126
+ || ast_mutation_1.MUTATION_MAP.relational[next[2]]?.includes(relation[2]) === true;
127
+ if (!relationMutation)
128
+ return 'unknown';
129
+ if ((relation[2] === '<' && next[2] === '<=') || (relation[2] === '>' && next[2] === '>='))
130
+ return 'relaxed';
131
+ if ((relation[2] === '<=' && next[2] === '<') || (relation[2] === '>=' && next[2] === '>'))
132
+ return 'narrowed';
133
+ if (['<', '<='].includes(relation[2]) && ['<', '<='].includes(next[2]))
134
+ return newValue > oldValue ? 'relaxed' : newValue < oldValue ? 'narrowed' : 'unknown';
135
+ if (['>', '>='].includes(relation[2]) && ['>', '>='].includes(next[2]))
136
+ return newValue < oldValue ? 'relaxed' : newValue > oldValue ? 'narrowed' : 'unknown';
137
+ return 'unknown';
138
+ }
139
+ /** Intersects hunk → narrowest symbol → branch span, retaining ties instead of inventing a winner. */
140
+ function resolveConditionHunks(input) {
141
+ const supported = input.language === undefined || ['typescript', 'tsx', 'javascript', 'jsx'].includes(input.language);
142
+ return input.hunks.map((hunk) => {
143
+ if (!supported)
144
+ return { file: hunk.file, hunk, direction: 'unknown', state: 'unavailable', reason: 'unsupported-language' };
145
+ if (hunk.deletionOnly)
146
+ return { file: hunk.file, hunk, direction: 'unknown', state: 'unavailable', reason: 'deletion-only-hunk' };
147
+ const enclosing = input.symbols.filter((symbol) => normalPath(symbol.file) === normalPath(hunk.file)
148
+ && contains(symbol.startLine, symbol.endLine, hunk.startLine, hunk.endLine));
149
+ if (enclosing.length === 0)
150
+ return { file: hunk.file, hunk, direction: 'unknown', state: 'unavailable', reason: 'no-containing-symbol' };
151
+ const width = Math.min(...enclosing.map((symbol) => symbol.endLine - symbol.startLine));
152
+ const symbols = enclosing.filter((symbol) => symbol.endLine - symbol.startLine === width);
153
+ if (symbols.length !== 1)
154
+ return { file: hunk.file, hunk, direction: 'unknown', state: 'ambiguous', reason: 'tied-symbols' };
155
+ const symbol = symbols[0];
156
+ const matchingBranches = input.branches.filter((branch) => normalPath(branch.file) === normalPath(hunk.file)
157
+ && contains(symbol.startLine, symbol.endLine, branch.startLine, branch.endLine)
158
+ && overlaps(branch.startLine, branch.endLine, hunk.startLine, hunk.endLine))
159
+ .sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine
160
+ || (a.branchLabel === 'true' ? -1 : b.branchLabel === 'true' ? 1 : a.branchLabel.localeCompare(b.branchLabel)));
161
+ // A single predicate normally emits both true and false CFG edges. Those two edges share one
162
+ // source span and are not two competing hunk locations; preserve one stable representative
163
+ // while distinct source spans still remain an explicit ambiguity.
164
+ const byPredicate = new Map();
165
+ for (const branch of matchingBranches) {
166
+ const key = `${branch.startLine}:${branch.endLine}:${branch.conditionText ?? ''}:${branch.astKind ?? ''}`;
167
+ if (!byPredicate.has(key))
168
+ byPredicate.set(key, branch);
169
+ }
170
+ const branches = [...byPredicate.values()];
171
+ if (branches.length === 0)
172
+ return { file: hunk.file, hunk, symbol: symbol.name, direction: 'unknown', state: 'unavailable', reason: 'no-condition-span' };
173
+ if (branches.length !== 1)
174
+ return { file: hunk.file, hunk, symbol: symbol.name, direction: 'unknown', state: 'ambiguous', reason: 'tied-condition-spans', candidates: branches };
175
+ const selected = branches[0];
176
+ const beforeConditionText = selected.beforeConditionText ?? beforeConditionFromHunk(hunk, selected.conditionText);
177
+ const branch = beforeConditionText === undefined ? selected : { ...selected, beforeConditionText };
178
+ return { file: hunk.file, hunk, symbol: symbol.name, branch, conditionText: branch.conditionText,
179
+ direction: classifyConditionDirection(beforeConditionText, branch.conditionText), state: 'resolved' };
180
+ });
181
+ }
182
+ const lineAt = (source, offset) => source.slice(0, offset).split('\n').length;
183
+ /**
184
+ * The explicit heavy advisory path: parse only caller-supplied TS/JS source, derive CFG predicate
185
+ * spans, and feed the same conservative resolver. It is intentionally separate from CpgScanner's
186
+ * synchronous hot path and cannot alter changedFiles, a graph, a gate, or a cache.
187
+ */
188
+ async function resolveConditionHunksFromSources(input) {
189
+ const branches = [];
190
+ for (const item of input.sources) {
191
+ const ast = await (0, ast_store_1.parseAst)(item.source, item.file);
192
+ if (ast === null || ast.errorCount > 0 || !['typescript', 'tsx'].includes(ast.lang))
193
+ continue;
194
+ for (const fn of (0, cfg_1.functionsIn)(ast)) {
195
+ const cfg = (0, cfg_1.cfgOf)(ast, fn, item.source);
196
+ if ('unsupported' in cfg)
197
+ continue;
198
+ for (const branch of cfg.conditionBranches ?? []) {
199
+ if (branch.startOffset === undefined || branch.endOffset === undefined)
200
+ continue;
201
+ branches.push({ file: item.file, startLine: lineAt(item.source, branch.startOffset), endLine: lineAt(item.source, branch.endOffset),
202
+ conditionText: branch.conditionText, branchLabel: branch.branchLabel, astKind: branch.astKind });
203
+ }
204
+ }
205
+ }
206
+ return resolveConditionHunks({ hunks: parseUnifiedZeroDiff(input.diff), symbols: input.symbols, branches });
207
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Frozen, blind evaluation protocol for requirement triage. The exported input intentionally
3
+ * omits the analyst judgement; scoring joins it only after a prediction has been recorded.
4
+ */
5
+ import type { RequirementVerdict } from './requirement-triage';
6
+ export interface RequirementTriagePredictionInput {
7
+ id: string;
8
+ prompt: string;
9
+ }
10
+ export interface RequirementTriagePrediction {
11
+ caseId: string;
12
+ verdict: RequirementVerdict;
13
+ candidates: Array<{
14
+ reqId?: string;
15
+ evidenceComplete?: boolean;
16
+ }>;
17
+ elapsedMs: number;
18
+ }
19
+ /** Preregistered protocol: agents receive only this frozen projection before predicting. */
20
+ export declare function frozenRequirementTriageCases(): RequirementTriagePredictionInput[];
21
+ /** Public preregistration; deliberately contains no expected verdict or analyst choice. */
22
+ export declare function requirementTriageHumanModelProtocol(): {
23
+ schema: 'requirement-triage-human-model/1';
24
+ corpusId: 'requirement-triage-blind-v1';
25
+ caseCount: number;
26
+ releaseGate: false;
27
+ metrics: readonly string[];
28
+ analystProcedure: readonly string[];
29
+ };
30
+ export interface RequirementTriageBenchmarkReport {
31
+ sampleSize: number;
32
+ judged: number;
33
+ retrievalCoverage: number | null;
34
+ humanChoiceAgreement: number | null;
35
+ falseReuse: number | null;
36
+ falseNew: number | null;
37
+ evidenceCompleteness: number | null;
38
+ ambiguityPreservation: number | null;
39
+ elapsedMs: {
40
+ median: number | null;
41
+ };
42
+ limitations: string[];
43
+ }
44
+ /** Scores a completed blind run without turning the human comparison into a release gate. */
45
+ export declare function scoreRequirementTriagePredictions(predictions: readonly RequirementTriagePrediction[]): RequirementTriageBenchmarkReport;
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.frozenRequirementTriageCases = frozenRequirementTriageCases;
4
+ exports.requirementTriageHumanModelProtocol = requirementTriageHumanModelProtocol;
5
+ exports.scoreRequirementTriagePredictions = scoreRequirementTriagePredictions;
6
+ const CASES = Object.freeze([
7
+ { input: { id: 'rt-001', prompt: 'existing approved read-only lifecycle advisory' }, expectedVerdict: 'fulfilled', humanChoice: 'REQ-713' },
8
+ { input: { id: 'rt-002', prompt: 'change evidence persistence digest handling' }, expectedVerdict: 'existing-change', humanChoice: 'REQ-713' },
9
+ { input: { id: 'rt-003', prompt: 'a distinct governed requirement with no supporting lineage' }, expectedVerdict: 'new', humanChoice: null },
10
+ { input: { id: 'rt-004', prompt: 'overlapping but contradictory requirements' }, expectedVerdict: 'ambiguous', humanChoice: null },
11
+ { input: { id: 'rt-005', prompt: 'verified local semantic model preparation already works' }, expectedVerdict: 'fulfilled', humanChoice: 'REQ-712' },
12
+ { input: { id: 'rt-006', prompt: 'retry local semantic preparation after a corrupt cache' }, expectedVerdict: 'existing-change', humanChoice: 'REQ-712' },
13
+ { input: { id: 'rt-007', prompt: 'classify a condition hunk through its CFG predicate' }, expectedVerdict: 'existing-change', humanChoice: 'REQ-661' },
14
+ { input: { id: 'rt-008', prompt: 'govern a previously unseen product capability' }, expectedVerdict: 'new', humanChoice: null },
15
+ { input: { id: 'rt-009', prompt: 'two approved intents conflict over the same behavior' }, expectedVerdict: 'ambiguous', humanChoice: null },
16
+ { input: { id: 'rt-010', prompt: 'the workspace binding diagnostic is already fulfilled' }, expectedVerdict: 'fulfilled', humanChoice: 'REQ-703' },
17
+ { input: { id: 'rt-011', prompt: 'change the coexistence guidance for an existing harness workflow' }, expectedVerdict: 'existing-change', humanChoice: 'REQ-706' },
18
+ { input: { id: 'rt-012', prompt: 'introduce an unrelated governed data-retention requirement' }, expectedVerdict: 'new', humanChoice: null },
19
+ ]);
20
+ /** Preregistered protocol: agents receive only this frozen projection before predicting. */
21
+ function frozenRequirementTriageCases() {
22
+ return CASES.map((entry) => ({ ...entry.input }));
23
+ }
24
+ /** Public preregistration; deliberately contains no expected verdict or analyst choice. */
25
+ function requirementTriageHumanModelProtocol() {
26
+ return Object.freeze({
27
+ schema: 'requirement-triage-human-model/1', corpusId: 'requirement-triage-blind-v1',
28
+ caseCount: CASES.length, releaseGate: false,
29
+ metrics: Object.freeze(['retrievalCoverage', 'humanChoiceAgreement', 'falseReuse', 'falseNew', 'evidenceCompleteness', 'ambiguityPreservation', 'elapsedMs']),
30
+ analystProcedure: Object.freeze([
31
+ 'Record a triage prediction from the frozen prompt projection before opening the answer key.',
32
+ 'A human analyst independently records a lifecycle verdict and preferred existing requirement, if any.',
33
+ 'Join prediction, analyst record, and answer key only after both records are immutable.',
34
+ 'Report disagreements and null metrics as gaps; do not use them as a release or edit-gate decision.',
35
+ ]),
36
+ });
37
+ }
38
+ const ratio = (n, d) => d === 0 ? null : n / d;
39
+ const median = (values) => {
40
+ if (values.length === 0)
41
+ return null;
42
+ const sorted = [...values].sort((a, b) => a - b), mid = Math.floor(sorted.length / 2);
43
+ return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
44
+ };
45
+ /** Scores a completed blind run without turning the human comparison into a release gate. */
46
+ function scoreRequirementTriagePredictions(predictions) {
47
+ const byId = new Map(predictions.map((prediction) => [prediction.caseId, prediction]));
48
+ const judged = CASES.flatMap((entry) => {
49
+ const prediction = byId.get(entry.input.id);
50
+ return prediction ? [{ entry, prediction }] : [];
51
+ });
52
+ const expectedReuse = judged.filter(({ entry }) => entry.expectedVerdict === 'fulfilled' || entry.expectedVerdict === 'existing-change');
53
+ const expectedNew = judged.filter(({ entry }) => entry.expectedVerdict === 'new');
54
+ const expectedAmbiguous = judged.filter(({ entry }) => entry.expectedVerdict === 'ambiguous');
55
+ const withHumanChoice = judged.filter(({ entry }) => entry.humanChoice !== null);
56
+ return {
57
+ sampleSize: predictions.length,
58
+ judged: judged.length,
59
+ retrievalCoverage: ratio(judged.filter(({ entry, prediction }) => entry.humanChoice === null || prediction.candidates.some((candidate) => candidate.reqId === entry.humanChoice)).length, judged.length),
60
+ humanChoiceAgreement: ratio(withHumanChoice.filter(({ entry, prediction }) => prediction.candidates[0]?.reqId === entry.humanChoice).length, withHumanChoice.length),
61
+ falseReuse: ratio(expectedNew.filter(({ prediction }) => prediction.verdict === 'fulfilled' || prediction.verdict === 'existing-change').length, expectedNew.length),
62
+ falseNew: ratio(expectedReuse.filter(({ prediction }) => prediction.verdict === 'new').length, expectedReuse.length),
63
+ evidenceCompleteness: ratio(judged.filter(({ prediction }) => prediction.candidates.every((candidate) => candidate.evidenceComplete === true)).length, judged.length),
64
+ ambiguityPreservation: ratio(expectedAmbiguous.filter(({ prediction }) => prediction.verdict === 'ambiguous').length, expectedAmbiguous.length),
65
+ elapsedMs: { median: median(judged.map(({ prediction }) => prediction.elapsedMs).filter(Number.isFinite)) },
66
+ limitations: [
67
+ 'Blind inputs omit expected verdict and human choice until after prediction recording.',
68
+ 'This frozen corpus is a comparison and gap-reporting instrument, not a human-superiority or release-gate claim.',
69
+ 'Impact-analysis benchmark results are excluded from requirement-triage metrics.',
70
+ ],
71
+ };
72
+ }
@@ -0,0 +1,61 @@
1
+ import { canonicalRequirementDocument as canonicalRequirementDocumentText } from '../semantic/vector-coverage';
2
+ export type RequirementVerdict = 'fulfilled' | 'existing-change' | 'new' | 'ambiguous';
3
+ export type RequirementDocumentKind = 'REQ' | 'H-SPEC' | 'A-SPEC' | 'T-SPEC';
4
+ export interface RequirementDocument {
5
+ id: string;
6
+ type: RequirementDocumentKind;
7
+ title: string;
8
+ status: string;
9
+ dependsOn?: readonly string[];
10
+ sections?: Readonly<Record<string, string>>;
11
+ }
12
+ export interface RequirementLineageEvidence {
13
+ implementationAnchors?: readonly string[];
14
+ freshGreenTests?: boolean;
15
+ contradictory?: boolean;
16
+ }
17
+ export interface RequirementSemanticCandidate {
18
+ id: string;
19
+ score: number;
20
+ }
21
+ export interface RequirementTriageInput {
22
+ prompt: string;
23
+ documents: readonly RequirementDocument[];
24
+ evidence?: Readonly<Record<string, RequirementLineageEvidence>>;
25
+ semanticCandidates?: readonly RequirementSemanticCandidate[];
26
+ /** Omit for the BM25-only comparison arm; configured cold/unavailable coverage is disclosed. */
27
+ semantic?: {
28
+ state: 'covered' | 'cold' | 'unavailable' | 'not-adopted';
29
+ covered: number;
30
+ total: number;
31
+ };
32
+ /** The read-only published RTM graph lane. Any unavailable/stale state is disclosed as ambiguity. */
33
+ graph?: {
34
+ state: 'current' | 'stale' | 'unverified' | 'absent' | 'unreadable' | 'empty';
35
+ };
36
+ topK?: number;
37
+ }
38
+ export interface RequirementTriageCandidate {
39
+ reqId: string;
40
+ documents: RequirementDocument[];
41
+ lexicalScore: number;
42
+ semanticScore?: number;
43
+ contentTerms: string[];
44
+ approved: boolean;
45
+ implementationAnchors: string[];
46
+ freshGreenTests: boolean;
47
+ reasons: string[];
48
+ }
49
+ export interface RequirementTriageResult {
50
+ verdict: RequirementVerdict;
51
+ candidates: RequirementTriageCandidate[];
52
+ /** Stable top-level explanation, duplicated from uncertainty for clients that render reasons. */
53
+ reasons: string[];
54
+ uncertainty: string[];
55
+ }
56
+ /** Re-exported for triage callers; the cache contract belongs to vector coverage. */
57
+ export declare const canonicalRequirementDocument: typeof canonicalRequirementDocumentText;
58
+ /**
59
+ * Retrieval only admits candidates. The verdict requires independent content and operational facts.
60
+ */
61
+ export declare function triageRequirements(input: RequirementTriageInput): RequirementTriageResult;
@@ -0,0 +1,143 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.canonicalRequirementDocument = void 0;
4
+ exports.triageRequirements = triageRequirements;
5
+ // @implements A-SPEC-713
6
+ /** Pure, conservative lifecycle triage over governed requirement documents. */
7
+ const semantic_retrieval_1 = require("./semantic-retrieval");
8
+ const vector_coverage_1 = require("../semantic/vector-coverage");
9
+ /** Re-exported for triage callers; the cache contract belongs to vector coverage. */
10
+ exports.canonicalRequirementDocument = vector_coverage_1.canonicalRequirementDocument;
11
+ function rankLimit(value) {
12
+ if (!Number.isInteger(value))
13
+ return 10;
14
+ return Math.min(20, Math.max(1, value));
15
+ }
16
+ function rootOf(id, byId) {
17
+ const seen = new Set();
18
+ let current = byId.get(id);
19
+ while (current) {
20
+ if (seen.has(current.id))
21
+ return null;
22
+ seen.add(current.id);
23
+ if (current.type === 'REQ')
24
+ return current.id;
25
+ const parent = (current.dependsOn ?? []).map((p) => byId.get(p)).find((p) => p !== undefined);
26
+ if (!parent)
27
+ return null;
28
+ current = parent;
29
+ }
30
+ return null;
31
+ }
32
+ function bm25(query, docs) {
33
+ const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedTerms)(text));
34
+ const avg = terms.reduce((n, row) => n + row.length, 0) / (terms.length || 1);
35
+ const df = new Map();
36
+ for (const row of terms)
37
+ for (const term of new Set(row))
38
+ df.set(term, (df.get(term) ?? 0) + 1);
39
+ return terms.map((row) => {
40
+ const frequencies = new Map();
41
+ for (const term of row)
42
+ frequencies.set(term, (frequencies.get(term) ?? 0) + 1);
43
+ return query.reduce((score, term) => {
44
+ const count = frequencies.get(term) ?? 0;
45
+ if (count === 0)
46
+ return score;
47
+ const n = df.get(term) ?? 0;
48
+ const idf = Math.max(Math.log(1 + (terms.length - n + 0.5) / (n + 0.5)), 0);
49
+ return score + idf * (count * 2.2) / (count + 1.2 * (0.25 + 0.75 * row.length / avg));
50
+ }, 0);
51
+ });
52
+ }
53
+ /**
54
+ * Retrieval only admits candidates. The verdict requires independent content and operational facts.
55
+ */
56
+ 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'] };
60
+ const governed = input.documents.filter((d) => d.type === 'REQ' || d.type === 'H-SPEC' || d.type === 'A-SPEC' || d.type === 'T-SPEC');
61
+ if (governed.length === 0)
62
+ return { verdict: 'ambiguous', candidates: [], reasons: ['empty-or-unreadable-corpus'], uncertainty: ['empty-or-unreadable-corpus'] };
63
+ const byId = new Map(governed.map((d) => [d.id, d]));
64
+ const lineages = new Map();
65
+ for (const doc of governed) {
66
+ const root = rootOf(doc.id, byId);
67
+ if (root === null)
68
+ continue;
69
+ const bucket = lineages.get(root) ?? [];
70
+ bucket.push(doc);
71
+ lineages.set(root, bucket);
72
+ }
73
+ if (lineages.size === 0)
74
+ return { verdict: 'ambiguous', candidates: [], reasons: ['no-readable-lineage'], uncertainty: ['no-readable-lineage'] };
75
+ const documents = [...lineages.entries()].map(([reqId, docs]) => ({
76
+ reqId,
77
+ docs: [...docs].sort((a, b) => a.id.localeCompare(b.id)),
78
+ text: docs.map((d) => (0, exports.canonicalRequirementDocument)(d, reqId)).join('\n'),
79
+ })).sort((a, b) => a.reqId.localeCompare(b.reqId));
80
+ const lexical = bm25(promptTerms, documents.map((d) => d.text));
81
+ const semantic = new Map();
82
+ for (const c of input.semanticCandidates ?? []) {
83
+ if (!Number.isFinite(c.score) || c.score <= 0)
84
+ continue;
85
+ const root = rootOf(c.id, byId);
86
+ if (root !== null)
87
+ semantic.set(root, Math.max(semantic.get(root) ?? 0, c.score));
88
+ }
89
+ const allCandidates = documents.map((row, i) => {
90
+ const semanticScore = semantic.get(row.reqId);
91
+ if (lexical[i] <= 0 && semanticScore === undefined)
92
+ return null;
93
+ const textLower = row.text.toLowerCase();
94
+ const contentTerms = promptTerms.filter((term) => textLower.includes(term));
95
+ const operational = input.evidence?.[row.reqId] ?? {};
96
+ const approved = row.docs.length === 4 && row.docs.every((d) => d.status === 'approved');
97
+ const anchors = [...new Set(operational.implementationAnchors ?? [])].sort();
98
+ const reasons = [
99
+ ...(lexical[i] > 0 ? ['bm25'] : []),
100
+ ...(semanticScore !== undefined ? ['semantic-candidate'] : []),
101
+ ...(contentTerms.length > 0 ? ['content-supported'] : ['content-unsupported']),
102
+ ...(approved ? ['approved-lineage'] : ['lineage-not-approved']),
103
+ ...(anchors.length > 0 ? ['implementation-anchors'] : ['implementation-anchors-absent']),
104
+ ...(operational.freshGreenTests === true ? ['fresh-green-execution'] : ['fresh-green-execution-absent']),
105
+ ...(operational.contradictory === true ? ['contradictory-evidence'] : []),
106
+ ];
107
+ return { reqId: row.reqId, documents: row.docs, lexicalScore: lexical[i],
108
+ ...(semanticScore !== undefined ? { semanticScore } : {}), contentTerms, approved,
109
+ implementationAnchors: anchors, freshGreenTests: operational.freshGreenTests === true, reasons };
110
+ }).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));
113
+ const candidates = allCandidates.slice(0, rankLimit(input.topK));
114
+ const semanticInadequate = input.semantic !== undefined
115
+ && input.semantic.state !== 'covered' && input.semantic.state !== 'not-adopted';
116
+ const graphInadequate = input.graph !== undefined && input.graph.state !== 'current';
117
+ if (graphInadequate)
118
+ return { verdict: 'ambiguous', candidates, reasons: ['graph-coverage-inadequate'], uncertainty: ['graph-coverage-inadequate'] };
119
+ if (semanticInadequate)
120
+ return { verdict: 'ambiguous', candidates, reasons: ['semantic-coverage-inadequate'], uncertainty: ['semantic-coverage-inadequate'] };
121
+ if (allCandidates.length === 0)
122
+ return { verdict: 'new', candidates, reasons: ['semantic-coverage-not-required-for-bm25-baseline'], uncertainty: ['semantic-coverage-not-required-for-bm25-baseline'] };
123
+ 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')) {
127
+ const uncertainty = [
128
+ ...(tied.length > 1 ? ['tied-candidates'] : []),
129
+ ...(top.contentTerms.length === 0 ? ['candidate-content-unsupported'] : []),
130
+ ...(top.reasons.includes('contradictory-evidence') ? ['contradictory-evidence'] : []),
131
+ ];
132
+ return { verdict: 'ambiguous', candidates, reasons: uncertainty, uncertainty };
133
+ }
134
+ if (top.approved && top.implementationAnchors.length > 0 && top.freshGreenTests) {
135
+ return { verdict: 'fulfilled', candidates, reasons: ['approved-lineage', 'implementation-anchors', 'fresh-green-execution'], uncertainty: [] };
136
+ }
137
+ const uncertainty = [
138
+ ...(top.approved ? [] : ['lineage-not-approved']),
139
+ ...(top.implementationAnchors.length > 0 ? [] : ['implementation-anchors-absent']),
140
+ ...(top.freshGreenTests ? [] : ['fresh-green-execution-absent']),
141
+ ];
142
+ return { verdict: 'existing-change', candidates, reasons: ['supported-existing-lineage', ...uncertainty], uncertainty };
143
+ }
@@ -1,7 +1,7 @@
1
1
  import { spawnSync } from 'node:child_process';
2
- import { modelCacheDir, modelCacheReady } from './model-cache';
3
- export { modelCacheDir, modelCacheReady };
4
- export declare const LOCAL_REVISION = "4de13258303883538bd53b696b452bf8099f0858";
2
+ import { LOCAL_REVISION, modelCacheDir, modelCacheReady, readLocalModelReadiness } from './model-cache';
3
+ export { modelCacheDir, modelCacheReady, readLocalModelReadiness };
4
+ export { LOCAL_REVISION };
5
5
  type Pipeline = (text: string, options: {
6
6
  pooling: string;
7
7
  normalize: boolean;
@@ -1,16 +1,17 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.LOCAL_REVISION = exports.modelCacheReady = exports.modelCacheDir = void 0;
3
+ exports.LOCAL_REVISION = exports.readLocalModelReadiness = exports.modelCacheReady = exports.modelCacheDir = void 0;
4
4
  exports.loadLocalPipeline = loadLocalPipeline;
5
5
  exports.verifyLocalModel = verifyLocalModel;
6
6
  exports.runModelSetup = runModelSetup;
7
- // @implements A-SPEC-591
7
+ // @implements A-SPEC-591, A-SPEC-712
8
8
  const node_child_process_1 = require("node:child_process");
9
9
  const tier_1 = require("./tier");
10
10
  const model_cache_1 = require("./model-cache");
11
+ Object.defineProperty(exports, "LOCAL_REVISION", { enumerable: true, get: function () { return model_cache_1.LOCAL_REVISION; } });
11
12
  Object.defineProperty(exports, "modelCacheDir", { enumerable: true, get: function () { return model_cache_1.modelCacheDir; } });
12
13
  Object.defineProperty(exports, "modelCacheReady", { enumerable: true, get: function () { return model_cache_1.modelCacheReady; } });
13
- exports.LOCAL_REVISION = '4de13258303883538bd53b696b452bf8099f0858';
14
+ Object.defineProperty(exports, "readLocalModelReadiness", { enumerable: true, get: function () { return model_cache_1.readLocalModelReadiness; } });
14
15
  // TypeScript's CommonJS transform rewrites import() into require(), which cannot load this ESM
15
16
  // dependency on supported Node 20 versions. Preserve native dynamic import without shell code.
16
17
  const importRuntime = new Function('return import("@xenova/transformers")');
@@ -29,7 +30,7 @@ async function loadLocalPipeline(model = tier_1.LOCAL_MODEL, options = {}) {
29
30
  return existing;
30
31
  const pending = importer().then(runtime => runtime.pipeline('feature-extraction', model, {
31
32
  quantized: true,
32
- revision: model === tier_1.LOCAL_MODEL ? exports.LOCAL_REVISION : 'main',
33
+ revision: model === tier_1.LOCAL_MODEL ? model_cache_1.LOCAL_REVISION : 'main',
33
34
  cache_dir: cacheDir,
34
35
  local_files_only: !options.download,
35
36
  })).catch(error => { cache.delete(key); throw error; });
@@ -45,6 +46,9 @@ async function verifyLocalModel(options = {}) {
45
46
  if (data.length !== 1024 || !Array.from(data).every(Number.isFinite) || Math.abs(norm - 1) > 0.001) {
46
47
  return { ready: false, dimension: data.length, message: 'BGE-M3 produced an invalid embedding. Select a clean HOLMES_MODEL_CACHE and run holmes-kit semantic-setup.' };
47
48
  }
49
+ const receipt = (0, model_cache_1.writeVerifiedModelReceipt)(options.cacheDir ?? (0, model_cache_1.modelCacheDir)());
50
+ if (!receipt.ready)
51
+ return { ready: false, dimension: data.length, message: `BGE-M3 inference passed but ${receipt.recovery}` };
48
52
  return { ready: true, dimension: data.length, message: 'BGE-M3 ready: verified 1024-dimensional normalized local embedding.' };
49
53
  }
50
54
  catch (error) {
@@ -57,19 +61,13 @@ async function verifyLocalModel(options = {}) {
57
61
  /** Isolate setup from the MCP and bound slow downloads/inference; all platforms share this path. */
58
62
  function runModelSetup(options = {}) {
59
63
  const env = options.env ?? process.env;
60
- // @implements A-SPEC-594 — the automatic path does not start a large download the user did not
61
- // ask for. An explicit refusal outranks an opt-in: someone who set SKIP meant it, and reading
62
- // AUTO as permission to override that would silently reverse their decision. The two skips say
63
- // DIFFERENT things, because telling a user "you opted out" when they never did is a lie.
64
+ // @implements A-SPEC-712 — normal package installation prepares the public model by default.
65
+ // Explicit SKIP remains the only automatic opt-out; legacy AUTO is ignored.
64
66
  if (options.automatic) {
65
67
  if (env.HOLMES_SKIP_MODEL_INSTALL === '1') {
66
68
  process.stderr.write('BGE-M3 automatic setup skipped (HOLMES_SKIP_MODEL_INSTALL=1). Run holmes-kit semantic-setup when ready.\n');
67
69
  return 0;
68
70
  }
69
- if (env.HOLMES_AUTO_MODEL_INSTALL !== '1') {
70
- process.stderr.write('BGE-M3 is not prepared automatically. Run `holmes-kit semantic-setup` to download the public model once (shared across projects), or set HOLMES_AUTO_MODEL_INSTALL=1 to prepare it during installation. Graph features work without it.\n');
71
- return 0;
72
- }
73
71
  }
74
72
  process.stderr.write(options.offline ? 'Checking BGE-M3 offline...\n' : 'Preparing BGE-M3 (public model download on first installation)...\n');
75
73
  const result = (options.spawn ?? node_child_process_1.spawnSync)(process.execPath, [__filename, '--worker', ...(options.offline ? ['--offline'] : [])], { env, stdio: 'inherit', timeout: 900_000, windowsHide: true });
@@ -1,8 +1,17 @@
1
+ export declare const LOCAL_MODEL = "Xenova/bge-m3";
2
+ export declare const LOCAL_REVISION = "4de13258303883538bd53b696b452bf8099f0858";
3
+ export type LocalModelState = 'verified' | 'missing-cache' | 'unverified-cache' | 'invalid-receipt' | 'stale-receipt';
4
+ export interface LocalModelReadiness {
5
+ ready: boolean;
6
+ state: LocalModelState;
7
+ recovery: string;
8
+ }
1
9
  export declare function modelCacheDir(env?: NodeJS.ProcessEnv, home?: string): string;
2
- /**
3
- * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
4
- * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
5
- * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
6
- * doctor calls this on every run and must stay cheap and offline.
7
- */
10
+ /** A metadata fingerprint cheap enough for offline tier resolution. */
11
+ export declare function modelCacheFingerprint(cacheDir?: string): string | null;
12
+ /** Missing or malformed proof is never promoted to readiness. */
13
+ export declare function readLocalModelReadiness(cacheDir?: string): LocalModelReadiness;
14
+ /** Only successful actual inference may write the same-directory atomic receipt. */
15
+ export declare function writeVerifiedModelReceipt(cacheDir?: string): LocalModelReadiness;
16
+ /** Compatibility boolean: actual verified inference, never directory presence. */
8
17
  export declare function modelCacheReady(cacheDir?: string): boolean;