@holmes-lab/holmes-kit 0.28.0 → 0.30.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 (83) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +24 -21
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  5. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  6. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  7. package/dist/holmes/cli/agents-guidance.js +11 -8
  8. package/dist/holmes/cli/codex-toml.d.ts +23 -1
  9. package/dist/holmes/cli/codex-toml.js +151 -4
  10. package/dist/holmes/cli/doctor.d.ts +11 -1
  11. package/dist/holmes/cli/doctor.js +113 -13
  12. package/dist/holmes/cli/init.d.ts +2 -0
  13. package/dist/holmes/cli/init.js +20 -40
  14. package/dist/holmes/cli/interactive-prompt.js +2 -2
  15. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  16. package/dist/holmes/cli/worktree-readiness.js +17 -3
  17. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  18. package/dist/holmes/cpg/ast-mutation.js +4 -2
  19. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  20. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  21. package/dist/holmes/governance/autonomy.d.ts +9 -0
  22. package/dist/holmes/governance/autonomy.js +28 -1
  23. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  24. package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
  25. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  26. package/dist/holmes/hooks/rtm-refresh.js +56 -15
  27. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  28. package/dist/holmes/mcp/approval-adapters.js +21 -0
  29. package/dist/holmes/mcp/approval-commit.d.ts +21 -0
  30. package/dist/holmes/mcp/approval-commit.js +92 -0
  31. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  32. package/dist/holmes/mcp/approval-intent.js +67 -0
  33. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  34. package/dist/holmes/mcp/approval-policy.js +18 -0
  35. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  36. package/dist/holmes/mcp/elicit-approval.js +5 -2
  37. package/dist/holmes/mcp/handlers/graph-operations.d.ts +24 -1
  38. package/dist/holmes/mcp/handlers/graph-operations.js +38 -6
  39. package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
  40. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +142 -0
  41. package/dist/holmes/mcp/handlers/requirement-triage.js +220 -0
  42. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  43. package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
  44. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
  45. package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
  46. package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
  47. package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
  48. package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
  49. package/dist/holmes/mcp/handlers.d.ts +153 -0
  50. package/dist/holmes/mcp/handlers.js +67 -13
  51. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  52. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  53. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +45 -0
  54. package/dist/holmes/mcp/requirement-triage-evidence.js +149 -0
  55. package/dist/holmes/mcp/server.js +5 -3
  56. package/dist/holmes/mcp/supervisor.js +7 -3
  57. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  58. package/dist/holmes/mcp/tool-schemas.js +44 -1
  59. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  60. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  61. package/dist/holmes/review/condition-hunk-replay.d.ts +45 -0
  62. package/dist/holmes/review/condition-hunk-replay.js +122 -0
  63. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  64. package/dist/holmes/review/condition-hunk-resolution.js +258 -0
  65. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  66. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  67. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  68. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  69. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  70. package/dist/holmes/review/requirement-triage.js +143 -0
  71. package/dist/holmes/review/scope.js +6 -1
  72. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  73. package/dist/holmes/review/test-outcomes.js +90 -1
  74. package/dist/holmes/semantic/local-model.d.ts +3 -3
  75. package/dist/holmes/semantic/local-model.js +10 -12
  76. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  77. package/dist/holmes/semantic/model-cache.js +77 -21
  78. package/dist/holmes/semantic/tier.d.ts +5 -1
  79. package/dist/holmes/semantic/tier.js +7 -6
  80. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  81. package/dist/holmes/semantic/vector-coverage.js +37 -0
  82. package/docs/install-guide.md +19 -24
  83. package/package.json +1 -1
@@ -42,6 +42,20 @@ export type SemanticWarmOutcome = {
42
42
  status: 'unavailable';
43
43
  tier: string;
44
44
  };
45
+ /** Durable outcome for the background source-vector lane. `null` would conflate owner non-adoption,
46
+ * an explicit suppression, and an unavailable embedder — each has a different recovery contract. */
47
+ export type SourceSemanticRefreshOutcome = {
48
+ lane: 'current';
49
+ coverage: PersistedCoverage;
50
+ } | {
51
+ lane: 'not-adopted';
52
+ } | {
53
+ lane: 'suppressed';
54
+ coverage: PersistedCoverage;
55
+ } | {
56
+ lane: 'failed';
57
+ reason: 'unavailable' | 'failed';
58
+ };
45
59
  /**
46
60
  * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
47
61
  * ranking hot path only ever LOOKS UP vectors. Idempotent through the cache. The outcome says
@@ -49,6 +63,10 @@ export type SemanticWarmOutcome = {
49
63
  * could not embed — a discharge must not record the last one as done.
50
64
  */
51
65
  export declare function warmSemanticCache(root: string, scanned: readonly ScannedFile[]): Promise<SemanticWarmOutcome>;
66
+ /** Requirement prose is warmed only by the explicit reindex operation. */
67
+ export declare function warmRequirementSemanticCache(root: string, specs: readonly Spec[]): Promise<SemanticWarmOutcome>;
68
+ /** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
69
+ export declare function headOf(root: string): string | null;
52
70
  /**
53
71
  * @implements A-SPEC-683 — vectors refresh on the channel that keeps the graph fresh.
54
72
  *
@@ -62,7 +80,7 @@ export declare function warmSemanticCache(root: string, scanned: readonly Scanne
62
80
  * with a switch; silent automatic transfer was considered and refused. `HOLMES_NO_SEMANTIC_WARM`
63
81
  * records SUPPRESSED rather than a failure, so an owner who turned it off is never shown a fault.
64
82
  */
65
- export declare function refreshSemanticVectors(root: string, env?: NodeJS.ProcessEnv, warm?: (r: string, s: readonly ScannedFile[]) => Promise<SemanticWarmOutcome>, scan?: () => readonly ScannedFile[]): Promise<PersistedCoverage | null>;
83
+ export declare function refreshSemanticVectors(root: string, env?: NodeJS.ProcessEnv, warm?: (r: string, s: readonly ScannedFile[]) => Promise<SemanticWarmOutcome>, scan?: () => readonly ScannedFile[]): Promise<SourceSemanticRefreshOutcome>;
66
84
  export declare function createGraphOperationsHandlers(context: GraphOperationsContext): {
67
85
  rtm_impact(a: {
68
86
  root: string;
@@ -93,6 +111,11 @@ export declare function createGraphOperationsHandlers(context: GraphOperationsCo
93
111
  head?: string;
94
112
  since?: string;
95
113
  }): Promise<{
114
+ requirementSemanticWarm?: {
115
+ tier: string;
116
+ computed: number;
117
+ cached: number;
118
+ } | undefined;
96
119
  semanticWarm?: {
97
120
  tier: string;
98
121
  computed: number;
@@ -35,8 +35,11 @@ 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;
39
+ exports.headOf = headOf;
38
40
  exports.refreshSemanticVectors = refreshSemanticVectors;
39
41
  exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
42
+ // @implements A-SPEC-719
40
43
  // @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
41
44
  // @implements A-SPEC-632
42
45
  const fs = __importStar(require("node:fs"));
@@ -106,6 +109,21 @@ async function warmSemanticCache(root, scanned) {
106
109
  // breaking change this slice never declared. The suite refused the first attempt and was right.
107
110
  return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
108
111
  }
112
+ /** Requirement prose is warmed only by the explicit reindex operation. */
113
+ async function warmRequirementSemanticCache(root, specs) {
114
+ const tier = (0, tier_1.resolveSemanticTier)();
115
+ if (tier.tier === 'none')
116
+ return { status: 'not-applicable', tier: 'none' };
117
+ const configured = tier.model ? `${tier.tier}:${tier.model}` : tier.tier;
118
+ const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
119
+ if (rt === null)
120
+ return { status: 'unavailable', tier: configured };
121
+ const texts = (0, vector_coverage_1.requirementDocumentTexts)(specs).map((item) => item.text);
122
+ const w = await rt.warm(texts);
123
+ if (texts.length > 0 && w.computed + w.cached === 0)
124
+ return { status: 'unavailable', tier: rt.label };
125
+ return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
126
+ }
109
127
  /** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
110
128
  function headOf(root) {
111
129
  try {
@@ -132,7 +150,7 @@ function headOf(root) {
132
150
  async function refreshSemanticVectors(root, env = process.env, warm = warmSemanticCache, scan) {
133
151
  const tier = (0, tier_1.resolveSemanticTier)();
134
152
  if (tier.tier === 'none')
135
- return null; // never opted in: nothing transferred, nothing said
153
+ return { lane: 'not-adopted' }; // never opted in: nothing transferred
136
154
  const at = new Date().toISOString();
137
155
  const scanned = scan ? scan() : [];
138
156
  const off = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
@@ -146,11 +164,17 @@ async function refreshSemanticVectors(root, env = process.env, warm = warmSemant
146
164
  reason: 'suppressed', at, ...(head !== null ? { head } : {}),
147
165
  };
148
166
  (0, vector_coverage_1.writeCoverageState)(root, state);
149
- return state;
167
+ return { lane: 'suppressed', coverage: state };
168
+ }
169
+ let outcome;
170
+ try {
171
+ outcome = await warm(root, scanned);
172
+ }
173
+ catch {
174
+ return { lane: 'failed', reason: 'failed' };
150
175
  }
151
- const outcome = await warm(root, scanned); // throws leave the previous verdict untouched
152
176
  if (outcome.status !== 'discharged')
153
- return null;
177
+ return { lane: 'failed', reason: 'unavailable' };
154
178
  // What LANDED, not what was attempted. Measured 2026-09-19 the warm answered `computed: 603`
155
179
  // while 26 vectors were never stored; a count of attempts reported as a success is the same
156
180
  // class of dishonesty as a tier that says PASS while covering nothing.
@@ -164,7 +188,7 @@ async function refreshSemanticVectors(root, env = process.env, warm = warmSemant
164
188
  ...(headOf(root) !== null ? { head: headOf(root) } : {}),
165
189
  };
166
190
  (0, vector_coverage_1.writeCoverageState)(root, state);
167
- return state;
191
+ return { lane: 'current', coverage: state };
168
192
  }
169
193
  function createGraphOperationsHandlers(context) {
170
194
  return {
@@ -338,8 +362,16 @@ function createGraphOperationsHandlers(context) {
338
362
  semanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
339
363
  }
340
364
  catch { /* warming is best-effort; reindex's own result is unaffected */ }
365
+ let requirementSemanticWarm;
366
+ try {
367
+ const w = await warmRequirementSemanticCache(root, specs);
368
+ if (w.status === 'discharged')
369
+ requirementSemanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
370
+ }
371
+ catch { /* requirement warming is advisory and cannot invalidate reindex */ }
341
372
  return { changed, nodes: published.nodes, edges: published.edges, changeSource,
342
- ...(semanticWarm !== undefined ? { semanticWarm } : {}) };
373
+ ...(semanticWarm !== undefined ? { semanticWarm } : {}),
374
+ ...(requirementSemanticWarm !== undefined ? { requirementSemanticWarm } : {}) };
343
375
  },
344
376
  };
345
377
  }
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createMaintenanceEvidenceHandlers = createMaintenanceEvidenceHandlers;
37
- // @implements A-SPEC-603
37
+ // @implements A-SPEC-724.1, A-SPEC-603
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const node_child_process_1 = require("node:child_process");
@@ -0,0 +1,142 @@
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
+ requestFreshness?(root: string): {
11
+ status: 'spawned' | 'coalesced' | 'failed';
12
+ generation?: string;
13
+ };
14
+ }
15
+ type GraphStatus = 'current' | 'stale' | 'unverified' | 'absent' | 'unreadable' | 'empty';
16
+ export declare function createRequirementTriageHandlers(context: RequirementTriageHandlerContext): {
17
+ requirement_triage(a: {
18
+ root: string;
19
+ prompt: string;
20
+ topK?: number;
21
+ persist?: boolean;
22
+ }): Promise<{
23
+ promptDigest: string;
24
+ semantic: {
25
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
26
+ recovery?: string | undefined;
27
+ suppressed?: true | undefined;
28
+ tier: "local" | "none" | "cloud";
29
+ covered: number;
30
+ total: number;
31
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
32
+ availability: string;
33
+ };
34
+ provenance: {
35
+ reqId: string;
36
+ documents: {
37
+ id: string;
38
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
39
+ status: string;
40
+ dependsOn: readonly string[];
41
+ }[];
42
+ implementationAnchors: string[];
43
+ graphProvenance: {
44
+ [k: string]: {} | null;
45
+ };
46
+ executionEvidence: {
47
+ state: string;
48
+ recordedHead: string | null;
49
+ currentHead: string;
50
+ };
51
+ }[];
52
+ graph: {
53
+ status: GraphStatus;
54
+ sourceCommit: string | null;
55
+ graphAsOf: string | null;
56
+ resolutionLimits: string[];
57
+ };
58
+ graphBasis: {
59
+ head: string;
60
+ governedDocumentCount: number;
61
+ scannedSourceCount: number;
62
+ };
63
+ freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
64
+ state: string;
65
+ };
66
+ refresh: {
67
+ status: "spawned" | "coalesced" | "failed";
68
+ generation?: string;
69
+ } | {
70
+ status: "unavailable" | "not-needed";
71
+ };
72
+ lexicalOnly?: true | undefined;
73
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
74
+ candidates: import("../../review/requirement-triage").RequirementTriageCandidate[];
75
+ reasons: string[];
76
+ uncertainty: string[];
77
+ schema: "requirement-triage/1";
78
+ } | {
79
+ evidenceDigest: string;
80
+ persistedTo: string;
81
+ artifact: {
82
+ digest: string;
83
+ path: string;
84
+ };
85
+ promptDigest: string;
86
+ semantic: {
87
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
88
+ recovery?: string | undefined;
89
+ suppressed?: true | undefined;
90
+ tier: "local" | "none" | "cloud";
91
+ covered: number;
92
+ total: number;
93
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
94
+ availability: string;
95
+ };
96
+ provenance: {
97
+ reqId: string;
98
+ documents: {
99
+ id: string;
100
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
101
+ status: string;
102
+ dependsOn: readonly string[];
103
+ }[];
104
+ implementationAnchors: string[];
105
+ graphProvenance: {
106
+ [k: string]: {} | null;
107
+ };
108
+ executionEvidence: {
109
+ state: string;
110
+ recordedHead: string | null;
111
+ currentHead: string;
112
+ };
113
+ }[];
114
+ graph: {
115
+ status: GraphStatus;
116
+ sourceCommit: string | null;
117
+ graphAsOf: string | null;
118
+ resolutionLimits: string[];
119
+ };
120
+ graphBasis: {
121
+ head: string;
122
+ governedDocumentCount: number;
123
+ scannedSourceCount: number;
124
+ };
125
+ freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
126
+ state: string;
127
+ };
128
+ refresh: {
129
+ status: "spawned" | "coalesced" | "failed";
130
+ generation?: string;
131
+ } | {
132
+ status: "unavailable" | "not-needed";
133
+ };
134
+ lexicalOnly?: true | undefined;
135
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
136
+ candidates: import("../../review/requirement-triage").RequirementTriageCandidate[];
137
+ reasons: string[];
138
+ uncertainty: string[];
139
+ schema: "requirement-triage/1";
140
+ }>;
141
+ };
142
+ export {};
@@ -0,0 +1,220 @@
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-723, A-SPEC-719
38
+ // @implements A-SPEC-713
39
+ /** Read-only MCP projection of the pure requirement lifecycle triage model. */
40
+ const node_child_process_1 = require("node:child_process");
41
+ const crypto = __importStar(require("node:crypto"));
42
+ const path = __importStar(require("node:path"));
43
+ const test_evidence_1 = require("../../review/test-evidence");
44
+ const requirement_triage_1 = require("../../review/requirement-triage");
45
+ const embedder_1 = require("../../semantic/embedder");
46
+ const tier_1 = require("../../semantic/tier");
47
+ const vector_cache_1 = require("../../semantic/vector-cache");
48
+ const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
49
+ const model_cache_1 = require("../../semantic/model-cache");
50
+ const graph_store_1 = require("../../rtm/graph-store");
51
+ const freshness_coordinator_1 = require("../../refresh/freshness-coordinator");
52
+ const requirementKinds = new Set(['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC']);
53
+ const cosine = (a, b) => {
54
+ if (a.length === 0 || a.length !== b.length)
55
+ return 0;
56
+ let dot = 0, an = 0, bn = 0;
57
+ for (let i = 0; i < a.length; i++) {
58
+ dot += a[i] * b[i];
59
+ an += a[i] * a[i];
60
+ bn += b[i] * b[i];
61
+ }
62
+ return an === 0 || bn === 0 ? 0 : dot / Math.sqrt(an * bn);
63
+ };
64
+ function lineageOf(id, byId) {
65
+ const seen = new Set();
66
+ let current = byId.get(id);
67
+ while (current) {
68
+ if (seen.has(current.id))
69
+ return null;
70
+ seen.add(current.id);
71
+ if (current.type === 'REQ')
72
+ return current.id;
73
+ current = (current.dependsOn ?? []).map((parent) => byId.get(parent)).find((parent) => parent !== undefined);
74
+ }
75
+ return null;
76
+ }
77
+ function headOf(root) {
78
+ try {
79
+ return (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
80
+ }
81
+ catch {
82
+ return '';
83
+ }
84
+ }
85
+ /** Reads a published graph without rebuilding, repairing, or otherwise changing it. */
86
+ function readGraphEvidence(root, currentHead, documents) {
87
+ const opened = (0, graph_store_1.openPublishedGraph)(path.join(root, '.ax', 'rtm.sqlite'), currentHead || null);
88
+ const base = {
89
+ status: opened.status,
90
+ sourceCommit: 'sourceCommit' in opened ? opened.sourceCommit : null,
91
+ graphAsOf: opened.graphAsOf ?? null,
92
+ resolutionLimits: opened.status === 'current' ? [] : [`rtm-graph-${opened.status}`],
93
+ provenanceBySpec: {},
94
+ };
95
+ if (opened.graph === null)
96
+ return base;
97
+ try {
98
+ for (const document of documents)
99
+ base.provenanceBySpec[document.id] = opened.graph.provenanceOfNode(`SPEC:${document.id}`);
100
+ return base;
101
+ }
102
+ finally {
103
+ opened.graph.close();
104
+ }
105
+ }
106
+ function createRequirementTriageHandlers(context) {
107
+ return {
108
+ async requirement_triage(a) {
109
+ context.assertStoreReachable('requirement_triage', a.root);
110
+ if (typeof a.prompt !== 'string' || a.prompt.trim() === '')
111
+ throw context.refusal('requirement_triage requires a non-empty prompt');
112
+ const foreign = context.foreignRootReason(a.root);
113
+ if (foreign)
114
+ throw context.refusal(foreign);
115
+ const root = context.projectRootOf(a.root);
116
+ const documents = (await context.listSpecs()).filter((s) => requirementKinds.has(s.type));
117
+ const byId = new Map(documents.map((doc) => [doc.id, doc]));
118
+ const scanned = context.cachedScan(root, root);
119
+ const evidence = (0, test_evidence_1.readTestEvidence)(root);
120
+ const currentHead = headOf(root);
121
+ const freshness = (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(root), head: currentHead || null, now: new Date() });
122
+ // A-SPEC-719: graph current plus a requirement lane that is current or the owner-chosen
123
+ // lexical-only not-adopted/suppressed. The source lane is reported, never required.
124
+ const freshnessCurrent = (0, freshness_coordinator_1.intakeUsable)(freshness);
125
+ // Triage remains read-only with respect to its decision: unavailable or
126
+ // stale evidence still returns ambiguity. The optional bridge merely
127
+ // requests the same detached, lease-coalesced refresh as the Stop hook.
128
+ let refresh;
129
+ if (!freshnessCurrent && context.requestFreshness) {
130
+ try {
131
+ refresh = context.requestFreshness(root);
132
+ }
133
+ catch {
134
+ refresh = { status: 'failed' };
135
+ }
136
+ }
137
+ const graph = readGraphEvidence(root, currentHead, documents);
138
+ const fresh = (0, test_evidence_1.isFresh)(evidence, currentHead) && evidence?.passed === true;
139
+ const lineageEvidence = {};
140
+ for (const doc of documents) {
141
+ const reqId = lineageOf(doc.id, byId);
142
+ if (!reqId)
143
+ continue;
144
+ const record = lineageEvidence[reqId] ??= { implementationAnchors: [], freshGreenTests: false };
145
+ if (doc.type !== 'A-SPEC')
146
+ continue;
147
+ for (const file of scanned)
148
+ if (file.implementsSpecs.includes(doc.id))
149
+ record.implementationAnchors.push(file.sourcePath);
150
+ if (fresh && (evidence?.executedByAspec[doc.id] ?? 0) > 0)
151
+ record.freshGreenTests = true;
152
+ }
153
+ for (const value of Object.values(lineageEvidence))
154
+ value.implementationAnchors.sort();
155
+ const tier = (0, tier_1.resolveSemanticTier)();
156
+ // A-SPEC-719: the owner's transfer switch is lexical-only for triage too — the prompt is not
157
+ // embedded (a cloud tier would send it out); the state reads as the owner-chosen not-adopted.
158
+ // The switch may live in only one process's env (hooks and MCP servers see different envs), so a
159
+ // receipt the refresh child recorded as suppressed also keeps this run from embedding.
160
+ const suppressed = (typeof process.env.HOLMES_NO_SEMANTIC_WARM === 'string' && process.env.HOLMES_NO_SEMANTIC_WARM !== '')
161
+ || freshness?.requirementSemantic === 'suppressed';
162
+ const runtime = suppressed ? null : (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
163
+ const query = runtime ? await runtime.embedQuery(a.prompt) : null;
164
+ const semanticCandidates = [];
165
+ let covered = 0;
166
+ if (runtime && query)
167
+ for (const doc of documents) {
168
+ const reqId = lineageOf(doc.id, byId);
169
+ if (!reqId)
170
+ continue;
171
+ const vector = runtime.cachedDocVector((0, requirement_triage_1.canonicalRequirementDocument)(doc, reqId));
172
+ if (vector) {
173
+ covered++;
174
+ semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
175
+ }
176
+ }
177
+ const semanticState = suppressed ? 'not-adopted'
178
+ : runtime === null || query === null
179
+ ? (tier.tier === 'none' && !tier.localRuntimePresent ? 'not-adopted' : 'unavailable')
180
+ : covered === documents.length ? 'covered' : 'cold';
181
+ const readiness = tier.tier === 'none' && tier.localRuntimePresent ? (0, model_cache_1.readLocalModelReadiness)() : null;
182
+ const availability = semanticState === 'covered' ? 'available'
183
+ : semanticState === 'cold' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
184
+ : 'unavailable';
185
+ const semantic = { tier: tier.tier, covered, total: documents.length, state: semanticState,
186
+ availability, ...(suppressed ? { suppressed: true } : {}),
187
+ ...(readiness ? { localState: readiness.state, recovery: readiness.recovery } : {}) };
188
+ // lexicalOnly describes THIS run: no semantic score contributed to its ranking.
189
+ const lexical = semanticCandidates.length === 0;
190
+ const ranked = (0, requirement_triage_1.triageRequirements)({ prompt: a.prompt, documents, evidence: lineageEvidence,
191
+ semanticCandidates, semantic, graph: { state: graph.status }, topK: a.topK });
192
+ const result = freshnessCurrent ? ranked : {
193
+ ...ranked, verdict: 'ambiguous',
194
+ reasons: [...ranked.reasons, `freshness-${freshness?.state ?? 'absent'}`],
195
+ uncertainty: [...ranked.uncertainty, `freshness-${freshness?.state ?? 'absent'}`],
196
+ };
197
+ const promptDigest = `sha256:${crypto.createHash('sha256').update(a.prompt).digest('hex')}`;
198
+ const executionState = evidence === undefined ? 'absent'
199
+ : !(0, test_evidence_1.isFresh)(evidence, currentHead) ? 'stale'
200
+ : evidence.passed ? 'fresh-green' : 'fresh-failed';
201
+ const provenance = result.candidates.map((candidate) => ({
202
+ reqId: candidate.reqId,
203
+ documents: candidate.documents.map((document) => ({ id: document.id, type: document.type, status: document.status, dependsOn: document.dependsOn ?? [] })),
204
+ implementationAnchors: candidate.implementationAnchors,
205
+ graphProvenance: Object.fromEntries(candidate.documents.map((document) => [document.id, graph.provenanceBySpec[document.id] ?? null])),
206
+ executionEvidence: { state: executionState, recordedHead: evidence?.head ?? null, currentHead },
207
+ }));
208
+ const answer = { schema: 'requirement-triage/1', ...result, ...(lexical ? { lexicalOnly: true } : {}), promptDigest, semantic, provenance,
209
+ graph: { status: graph.status, sourceCommit: graph.sourceCommit, graphAsOf: graph.graphAsOf, resolutionLimits: graph.resolutionLimits },
210
+ graphBasis: { head: currentHead, governedDocumentCount: documents.length, scannedSourceCount: scanned.length },
211
+ freshness: freshness === null ? { state: 'absent' } : freshness,
212
+ refresh: refresh ?? { status: freshnessCurrent ? 'not-needed' : 'unavailable' } };
213
+ if (!a.persist || !freshnessCurrent || freshness === null)
214
+ return answer;
215
+ const artifact = (0, requirement_triage_evidence_1.writeRequirementTriageEvidence)(root, { schema: 'requirement-triage-evidence/2', promptDigest,
216
+ workspaceId: freshness.workspaceId, head: freshness.head, freshnessGeneration: freshness.generation, result: answer });
217
+ return { ...answer, evidenceDigest: artifact.digest, persistedTo: artifact.path, artifact };
218
+ },
219
+ };
220
+ }
@@ -10,8 +10,9 @@ export interface ReviewEvidenceContext {
10
10
  projectRootOf(root: string): string;
11
11
  basisFor(root: string | undefined, withDisk?: boolean): Basis;
12
12
  hasElicitor(): boolean;
13
- tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
13
+ tryElicit(kind: string, target: string, summary: string, timeoutBehavior?: 'queue' | 'autonomous-approve'): Promise<ElicitOutcome>;
14
14
  elicitApproval(reason?: string): Approval;
15
+ autonomousApproval(derivedFrom?: string[], source?: 'immediate' | 'timeout'): Approval;
15
16
  resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
16
17
  kind: string;
17
18
  target: string;
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createReviewEvidenceHandlers = createReviewEvidenceHandlers;
37
- // @implements A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1
37
+ // @implements A-SPEC-718, A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1
38
38
  const path = __importStar(require("node:path"));
39
39
  const findings_1 = require("../../review/findings");
40
40
  const review_targets_1 = require("../../review/review-targets");
@@ -44,6 +44,7 @@ const ledger_store_1 = require("../../governance/ledger-store");
44
44
  const ledger_lock_1 = require("../../governance/ledger-lock");
45
45
  const approval_grants_1 = require("../../governance/approval-grants");
46
46
  const provenance_chain_1 = require("../../governance/provenance-chain");
47
+ const autonomy_1 = require("../../governance/autonomy");
47
48
  function createReviewEvidenceHandlers(context) {
48
49
  return {
49
50
  async review_record(a) {
@@ -104,6 +105,7 @@ function createReviewEvidenceHandlers(context) {
104
105
  const elicitExpiries = new Map();
105
106
  if (context.hasElicitor()) {
106
107
  try {
108
+ const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
107
109
  const snapshot = new Map();
108
110
  for (const f of new findings_1.FindingsLedger(findingsFile).list())
109
111
  snapshot.set(f.id, f);
@@ -121,11 +123,13 @@ function createReviewEvidenceHandlers(context) {
121
123
  }
122
124
  if (context.resolveHandlerApproval(a.root, env0, { kind: 'review-resolve', target: f.id }, new Date().toISOString()) !== undefined)
123
125
  continue; // an open door never summons a human
124
- const out = await context.tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`);
126
+ const out = await context.tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`, autonomyOn ? 'autonomous-approve' : 'queue');
125
127
  if (out.kind === 'answered' && out.decision.granted)
126
- elicitGrants.set(f.id, context.elicitApproval(out.decision.reason));
128
+ elicitGrants.set(f.id, { approval: context.elicitApproval(out.decision.reason), source: 'elicitation' });
127
129
  else if (out.kind === 'answered')
128
130
  elicitDenials.set(f.id, out.decision.reason ?? '(사유 없음)');
131
+ else if (out.kind === 'expired' && autonomyOn)
132
+ elicitGrants.set(f.id, { approval: context.autonomousApproval(undefined, 'timeout'), source: 'autonomous' });
129
133
  else if (out.kind === 'expired')
130
134
  elicitExpiries.set(f.id, out.waitedMs);
131
135
  }
@@ -190,8 +194,8 @@ function createReviewEvidenceHandlers(context) {
190
194
  const g = elicitGrants.get(f.id);
191
195
  if (g) {
192
196
  elicitGrants.delete(f.id);
193
- rrResolved = { approval: g, source: 'elicitation' };
194
- elicitationLifts.push({ id: f.id, approval: g });
197
+ rrResolved = { approval: g.approval, source: g.source };
198
+ elicitationLifts.push({ id: f.id, approval: g.approval });
195
199
  }
196
200
  }
197
201
  if (rrResolved === undefined) {
@@ -32,12 +32,19 @@ export declare function createSliceOrchestrationHandlers(context: SliceOrchestra
32
32
  title: string;
33
33
  objective: string;
34
34
  filesToTouch: string[];
35
+ triage_evidence?: unknown;
35
36
  }): Promise<{
36
37
  ok: boolean;
37
38
  reason: string;
38
39
  existing: string[];
39
40
  specsCreated: string[];
40
41
  unreadable: string[];
42
+ } | {
43
+ ok: boolean;
44
+ reason: string;
45
+ specsCreated: string[];
46
+ unreadable: string[];
47
+ existing?: undefined;
41
48
  } | {
42
49
  ok: boolean;
43
50
  specsCreated: string[];
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.tspecFor = tspecFor;
37
37
  exports.createSliceOrchestrationHandlers = createSliceOrchestrationHandlers;
38
- // @implements A-SPEC-609, A-SPEC-100.2, A-SPEC-156, A-SPEC-203, A-SPEC-204, A-SPEC-298, A-SPEC-299, A-SPEC-536.1, A-SPEC-546.1, A-SPEC-565.2, A-SPEC-587.2, A-SPEC-501.1
38
+ // @implements A-SPEC-724, A-SPEC-609, A-SPEC-100.2, A-SPEC-156, A-SPEC-203, A-SPEC-204, A-SPEC-298, A-SPEC-299, A-SPEC-536.1, A-SPEC-546.1, A-SPEC-565.2, A-SPEC-587.2, A-SPEC-501.1
39
39
  const fs = __importStar(require("node:fs"));
40
40
  const path = __importStar(require("node:path"));
41
41
  const spec_store_1 = require("../../spec/spec-store");
@@ -43,6 +43,7 @@ const root_1 = require("../../project/root");
43
43
  const yaml_scalar_1 = require("../../spec/yaml-scalar");
44
44
  const draft_1 = require("../../reverse/draft");
45
45
  const anchor_comment_1 = require("../../rtm/anchor-comment");
46
+ const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
46
47
  /**
47
48
  * @implements A-SPEC-652.1 — the T-SPEC that belongs to an A-SPEC, by the mirror rule the
48
49
  * author-slice playbook states (the chain inherits the parent's number, dot included): the
@@ -233,6 +234,12 @@ depends_on:
233
234
  if (existingFiles.length > 0) {
234
235
  return { ok: false, reason: `spec_slice_init: ${existingFiles.length} target file(s) already exist — nothing written`, existing: existingFiles, specsCreated: [], unreadable: [] };
235
236
  }
237
+ // @implements A-SPEC-724 — this act writes a new REQ, so it crosses the same intake boundary as
238
+ // spec_create(type=REQ): one shared validator, after the deterministic refusals above and
239
+ // before the first byte below.
240
+ const intake = (0, requirement_triage_evidence_1.validateRequirementIntake)(root, a.triage_evidence);
241
+ if (!intake.ok)
242
+ return { ok: false, reason: intake.reason, specsCreated: [], unreadable: [] };
236
243
  fs.mkdirSync(path.join(specsDir, '01_req'), { recursive: true });
237
244
  fs.mkdirSync(path.join(specsDir, '02_h-spec', 'functional'), { recursive: true });
238
245
  fs.mkdirSync(path.join(specsDir, '03_a-spec'), { recursive: true });