@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
@@ -3,14 +3,30 @@ import { Spec } from '../../spec/spec-parser';
3
3
  import { ScannedFile } from '../../cpg/cpg-scanner';
4
4
  import { Approval } from '../../guardrail/risk-gate';
5
5
  import { ElicitOutcome } from '../elicit-approval';
6
+ import { ApprovalIntent } from '../approval-intent';
7
+ import { ApprovalAdapter } from '../approval-adapters';
6
8
  export interface SpecApprovalContext {
7
9
  store: SpecStore;
8
10
  resolver(specs: Spec[]): (id: string) => Spec | null;
9
11
  projectRootOf(root: string): string;
10
12
  cachedScan(root: string, repoRoot?: string): ScannedFile[];
11
- tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
13
+ tryElicit(kind: string, target: string, summary: string, timeoutBehavior?: 'queue' | 'autonomous-approve'): Promise<ElicitOutcome>;
12
14
  elicitApproval(reason?: string): Approval;
13
- autonomousApproval(derivedFrom?: string[]): Approval;
15
+ autonomousApproval(derivedFrom?: string[], source?: 'immediate' | 'timeout'): Approval;
16
+ approvalAdapter(): ApprovalAdapter;
17
+ approvalHarness(): string;
18
+ prepareHostApproval(input: {
19
+ kind: string;
20
+ target: string;
21
+ subject: string;
22
+ root?: string;
23
+ }): ApprovalIntent;
24
+ consumeHostApproval(input: {
25
+ kind: string;
26
+ target: string;
27
+ subject: string;
28
+ root?: string;
29
+ }): Approval | undefined;
14
30
  resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
15
31
  kind: string;
16
32
  target: string;
@@ -52,11 +68,18 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
52
68
  } | {
53
69
  ok: boolean;
54
70
  reason: string;
71
+ approvalIntent?: undefined;
72
+ conflict?: undefined;
73
+ } | {
74
+ ok: boolean;
75
+ reason: string;
76
+ approvalIntent: ApprovalIntent;
55
77
  conflict?: undefined;
56
78
  } | {
57
79
  ok: boolean;
58
80
  reason: string;
59
81
  conflict: import("../../spec/version-conflict").ConflictDetail;
82
+ approvalIntent?: undefined;
60
83
  } | {
61
84
  dismissUnknown?: string[] | undefined;
62
85
  advisoryHistory?: import("../../rtm/advisory-outcomes").AdvisoryState[] | undefined;
@@ -76,6 +99,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
76
99
  digest: string;
77
100
  ok?: undefined;
78
101
  reason?: undefined;
102
+ approvalIntent?: undefined;
79
103
  conflict?: undefined;
80
104
  }>;
81
105
  /**
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createSpecApprovalHandlers = createSpecApprovalHandlers;
37
- // @implements A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
37
+ // @implements A-SPEC-718, A-SPEC-551.1, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
38
38
  // @implements A-SPEC-631
39
39
  const fs = __importStar(require("node:fs"));
40
40
  const path = __importStar(require("node:path"));
@@ -50,6 +50,7 @@ const version_conflict_1 = require("../../spec/version-conflict");
50
50
  const ledger_store_1 = require("../../governance/ledger-store");
51
51
  const provenance_chain_1 = require("../../governance/provenance-chain");
52
52
  const review_targets_1 = require("../../review/review-targets");
53
+ const approval_policy_1 = require("../approval-policy");
53
54
  function createSpecApprovalHandlers(context) {
54
55
  const { store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval } = context;
55
56
  return {
@@ -90,57 +91,81 @@ function createSpecApprovalHandlers(context) {
90
91
  // @implements A-SPEC-649 — the digest of what the operator will read rides the request.
91
92
  subject = target ? (0, spec_digest_1.specDigest)(target.spec) : undefined;
92
93
  if (target) {
93
- // @implements A-SPEC-532.2 — the autonomous gate sits BEFORE the human ask: when the
94
- // out-of-band autonomy switch is on AND the spec is low/mid-risk (never gate-behavior, an
95
- // architecture/taint file, or an upstream REQ/H/C — those stay human), the agent seals it
96
- // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
97
- // A-SPEC-532.2). Off, or a hitl-classed spec, falls straight through to the elicitor
98
- // unchanged — the autonomous-OFF path is byte-identical to before.
99
- // @implements A-SPEC-553.1 — autonomy is the out-of-band env switch OR a valid, non-expired
100
- // session envelope marker under this project's `.ax/state/` (which an agent cannot write).
101
- const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
102
- // @implements A-SPEC-587 — an upstream REQ/H-SPEC is graded by the A-SPECs beneath it, so
103
- // the store is consulted for its descendants (only then: the list is a cost the auto-grade
104
- // A-SPEC/T-SPEC path does not pay). Unknown scope (none yet) keeps the human answer.
105
- const upstream = target.spec.type === 'REQ' || target.spec.type === 'H-SPEC';
106
- const below = upstream ? (0, autonomy_1.descendantAspecs)(target.spec, await store.list()) : undefined;
107
- // @implements A-SPEC-649 — the grade is recorded on the request either way (the screen shows it).
108
- risk = (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below);
109
- if (autonomyOn
110
- && (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below) === 'auto') {
111
- approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
112
- }
113
- else if (autonomyOn) {
114
- // @implements A-SPEC-551.1 — hitl-grade spec under autonomy: the in-session elicitation
115
- // dialog is auto-acceptable by an auto-mode client (the protocol cannot tell a human
116
- // from an auto-accept), so a governance-critical spec is never offered it. Do nothing
117
- // here — approveResolved stays undefined and the fail-closed refuse+enqueue path below
118
- // routes the act to the out-of-band human queue (holmes-kit approve). The A-SPEC-532.1
119
- // bound ("governance-critical specs never leave the human channel") thus becomes
120
- // ENFORCED, not aspirational. Autonomy OFF (the else) and the auto-grade branch above
121
- // stay byte-identical to before.
94
+ const targetSubject = (0, spec_digest_1.specDigest)(target.spec);
95
+ // A host-gated commit is a continuation of this exact original action. It is checked
96
+ // before presentation and is memory-only, so a bare retry never carries authority.
97
+ const hostApproval = context.consumeHostApproval({ kind: action.kind, target: action.target, subject: targetSubject, root: a.root });
98
+ if (hostApproval)
99
+ approveResolved = { approval: hostApproval, source: 'elicitation' };
100
+ if (approveResolved !== undefined) {
101
+ // The rest of the existing seal path owns all validation and audit behavior.
122
102
  }
123
103
  else {
124
- const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
125
- // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
126
- // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
127
- // more consequential act) as a first approval. The cap cuts the title, never the marker.
128
- const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
129
- if (out.kind === 'answered' && out.decision.granted) {
130
- approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
104
+ // @implements A-SPEC-532.2 — the autonomous gate sits BEFORE the human ask: when the
105
+ // out-of-band autonomy switch is on AND the spec is low/mid-risk (never gate-behavior, an
106
+ // architecture/taint file, or an upstream REQ/H/C — those stay human), the agent seals it
107
+ // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
108
+ // A-SPEC-532.2). With autonomy off, every HITL spec uses the established elicitor path.
109
+ // With autonomy on, A-SPEC-718 preserves that UI only for known high-risk/architecture
110
+ // exceptions; an unclassified upstream request is intentionally queued instead.
111
+ // @implements A-SPEC-553.1 — autonomy is the out-of-band env switch OR a valid, non-expired
112
+ // session envelope marker under this project's `.ax/state/` (which an agent cannot write).
113
+ const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
114
+ // @implements A-SPEC-587 — an upstream REQ/H-SPEC is graded by the A-SPECs beneath it, so
115
+ // the store is consulted for its descendants (only then: the list is a cost the auto-grade
116
+ // A-SPEC/T-SPEC path does not pay). Unknown scope (none yet) keeps the human answer.
117
+ const upstream = target.spec.type === 'REQ' || target.spec.type === 'H-SPEC';
118
+ const below = upstream ? (0, autonomy_1.descendantAspecs)(target.spec, await store.list()) : undefined;
119
+ // @implements A-SPEC-649 — the grade is recorded on the request either way (the screen shows it).
120
+ risk = (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below);
121
+ if (autonomyOn && risk === 'auto') {
122
+ approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
131
123
  }
132
- else if (out.kind === 'answered') {
133
- // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
134
- // entry is filed — a decided request is not a pending one (REQ-246 visibility).
135
- return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
124
+ else if (autonomyOn && !(0, autonomy_1.requiresAutonomousApprovalPrompt)(target.spec, below)) {
125
+ // @implements A-SPEC-551.1 — autonomous mode does not turn an ordinary HITL request
126
+ // into a human decision. An unclassified upstream request is queued without opening
127
+ // a dialog; A-SPEC-718's architecture/high-risk exceptions take the next branch.
136
128
  }
137
- else if (out.kind === 'expired') {
138
- // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
139
- // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
140
- // message learned to say what happened.
141
- elicitExpiredMs = out.waitedMs;
129
+ else {
130
+ const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
131
+ // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
132
+ // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
133
+ // more consequential act) as a first approval. The cap cuts the title, never the marker.
134
+ const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`, autonomyOn ? 'autonomous-approve' : 'queue');
135
+ const presentation = out.kind === 'answered'
136
+ ? (out.decision.granted ? { kind: 'approve', reason: out.decision.reason } : { kind: 'deny', reason: out.decision.reason })
137
+ : out.kind === 'expired' ? { kind: 'timeout' } : { kind: 'unavailable' };
138
+ const decision = (0, approval_policy_1.resolveApprovalPresentation)(presentation, { autonomous: autonomyOn, harness: context.approvalHarness() });
139
+ if (decision.kind === 'approved' && presentation.kind === 'approve') {
140
+ approveResolved = { approval: elicitApproval(out.kind === 'answered' ? out.decision.reason : undefined), source: 'elicitation' };
141
+ }
142
+ else if (decision.kind === 'approved' && presentation.kind === 'timeout') {
143
+ approveResolved = { approval: autonomousApproval(undefined, 'timeout'), source: 'autonomous' };
144
+ }
145
+ else if (out.kind === 'answered') {
146
+ // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
147
+ // entry is filed — a decided request is not a pending one (REQ-246 visibility).
148
+ return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
149
+ }
150
+ else if (out.kind === 'expired') {
151
+ // @implements A-SPEC-718 — a direct in-session prompt may time out. Only an explicit
152
+ // autonomous posture may turn that absence into a one-shot, audit-distinguishable grant.
153
+ // OFF keeps the established fail-closed expiry + queue behavior.
154
+ elicitExpiredMs = out.waitedMs;
155
+ }
156
+ else if (out.kind === 'silent' && context.approvalAdapter().kind === 'host-gated-tool') {
157
+ // The adapter's sensitive `approval_commit` invocation is rendered in the same agent
158
+ // session. Its complete immutable payload is what the host shows and what the server
159
+ // checks before a retry can consume it; it is never a config/env authorization.
160
+ const intent = context.prepareHostApproval({ kind: action.kind, target: action.target, subject: targetSubject, root: a.root });
161
+ return {
162
+ ok: false,
163
+ reason: `spec_approve: 이 세션은 직접 승인 폼을 광고하지 않았습니다. Holmes-Kit 승인 확인 UI에서 approval_commit 을 확인한 뒤 같은 spec_approve 를 다시 시도하십시오.`,
164
+ approvalIntent: intent,
165
+ };
166
+ }
167
+ // silent: the channel gave no answer — fall through to the byte-identical refusal.
142
168
  }
143
- // silent: the channel gave no answer — fall through to the byte-identical refusal.
144
169
  }
145
170
  }
146
171
  }
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createSpecAuthoringHandlers = createSpecAuthoringHandlers;
37
+ // @implements A-SPEC-724, A-SPEC-719
37
38
  // @implements A-SPEC-618, A-SPEC-100.2, A-SPEC-128, A-SPEC-151, A-SPEC-169, A-SPEC-189, A-SPEC-420, A-SPEC-174, A-SPEC-252, A-SPEC-188, A-SPEC-146, A-SPEC-184
38
39
  const fs = __importStar(require("node:fs"));
39
40
  const path = __importStar(require("node:path"));
@@ -44,6 +45,7 @@ const legacy_format_1 = require("../../spec/legacy-format");
44
45
  const write_target_1 = require("../../guardrail/write-target");
45
46
  const root_1 = require("../../project/root");
46
47
  const spec_id_guard_1 = require("../spec-id-guard");
48
+ const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
47
49
  function createSpecAuthoringHandlers(context) {
48
50
  const { store, projectRootOf, resolver } = context;
49
51
  return {
@@ -53,7 +55,7 @@ function createSpecAuthoringHandlers(context) {
53
55
  // frontmatter and a machine-local absolute path lands in a git-shared document. A blacklist,
54
56
  // not a whitelist: domain fields (`priority`, `slice`, …) must keep flowing through without
55
57
  // anyone maintaining a list of them.
56
- const { type, id, title, depends_on = [], root: reqRoot, ...extra } = a;
58
+ const { type, id, title, depends_on = [], root: reqRoot, triage_evidence, ...extra } = a;
57
59
  // The server binds its spec store once, so a `root` naming another project cannot be honoured.
58
60
  // Silently writing to this one is a data-integrity problem; refusing says so. Compared by
59
61
  // resolved identity (A-SPEC-163) — `<root>//.` is the same directory, not a different project.
@@ -74,7 +76,11 @@ function createSpecAuthoringHandlers(context) {
74
76
  if (boundSpecsRoot === null)
75
77
  return null;
76
78
  try {
77
- const d = projectRootOf(boundSpecsRoot);
79
+ // The first REQ is allowed to create the specs directory itself. Resolve from its
80
+ // existing `.ax` parent in that case; resolving a non-existent `.ax/specs` path cannot
81
+ // discover the already-bound workspace and would incorrectly reject valid evidence.
82
+ const derivationStart = fs.existsSync(boundSpecsRoot) ? boundSpecsRoot : path.dirname(boundSpecsRoot);
83
+ const d = projectRootOf(derivationStart);
78
84
  return fs.existsSync(path.join(d, '.ax')) ? d : null;
79
85
  }
80
86
  catch {
@@ -241,6 +247,18 @@ function createSpecAuthoringHandlers(context) {
241
247
  };
242
248
  }
243
249
  }
250
+ // @implements A-SPEC-719 — requirement intake is shared MCP enforcement, not harness prose.
251
+ // This stays immediately before the sole write. Structural, foreign-root, and occupied-target
252
+ // refusals above are deterministic and write nothing; preserving them lets callers repair the
253
+ // actual malformed request instead of first manufacturing evidence for an impossible create.
254
+ // A new REQ may still be born only from a current, prompt-bound v2 triage artifact. H/A/T
255
+ // creation remains the established continuation path and needs no second intake receipt.
256
+ if (type === 'REQ') {
257
+ const root = derivedForCreate ?? (typeof reqRoot === 'string' && reqRoot !== '' ? projectRootOf(reqRoot) : null);
258
+ const intake = root ? (0, requirement_triage_evidence_1.validateRequirementIntake)(root, triage_evidence) : (0, requirement_triage_evidence_1.validateRequirementIntake)('', undefined);
259
+ if (!intake.ok)
260
+ return { ok: false, reason: intake.reason };
261
+ }
244
262
  try {
245
263
  await store.write(spec);
246
264
  }
@@ -5,6 +5,7 @@ import { type DecisionRecord, type DecisionCitation } from '../rtm/rtm-builder';
5
5
  import { Basis } from './basis';
6
6
  import { Approval } from '../guardrail/risk-gate';
7
7
  import { Elicitor } from './elicit-approval';
8
+ import { ApprovalIntent } from './approval-intent';
8
9
  /**
9
10
  * @implements A-SPEC-189 §7 (round 10)
10
11
  * A DELIBERATE refusal, distinguished by construction rather than by class.
@@ -32,6 +33,8 @@ import { ChangeSourceInfo } from '../project/change-source';
32
33
  */
33
34
  export interface ElicitOpts {
34
35
  elicit?: Elicitor;
36
+ /** The negotiated MCP capability, not the presence of our injected wrapper. */
37
+ elicitationAvailable?: () => boolean;
35
38
  clientName?: () => string;
36
39
  observeInvocation?: (root: string) => void | Promise<void>;
37
40
  }
@@ -62,6 +65,12 @@ export declare function collectDecisions(root: string, scanned: readonly Scanned
62
65
  citations: DecisionCitation[];
63
66
  };
64
67
  declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
68
+ approval_commit: (a: ApprovalIntent) => Promise<{
69
+ ok: true;
70
+ } | {
71
+ ok: false;
72
+ reason: string;
73
+ }>;
65
74
  entity_integrate(a: {
66
75
  root?: string;
67
76
  operation?: string;
@@ -383,6 +392,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
383
392
  head?: string;
384
393
  since?: string;
385
394
  }) => Promise<{
395
+ requirementSemanticWarm?: {
396
+ tier: string;
397
+ computed: number;
398
+ cached: number;
399
+ } | undefined;
386
400
  semanticWarm?: {
387
401
  tier: string;
388
402
  computed: number;
@@ -550,12 +564,19 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
550
564
  title: string;
551
565
  objective: string;
552
566
  filesToTouch: string[];
567
+ triage_evidence?: unknown;
553
568
  }) => Promise<{
554
569
  ok: boolean;
555
570
  reason: string;
556
571
  existing: string[];
557
572
  specsCreated: string[];
558
573
  unreadable: string[];
574
+ } | {
575
+ ok: boolean;
576
+ reason: string;
577
+ specsCreated: string[];
578
+ unreadable: string[];
579
+ existing?: undefined;
559
580
  } | {
560
581
  ok: boolean;
561
582
  specsCreated: string[];
@@ -591,6 +612,130 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
591
612
  root: string;
592
613
  harness?: import("../cli/agents").Agent;
593
614
  }): Promise<import("../project/workspace-preflight").WorkspacePreflight>;
615
+ requirement_triage: (a: {
616
+ root: string;
617
+ prompt: string;
618
+ topK?: number;
619
+ persist?: boolean;
620
+ }) => Promise<{
621
+ promptDigest: string;
622
+ semantic: {
623
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
624
+ recovery?: string | undefined;
625
+ suppressed?: true | undefined;
626
+ tier: "local" | "none" | "cloud";
627
+ covered: number;
628
+ total: number;
629
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
630
+ availability: string;
631
+ };
632
+ provenance: {
633
+ reqId: string;
634
+ documents: {
635
+ id: string;
636
+ type: import("../review/requirement-triage").RequirementDocumentKind;
637
+ status: string;
638
+ dependsOn: readonly string[];
639
+ }[];
640
+ implementationAnchors: string[];
641
+ graphProvenance: {
642
+ [k: string]: {} | null;
643
+ };
644
+ executionEvidence: {
645
+ state: string;
646
+ recordedHead: string | null;
647
+ currentHead: string;
648
+ };
649
+ }[];
650
+ graph: {
651
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
652
+ sourceCommit: string | null;
653
+ graphAsOf: string | null;
654
+ resolutionLimits: string[];
655
+ };
656
+ graphBasis: {
657
+ head: string;
658
+ governedDocumentCount: number;
659
+ scannedSourceCount: number;
660
+ };
661
+ freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
662
+ state: string;
663
+ };
664
+ refresh: {
665
+ status: "spawned" | "coalesced" | "failed";
666
+ generation?: string;
667
+ } | {
668
+ status: "unavailable" | "not-needed";
669
+ };
670
+ lexicalOnly?: true | undefined;
671
+ verdict: import("../review/requirement-triage").RequirementVerdict;
672
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
673
+ reasons: string[];
674
+ uncertainty: string[];
675
+ schema: "requirement-triage/1";
676
+ } | {
677
+ evidenceDigest: string;
678
+ persistedTo: string;
679
+ artifact: {
680
+ digest: string;
681
+ path: string;
682
+ };
683
+ promptDigest: string;
684
+ semantic: {
685
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
686
+ recovery?: string | undefined;
687
+ suppressed?: true | undefined;
688
+ tier: "local" | "none" | "cloud";
689
+ covered: number;
690
+ total: number;
691
+ state: "covered" | "unavailable" | "not-adopted" | "cold";
692
+ availability: string;
693
+ };
694
+ provenance: {
695
+ reqId: string;
696
+ documents: {
697
+ id: string;
698
+ type: import("../review/requirement-triage").RequirementDocumentKind;
699
+ status: string;
700
+ dependsOn: readonly string[];
701
+ }[];
702
+ implementationAnchors: string[];
703
+ graphProvenance: {
704
+ [k: string]: {} | null;
705
+ };
706
+ executionEvidence: {
707
+ state: string;
708
+ recordedHead: string | null;
709
+ currentHead: string;
710
+ };
711
+ }[];
712
+ graph: {
713
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
714
+ sourceCommit: string | null;
715
+ graphAsOf: string | null;
716
+ resolutionLimits: string[];
717
+ };
718
+ graphBasis: {
719
+ head: string;
720
+ governedDocumentCount: number;
721
+ scannedSourceCount: number;
722
+ };
723
+ freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
724
+ state: string;
725
+ };
726
+ refresh: {
727
+ status: "spawned" | "coalesced" | "failed";
728
+ generation?: string;
729
+ } | {
730
+ status: "unavailable" | "not-needed";
731
+ };
732
+ lexicalOnly?: true | undefined;
733
+ verdict: import("../review/requirement-triage").RequirementVerdict;
734
+ candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
735
+ reasons: string[];
736
+ uncertainty: string[];
737
+ schema: "requirement-triage/1";
738
+ }>;
594
739
  ledger_reconcile: (a: {
595
740
  root?: string;
596
741
  nonce: string;
@@ -876,11 +1021,18 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
876
1021
  } | {
877
1022
  ok: boolean;
878
1023
  reason: string;
1024
+ approvalIntent?: undefined;
1025
+ conflict?: undefined;
1026
+ } | {
1027
+ ok: boolean;
1028
+ reason: string;
1029
+ approvalIntent: ApprovalIntent;
879
1030
  conflict?: undefined;
880
1031
  } | {
881
1032
  ok: boolean;
882
1033
  reason: string;
883
1034
  conflict: import("../spec/version-conflict").ConflictDetail;
1035
+ approvalIntent?: undefined;
884
1036
  } | {
885
1037
  dismissUnknown?: string[] | undefined;
886
1038
  advisoryHistory?: import("../rtm/advisory-outcomes").AdvisoryState[] | undefined;
@@ -900,6 +1052,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
900
1052
  digest: string;
901
1053
  ok?: undefined;
902
1054
  reason?: undefined;
1055
+ approvalIntent?: undefined;
903
1056
  conflict?: undefined;
904
1057
  }>;
905
1058
  spec_list: (a: any) => Promise<{
@@ -38,7 +38,7 @@ exports.isHandlerRefusal = isHandlerRefusal;
38
38
  exports.unreadableAmong = unreadableAmong;
39
39
  exports.makeHandlers = makeHandlers;
40
40
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627
41
+ // @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713
42
42
  // @implements A-SPEC-643
43
43
  // @implements A-SPEC-642
44
44
  // @implements A-SPEC-642
@@ -82,6 +82,8 @@ const graph_operations_1 = require("./handlers/graph-operations");
82
82
  // @implements A-SPEC-632 — the rebuild paths discharge shares with reindex.
83
83
  const graph_operations_2 = require("./handlers/graph-operations");
84
84
  const maintenance_analysis_1 = require("./handlers/maintenance-analysis");
85
+ const requirement_triage_1 = require("./handlers/requirement-triage");
86
+ const rtm_refresh_1 = require("../hooks/rtm-refresh");
85
87
  const taint_screening_1 = require("./handlers/taint-screening");
86
88
  const cpg_scanner_1 = require("../cpg/cpg-scanner");
87
89
  const scan_cache_1 = require("../cpg/scan-cache");
@@ -118,6 +120,9 @@ const write_target_1 = require("../guardrail/write-target");
118
120
  const spec_store_1 = require("../spec/spec-store");
119
121
  const risk_gate_1 = require("../guardrail/risk-gate");
120
122
  const elicit_approval_1 = require("./elicit-approval");
123
+ const approval_commit_1 = require("./approval-commit");
124
+ const approval_intent_1 = require("./approval-intent");
125
+ const approval_adapters_1 = require("./approval-adapters");
121
126
  const approval_queue_1 = require("../governance/approval-queue");
122
127
  const approval_grants_1 = require("../governance/approval-grants");
123
128
  const ledger_store_1 = require("../governance/ledger-store");
@@ -677,6 +682,36 @@ function collectDecisions(root, scanned, specs) {
677
682
  return { decisions, citations };
678
683
  }
679
684
  function makeRawHandlers(store, opts) {
685
+ // These values are process/session scoped and intentionally never reach disk or config. A
686
+ // restarted MCP process invalidates every pending host-gated continuation.
687
+ const approvalContinuations = new approval_commit_1.ApprovalContinuationStore();
688
+ const approvalRunId = crypto.randomUUID();
689
+ const canonicalHarness = () => {
690
+ const raw = opts?.clientName?.().trim().toLowerCase() ?? 'unknown';
691
+ if (raw.includes('claude'))
692
+ return 'claude';
693
+ if (raw.includes('antigravity') || raw === 'agy')
694
+ return 'antigravity';
695
+ if (raw.includes('codex'))
696
+ return 'codex';
697
+ return raw;
698
+ };
699
+ const approvalAdapter = () => (0, approval_adapters_1.selectApprovalAdapter)({
700
+ harness: canonicalHarness(),
701
+ formElicitation: opts?.elicitationAvailable?.() ?? Boolean(opts?.elicit),
702
+ });
703
+ const approvalWorkspace = (root) => projectRootOf(root ?? store.specsRoot);
704
+ const prepareHostApproval = (input) => {
705
+ const intent = (0, approval_intent_1.createApprovalIntent)({
706
+ ...input, workspace: approvalWorkspace(input.root), runId: approvalRunId, harness: canonicalHarness(),
707
+ });
708
+ approvalContinuations.prepare(intent);
709
+ return intent;
710
+ };
711
+ const consumeHostApproval = (input) => approvalContinuations.consumeForAction({
712
+ kind: input.kind, target: input.target, subject: input.subject,
713
+ workspace: approvalWorkspace(input.root), runId: approvalRunId,
714
+ });
680
715
  // @implements A-SPEC-100.2, A-SPEC-102.1, A-SPEC-111.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-121.4, A-SPEC-128, A-SPEC-130, A-SPEC-131, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-614
681
716
  // @implements A-SPEC-616, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-128, A-SPEC-130, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-534.5, A-SPEC-534.8, A-SPEC-578.4, A-SPEC-614
682
717
  const testExecution = (0, test_execution_1.createTestExecutionHandlers)({
@@ -716,6 +751,15 @@ function makeRawHandlers(store, opts) {
716
751
  specStoreBlindReason: (root, count) => specStoreBlindReason(store, root, count),
717
752
  fileDigestOf,
718
753
  });
754
+ const requirementTriage = (0, requirement_triage_1.createRequirementTriageHandlers)({
755
+ listSpecs: () => store.list(),
756
+ foreignRootReason: root => foreignRootReason(store, root),
757
+ projectRootOf,
758
+ cachedScan,
759
+ assertStoreReachable: (tool, root) => assertSpecStoreReachable(tool, store, root),
760
+ refusal: reason => new HandlerRefusal(reason),
761
+ requestFreshness: rtm_refresh_1.requestBackgroundFreshness,
762
+ });
719
763
  const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
720
764
  // @implements A-SPEC-100.2, A-SPEC-128, A-SPEC-138, A-SPEC-140.2, A-SPEC-189, A-SPEC-461, A-SPEC-512.2, A-SPEC-513.1, A-SPEC-524.1
721
765
  const taintScreening = (0, taint_screening_1.createTaintScreeningHandlers)({
@@ -749,7 +793,7 @@ function makeRawHandlers(store, opts) {
749
793
  // other failure mode (no channel, wrong kind, a throwing elicitor) is `silent`, whose refusal
750
794
  // stays byte-identical to the pre-elicitation one — nothing is ever worse than before the
751
795
  // channel existed.
752
- const tryElicit = async (kind, target, summary) => {
796
+ const tryElicit = async (kind, target, summary, timeoutBehavior = 'queue') => {
753
797
  // @implements A-SPEC-540.1 — operator opt-out: with HOLMES_ELICIT=off the server never shows the
754
798
  // in-client prompt, folding to the byte-identical `silent` (refuse+enqueue) path so claude/agy/
755
799
  // codex all converge on one out-of-band surface (holmes-kit approve). Unset ⇒ unchanged.
@@ -758,7 +802,7 @@ function makeRawHandlers(store, opts) {
758
802
  if (!opts?.elicit || !elicit_approval_1.ELICITABLE_KINDS.has(kind))
759
803
  return { kind: 'silent' };
760
804
  try {
761
- return await opts.elicit({ kind, target, summary });
805
+ return await opts.elicit({ kind, target, summary, timeoutBehavior });
762
806
  }
763
807
  catch {
764
808
  return { kind: 'silent' };
@@ -772,6 +816,16 @@ function makeRawHandlers(store, opts) {
772
816
  token: crypto.randomUUID(),
773
817
  rationale: reason ?? 'elicitation grant',
774
818
  });
819
+ // @implements A-SPEC-532.2 — the autonomous channel: the SAME synthesized-Approval shape that
820
+ // rides the existing seal path, but its actor names `autonomous:<client>` so an audit can tell a
821
+ // self-approved seal from a human-approved (elicitation) or operator (env/grant) one. Single-use
822
+ // by construction — it exists only inside this call, persisted nowhere.
823
+ const autonomousApproval = (derivedFrom, source = 'immediate') => ({
824
+ actor: `${source === 'timeout' ? 'autonomous-timeout' : 'autonomous'}:${opts?.clientName?.() ?? 'unknown'}`,
825
+ token: crypto.randomUUID(),
826
+ // @implements A-SPEC-587 — an upstream grade is DERIVED; the audit line names the A-SPECs it came from.
827
+ rationale: `autonomous grant (${'HOLMES_AUTONOMOUS_APPROVAL'} enabled, ${source === 'timeout' ? 'in-session approval timeout' : 'spec grade auto'}${derivedFrom && derivedFrom.length > 0 ? ` — derived from ${derivedFrom.join(', ')}` : ''})`,
828
+ });
775
829
  // @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
776
830
  const reviewEvidence = (0, review_evidence_1.createReviewEvidenceHandlers)({
777
831
  foreignRootReason: root => foreignRootReason(store, root),
@@ -783,22 +837,17 @@ function makeRawHandlers(store, opts) {
783
837
  hasElicitor: () => Boolean(opts?.elicit),
784
838
  tryElicit,
785
839
  elicitApproval,
840
+ autonomousApproval,
786
841
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
787
842
  refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
788
843
  });
789
- // @implements A-SPEC-532.2 — the autonomous channel: the SAME synthesized-Approval shape that
790
- // rides the existing seal path, but its actor names `autonomous:<client>` so an audit can tell a
791
- // self-approved seal from a human-approved (elicitation) or operator (env/grant) one. Single-use
792
- // by construction — it exists only inside this call, persisted nowhere.
793
- const autonomousApproval = (derivedFrom) => ({
794
- actor: `autonomous:${opts?.clientName?.() ?? 'unknown'}`,
795
- token: crypto.randomUUID(),
796
- // @implements A-SPEC-587 — an upstream grade is DERIVED; the audit line names the A-SPECs it came from.
797
- rationale: `autonomous grant (${'HOLMES_AUTONOMOUS_APPROVAL'} enabled, spec grade auto${derivedFrom && derivedFrom.length > 0 ? ` — derived from ${derivedFrom.join(', ')}` : ''})`,
798
- });
799
844
  // @implements A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
800
845
  const specApproval = (0, spec_approval_1.createSpecApprovalHandlers)({
801
846
  store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval,
847
+ approvalAdapter,
848
+ approvalHarness: canonicalHarness,
849
+ prepareHostApproval,
850
+ consumeHostApproval,
802
851
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
803
852
  refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
804
853
  foreignRootReason: (root) => foreignRootReason(store, root),
@@ -927,6 +976,7 @@ function makeRawHandlers(store, opts) {
927
976
  listSpecs: () => store.list(),
928
977
  cachedScan,
929
978
  }),
979
+ requirement_triage: requirementTriage.requirement_triage,
930
980
  // @implements A-SPEC-642 — placed in the one slot no public-key-order pin covers (the handler suites pin
931
981
  // spec_create..spec_upgrade, spec_retire..spec_unseal, spec_unseal+5, spec_approve+4, spec_next+3,
932
982
  // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
@@ -969,5 +1019,9 @@ function makeRawHandlers(store, opts) {
969
1019
  };
970
1020
  },
971
1021
  }),
1022
+ // The client must render this sensitive invocation before it reaches the server. The handler
1023
+ // still validates every server-derived binding; a tool argument alone is never authority.
1024
+ // Kept at the unpinned tail: historical public-neighbour order remains a wire contract.
1025
+ approval_commit: async (a) => approvalContinuations.commit(a),
972
1026
  };
973
1027
  }