@holmes-lab/holmes-kit 0.29.0 → 0.31.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 (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
@@ -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,81 @@
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
+ /** A-SPEC-729 — a random id per issuance, so every persist is a fresh, spendable digest. */
14
+ issuance?: string;
15
+ result: unknown;
16
+ }
17
+ type StoredArtifact = RequirementTriageArtifactV1 | RequirementTriageArtifact;
7
18
  /** Writes an atomically published artifact addressed by its content digest. */
8
- export declare function writeRequirementTriageEvidence(root: string, artifact: RequirementTriageArtifact): {
19
+ export declare function writeRequirementTriageEvidence(root: string, artifact: StoredArtifact): {
20
+ digest: string;
21
+ path: string;
22
+ };
23
+ /**
24
+ * @implements A-SPEC-729
25
+ * Persist AND issue: the artifact is written exactly as before, and the server records a
26
+ * `triage-issued` event for its digest on the hash-chained ledger. Intake accepts only issued digests,
27
+ * so a file written straight into the evidence directory — which anyone with a shell could do — is
28
+ * not authority.
29
+ */
30
+ export declare function issueRequirementTriageEvidence(root: string, artifact: StoredArtifact): {
9
31
  digest: string;
10
32
  path: string;
11
33
  };
34
+ /**
35
+ * @implements A-SPEC-729
36
+ * Spend the evidence on ONE REQ, atomically (lock + cross-chain spent check). Called after
37
+ * `validateRequirementIntake` and immediately before the REQ's first byte; a lost race or an
38
+ * unobtainable lock is a refusal, never a silent pass.
39
+ */
40
+ export declare function consumeRequirementTriageEvidence(root: string, digest: string, reqId: string): {
41
+ ok: true;
42
+ } | {
43
+ ok: false;
44
+ reason: string;
45
+ };
46
+ /**
47
+ * @implements A-SPEC-729 (round 5) — whether `reqId` entered through the intake: a verifying chain holds
48
+ * the consumption of `requirement-triage:<digest>` whose summary names `reqId`. The seal uses this to
49
+ * keep a REQ written around the intake from ever being sealed autonomously.
50
+ */
51
+ export declare function hasRequirementIntakeRecord(root: string, reqId: string, digest: unknown): boolean;
52
+ /**
53
+ * @implements A-SPEC-729 (round 6) — whether a verifying chain ever recorded `spec-approved` for this
54
+ * id. The FILE's approved_digest cannot answer it: an agent can write one into a draft (measured).
55
+ */
56
+ export declare function everSealedInLedger(root: string, specId: string): boolean;
57
+ /** Validates the address and all authoring-relevant bindings; v1 is advisory-only and never authoring evidence. */
58
+ export declare function validateTriageArtifact(root: string, digest: string, expected: {
59
+ promptDigest: string;
60
+ workspaceId: string;
61
+ head: string | null;
62
+ }): {
63
+ ok: true;
64
+ artifact: RequirementTriageArtifact;
65
+ } | {
66
+ ok: false;
67
+ reason: string;
68
+ };
69
+ /**
70
+ * @implements A-SPEC-724 — the ONE intake boundary every REQ-creating act crosses (spec_create and
71
+ * spec_slice_init). A new REQ may be born only from a current, prompt-bound v2 triage artifact whose
72
+ * freshness receipt is the current one for this workspace and HEAD. Callers run their own
73
+ * deterministic refusals first and call this immediately before their first write.
74
+ */
75
+ export declare function validateRequirementIntake(root: string, triageEvidence: unknown): {
76
+ ok: true;
77
+ } | {
78
+ ok: false;
79
+ reason: string;
80
+ };
81
+ export {};
@@ -35,11 +35,25 @@ 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.issueRequirementTriageEvidence = issueRequirementTriageEvidence;
39
+ exports.consumeRequirementTriageEvidence = consumeRequirementTriageEvidence;
40
+ exports.hasRequirementIntakeRecord = hasRequirementIntakeRecord;
41
+ exports.everSealedInLedger = everSealedInLedger;
42
+ exports.validateTriageArtifact = validateTriageArtifact;
43
+ exports.validateRequirementIntake = validateRequirementIntake;
44
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734
38
45
  // @implements A-SPEC-713
39
46
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
40
47
  const crypto = __importStar(require("node:crypto"));
41
48
  const fs = __importStar(require("node:fs"));
42
49
  const path = __importStar(require("node:path"));
50
+ const node_child_process_1 = require("node:child_process");
51
+ const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
+ const ledger_store_1 = require("../governance/ledger-store");
53
+ const provenance_chain_1 = require("../governance/provenance-chain");
54
+ const ledger_lock_1 = require("../governance/ledger-lock");
55
+ const display_id_aliases_1 = require("../governance/display-id-aliases");
56
+ const bounded_io_1 = require("../project/bounded-io");
43
57
  exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = path.join('.ax', 'evidence', 'requirement-triage');
44
58
  const sha256 = (text) => `sha256:${crypto.createHash('sha256').update(text).digest('hex')}`;
45
59
  const DIGEST = /^sha256:[a-f0-9]{64}$/;
@@ -62,7 +76,11 @@ function stable(value) {
62
76
  }
63
77
  /** Writes an atomically published artifact addressed by its content digest. */
64
78
  function writeRequirementTriageEvidence(root, artifact) {
65
- if (artifact.schema !== 'requirement-triage-evidence/1' || !DIGEST.test(artifact.promptDigest)) {
79
+ const v2 = artifact.schema === 'requirement-triage-evidence/2'
80
+ && typeof artifact.workspaceId === 'string' && artifact.workspaceId !== ''
81
+ && (typeof artifact.head === 'string' || artifact.head === null)
82
+ && typeof artifact.freshnessGeneration === 'string' && artifact.freshnessGeneration !== '';
83
+ if ((!v2 && artifact.schema !== 'requirement-triage-evidence/1') || !DIGEST.test(artifact.promptDigest)) {
66
84
  throw new Error('requirement triage artifact requires a sha256 prompt digest');
67
85
  }
68
86
  const body = `${stable(artifact)}\n`;
@@ -77,3 +95,211 @@ function writeRequirementTriageEvidence(root, artifact) {
77
95
  }
78
96
  return { digest, path: target };
79
97
  }
98
+ const ledgerDirOf = (root) => path.join(root, '.ax', 'ledger');
99
+ /** The single-use key a REQ spends: one per evidence digest. */
100
+ const spendKeyOf = (digest) => `requirement-triage:${digest}`;
101
+ const SPENT = '새 REQ triage evidence is already spent — each requirement_triage(persist:true) result admits one REQ creation attempt. 이 요구사항으로 requirement_triage(persist:true)를 다시 실행해 새 증거를 받으십시오.';
102
+ /**
103
+ * @implements A-SPEC-729
104
+ * Persist AND issue: the artifact is written exactly as before, and the server records a
105
+ * `triage-issued` event for its digest on the hash-chained ledger. Intake accepts only issued digests,
106
+ * so a file written straight into the evidence directory — which anyone with a shell could do — is
107
+ * not authority.
108
+ */
109
+ function issueRequirementTriageEvidence(root, artifact) {
110
+ // A unique issuance: re-running triage after a burned or spent digest yields a new one (round 1).
111
+ const unique = artifact.schema === 'requirement-triage-evidence/2' && !artifact.issuance
112
+ ? { ...artifact, issuance: crypto.randomUUID() } : artifact;
113
+ const written = writeRequirementTriageEvidence(root, unique);
114
+ new ledger_store_1.FileLedgerStore(ledgerDirOf(root)).append({
115
+ ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'triage-issued',
116
+ summary: 'requirement triage evidence issued', inputs: [written.digest],
117
+ });
118
+ return written;
119
+ }
120
+ /**
121
+ * @implements A-SPEC-729
122
+ * Spend the evidence on ONE REQ, atomically (lock + cross-chain spent check). Called after
123
+ * `validateRequirementIntake` and immediately before the REQ's first byte; a lost race or an
124
+ * unobtainable lock is a refusal, never a silent pass.
125
+ */
126
+ function consumeRequirementTriageEvidence(root, digest, reqId) {
127
+ const ledgerFile = (0, ledger_store_1.writerChainFile)(ledgerDirOf(root));
128
+ const key = spendKeyOf(digest);
129
+ try {
130
+ const won = (0, provenance_chain_1.consumeNonceExclusively)(key, ledgerFile, {
131
+ ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'nonce-consumed',
132
+ summary: `requirement triage evidence spent on ${reqId}`, inputs: [(0, provenance_chain_1.nonceFingerprint)(key)],
133
+ }, { isNonceConsumed: (0, ledger_store_1.nonceConsumedIn)(ledgerFile) });
134
+ return won ? { ok: true } : { ok: false, reason: SPENT };
135
+ }
136
+ catch (e) {
137
+ const busy = e instanceof ledger_lock_1.LedgerLockError;
138
+ return { ok: false, reason: busy
139
+ ? `새 REQ triage evidence could not be spent (ledger busy: ${e.message}) — 다시 시도하십시오.`
140
+ : `새 REQ triage evidence could not be spent (${e instanceof Error ? e.message : String(e)}) — the ledger could not record it; check it with holmes-kit doctor.` };
141
+ }
142
+ }
143
+ /**
144
+ * @implements A-SPEC-729 (round 5) — whether `reqId` entered through the intake: a verifying chain holds
145
+ * the consumption of `requirement-triage:<digest>` whose summary names `reqId`. The seal uses this to
146
+ * keep a REQ written around the intake from ever being sealed autonomously.
147
+ */
148
+ function hasRequirementIntakeRecord(root, reqId, digest) {
149
+ if (typeof digest !== 'string' || !DIGEST.test(digest))
150
+ return false;
151
+ try {
152
+ const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
153
+ const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
154
+ const fp = (0, provenance_chain_1.nonceFingerprint)(spendKeyOf(digest));
155
+ return store.loadAll().some((e) => e.kind === 'nonce-consumed' && !broken.has(e.replicaId)
156
+ && (e.inputs ?? []).includes(fp) && e.summary === `requirement triage evidence spent on ${reqId}`);
157
+ }
158
+ catch {
159
+ return false;
160
+ }
161
+ }
162
+ /**
163
+ * @implements A-SPEC-729 (round 6) — whether a verifying chain ever recorded `spec-approved` for this
164
+ * id. The FILE's approved_digest cannot answer it: an agent can write one into a draft (measured).
165
+ */
166
+ function everSealedInLedger(root, specId) {
167
+ try {
168
+ const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
169
+ const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
170
+ // @implements A-SPEC-729 (round 7) — the mark follows RECORDED renames, in ledger order: a sealed
171
+ // REQ renumbered away freed its id, and an untriaged REQ renumbered onto it read as "sealed
172
+ // before" (measured). Pairs of one rename event move at once, so a swap moves both marks.
173
+ const events = store.loadAll().map((e, i) => ({ e, i })).filter(({ e }) => !broken.has(e.replicaId));
174
+ events.sort((a, b) => (a.e.ts < b.e.ts ? -1 : a.e.ts > b.e.ts ? 1 : a.i - b.i));
175
+ const sealed = new Set();
176
+ for (const { e } of events) {
177
+ if (e.kind === 'spec-approved') {
178
+ const id = (e.inputs ?? [])[0];
179
+ if (typeof id === 'string')
180
+ sealed.add(id);
181
+ continue;
182
+ }
183
+ const pairs = (0, display_id_aliases_1.displayIdRenames)([e]);
184
+ if (pairs.length === 0)
185
+ continue;
186
+ const movedTo = pairs.filter((r) => sealed.has(r.oldId)).map((r) => r.newId);
187
+ for (const r of pairs)
188
+ sealed.delete(r.oldId);
189
+ for (const id of movedTo)
190
+ sealed.add(id);
191
+ }
192
+ return sealed.has(specId);
193
+ }
194
+ catch {
195
+ return false;
196
+ } // unreadable ledger: "never sealed" — the stricter answer
197
+ }
198
+ /** Validates the address and all authoring-relevant bindings; v1 is advisory-only and never authoring evidence. */
199
+ function validateTriageArtifact(root, digest, expected) {
200
+ if (!DIGEST.test(digest))
201
+ return { ok: false, reason: 'triage evidence digest is malformed' };
202
+ const file = path.join(root, exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR, `${digest.slice('sha256:'.length)}.json`);
203
+ let raw;
204
+ try {
205
+ raw = fs.readFileSync(file, 'utf8');
206
+ }
207
+ catch {
208
+ return { ok: false, reason: 'triage evidence is missing' };
209
+ }
210
+ if (sha256(raw) !== digest)
211
+ return { ok: false, reason: 'triage evidence digest does not match its content' };
212
+ let artifact;
213
+ try {
214
+ artifact = JSON.parse(raw);
215
+ }
216
+ catch {
217
+ return { ok: false, reason: 'triage evidence is unreadable' };
218
+ }
219
+ const a = artifact;
220
+ if (a.schema !== 'requirement-triage-evidence/2' || a.promptDigest !== expected.promptDigest
221
+ || a.workspaceId !== expected.workspaceId || a.head !== expected.head || typeof a.freshnessGeneration !== 'string') {
222
+ return { ok: false, reason: 'triage evidence does not bind this prompt, workspace, and HEAD' };
223
+ }
224
+ return { ok: true, artifact: a };
225
+ }
226
+ /**
227
+ * @implements A-SPEC-724 — the ONE intake boundary every REQ-creating act crosses (spec_create and
228
+ * spec_slice_init). A new REQ may be born only from a current, prompt-bound v2 triage artifact whose
229
+ * freshness receipt is the current one for this workspace and HEAD. Callers run their own
230
+ * deterministic refusals first and call this immediately before their first write.
231
+ */
232
+ function validateRequirementIntake(root, triageEvidence) {
233
+ const evidence = triageEvidence;
234
+ if (!evidence || typeof evidence.digest !== 'string' || typeof evidence.promptDigest !== 'string') {
235
+ return { ok: false, reason: '새 REQ에는 requirement_triage가 발급한 현재 triage_evidence {digest,promptDigest}가 필요합니다. 같은 prompt로 requirement_triage(persist:true)를 실행한 뒤 다시 시도하십시오.' };
236
+ }
237
+ let head = null;
238
+ try {
239
+ head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
240
+ }
241
+ catch { /* non-git root is null */ }
242
+ const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
243
+ const artifact = validateTriageArtifact(root, evidence.digest, { promptDigest: evidence.promptDigest, workspaceId, head });
244
+ if (!artifact.ok)
245
+ return { ok: false, reason: `새 REQ triage evidence를 검증할 수 없습니다: ${artifact.reason}` };
246
+ const receipt = (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId, head, now: new Date() });
247
+ // A-SPEC-719: intake-usable, i.e. current graph and a current or owner-chosen lexical-only
248
+ // requirement lane; the source lane is reported, never required.
249
+ // @implements A-SPEC-730 — name WHICH freshness problem it is, and its one recovery step.
250
+ if (!receipt) {
251
+ return { ok: false, reason: '새 REQ triage evidence: no fresh-evidence receipt exists for this workspace/HEAD. refresh가 완료된 뒤 requirement_triage(persist:true)를 다시 실행하십시오.' };
252
+ }
253
+ if (!(0, freshness_coordinator_1.intakeUsable)(receipt)) {
254
+ // Round 2: only a running refresh finishes by itself; any other state needs a new request.
255
+ return { ok: false, reason: receipt.state === 'refreshing'
256
+ ? '새 REQ triage evidence: the fresh-evidence receipt is refreshing (not intake-usable). refresh가 끝나기를 기다린 뒤 requirement_triage(persist:true)를 다시 실행하십시오.'
257
+ : `새 REQ triage evidence: the fresh-evidence receipt is ${receipt.state} (not intake-usable). requirement_triage(persist:true)를 다시 실행하면 refresh가 요청됩니다 — 그 refresh가 끝난 뒤 한 번 더 실행하십시오.` };
258
+ }
259
+ if (receipt.generation !== artifact.artifact.freshnessGeneration) {
260
+ return { ok: false, reason: `새 REQ triage evidence: the fresh-evidence receipt was re-issued after this triage (${artifact.artifact.freshnessGeneration} → ${receipt.generation}). re-run requirement_triage(persist:true) — no refresh is needed.` };
261
+ }
262
+ const verdict = artifact.artifact.result.verdict;
263
+ if (verdict === 'fulfilled')
264
+ return { ok: false, reason: 'triage 결과가 fulfilled입니다. 동일 요구사항의 새 REQ를 만들지 말고 기존 lineage를 사용하십시오.' };
265
+ if (verdict !== 'new' && verdict !== 'ambiguous')
266
+ return { ok: false, reason: `triage 결과 ${String(verdict)}는 새 REQ 생성 근거가 아닙니다. existing-change는 기존 REQ의 후속 변경으로 작성하십시오.` };
267
+ // @implements A-SPEC-729 — authority, not a file: the server must have issued this digest, and it
268
+ // must not have been spent on another REQ yet (the spend itself happens at the write).
269
+ // Only a chain that VERIFIES counts (round 1: a planted `provenance.<x>.jsonl` minted issuance). With
270
+ // HOLMES_LEDGER_KEY set, verification checks signatures, so a forged chain cannot pass.
271
+ const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
272
+ let issuedOn = [];
273
+ let broken = new Map();
274
+ let own = null;
275
+ try {
276
+ issuedOn = store.loadAll().filter((e) => e.kind === 'triage-issued' && (e.inputs ?? []).includes(evidence.digest)).map((e) => e.replicaId);
277
+ broken = new Map(store.verifyAll().broken.map((b) => [b.replicaId, b.detail]));
278
+ }
279
+ catch (e) {
280
+ // @implements A-SPEC-729 (round 4) — a ledger that cannot be read at all is a ledger fault; calling
281
+ // it "not issued" sent the user to re-run triage, which lands on the same unreadable ledger.
282
+ return { ok: false, reason: `새 REQ triage evidence: the ledger under .ax/ledger could not be read or verified (${String(e instanceof Error ? e.message : e).slice(0, 200)}) — nothing was spent. Fix the ledger first (holmes-kit doctor), then retry with the same evidence.` };
283
+ }
284
+ // Resolving the own chain id may throw (foreign execution); that must not read as never issued.
285
+ try {
286
+ own = store.replicaId();
287
+ }
288
+ catch {
289
+ own = null;
290
+ }
291
+ const verified = issuedOn.filter((r) => !broken.has(r));
292
+ if (verified.length === 0) {
293
+ // Round 2: when the broken chain is this writer's OWN, re-triage would land on the same chain —
294
+ // the only recovery is repairing the ledger, so the refusal says that instead.
295
+ if (issuedOn.length > 0 && own !== null && issuedOn.includes(own)) {
296
+ return { ok: false, reason: `새 REQ triage evidence: its issuance record is on this writer's own ledger chain ${own}, which fails verification (${String(broken.get(own)).slice(0, 200)}). Re-running triage would land on the same chain — repair the ledger first (holmes-kit doctor; ledger_reconcile), then re-run requirement_triage(persist:true).` };
297
+ }
298
+ return { ok: false, reason: issuedOn.length > 0
299
+ ? `새 REQ triage evidence: its issuance record is only on ledger chain ${issuedOn.map((r) => r ?? 'legacy').join(', ')}, which fails verification — not accepted. requirement_triage(persist:true)를 다시 실행하십시오.`
300
+ : '새 REQ triage evidence was not issued by requirement_triage (no ledger issuance record) — 같은 prompt로 requirement_triage(persist:true)를 실행해 발급받은 증거로 다시 시도하십시오.' };
301
+ }
302
+ if (store.isNonceConsumed(spendKeyOf(evidence.digest)))
303
+ return { ok: false, reason: SPENT };
304
+ return { ok: true };
305
+ }
@@ -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, A-SPEC-732, A-SPEC-734
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,10 +10,13 @@ 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
16
17
  // logged once to stderr (stdout is the protocol channel) so a mis-bound server is diagnosable.
18
+ // @implements A-SPEC-734 (round 13) — this process never blocks on a file that is not a regular file.
19
+ require('../project/regular-file-guard').installProcessGuards();
17
20
  const { resolveServerSpecsDir } = require('./server-specs-dir');
18
21
  const SPECS_DIR = resolveServerSpecsDir(process.env, process.cwd());
19
22
  try {
@@ -35,7 +38,9 @@ const store = new spec_store_1.LocalMarkdownRepository(SPECS_DIR);
35
38
  const { runElicitFlow } = require('./elicit-approval');
36
39
  const elicit = async (req) => {
37
40
  try {
38
- if (!server.getClientCapabilities()?.elicitation)
41
+ if (!(0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()))
42
+ return { kind: 'silent' };
43
+ if (!harnessAttestation().attested)
39
44
  return { kind: 'silent' };
40
45
  return await runElicitFlow((form, timeoutMs) => server.elicitInput(form, { timeout: timeoutMs }), req);
41
46
  }
@@ -43,8 +48,24 @@ const elicit = async (req) => {
43
48
  return { kind: 'silent' };
44
49
  }
45
50
  };
51
+ // @implements A-SPEC-732 (round 2) — who launched this server, asked once, on first need.
52
+ const { attestHarness, systemProcLookup } = require('./harness-attestation');
53
+ let attested;
54
+ const harnessAttestation = () => {
55
+ if (attested === undefined) {
56
+ try {
57
+ attested = attestHarness(process.ppid, systemProcLookup());
58
+ }
59
+ catch {
60
+ attested = { attested: false, chain: [], reason: 'the process table could not be read' };
61
+ }
62
+ }
63
+ return attested;
64
+ };
46
65
  const handlers = (0, handlers_1.makeHandlers)(store, {
66
+ harnessAttestation,
47
67
  elicit,
68
+ elicitationAvailable: () => (0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()),
48
69
  observeInvocation: root => stampSession(root),
49
70
  clientName: () => { try {
50
71
  return server.getClientVersion()?.name ?? 'unknown';
@@ -126,7 +147,7 @@ const TOOLS = Object.keys(handlers)
126
147
  .map((name) => {
127
148
  const def = tool_schemas_1.TOOL_SCHEMAS[name];
128
149
  return def
129
- ? { name, description: def.description, inputSchema: def.inputSchema }
150
+ ? { name, description: def.description, inputSchema: def.inputSchema, ...(def.annotations ? { annotations: def.annotations } : {}) }
130
151
  : { name, description: name, inputSchema: { type: 'object', properties: {} } };
131
152
  });
132
153
  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-736, A-SPEC-735, A-SPEC-729, 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. Single-use: one evidence admits one REQ creation attempt; re-run triage for another.',
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,
@@ -237,8 +262,13 @@ exports.TOOL_SCHEMAS = {
237
262
  },
238
263
  },
239
264
  spec_next: {
240
- description: 'Return the next spec kind in the pipeline that has no approved instance yet ({ next }).',
241
- inputSchema: { type: 'object', properties: {} },
265
+ // @implements A-SPEC-736
266
+ description: 'Name the governance actions a slice needs now. With `id`, returns that spec\'s whole chain (ancestors and descendants, '
267
+ + 'parent-first) as `chain` rows and one action per unsealed member: seal | fill-then-seal (placeholder sections named) | '
268
+ + 'after-parent (the unsealed parent named) | create-parent (the missing id named), plus author-tspec for a sealed A-SPEC with no '
269
+ + 'T-SPEC. Without `id`, the first 20 such actions across the store (after-parent omitted) and `actionsTotal`. Read-only. '
270
+ + '`next` is kept for existing callers: the first spec kind with no approved instance anywhere — a v0.1 heuristic, not a step.',
271
+ inputSchema: { type: 'object', properties: { id: str('Optional spec id whose chain to report, e.g. A-SPEC-188.') } },
242
272
  },
243
273
  citation_pin: {
244
274
  description: "Compute and record the content digest (sha256) of a REQ's cited sources that resolve inside the repo, so a citation's rev is derived from what is actually on disk. Dry-run by default; never overwrites an existing digest.",
@@ -260,12 +290,24 @@ exports.TOOL_SCHEMAS = {
260
290
  },
261
291
  },
262
292
  phase_status: {
263
- description: 'Return every spec with its id/type/status (raw material for deriving phase via phase_check). '
293
+ // @implements A-SPEC-735 — the whole corpus in one answer was 153,888 characters here.
294
+ description: 'Summarize the spec corpus and page its id/type/status rows (raw material for deriving phase via phase_check). '
295
+ + 'Always returns `summary` { total, counts[type][status], notApproved (first 50 non-approved rows), notApprovedTotal } '
296
+ + 'and one page: `specs` (id order, default 100 rows, `limit` 1..500), `matched` (rows passing the filters) and '
297
+ + '`nextCursor` when more follow — pass it back as `cursor`. Filter with `ids` (unknown ones are named in `unknownIds`), '
298
+ + '`type` and `status`. '
264
299
  + 'The corpus is the store this server is BOUND to; a root naming a different project is refused rather than answered '
265
300
  + "with this server's specs (round-9: it was advertised, ignored, and answered success-shaped for someone else's root).",
266
301
  inputSchema: {
267
302
  type: 'object',
268
- properties: { root: ROOT },
303
+ properties: {
304
+ root: ROOT,
305
+ ids: strArray('Only these spec ids; ids that do not exist are listed in `unknownIds`.'),
306
+ type: str('Only this spec kind, e.g. REQ | H-SPEC | A-SPEC | C-SPEC | T-SPEC | ADR.'),
307
+ status: str('Only this status, e.g. draft | approved | outdated.'),
308
+ limit: num('Rows per page: an integer 1..500 (default 100).'),
309
+ cursor: str('The `nextCursor` of the previous page; rows after this id are returned.'),
310
+ },
269
311
  },
270
312
  },
271
313
  phase_check: {
@@ -367,14 +409,14 @@ exports.TOOL_SCHEMAS = {
367
409
  },
368
410
  },
369
411
  requirement_triage: {
370
- description: 'Read-only requirement lifecycle advisory. BM25 always ranks governed REQ/H-SPEC/A-SPEC/T-SPEC lineages; cached local BGE-M3 or explicit Gemini candidates are additive. Content, approval, implementation-anchor, and fresh execution evidence determine fulfilled, existing-change, new, or ambiguous. It never creates, edits, approves, unseals, retires, or opens a source-edit gate.',
412
+ description: 'Read-only requirement lifecycle advisory. BM25 always ranks governed REQ/H-SPEC/A-SPEC/T-SPEC lineages; cached local BGE-M3 or explicit Gemini candidates are additive. Content, approval, implementation-anchor, and fresh execution evidence determine fulfilled, existing-change, new, or ambiguous. It never creates, edits, approves, unseals, retires, or opens a source-edit gate; with persist:true it records one evidence artifact and its ledger issuance.',
371
413
  inputSchema: {
372
414
  type: 'object',
373
415
  properties: {
374
416
  root: ROOT_ANY,
375
417
  prompt: str('User requirement or requested behavior to compare with governed requirement lineages.'),
376
418
  topK: num('Maximum displayed candidate lineages (default 10, clamped to 1..20).'),
377
- persist: bool('Write only a content-addressed requirement-triage evidence artifact. Default false.'),
419
+ persist: bool('Write a content-addressed requirement-triage evidence artifact and record its issuance on the provenance ledger (single-use REQ intake evidence). Default false.'),
378
420
  },
379
421
  required: ['root', 'prompt'],
380
422
  },
@@ -622,6 +664,11 @@ exports.TOOL_SCHEMAS = {
622
664
  title: str('Title for the requirement and specs.'),
623
665
  objective: str('High-level objective or problem statement.'),
624
666
  filesToTouch: strArray('List of source/test file paths to be touched by this slice.'),
667
+ triage_evidence: {
668
+ 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. Single-use: one evidence admits one REQ creation attempt.',
669
+ properties: { digest: str('Content-addressed triage evidence digest.'), promptDigest: str('Digest of the exact authoring prompt.') },
670
+ required: ['digest', 'promptDigest'],
671
+ },
625
672
  },
626
673
  required: ['sliceName', 'title', 'objective', 'filesToTouch'],
627
674
  },