@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
@@ -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, A-SPEC-713
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
@@ -83,6 +83,7 @@ const graph_operations_1 = require("./handlers/graph-operations");
83
83
  const graph_operations_2 = require("./handlers/graph-operations");
84
84
  const maintenance_analysis_1 = require("./handlers/maintenance-analysis");
85
85
  const requirement_triage_1 = require("./handlers/requirement-triage");
86
+ const rtm_refresh_1 = require("../hooks/rtm-refresh");
86
87
  const taint_screening_1 = require("./handlers/taint-screening");
87
88
  const cpg_scanner_1 = require("../cpg/cpg-scanner");
88
89
  const scan_cache_1 = require("../cpg/scan-cache");
@@ -119,6 +120,9 @@ const write_target_1 = require("../guardrail/write-target");
119
120
  const spec_store_1 = require("../spec/spec-store");
120
121
  const risk_gate_1 = require("../guardrail/risk-gate");
121
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");
122
126
  const approval_queue_1 = require("../governance/approval-queue");
123
127
  const approval_grants_1 = require("../governance/approval-grants");
124
128
  const ledger_store_1 = require("../governance/ledger-store");
@@ -678,6 +682,36 @@ function collectDecisions(root, scanned, specs) {
678
682
  return { decisions, citations };
679
683
  }
680
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
+ });
681
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
682
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
683
717
  const testExecution = (0, test_execution_1.createTestExecutionHandlers)({
@@ -724,6 +758,7 @@ function makeRawHandlers(store, opts) {
724
758
  cachedScan,
725
759
  assertStoreReachable: (tool, root) => assertSpecStoreReachable(tool, store, root),
726
760
  refusal: reason => new HandlerRefusal(reason),
761
+ requestFreshness: rtm_refresh_1.requestBackgroundFreshness,
727
762
  });
728
763
  const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
729
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
@@ -758,7 +793,7 @@ function makeRawHandlers(store, opts) {
758
793
  // other failure mode (no channel, wrong kind, a throwing elicitor) is `silent`, whose refusal
759
794
  // stays byte-identical to the pre-elicitation one — nothing is ever worse than before the
760
795
  // channel existed.
761
- const tryElicit = async (kind, target, summary) => {
796
+ const tryElicit = async (kind, target, summary, timeoutBehavior = 'queue') => {
762
797
  // @implements A-SPEC-540.1 — operator opt-out: with HOLMES_ELICIT=off the server never shows the
763
798
  // in-client prompt, folding to the byte-identical `silent` (refuse+enqueue) path so claude/agy/
764
799
  // codex all converge on one out-of-band surface (holmes-kit approve). Unset ⇒ unchanged.
@@ -767,7 +802,7 @@ function makeRawHandlers(store, opts) {
767
802
  if (!opts?.elicit || !elicit_approval_1.ELICITABLE_KINDS.has(kind))
768
803
  return { kind: 'silent' };
769
804
  try {
770
- return await opts.elicit({ kind, target, summary });
805
+ return await opts.elicit({ kind, target, summary, timeoutBehavior });
771
806
  }
772
807
  catch {
773
808
  return { kind: 'silent' };
@@ -781,6 +816,16 @@ function makeRawHandlers(store, opts) {
781
816
  token: crypto.randomUUID(),
782
817
  rationale: reason ?? 'elicitation grant',
783
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
+ });
784
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
785
830
  const reviewEvidence = (0, review_evidence_1.createReviewEvidenceHandlers)({
786
831
  foreignRootReason: root => foreignRootReason(store, root),
@@ -792,22 +837,17 @@ function makeRawHandlers(store, opts) {
792
837
  hasElicitor: () => Boolean(opts?.elicit),
793
838
  tryElicit,
794
839
  elicitApproval,
840
+ autonomousApproval,
795
841
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
796
842
  refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
797
843
  });
798
- // @implements A-SPEC-532.2 — the autonomous channel: the SAME synthesized-Approval shape that
799
- // rides the existing seal path, but its actor names `autonomous:<client>` so an audit can tell a
800
- // self-approved seal from a human-approved (elicitation) or operator (env/grant) one. Single-use
801
- // by construction — it exists only inside this call, persisted nowhere.
802
- const autonomousApproval = (derivedFrom) => ({
803
- actor: `autonomous:${opts?.clientName?.() ?? 'unknown'}`,
804
- token: crypto.randomUUID(),
805
- // @implements A-SPEC-587 — an upstream grade is DERIVED; the audit line names the A-SPECs it came from.
806
- rationale: `autonomous grant (${'HOLMES_AUTONOMOUS_APPROVAL'} enabled, spec grade auto${derivedFrom && derivedFrom.length > 0 ? ` — derived from ${derivedFrom.join(', ')}` : ''})`,
807
- });
808
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
809
845
  const specApproval = (0, spec_approval_1.createSpecApprovalHandlers)({
810
846
  store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval,
847
+ approvalAdapter,
848
+ approvalHarness: canonicalHarness,
849
+ prepareHostApproval,
850
+ consumeHostApproval,
811
851
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
812
852
  refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
813
853
  foreignRootReason: (root) => foreignRootReason(store, root),
@@ -979,5 +1019,9 @@ function makeRawHandlers(store, opts) {
979
1019
  };
980
1020
  },
981
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),
982
1026
  };
983
1027
  }
@@ -4,7 +4,7 @@ exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH
4
4
  exports.unquoteGitPath = unquoteGitPath;
5
5
  exports.analyzeMaintenance = analyzeMaintenance;
6
6
  exports.boundAnalysis = boundAnalysis;
7
- // @implements A-SPEC-310
7
+ // @implements A-SPEC-725, A-SPEC-310
8
8
  // @implements A-SPEC-295
9
9
  // @implements A-SPEC-294
10
10
  // @implements A-SPEC-293
@@ -398,8 +398,32 @@ function analyzeMaintenance(input) {
398
398
  // the pinned replay floors read that field and are unchanged by construction — and the reserved
399
399
  // slots come out of the pool, which is material for the caller rather than a verdict.
400
400
  const LEXICAL_GUARANTEE = 10;
401
+ const candidateHits = [...ordered.slice(0, LOCALIZATION_TOP_N)];
402
+ // @implements A-SPEC-725 — a cited request may have fewer than ten local lexical/spec results.
403
+ // Only then may a direct, scanned importer of the lexical leader fill a vacant slot: it is a
404
+ // local dependency fact, does not displace or reorder an emitted candidate, and is deliberately
405
+ // narrower than the cited-request graph expansion A-SPEC-407 rejected.
406
+ const citedForUnderfullWindow = (0, localize_1.citationsIn)(input.request, new Set(specs.map((spec) => spec.id))).cited;
407
+ if (citedForUnderfullWindow.length > 0 && candidateHits.length > 0 && candidateHits.length < LOCALIZATION_TOP_N) {
408
+ const emitted = new Set(candidateHits.map((hit) => hit.file));
409
+ const scannedPaths = new Set(scanned.map((file) => file.sourcePath));
410
+ for (const importer of input.graph.importersOf(candidateHits[0].file).sort()) {
411
+ if (candidateHits.length >= LOCALIZATION_TOP_N)
412
+ break;
413
+ if (emitted.has(importer) || !scannedPaths.has(importer) || (0, history_admission_1.isVendorPath)(importer))
414
+ continue;
415
+ candidateHits.push({
416
+ file: importer,
417
+ score: 0,
418
+ matchedSymbols: [],
419
+ viaSpecs: [],
420
+ why: [`reached through direct importer of ${candidateHits[0].file}`],
421
+ });
422
+ emitted.add(importer);
423
+ }
424
+ }
401
425
  const exposedTail = ordered.slice(LOCALIZATION_TOP_N);
402
- const inCandidates = new Set(ordered.slice(0, LOCALIZATION_TOP_N).map((h) => h.file));
426
+ const inCandidates = new Set(candidateHits.map((h) => h.file));
403
427
  const wouldShow = new Set(exposedTail.slice(0, RERANK_POOL_N).map((h) => h.file));
404
428
  const rescued = localization.hits.slice(0, LEXICAL_GUARANTEE)
405
429
  .filter((h) => !inCandidates.has(h.file) && !wouldShow.has(h.file))
@@ -408,8 +432,8 @@ function analyzeMaintenance(input) {
408
432
  const rescuedFiles = new Set(rescued.map((h) => h.file));
409
433
  const rerankPool = [...rescued, ...exposedTail.filter((h) => !rescuedFiles.has(h.file))]
410
434
  .slice(0, RERANK_POOL_N).map(shape);
411
- const lexicalSymbolsOf = new Map(ordered.slice(0, LOCALIZATION_TOP_N).map((hit) => [hit.file, sortedUnique(hit.matchedSymbols)]));
412
- const candidates = ordered.slice(0, LOCALIZATION_TOP_N).map((hit) => ({
435
+ const lexicalSymbolsOf = new Map(candidateHits.map((hit) => [hit.file, sortedUnique(hit.matchedSymbols)]));
436
+ const candidates = candidateHits.map((hit) => ({
413
437
  file: hit.file,
414
438
  score: hit.score,
415
439
  // @implements A-SPEC-573.4 — the emitted list, which is what a caller reads and what the
@@ -42,7 +42,7 @@ exports.recordOutcome = recordOutcome;
42
42
  exports.openArtifacts = openArtifacts;
43
43
  exports.closeOpenArtifacts = closeOpenArtifacts;
44
44
  exports.computeCalibration = computeCalibration;
45
- // @implements A-SPEC-271
45
+ // @implements A-SPEC-724.1, A-SPEC-271
46
46
  // @implements A-SPEC-268
47
47
  const fs = __importStar(require("node:fs"));
48
48
  const path = __importStar(require("node:path"));
@@ -1,11 +1,45 @@
1
1
  export declare const REQUIREMENT_TRIAGE_EVIDENCE_DIR: string;
2
- export interface RequirementTriageArtifact {
2
+ export interface RequirementTriageArtifactV1 {
3
3
  schema: 'requirement-triage-evidence/1';
4
4
  promptDigest: string;
5
5
  result: unknown;
6
6
  }
7
+ export interface RequirementTriageArtifact {
8
+ schema: 'requirement-triage-evidence/2';
9
+ promptDigest: string;
10
+ workspaceId: string;
11
+ head: string | null;
12
+ freshnessGeneration: string;
13
+ result: unknown;
14
+ }
15
+ type StoredArtifact = RequirementTriageArtifactV1 | RequirementTriageArtifact;
7
16
  /** Writes an atomically published artifact addressed by its content digest. */
8
- export declare function writeRequirementTriageEvidence(root: string, artifact: RequirementTriageArtifact): {
17
+ export declare function writeRequirementTriageEvidence(root: string, artifact: StoredArtifact): {
9
18
  digest: string;
10
19
  path: string;
11
20
  };
21
+ /** Validates the address and all authoring-relevant bindings; v1 is advisory-only and never authoring evidence. */
22
+ export declare function validateTriageArtifact(root: string, digest: string, expected: {
23
+ promptDigest: string;
24
+ workspaceId: string;
25
+ head: string | null;
26
+ }): {
27
+ ok: true;
28
+ artifact: RequirementTriageArtifact;
29
+ } | {
30
+ ok: false;
31
+ reason: string;
32
+ };
33
+ /**
34
+ * @implements A-SPEC-724 — the ONE intake boundary every REQ-creating act crosses (spec_create and
35
+ * spec_slice_init). A new REQ may be born only from a current, prompt-bound v2 triage artifact whose
36
+ * freshness receipt is the current one for this workspace and HEAD. Callers run their own
37
+ * deterministic refusals first and call this immediately before their first write.
38
+ */
39
+ export declare function validateRequirementIntake(root: string, triageEvidence: unknown): {
40
+ ok: true;
41
+ } | {
42
+ ok: false;
43
+ reason: string;
44
+ };
45
+ export {};
@@ -35,11 +35,16 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = void 0;
37
37
  exports.writeRequirementTriageEvidence = writeRequirementTriageEvidence;
38
+ exports.validateTriageArtifact = validateTriageArtifact;
39
+ exports.validateRequirementIntake = validateRequirementIntake;
40
+ // @implements A-SPEC-724, A-SPEC-719
38
41
  // @implements A-SPEC-713
39
42
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
40
43
  const crypto = __importStar(require("node:crypto"));
41
44
  const fs = __importStar(require("node:fs"));
42
45
  const path = __importStar(require("node:path"));
46
+ const node_child_process_1 = require("node:child_process");
47
+ const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
43
48
  exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = path.join('.ax', 'evidence', 'requirement-triage');
44
49
  const sha256 = (text) => `sha256:${crypto.createHash('sha256').update(text).digest('hex')}`;
45
50
  const DIGEST = /^sha256:[a-f0-9]{64}$/;
@@ -62,7 +67,11 @@ function stable(value) {
62
67
  }
63
68
  /** Writes an atomically published artifact addressed by its content digest. */
64
69
  function writeRequirementTriageEvidence(root, artifact) {
65
- if (artifact.schema !== 'requirement-triage-evidence/1' || !DIGEST.test(artifact.promptDigest)) {
70
+ const v2 = artifact.schema === 'requirement-triage-evidence/2'
71
+ && typeof artifact.workspaceId === 'string' && artifact.workspaceId !== ''
72
+ && (typeof artifact.head === 'string' || artifact.head === null)
73
+ && typeof artifact.freshnessGeneration === 'string' && artifact.freshnessGeneration !== '';
74
+ if ((!v2 && artifact.schema !== 'requirement-triage-evidence/1') || !DIGEST.test(artifact.promptDigest)) {
66
75
  throw new Error('requirement triage artifact requires a sha256 prompt digest');
67
76
  }
68
77
  const body = `${stable(artifact)}\n`;
@@ -77,3 +86,64 @@ function writeRequirementTriageEvidence(root, artifact) {
77
86
  }
78
87
  return { digest, path: target };
79
88
  }
89
+ /** Validates the address and all authoring-relevant bindings; v1 is advisory-only and never authoring evidence. */
90
+ function validateTriageArtifact(root, digest, expected) {
91
+ if (!DIGEST.test(digest))
92
+ return { ok: false, reason: 'triage evidence digest is malformed' };
93
+ const file = path.join(root, exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR, `${digest.slice('sha256:'.length)}.json`);
94
+ let raw;
95
+ try {
96
+ raw = fs.readFileSync(file, 'utf8');
97
+ }
98
+ catch {
99
+ return { ok: false, reason: 'triage evidence is missing' };
100
+ }
101
+ if (sha256(raw) !== digest)
102
+ return { ok: false, reason: 'triage evidence digest does not match its content' };
103
+ let artifact;
104
+ try {
105
+ artifact = JSON.parse(raw);
106
+ }
107
+ catch {
108
+ return { ok: false, reason: 'triage evidence is unreadable' };
109
+ }
110
+ const a = artifact;
111
+ if (a.schema !== 'requirement-triage-evidence/2' || a.promptDigest !== expected.promptDigest
112
+ || a.workspaceId !== expected.workspaceId || a.head !== expected.head || typeof a.freshnessGeneration !== 'string') {
113
+ return { ok: false, reason: 'triage evidence does not bind this prompt, workspace, and HEAD' };
114
+ }
115
+ return { ok: true, artifact: a };
116
+ }
117
+ /**
118
+ * @implements A-SPEC-724 — the ONE intake boundary every REQ-creating act crosses (spec_create and
119
+ * spec_slice_init). A new REQ may be born only from a current, prompt-bound v2 triage artifact whose
120
+ * freshness receipt is the current one for this workspace and HEAD. Callers run their own
121
+ * deterministic refusals first and call this immediately before their first write.
122
+ */
123
+ function validateRequirementIntake(root, triageEvidence) {
124
+ const evidence = triageEvidence;
125
+ if (!evidence || typeof evidence.digest !== 'string' || typeof evidence.promptDigest !== 'string') {
126
+ return { ok: false, reason: '새 REQ에는 requirement_triage가 발급한 현재 triage_evidence {digest,promptDigest}가 필요합니다. 같은 prompt로 requirement_triage(persist:true)를 실행한 뒤 다시 시도하십시오.' };
127
+ }
128
+ let head = null;
129
+ try {
130
+ head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
131
+ }
132
+ catch { /* non-git root is null */ }
133
+ const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
134
+ const artifact = validateTriageArtifact(root, evidence.digest, { promptDigest: evidence.promptDigest, workspaceId, head });
135
+ if (!artifact.ok)
136
+ return { ok: false, reason: `새 REQ triage evidence를 검증할 수 없습니다: ${artifact.reason}` };
137
+ const receipt = (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId, head, now: new Date() });
138
+ // A-SPEC-719: intake-usable, i.e. current graph and a current or owner-chosen lexical-only
139
+ // requirement lane; the source lane is reported, never required.
140
+ if (!receipt || !(0, freshness_coordinator_1.intakeUsable)(receipt) || receipt.generation !== artifact.artifact.freshnessGeneration) {
141
+ return { ok: false, reason: '새 REQ triage evidence의 fresh-evidence receipt가 현재 workspace/HEAD에서 current가 아닙니다. refresh가 완료된 뒤 requirement_triage를 다시 실행하십시오.' };
142
+ }
143
+ const verdict = artifact.artifact.result.verdict;
144
+ if (verdict === 'fulfilled')
145
+ return { ok: false, reason: 'triage 결과가 fulfilled입니다. 동일 요구사항의 새 REQ를 만들지 말고 기존 lineage를 사용하십시오.' };
146
+ if (verdict !== 'new' && verdict !== 'ambiguous')
147
+ return { ok: false, reason: `triage 결과 ${String(verdict)}는 새 REQ 생성 근거가 아닙니다. existing-change는 기존 REQ의 후속 변경으로 작성하십시오.` };
148
+ return { ok: true };
149
+ }
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-625, A-SPEC-564.1
4
+ // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1
5
5
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
6
6
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
7
7
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -10,6 +10,7 @@ const handlers_1 = require("./handlers");
10
10
  const tool_schemas_1 = require("./tool-schemas");
11
11
  Object.defineProperty(exports, "HOOK_ENFORCED_TOOLS", { enumerable: true, get: function () { return tool_schemas_1.HOOK_ENFORCED_TOOLS; } });
12
12
  const validate_args_1 = require("./validate-args");
13
+ const approval_adapters_1 = require("./approval-adapters");
13
14
  // @implements A-SPEC-100.2
14
15
  // @implements A-SPEC-652.2 — the store is opened at an ABSOLUTE path resolved against the project
15
16
  // root (CLAUDE_PROJECT_DIR, then the nearest .mcp.json/.ax ancestor, then cwd), and the path is
@@ -35,7 +36,7 @@ const store = new spec_store_1.LocalMarkdownRepository(SPECS_DIR);
35
36
  const { runElicitFlow } = require('./elicit-approval');
36
37
  const elicit = async (req) => {
37
38
  try {
38
- if (!server.getClientCapabilities()?.elicitation)
39
+ if (!(0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()))
39
40
  return { kind: 'silent' };
40
41
  return await runElicitFlow((form, timeoutMs) => server.elicitInput(form, { timeout: timeoutMs }), req);
41
42
  }
@@ -45,6 +46,7 @@ const elicit = async (req) => {
45
46
  };
46
47
  const handlers = (0, handlers_1.makeHandlers)(store, {
47
48
  elicit,
49
+ elicitationAvailable: () => (0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()),
48
50
  observeInvocation: root => stampSession(root),
49
51
  clientName: () => { try {
50
52
  return server.getClientVersion()?.name ?? 'unknown';
@@ -126,7 +128,7 @@ const TOOLS = Object.keys(handlers)
126
128
  .map((name) => {
127
129
  const def = tool_schemas_1.TOOL_SCHEMAS[name];
128
130
  return def
129
- ? { name, description: def.description, inputSchema: def.inputSchema }
131
+ ? { name, description: def.description, inputSchema: def.inputSchema, ...(def.annotations ? { annotations: def.annotations } : {}) }
130
132
  : { name, description: name, inputSchema: { type: 'object', properties: {} } };
131
133
  });
132
134
  server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
@@ -37,7 +37,7 @@ exports.Supervisor = exports.MAX_CONSECUTIVE_SILENT_DEATHS = exports.AUTORELOAD_
37
37
  exports.autoreloadEnabled = autoreloadEnabled;
38
38
  exports.shouldSwap = shouldSwap;
39
39
  exports.createResponseCounter = createResponseCounter;
40
- // @implements A-SPEC-162
40
+ // @implements A-SPEC-721, A-SPEC-162
41
41
  const node_child_process_1 = require("node:child_process");
42
42
  const path = __importStar(require("node:path"));
43
43
  const basis_1 = require("./basis");
@@ -235,8 +235,12 @@ class Supervisor {
235
235
  spawnChild(stdout) {
236
236
  // `stdio: ['pipe','pipe','pipe']` keeps the typed streams non-null; the child's stderr is
237
237
  // forwarded rather than inherited so a supervised run logs identically to an unsupervised one.
238
- const child = (0, node_child_process_1.spawn)('node', [path.join('dist', 'holmes', 'mcp', 'server.js')], {
239
- cwd: this.repoRoot, stdio: ['pipe', 'pipe', 'pipe'],
238
+ // @implements A-SPEC-721 — the child runs where the unsupervised server would: the launcher's own
239
+ // working directory, i.e. the harness session's workspace. The package root is only where the
240
+ // code lives; running the child there bound Codex sessions (autoreload on, no HOLMES_SPECS) to
241
+ // the package instead of the user's project.
242
+ const child = (0, node_child_process_1.spawn)('node', [path.join(this.repoRoot, 'dist', 'holmes', 'mcp', 'server.js')], {
243
+ cwd: process.cwd(), stdio: ['pipe', 'pipe', 'pipe'],
240
244
  });
241
245
  child.stderr.on('data', (d) => process.stderr.write(d));
242
246
  this.child = child;
@@ -7,6 +7,14 @@ export interface JsonSchema {
7
7
  export interface ToolSchema {
8
8
  description: string;
9
9
  inputSchema: JsonSchema;
10
+ /** MCP presentation hints. They ask the host to show a confirmation; they are never authority. */
11
+ annotations?: {
12
+ title?: string;
13
+ readOnlyHint?: boolean;
14
+ destructiveHint?: boolean;
15
+ idempotentHint?: boolean;
16
+ openWorldHint?: boolean;
17
+ };
10
18
  }
11
19
  export declare const HOOK_ENFORCED_TOOLS: Set<string>;
12
20
  export declare const TOOL_SCHEMAS: Record<string, ToolSchema>;
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713
4
+ // @implements A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713
5
5
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
6
6
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
7
7
  // @implements A-SPEC-642
@@ -38,6 +38,26 @@ const ROOT_ANY = str('Absolute path to the project root. Version control is opti
38
38
  // the rest of the tool metadata and has no import side effects.
39
39
  exports.HOOK_ENFORCED_TOOLS = new Set(['phase_check', 'risk_check', 'rtm_check', 'spec_validate']);
40
40
  exports.TOOL_SCHEMAS = {
41
+ approval_commit: {
42
+ description: 'Complete a server-issued, one-use in-session approval continuation. This sensitive annotation asks the host to show its native tool confirmation; the server records arrival only as a host-gated continuation, never proof of a human response. Send the unmodified approvalIntent returned by the original refused action, then retry that original action. The server verifies challenge, kind, target, subject digest, workspace, session run and expiry; this tool never reads HOLMES_APPROVAL or writes configuration.',
43
+ annotations: { title: 'Holmes-Kit approval confirmation', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
44
+ inputSchema: {
45
+ type: 'object',
46
+ properties: {
47
+ id: str('Opaque server-issued approval intent id.'),
48
+ challenge: str('Opaque one-use server challenge; copy unchanged from approvalIntent.'),
49
+ kind: str('Canonical action kind displayed by the host.'),
50
+ target: str('Canonical action target displayed by the host.'),
51
+ subject: str('Exact subject digest displayed by the host.'),
52
+ workspace: str('Server-derived workspace binding displayed by the host.'),
53
+ runId: str('Server session binding displayed by the host.'),
54
+ harness: str('Detected harness name displayed by the host.'),
55
+ expiresAt: str('Server-issued expiry timestamp displayed by the host.'),
56
+ },
57
+ required: ['id', 'challenge', 'kind', 'target', 'subject', 'workspace', 'runId', 'harness', 'expiresAt'],
58
+ additionalProperties: false,
59
+ },
60
+ },
41
61
  entity_integrate: {
42
62
  description: 'Plan integration of fixed common-ancestor Git inputs for the configured adopted store, apply an exact approved plan, inspect an operation recovery-plan, or recover it with current authority. Preserves entity UUIDs and explicit conflicts, coordinates store/source ownership, journals publication and records completion audit and derived-state obligations. Leaves Git refs/index unchanged. Completed retries verify existing evidence without republishing. discharge rebuilds this replica\'s graph and semantic cache for a completed operation and records one immutable discharge.json bound to its obligations; obligations lists completed operations with pending, discharged or invalid obligations (read-only). abandon rolls a pending operation a third state blocked back to its own before-bytes, preserves foreign bytes, releases ownership and audits the abandonment. Unsupported inputs remain explicit blockers; no implicit adoption or approval.',
43
63
  inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['plan', 'apply', 'recovery-plan', 'recover', 'abandon', 'discharge', 'obligations'] },
@@ -104,6 +124,11 @@ exports.TOOL_SCHEMAS = {
104
124
  // silently, with no refusal. Declaring it makes the control surface visible; the data
105
125
  // exemption stays for genuine frontmatter.
106
126
  root: ROOT,
127
+ triage_evidence: {
128
+ type: 'object', description: 'Required for a new REQ: current requirement_triage(persist:true) v2 evidence.',
129
+ properties: { digest: str('Content-addressed triage evidence digest.'), promptDigest: str('Digest of the exact authoring prompt.') },
130
+ required: ['digest', 'promptDigest'],
131
+ },
107
132
  },
108
133
  required: ['type', 'id', 'title'],
109
134
  additionalProperties: true,
@@ -622,6 +647,11 @@ exports.TOOL_SCHEMAS = {
622
647
  title: str('Title for the requirement and specs.'),
623
648
  objective: str('High-level objective or problem statement.'),
624
649
  filesToTouch: strArray('List of source/test file paths to be touched by this slice.'),
650
+ triage_evidence: {
651
+ type: 'object', description: 'Required: this call creates a new REQ, so it needs current requirement_triage(persist:true) v2 evidence for the same prompt, exactly as spec_create(type=REQ) does.',
652
+ properties: { digest: str('Content-addressed triage evidence digest.'), promptDigest: str('Digest of the exact authoring prompt.') },
653
+ required: ['digest', 'promptDigest'],
654
+ },
625
655
  },
626
656
  required: ['sliceName', 'title', 'objective', 'filesToTouch'],
627
657
  },
@@ -0,0 +1,67 @@
1
+ export type FreshnessLane = 'current' | 'refreshing' | 'retry-at' | 'failed' | 'suppressed' | 'not-adopted' | 'stale';
2
+ export interface FreshnessReceipt {
3
+ schema: 'fresh-evidence/1';
4
+ workspaceId: string;
5
+ head: string | null;
6
+ generation: string;
7
+ state: FreshnessLane;
8
+ startedAt?: string;
9
+ completedAt?: string;
10
+ attempt: number;
11
+ retryAt?: string;
12
+ graph: FreshnessLane;
13
+ sourceSemantic: FreshnessLane;
14
+ requirementSemantic: FreshnessLane;
15
+ }
16
+ export interface RefreshRequest {
17
+ workspaceId: string;
18
+ head: string | null;
19
+ now: Date;
20
+ }
21
+ export interface RefreshCompletion {
22
+ graph: FreshnessLane;
23
+ sourceSemantic: FreshnessLane;
24
+ requirementSemantic: FreshnessLane;
25
+ head: string | null;
26
+ }
27
+ export declare const FRESHNESS_RECEIPT_FILE: string;
28
+ export declare const FRESHNESS_LEASE_MS: number;
29
+ /** A failed detached worker is visible immediately but retries only after this bounded pause. */
30
+ export declare const FRESHNESS_RETRY_MS: number;
31
+ /**
32
+ * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
33
+ * someone edits, so without an interval the graph would never refresh between commits — the former
34
+ * marker's 30-minute window, which A-SPEC-566.4 measured as the advisory's quality factor.
35
+ */
36
+ export declare const FRESHNESS_REREFRESH_MS: number;
37
+ /**
38
+ * Whether a receipt can ground requirement intake: a current graph plus a requirement lane that is
39
+ * current or the owner-chosen lexical-only `not-adopted`/`suppressed`. The source lane never counts.
40
+ */
41
+ export declare function intakeUsable(receipt: FreshnessReceipt | null | undefined): boolean;
42
+ /** Usable, but without requirement vectors: triage ran on lexical evidence alone. */
43
+ export declare function lexicalOnly(receipt: FreshnessReceipt | null | undefined): boolean;
44
+ /** Read-only judgement: untrusted, expired, foreign, and commit-mismatched state is never current. */
45
+ export declare function readFreshnessReceipt(root: string, expected: RefreshRequest): FreshnessReceipt | null;
46
+ /**
47
+ * Publish a new lease before the detached worker is started. The caller alone
48
+ * performs spawning when `spawn` is true; all matching live callers coalesce.
49
+ */
50
+ export declare function requestRefresh(root: string, input: RefreshRequest): {
51
+ spawn: boolean;
52
+ receipt: FreshnessReceipt;
53
+ };
54
+ /**
55
+ * True only while `generation` still holds the live lease in an existing root. A worker asks this
56
+ * before each phase that writes, so a superseded or orphaned child stops instead of recreating
57
+ * `.ax` under a root that was removed (A-SPEC-724).
58
+ */
59
+ export declare function ownsLease(root: string, generation: string): boolean;
60
+ /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
61
+ export declare function completeRefresh(root: string, generation: string, completion: RefreshCompletion, now: Date): FreshnessReceipt | null;
62
+ /**
63
+ * Initialized/registered workspaces use their governed identity. Legacy
64
+ * workspaces remain safe to refresh: their canonical real path is a local,
65
+ * deterministic identity and is never persisted as a secret or sent remotely.
66
+ */
67
+ export declare function workspaceIdFor(root: string): string;