@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
@@ -23,6 +23,14 @@ export interface CfgEdge {
23
23
  to: number;
24
24
  kind: EdgeKind;
25
25
  }
26
+ /** Source provenance for a TS/JS predicate-bearing branch; absent where the language/source cannot prove it. */
27
+ export interface CfgConditionBranch {
28
+ conditionText?: string;
29
+ startOffset?: number;
30
+ endOffset?: number;
31
+ astKind?: string;
32
+ branchLabel: 'true' | 'false' | 'case' | 'default';
33
+ }
26
34
  export interface Cfg {
27
35
  blocks: CfgBlock[];
28
36
  edges: CfgEdge[];
@@ -34,6 +42,8 @@ export interface Cfg {
34
42
  ipostdom: Int32Array;
35
43
  /** Blocks not reachable from ENTRY (dead code after return etc.) — lint material, not an error. */
36
44
  unreachable: number[];
45
+ /** Additive condition facts. Existing blocks and edge labels retain their original contract. */
46
+ conditionBranches?: CfgConditionBranch[];
37
47
  }
38
48
  export interface FunctionRef {
39
49
  nodeIndex: number;
@@ -1085,7 +1085,33 @@ function cfgOf(ast, fn, source) {
1085
1085
  link(e.from, EXIT, e.kind === 'seq' ? 'seq' : e.kind);
1086
1086
  if (pendingBreaks.length > 0)
1087
1087
  throw new Unsupported('unresolved break label');
1088
- return finalize(stmtsOf, edges, ENTRY, EXIT);
1088
+ const cfg = finalize(stmtsOf, edges, ENTRY, EXIT);
1089
+ // Predicate provenance is deliberately narrower than CFG support: this slice has verified the
1090
+ // tree shapes only for TS/JS, and an absent fact is safer than a guessed condition in another
1091
+ // language. It is attached beside edges, never changes their labels or connectivity.
1092
+ if (source !== undefined && (ast.lang === 'typescript' || ast.lang === 'tsx')) {
1093
+ const conditions = [];
1094
+ const bodyTypes = new Set(['statement_block', 'else_clause', 'switch_body']);
1095
+ for (const edge of cfg.edges) {
1096
+ if (!['true', 'false', 'case', 'default'].includes(edge.kind))
1097
+ continue;
1098
+ const stmt = cfg.blocks[edge.from]?.stmts[0];
1099
+ if (stmt === undefined)
1100
+ continue;
1101
+ const type = ast.nodes[stmt]?.type;
1102
+ if (!['if_statement', 'while_statement', 'do_statement', 'for_statement', 'for_in_statement', 'switch_statement'].includes(type))
1103
+ continue;
1104
+ const condition = kids.of(stmt).find((child) => ast.nodes[child].named && !bodyTypes.has(ast.nodes[child].type));
1105
+ if (condition === undefined)
1106
+ continue;
1107
+ conditions.push({ conditionText: source.slice(ast.nodes[condition].start, ast.nodes[condition].end),
1108
+ startOffset: ast.nodes[condition].start, endOffset: ast.nodes[condition].end,
1109
+ astKind: ast.nodes[condition].type, branchLabel: edge.kind });
1110
+ }
1111
+ if (conditions.length > 0)
1112
+ cfg.conditionBranches = conditions;
1113
+ }
1114
+ return cfg;
1089
1115
  }
1090
1116
  catch (e) {
1091
1117
  if (e instanceof Unsupported)
@@ -49,6 +49,8 @@ export type SemanticWarmOutcome = {
49
49
  * could not embed — a discharge must not record the last one as done.
50
50
  */
51
51
  export declare function warmSemanticCache(root: string, scanned: readonly ScannedFile[]): Promise<SemanticWarmOutcome>;
52
+ /** Requirement prose is warmed only by the explicit reindex operation. */
53
+ export declare function warmRequirementSemanticCache(root: string, specs: readonly Spec[]): Promise<SemanticWarmOutcome>;
52
54
  /**
53
55
  * @implements A-SPEC-683 — vectors refresh on the channel that keeps the graph fresh.
54
56
  *
@@ -93,6 +95,11 @@ export declare function createGraphOperationsHandlers(context: GraphOperationsCo
93
95
  head?: string;
94
96
  since?: string;
95
97
  }): Promise<{
98
+ requirementSemanticWarm?: {
99
+ tier: string;
100
+ computed: number;
101
+ cached: number;
102
+ } | undefined;
96
103
  semanticWarm?: {
97
104
  tier: string;
98
105
  computed: number;
@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.publishCurrentGraph = publishCurrentGraph;
37
37
  exports.warmSemanticCache = warmSemanticCache;
38
+ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
38
39
  exports.refreshSemanticVectors = refreshSemanticVectors;
39
40
  exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
40
41
  // @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
@@ -106,6 +107,21 @@ async function warmSemanticCache(root, scanned) {
106
107
  // breaking change this slice never declared. The suite refused the first attempt and was right.
107
108
  return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
108
109
  }
110
+ /** Requirement prose is warmed only by the explicit reindex operation. */
111
+ async function warmRequirementSemanticCache(root, specs) {
112
+ const tier = (0, tier_1.resolveSemanticTier)();
113
+ if (tier.tier === 'none')
114
+ return { status: 'not-applicable', tier: 'none' };
115
+ const configured = tier.model ? `${tier.tier}:${tier.model}` : tier.tier;
116
+ const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
117
+ if (rt === null)
118
+ return { status: 'unavailable', tier: configured };
119
+ const texts = (0, vector_coverage_1.requirementDocumentTexts)(specs).map((item) => item.text);
120
+ const w = await rt.warm(texts);
121
+ if (texts.length > 0 && w.computed + w.cached === 0)
122
+ return { status: 'unavailable', tier: rt.label };
123
+ return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
124
+ }
109
125
  /** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
110
126
  function headOf(root) {
111
127
  try {
@@ -338,8 +354,16 @@ function createGraphOperationsHandlers(context) {
338
354
  semanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
339
355
  }
340
356
  catch { /* warming is best-effort; reindex's own result is unaffected */ }
357
+ let requirementSemanticWarm;
358
+ try {
359
+ const w = await warmRequirementSemanticCache(root, specs);
360
+ if (w.status === 'discharged')
361
+ requirementSemanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
362
+ }
363
+ catch { /* requirement warming is advisory and cannot invalidate reindex */ }
341
364
  return { changed, nodes: published.nodes, edges: published.edges, changeSource,
342
- ...(semanticWarm !== undefined ? { semanticWarm } : {}) };
365
+ ...(semanticWarm !== undefined ? { semanticWarm } : {}),
366
+ ...(requirementSemanticWarm !== undefined ? { requirementSemanticWarm } : {}) };
343
367
  },
344
368
  };
345
369
  }
@@ -0,0 +1,116 @@
1
+ import type { Spec } from '../../spec/spec-parser';
2
+ import type { ScannedFile } from '../../cpg/cpg-scanner';
3
+ export interface RequirementTriageHandlerContext {
4
+ listSpecs(): Promise<Spec[]>;
5
+ foreignRootReason(root?: string): string | null;
6
+ projectRootOf(root: string): string;
7
+ cachedScan(root: string, repoRoot?: string): ScannedFile[];
8
+ assertStoreReachable(tool: string, root: unknown): void;
9
+ refusal(reason: string): Error;
10
+ }
11
+ type GraphStatus = 'current' | 'stale' | 'unverified' | 'absent' | 'unreadable' | 'empty';
12
+ export declare function createRequirementTriageHandlers(context: RequirementTriageHandlerContext): {
13
+ requirement_triage(a: {
14
+ root: string;
15
+ prompt: string;
16
+ topK?: number;
17
+ persist?: boolean;
18
+ }): Promise<{
19
+ promptDigest: string;
20
+ semantic: {
21
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
22
+ recovery?: string | undefined;
23
+ tier: "local" | "none" | "cloud";
24
+ covered: number;
25
+ total: number;
26
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
27
+ availability: string;
28
+ };
29
+ provenance: {
30
+ reqId: string;
31
+ documents: {
32
+ id: string;
33
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
34
+ status: string;
35
+ dependsOn: readonly string[];
36
+ }[];
37
+ implementationAnchors: string[];
38
+ graphProvenance: {
39
+ [k: string]: {} | null;
40
+ };
41
+ executionEvidence: {
42
+ state: string;
43
+ recordedHead: string | null;
44
+ currentHead: string;
45
+ };
46
+ }[];
47
+ graph: {
48
+ status: GraphStatus;
49
+ sourceCommit: string | null;
50
+ graphAsOf: string | null;
51
+ resolutionLimits: string[];
52
+ };
53
+ graphBasis: {
54
+ head: string;
55
+ governedDocumentCount: number;
56
+ scannedSourceCount: number;
57
+ };
58
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
59
+ candidates: import("../../review/requirement-triage").RequirementTriageCandidate[];
60
+ reasons: string[];
61
+ uncertainty: string[];
62
+ schema: "requirement-triage/1";
63
+ } | {
64
+ evidenceDigest: string;
65
+ persistedTo: string;
66
+ artifact: {
67
+ digest: string;
68
+ path: string;
69
+ };
70
+ promptDigest: string;
71
+ semantic: {
72
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
73
+ recovery?: string | undefined;
74
+ tier: "local" | "none" | "cloud";
75
+ covered: number;
76
+ total: number;
77
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
78
+ availability: string;
79
+ };
80
+ provenance: {
81
+ reqId: string;
82
+ documents: {
83
+ id: string;
84
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
85
+ status: string;
86
+ dependsOn: readonly string[];
87
+ }[];
88
+ implementationAnchors: string[];
89
+ graphProvenance: {
90
+ [k: string]: {} | null;
91
+ };
92
+ executionEvidence: {
93
+ state: string;
94
+ recordedHead: string | null;
95
+ currentHead: string;
96
+ };
97
+ }[];
98
+ graph: {
99
+ status: GraphStatus;
100
+ sourceCommit: string | null;
101
+ graphAsOf: string | null;
102
+ resolutionLimits: string[];
103
+ };
104
+ graphBasis: {
105
+ head: string;
106
+ governedDocumentCount: number;
107
+ scannedSourceCount: number;
108
+ };
109
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
110
+ candidates: import("../../review/requirement-triage").RequirementTriageCandidate[];
111
+ reasons: string[];
112
+ uncertainty: string[];
113
+ schema: "requirement-triage/1";
114
+ }>;
115
+ };
116
+ export {};
@@ -0,0 +1,185 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
37
+ // @implements A-SPEC-713
38
+ /** Read-only MCP projection of the pure requirement lifecycle triage model. */
39
+ const node_child_process_1 = require("node:child_process");
40
+ const crypto = __importStar(require("node:crypto"));
41
+ const path = __importStar(require("node:path"));
42
+ const test_evidence_1 = require("../../review/test-evidence");
43
+ const requirement_triage_1 = require("../../review/requirement-triage");
44
+ const embedder_1 = require("../../semantic/embedder");
45
+ const tier_1 = require("../../semantic/tier");
46
+ const vector_cache_1 = require("../../semantic/vector-cache");
47
+ const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
48
+ const model_cache_1 = require("../../semantic/model-cache");
49
+ const graph_store_1 = require("../../rtm/graph-store");
50
+ const requirementKinds = new Set(['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC']);
51
+ const cosine = (a, b) => {
52
+ if (a.length === 0 || a.length !== b.length)
53
+ return 0;
54
+ let dot = 0, an = 0, bn = 0;
55
+ for (let i = 0; i < a.length; i++) {
56
+ dot += a[i] * b[i];
57
+ an += a[i] * a[i];
58
+ bn += b[i] * b[i];
59
+ }
60
+ return an === 0 || bn === 0 ? 0 : dot / Math.sqrt(an * bn);
61
+ };
62
+ function lineageOf(id, byId) {
63
+ const seen = new Set();
64
+ let current = byId.get(id);
65
+ while (current) {
66
+ if (seen.has(current.id))
67
+ return null;
68
+ seen.add(current.id);
69
+ if (current.type === 'REQ')
70
+ return current.id;
71
+ current = (current.dependsOn ?? []).map((parent) => byId.get(parent)).find((parent) => parent !== undefined);
72
+ }
73
+ return null;
74
+ }
75
+ function headOf(root) {
76
+ try {
77
+ return (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
78
+ }
79
+ catch {
80
+ return '';
81
+ }
82
+ }
83
+ /** Reads a published graph without rebuilding, repairing, or otherwise changing it. */
84
+ function readGraphEvidence(root, currentHead, documents) {
85
+ const opened = (0, graph_store_1.openPublishedGraph)(path.join(root, '.ax', 'rtm.sqlite'), currentHead || null);
86
+ const base = {
87
+ status: opened.status,
88
+ sourceCommit: 'sourceCommit' in opened ? opened.sourceCommit : null,
89
+ graphAsOf: opened.graphAsOf ?? null,
90
+ resolutionLimits: opened.status === 'current' ? [] : [`rtm-graph-${opened.status}`],
91
+ provenanceBySpec: {},
92
+ };
93
+ if (opened.graph === null)
94
+ return base;
95
+ try {
96
+ for (const document of documents)
97
+ base.provenanceBySpec[document.id] = opened.graph.provenanceOfNode(`SPEC:${document.id}`);
98
+ return base;
99
+ }
100
+ finally {
101
+ opened.graph.close();
102
+ }
103
+ }
104
+ function createRequirementTriageHandlers(context) {
105
+ return {
106
+ async requirement_triage(a) {
107
+ context.assertStoreReachable('requirement_triage', a.root);
108
+ if (typeof a.prompt !== 'string' || a.prompt.trim() === '')
109
+ throw context.refusal('requirement_triage requires a non-empty prompt');
110
+ const foreign = context.foreignRootReason(a.root);
111
+ if (foreign)
112
+ throw context.refusal(foreign);
113
+ const root = context.projectRootOf(a.root);
114
+ const documents = (await context.listSpecs()).filter((s) => requirementKinds.has(s.type));
115
+ const byId = new Map(documents.map((doc) => [doc.id, doc]));
116
+ const scanned = context.cachedScan(root, root);
117
+ const evidence = (0, test_evidence_1.readTestEvidence)(root);
118
+ const currentHead = headOf(root);
119
+ const graph = readGraphEvidence(root, currentHead, documents);
120
+ const fresh = (0, test_evidence_1.isFresh)(evidence, currentHead) && evidence?.passed === true;
121
+ const lineageEvidence = {};
122
+ for (const doc of documents) {
123
+ const reqId = lineageOf(doc.id, byId);
124
+ if (!reqId)
125
+ continue;
126
+ const record = lineageEvidence[reqId] ??= { implementationAnchors: [], freshGreenTests: false };
127
+ if (doc.type !== 'A-SPEC')
128
+ continue;
129
+ for (const file of scanned)
130
+ if (file.implementsSpecs.includes(doc.id))
131
+ record.implementationAnchors.push(file.sourcePath);
132
+ if (fresh && (evidence?.executedByAspec[doc.id] ?? 0) > 0)
133
+ record.freshGreenTests = true;
134
+ }
135
+ for (const value of Object.values(lineageEvidence))
136
+ value.implementationAnchors.sort();
137
+ const tier = (0, tier_1.resolveSemanticTier)();
138
+ const runtime = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
139
+ const query = runtime ? await runtime.embedQuery(a.prompt) : null;
140
+ const semanticCandidates = [];
141
+ let covered = 0;
142
+ if (runtime && query)
143
+ for (const doc of documents) {
144
+ const reqId = lineageOf(doc.id, byId);
145
+ if (!reqId)
146
+ continue;
147
+ const vector = runtime.cachedDocVector((0, requirement_triage_1.canonicalRequirementDocument)(doc, reqId));
148
+ if (vector) {
149
+ covered++;
150
+ semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
151
+ }
152
+ }
153
+ const semanticState = runtime === null || query === null
154
+ ? (tier.tier === 'none' && !tier.localRuntimePresent ? 'not-adopted' : 'unavailable')
155
+ : covered === documents.length ? 'covered' : 'cold';
156
+ const readiness = tier.tier === 'none' && tier.localRuntimePresent ? (0, model_cache_1.readLocalModelReadiness)() : null;
157
+ const availability = semanticState === 'covered' ? 'available'
158
+ : semanticState === 'cold' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
159
+ : 'unavailable';
160
+ const semantic = { tier: tier.tier, covered, total: documents.length, state: semanticState,
161
+ availability,
162
+ ...(readiness ? { localState: readiness.state, recovery: readiness.recovery } : {}) };
163
+ const result = (0, requirement_triage_1.triageRequirements)({ prompt: a.prompt, documents, evidence: lineageEvidence,
164
+ semanticCandidates, semantic, graph: { state: graph.status }, topK: a.topK });
165
+ const promptDigest = `sha256:${crypto.createHash('sha256').update(a.prompt).digest('hex')}`;
166
+ const executionState = evidence === undefined ? 'absent'
167
+ : !(0, test_evidence_1.isFresh)(evidence, currentHead) ? 'stale'
168
+ : evidence.passed ? 'fresh-green' : 'fresh-failed';
169
+ const provenance = result.candidates.map((candidate) => ({
170
+ reqId: candidate.reqId,
171
+ documents: candidate.documents.map((document) => ({ id: document.id, type: document.type, status: document.status, dependsOn: document.dependsOn ?? [] })),
172
+ implementationAnchors: candidate.implementationAnchors,
173
+ graphProvenance: Object.fromEntries(candidate.documents.map((document) => [document.id, graph.provenanceBySpec[document.id] ?? null])),
174
+ executionEvidence: { state: executionState, recordedHead: evidence?.head ?? null, currentHead },
175
+ }));
176
+ const answer = { schema: 'requirement-triage/1', ...result, promptDigest, semantic, provenance,
177
+ graph: { status: graph.status, sourceCommit: graph.sourceCommit, graphAsOf: graph.graphAsOf, resolutionLimits: graph.resolutionLimits },
178
+ graphBasis: { head: currentHead, governedDocumentCount: documents.length, scannedSourceCount: scanned.length } };
179
+ if (!a.persist)
180
+ return answer;
181
+ const artifact = (0, requirement_triage_evidence_1.writeRequirementTriageEvidence)(root, { schema: 'requirement-triage-evidence/1', promptDigest, result: answer });
182
+ return { ...answer, evidenceDigest: artifact.digest, persistedTo: artifact.path, artifact };
183
+ },
184
+ };
185
+ }
@@ -0,0 +1,9 @@
1
+ import { Agent } from '../../cli/agents';
2
+ export declare function createWorkspacePreflightHandlers(context: {
3
+ storeRoot?: string;
4
+ }): {
5
+ workspace_preflight(a: {
6
+ root: string;
7
+ harness?: Agent;
8
+ }): Promise<import("../../project/workspace-preflight").WorkspacePreflight>;
9
+ };
@@ -0,0 +1,13 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createWorkspacePreflightHandlers = createWorkspacePreflightHandlers;
4
+ // @implements A-SPEC-703
5
+ const agents_1 = require("../../cli/agents");
6
+ const workspace_preflight_1 = require("../../project/workspace-preflight");
7
+ function createWorkspacePreflightHandlers(context) {
8
+ return { async workspace_preflight(a) {
9
+ if (a?.harness !== undefined && !agents_1.AGENTS.includes(a.harness))
10
+ throw new Error('Unsupported harness.');
11
+ return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot });
12
+ } };
13
+ }
@@ -349,52 +349,6 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
349
349
  code: string;
350
350
  reason: string;
351
351
  }>;
352
- ledger_reconcile: (a: {
353
- root?: string;
354
- nonce: string;
355
- rationale?: string;
356
- }) => Promise<{
357
- ok: boolean;
358
- reason: string;
359
- reconciled?: undefined;
360
- nonce?: undefined;
361
- pending?: undefined;
362
- code?: undefined;
363
- events?: undefined;
364
- remaining?: undefined;
365
- } | {
366
- ok: boolean;
367
- reconciled: boolean;
368
- nonce: string;
369
- pending: string[];
370
- reason: string;
371
- code?: undefined;
372
- events?: undefined;
373
- remaining?: undefined;
374
- } | {
375
- ok: boolean;
376
- code: string;
377
- reason: string;
378
- reconciled?: undefined;
379
- nonce?: undefined;
380
- pending?: undefined;
381
- events?: undefined;
382
- remaining?: undefined;
383
- } | {
384
- ok: boolean;
385
- reconciled: boolean;
386
- nonce: string;
387
- events: {
388
- replicaId: string | null;
389
- seq: number;
390
- hash: string;
391
- ts: string;
392
- }[];
393
- remaining: string[];
394
- reason?: undefined;
395
- pending?: undefined;
396
- code?: undefined;
397
- }>;
398
352
  spec_reconcile: (a: {
399
353
  root?: string;
400
354
  operation?: string;
@@ -429,6 +383,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
429
383
  head?: string;
430
384
  since?: string;
431
385
  }) => Promise<{
386
+ requirementSemanticWarm?: {
387
+ tier: string;
388
+ computed: number;
389
+ cached: number;
390
+ } | undefined;
432
391
  semanticWarm?: {
433
392
  tier: string;
434
393
  computed: number;
@@ -633,6 +592,158 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
633
592
  reason: string;
634
593
  }[];
635
594
  }>;
595
+ workspace_preflight(a: {
596
+ root: string;
597
+ harness?: import("../cli/agents").Agent;
598
+ }): Promise<import("../project/workspace-preflight").WorkspacePreflight>;
599
+ requirement_triage: (a: {
600
+ root: string;
601
+ prompt: string;
602
+ topK?: number;
603
+ persist?: boolean;
604
+ }) => Promise<{
605
+ promptDigest: string;
606
+ semantic: {
607
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
608
+ recovery?: string | undefined;
609
+ tier: "local" | "none" | "cloud";
610
+ covered: number;
611
+ total: number;
612
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
613
+ availability: string;
614
+ };
615
+ provenance: {
616
+ reqId: string;
617
+ documents: {
618
+ id: string;
619
+ type: import("../review/requirement-triage").RequirementDocumentKind;
620
+ status: string;
621
+ dependsOn: readonly string[];
622
+ }[];
623
+ implementationAnchors: string[];
624
+ graphProvenance: {
625
+ [k: string]: {} | null;
626
+ };
627
+ executionEvidence: {
628
+ state: string;
629
+ recordedHead: string | null;
630
+ currentHead: string;
631
+ };
632
+ }[];
633
+ graph: {
634
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
635
+ sourceCommit: string | null;
636
+ graphAsOf: string | null;
637
+ resolutionLimits: string[];
638
+ };
639
+ graphBasis: {
640
+ head: string;
641
+ governedDocumentCount: number;
642
+ scannedSourceCount: number;
643
+ };
644
+ verdict: import("../review/requirement-triage").RequirementVerdict;
645
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
646
+ reasons: string[];
647
+ uncertainty: string[];
648
+ schema: "requirement-triage/1";
649
+ } | {
650
+ evidenceDigest: string;
651
+ persistedTo: string;
652
+ artifact: {
653
+ digest: string;
654
+ path: string;
655
+ };
656
+ promptDigest: string;
657
+ semantic: {
658
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
659
+ recovery?: string | undefined;
660
+ tier: "local" | "none" | "cloud";
661
+ covered: number;
662
+ total: number;
663
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
664
+ availability: string;
665
+ };
666
+ provenance: {
667
+ reqId: string;
668
+ documents: {
669
+ id: string;
670
+ type: import("../review/requirement-triage").RequirementDocumentKind;
671
+ status: string;
672
+ dependsOn: readonly string[];
673
+ }[];
674
+ implementationAnchors: string[];
675
+ graphProvenance: {
676
+ [k: string]: {} | null;
677
+ };
678
+ executionEvidence: {
679
+ state: string;
680
+ recordedHead: string | null;
681
+ currentHead: string;
682
+ };
683
+ }[];
684
+ graph: {
685
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
686
+ sourceCommit: string | null;
687
+ graphAsOf: string | null;
688
+ resolutionLimits: string[];
689
+ };
690
+ graphBasis: {
691
+ head: string;
692
+ governedDocumentCount: number;
693
+ scannedSourceCount: number;
694
+ };
695
+ verdict: import("../review/requirement-triage").RequirementVerdict;
696
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
697
+ reasons: string[];
698
+ uncertainty: string[];
699
+ schema: "requirement-triage/1";
700
+ }>;
701
+ ledger_reconcile: (a: {
702
+ root?: string;
703
+ nonce: string;
704
+ rationale?: string;
705
+ }) => Promise<{
706
+ ok: boolean;
707
+ reason: string;
708
+ reconciled?: undefined;
709
+ nonce?: undefined;
710
+ pending?: undefined;
711
+ code?: undefined;
712
+ events?: undefined;
713
+ remaining?: undefined;
714
+ } | {
715
+ ok: boolean;
716
+ reconciled: boolean;
717
+ nonce: string;
718
+ pending: string[];
719
+ reason: string;
720
+ code?: undefined;
721
+ events?: undefined;
722
+ remaining?: undefined;
723
+ } | {
724
+ ok: boolean;
725
+ code: string;
726
+ reason: string;
727
+ reconciled?: undefined;
728
+ nonce?: undefined;
729
+ pending?: undefined;
730
+ events?: undefined;
731
+ remaining?: undefined;
732
+ } | {
733
+ ok: boolean;
734
+ reconciled: boolean;
735
+ nonce: string;
736
+ events: {
737
+ replicaId: string | null;
738
+ seq: number;
739
+ hash: string;
740
+ ts: string;
741
+ }[];
742
+ remaining: string[];
743
+ reason?: undefined;
744
+ pending?: undefined;
745
+ code?: undefined;
746
+ }>;
636
747
  maintenance_outcome(a: {
637
748
  root: string;
638
749
  digest: string;