@holmes-lab/holmes-kit 0.29.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 (65) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +6 -5
  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 +88 -12
  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/governance/autonomy.d.ts +9 -0
  18. package/dist/holmes/governance/autonomy.js +28 -1
  19. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  20. package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
  21. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  22. package/dist/holmes/hooks/rtm-refresh.js +56 -15
  23. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  24. package/dist/holmes/mcp/approval-adapters.js +21 -0
  25. package/dist/holmes/mcp/approval-commit.d.ts +21 -0
  26. package/dist/holmes/mcp/approval-commit.js +92 -0
  27. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  28. package/dist/holmes/mcp/approval-intent.js +67 -0
  29. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  30. package/dist/holmes/mcp/approval-policy.js +18 -0
  31. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  32. package/dist/holmes/mcp/elicit-approval.js +5 -2
  33. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  34. package/dist/holmes/mcp/handlers/graph-operations.js +13 -5
  35. package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
  36. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  37. package/dist/holmes/mcp/handlers/requirement-triage.js +45 -10
  38. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  39. package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
  40. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
  41. package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
  42. package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
  43. package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
  44. package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
  45. package/dist/holmes/mcp/handlers.d.ts +46 -0
  46. package/dist/holmes/mcp/handlers.js +57 -13
  47. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  48. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  49. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -2
  50. package/dist/holmes/mcp/requirement-triage-evidence.js +71 -1
  51. package/dist/holmes/mcp/server.js +5 -3
  52. package/dist/holmes/mcp/supervisor.js +7 -3
  53. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  54. package/dist/holmes/mcp/tool-schemas.js +31 -1
  55. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  56. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  57. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  58. package/dist/holmes/review/condition-hunk-replay.js +11 -1
  59. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  60. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  61. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  62. package/dist/holmes/review/scope.js +6 -1
  63. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  64. package/dist/holmes/review/test-outcomes.js +90 -1
  65. package/package.json +1 -1
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
37
+ // @implements A-SPEC-723, A-SPEC-719
37
38
  // @implements A-SPEC-713
38
39
  /** Read-only MCP projection of the pure requirement lifecycle triage model. */
39
40
  const node_child_process_1 = require("node:child_process");
@@ -47,6 +48,7 @@ const vector_cache_1 = require("../../semantic/vector-cache");
47
48
  const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
48
49
  const model_cache_1 = require("../../semantic/model-cache");
49
50
  const graph_store_1 = require("../../rtm/graph-store");
51
+ const freshness_coordinator_1 = require("../../refresh/freshness-coordinator");
50
52
  const requirementKinds = new Set(['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC']);
51
53
  const cosine = (a, b) => {
52
54
  if (a.length === 0 || a.length !== b.length)
@@ -116,6 +118,22 @@ function createRequirementTriageHandlers(context) {
116
118
  const scanned = context.cachedScan(root, root);
117
119
  const evidence = (0, test_evidence_1.readTestEvidence)(root);
118
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
+ }
119
137
  const graph = readGraphEvidence(root, currentHead, documents);
120
138
  const fresh = (0, test_evidence_1.isFresh)(evidence, currentHead) && evidence?.passed === true;
121
139
  const lineageEvidence = {};
@@ -135,7 +153,13 @@ function createRequirementTriageHandlers(context) {
135
153
  for (const value of Object.values(lineageEvidence))
136
154
  value.implementationAnchors.sort();
137
155
  const tier = (0, tier_1.resolveSemanticTier)();
138
- const runtime = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
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));
139
163
  const query = runtime ? await runtime.embedQuery(a.prompt) : null;
140
164
  const semanticCandidates = [];
141
165
  let covered = 0;
@@ -150,18 +174,26 @@ function createRequirementTriageHandlers(context) {
150
174
  semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
151
175
  }
152
176
  }
153
- const semanticState = runtime === null || query === null
154
- ? (tier.tier === 'none' && !tier.localRuntimePresent ? 'not-adopted' : 'unavailable')
155
- : covered === documents.length ? 'covered' : 'cold';
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';
156
181
  const readiness = tier.tier === 'none' && tier.localRuntimePresent ? (0, model_cache_1.readLocalModelReadiness)() : null;
157
182
  const availability = semanticState === 'covered' ? 'available'
158
183
  : semanticState === 'cold' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
159
184
  : 'unavailable';
160
185
  const semantic = { tier: tier.tier, covered, total: documents.length, state: semanticState,
161
- availability,
186
+ availability, ...(suppressed ? { suppressed: true } : {}),
162
187
  ...(readiness ? { localState: readiness.state, recovery: readiness.recovery } : {}) };
163
- const result = (0, requirement_triage_1.triageRequirements)({ prompt: a.prompt, documents, evidence: lineageEvidence,
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,
164
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
+ };
165
197
  const promptDigest = `sha256:${crypto.createHash('sha256').update(a.prompt).digest('hex')}`;
166
198
  const executionState = evidence === undefined ? 'absent'
167
199
  : !(0, test_evidence_1.isFresh)(evidence, currentHead) ? 'stale'
@@ -173,12 +205,15 @@ function createRequirementTriageHandlers(context) {
173
205
  graphProvenance: Object.fromEntries(candidate.documents.map((document) => [document.id, graph.provenanceBySpec[document.id] ?? null])),
174
206
  executionEvidence: { state: executionState, recordedHead: evidence?.head ?? null, currentHead },
175
207
  }));
176
- const answer = { schema: 'requirement-triage/1', ...result, promptDigest, semantic, provenance,
208
+ const answer = { schema: 'requirement-triage/1', ...result, ...(lexical ? { lexicalOnly: true } : {}), promptDigest, semantic, provenance,
177
209
  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)
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)
180
214
  return answer;
181
- const artifact = (0, requirement_triage_evidence_1.writeRequirementTriageEvidence)(root, { schema: 'requirement-triage-evidence/1', promptDigest, result: 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 });
182
217
  return { ...answer, evidenceDigest: artifact.digest, persistedTo: artifact.path, artifact };
183
218
  },
184
219
  };
@@ -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 });
@@ -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;
@@ -555,12 +564,19 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
555
564
  title: string;
556
565
  objective: string;
557
566
  filesToTouch: string[];
567
+ triage_evidence?: unknown;
558
568
  }) => Promise<{
559
569
  ok: boolean;
560
570
  reason: string;
561
571
  existing: string[];
562
572
  specsCreated: string[];
563
573
  unreadable: string[];
574
+ } | {
575
+ ok: boolean;
576
+ reason: string;
577
+ specsCreated: string[];
578
+ unreadable: string[];
579
+ existing?: undefined;
564
580
  } | {
565
581
  ok: boolean;
566
582
  specsCreated: string[];
@@ -606,6 +622,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
606
622
  semantic: {
607
623
  localState?: import("../semantic/model-cache").LocalModelState | undefined;
608
624
  recovery?: string | undefined;
625
+ suppressed?: true | undefined;
609
626
  tier: "local" | "none" | "cloud";
610
627
  covered: number;
611
628
  total: number;
@@ -641,6 +658,16 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
641
658
  governedDocumentCount: number;
642
659
  scannedSourceCount: number;
643
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;
644
671
  verdict: import("../review/requirement-triage").RequirementVerdict;
645
672
  candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
646
673
  reasons: string[];
@@ -657,6 +684,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
657
684
  semantic: {
658
685
  localState?: import("../semantic/model-cache").LocalModelState | undefined;
659
686
  recovery?: string | undefined;
687
+ suppressed?: true | undefined;
660
688
  tier: "local" | "none" | "cloud";
661
689
  covered: number;
662
690
  total: number;
@@ -692,6 +720,16 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
692
720
  governedDocumentCount: number;
693
721
  scannedSourceCount: number;
694
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;
695
733
  verdict: import("../review/requirement-triage").RequirementVerdict;
696
734
  candidates: import("../review/requirement-triage").RequirementTriageCandidate[];
697
735
  reasons: string[];
@@ -983,11 +1021,18 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
983
1021
  } | {
984
1022
  ok: boolean;
985
1023
  reason: string;
1024
+ approvalIntent?: undefined;
1025
+ conflict?: undefined;
1026
+ } | {
1027
+ ok: boolean;
1028
+ reason: string;
1029
+ approvalIntent: ApprovalIntent;
986
1030
  conflict?: undefined;
987
1031
  } | {
988
1032
  ok: boolean;
989
1033
  reason: string;
990
1034
  conflict: import("../spec/version-conflict").ConflictDetail;
1035
+ approvalIntent?: undefined;
991
1036
  } | {
992
1037
  dismissUnknown?: string[] | undefined;
993
1038
  advisoryHistory?: import("../rtm/advisory-outcomes").AdvisoryState[] | undefined;
@@ -1007,6 +1052,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1007
1052
  digest: string;
1008
1053
  ok?: undefined;
1009
1054
  reason?: undefined;
1055
+ approvalIntent?: undefined;
1010
1056
  conflict?: undefined;
1011
1057
  }>;
1012
1058
  spec_list: (a: any) => Promise<{