@holmes-lab/holmes-kit 0.30.0 → 0.31.1

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 (139) hide show
  1. package/CHANGELOG.md +505 -0
  2. package/README.md +10 -1
  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.d.ts +41 -0
  9. package/dist/holmes/cli/agents.js +382 -2
  10. package/dist/holmes/cli/attest.d.ts +2 -0
  11. package/dist/holmes/cli/attest.js +66 -15
  12. package/dist/holmes/cli/ci-gate.js +16 -1
  13. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  14. package/dist/holmes/cli/claude-switches.js +967 -0
  15. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  16. package/dist/holmes/cli/codex-hooks.js +802 -0
  17. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  18. package/dist/holmes/cli/codex-oracle.js +1245 -0
  19. package/dist/holmes/cli/codex-toml.d.ts +35 -0
  20. package/dist/holmes/cli/codex-toml.js +321 -52
  21. package/dist/holmes/cli/doctor.d.ts +98 -8
  22. package/dist/holmes/cli/doctor.js +1328 -94
  23. package/dist/holmes/cli/index.js +26 -11
  24. package/dist/holmes/cli/init.d.ts +11 -0
  25. package/dist/holmes/cli/init.js +736 -44
  26. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  27. package/dist/holmes/cli/mcp-launcher.js +189 -6
  28. package/dist/holmes/cli/mcp-version.js +13 -2
  29. package/dist/holmes/cli/settings-merge.js +8 -2
  30. package/dist/holmes/cli/upgrade.d.ts +18 -0
  31. package/dist/holmes/cli/upgrade.js +129 -24
  32. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  33. package/dist/holmes/cli/workspace-scope.js +375 -0
  34. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  35. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  36. package/dist/holmes/cpg/cycle-detect.js +2 -1
  37. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  38. package/dist/holmes/cpg/required-calls.js +8 -1
  39. package/dist/holmes/governance/constitution-debt.js +3 -2
  40. package/dist/holmes/governance/constitution.js +15 -3
  41. package/dist/holmes/governance/provenance-chain.js +3 -2
  42. package/dist/holmes/governance/push-gate-runner.js +4 -3
  43. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  44. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  45. package/dist/holmes/guardrail/linear-match.js +256 -0
  46. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  47. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  48. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  49. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  50. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  51. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  52. package/dist/holmes/guardrail/shell-words.js +1720 -0
  53. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  54. package/dist/holmes/guardrail/write-target.js +2379 -87
  55. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  56. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  57. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  58. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  59. package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
  60. package/dist/holmes/hooks/rtm-refresh.js +8 -4
  61. package/dist/holmes/hooks/session-start.d.ts +10 -0
  62. package/dist/holmes/hooks/session-start.js +31 -7
  63. package/dist/holmes/hooks/stop.d.ts +2 -1
  64. package/dist/holmes/hooks/stop.js +197 -91
  65. package/dist/holmes/mcp/approval-commit.d.ts +5 -6
  66. package/dist/holmes/mcp/approval-commit.js +18 -2
  67. package/dist/holmes/mcp/elicit-approval.js +4 -2
  68. package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
  69. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  70. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  71. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  72. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  73. package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
  74. package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
  75. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
  76. package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
  77. package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
  78. package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
  79. package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
  80. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  81. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  82. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  83. package/dist/holmes/mcp/handlers.d.ts +81 -9
  84. package/dist/holmes/mcp/handlers.js +70 -23
  85. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  86. package/dist/holmes/mcp/harness-attestation.js +179 -0
  87. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
  88. package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
  89. package/dist/holmes/mcp/server.js +20 -1
  90. package/dist/holmes/mcp/tool-schemas.js +26 -9
  91. package/dist/holmes/mcp/validate-args.js +12 -0
  92. package/dist/holmes/project/bounded-io.d.ts +102 -0
  93. package/dist/holmes/project/bounded-io.js +212 -0
  94. package/dist/holmes/project/change-source.js +3 -1
  95. package/dist/holmes/project/ci-runs.js +3 -2
  96. package/dist/holmes/project/ignore.d.ts +31 -2
  97. package/dist/holmes/project/ignore.js +409 -50
  98. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  99. package/dist/holmes/project/regular-file-guard.js +149 -0
  100. package/dist/holmes/project/root.js +12 -3
  101. package/dist/holmes/reverse/anchor.js +4 -3
  102. package/dist/holmes/reverse/scan.js +6 -2
  103. package/dist/holmes/review/commit-text.js +3 -2
  104. package/dist/holmes/review/condition-hunk-replay.js +3 -2
  105. package/dist/holmes/review/failed-test-names.js +13 -10
  106. package/dist/holmes/review/findings.js +3 -1
  107. package/dist/holmes/review/kills-check.js +6 -1
  108. package/dist/holmes/review/point-in-time-replay.js +5 -4
  109. package/dist/holmes/review/replay-corpus.js +5 -4
  110. package/dist/holmes/review/run-replay.js +3 -2
  111. package/dist/holmes/review/temporal-prior.js +3 -2
  112. package/dist/holmes/review/test-evidence.js +3 -2
  113. package/dist/holmes/review/test-outcomes.js +3 -2
  114. package/dist/holmes/review/test-runner.d.ts +6 -0
  115. package/dist/holmes/review/test-runner.js +36 -15
  116. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  117. package/dist/holmes/rtm/anchor-ids.js +42 -2
  118. package/dist/holmes/rtm/file-anchors.js +4 -1
  119. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  120. package/dist/holmes/rtm/git-changes.js +3 -1
  121. package/dist/holmes/rtm/graph-store.js +3 -2
  122. package/dist/holmes/rtm/test-scope.js +9 -4
  123. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  124. package/dist/holmes/spec/compat-impact.js +682 -11
  125. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  126. package/dist/holmes/spec/entity-integration.js +3 -2
  127. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  128. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  129. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  130. package/dist/holmes/spec/renumber.js +25 -10
  131. package/dist/holmes/spec/spec-parser.js +9 -3
  132. package/dist/holmes/spec/yaml-scalar.js +2 -2
  133. package/dist/holmes/update/refresh.d.ts +5 -0
  134. package/dist/holmes/update/refresh.js +26 -1
  135. package/dist/holmes/update/update-notice.d.ts +6 -0
  136. package/dist/holmes/update/update-notice.js +18 -1
  137. package/dist/holmes/update/upgrade-plan.d.ts +28 -0
  138. package/dist/holmes/update/upgrade-plan.js +31 -2
  139. package/package.json +11 -4
@@ -35,9 +35,13 @@ 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;
38
42
  exports.validateTriageArtifact = validateTriageArtifact;
39
43
  exports.validateRequirementIntake = validateRequirementIntake;
40
- // @implements A-SPEC-724, A-SPEC-719
44
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734
41
45
  // @implements A-SPEC-713
42
46
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
43
47
  const crypto = __importStar(require("node:crypto"));
@@ -45,6 +49,11 @@ const fs = __importStar(require("node:fs"));
45
49
  const path = __importStar(require("node:path"));
46
50
  const node_child_process_1 = require("node:child_process");
47
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");
48
57
  exports.REQUIREMENT_TRIAGE_EVIDENCE_DIR = path.join('.ax', 'evidence', 'requirement-triage');
49
58
  const sha256 = (text) => `sha256:${crypto.createHash('sha256').update(text).digest('hex')}`;
50
59
  const DIGEST = /^sha256:[a-f0-9]{64}$/;
@@ -86,6 +95,106 @@ function writeRequirementTriageEvidence(root, artifact) {
86
95
  }
87
96
  return { digest, path: target };
88
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
+ }
89
198
  /** Validates the address and all authoring-relevant bindings; v1 is advisory-only and never authoring evidence. */
90
199
  function validateTriageArtifact(root, digest, expected) {
91
200
  if (!DIGEST.test(digest))
@@ -127,7 +236,7 @@ function validateRequirementIntake(root, triageEvidence) {
127
236
  }
128
237
  let head = null;
129
238
  try {
130
- head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
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;
131
240
  }
132
241
  catch { /* non-git root is null */ }
133
242
  const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
@@ -137,13 +246,60 @@ function validateRequirementIntake(root, triageEvidence) {
137
246
  const receipt = (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId, head, now: new Date() });
138
247
  // A-SPEC-719: intake-usable, i.e. current graph and a current or owner-chosen lexical-only
139
248
  // 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를 다시 실행하십시오.' };
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.` };
142
261
  }
143
262
  const verdict = artifact.artifact.result.verdict;
144
263
  if (verdict === 'fulfilled')
145
264
  return { ok: false, reason: 'triage 결과가 fulfilled입니다. 동일 요구사항의 새 REQ를 만들지 말고 기존 lineage를 사용하십시오.' };
146
265
  if (verdict !== 'new' && verdict !== 'ambiguous')
147
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 };
148
304
  return { ok: true };
149
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-720, A-SPEC-718, 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");
@@ -15,6 +15,8 @@ const approval_adapters_1 = require("./approval-adapters");
15
15
  // @implements A-SPEC-652.2 — the store is opened at an ABSOLUTE path resolved against the project
16
16
  // root (CLAUDE_PROJECT_DIR, then the nearest .mcp.json/.ax ancestor, then cwd), and the path is
17
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();
18
20
  const { resolveServerSpecsDir } = require('./server-specs-dir');
19
21
  const SPECS_DIR = resolveServerSpecsDir(process.env, process.cwd());
20
22
  try {
@@ -38,13 +40,30 @@ const elicit = async (req) => {
38
40
  try {
39
41
  if (!(0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()))
40
42
  return { kind: 'silent' };
43
+ if (!harnessAttestation().attested)
44
+ return { kind: 'silent' };
41
45
  return await runElicitFlow((form, timeoutMs) => server.elicitInput(form, { timeout: timeoutMs }), req);
42
46
  }
43
47
  catch {
44
48
  return { kind: 'silent' };
45
49
  }
46
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
+ };
47
65
  const handlers = (0, handlers_1.makeHandlers)(store, {
66
+ harnessAttestation,
48
67
  elicit,
49
68
  elicitationAvailable: () => (0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()),
50
69
  observeInvocation: root => stampSession(root),
@@ -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-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
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
@@ -125,7 +125,7 @@ exports.TOOL_SCHEMAS = {
125
125
  // exemption stays for genuine frontmatter.
126
126
  root: ROOT,
127
127
  triage_evidence: {
128
- type: 'object', description: 'Required for a new REQ: current requirement_triage(persist:true) v2 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
129
  properties: { digest: str('Content-addressed triage evidence digest.'), promptDigest: str('Digest of the exact authoring prompt.') },
130
130
  required: ['digest', 'promptDigest'],
131
131
  },
@@ -262,8 +262,13 @@ exports.TOOL_SCHEMAS = {
262
262
  },
263
263
  },
264
264
  spec_next: {
265
- description: 'Return the next spec kind in the pipeline that has no approved instance yet ({ next }).',
266
- 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.') } },
267
272
  },
268
273
  citation_pin: {
269
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.",
@@ -285,12 +290,24 @@ exports.TOOL_SCHEMAS = {
285
290
  },
286
291
  },
287
292
  phase_status: {
288
- 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`. '
289
299
  + 'The corpus is the store this server is BOUND to; a root naming a different project is refused rather than answered '
290
300
  + "with this server's specs (round-9: it was advertised, ignored, and answered success-shaped for someone else's root).",
291
301
  inputSchema: {
292
302
  type: 'object',
293
- 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
+ },
294
311
  },
295
312
  },
296
313
  phase_check: {
@@ -392,14 +409,14 @@ exports.TOOL_SCHEMAS = {
392
409
  },
393
410
  },
394
411
  requirement_triage: {
395
- 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.',
396
413
  inputSchema: {
397
414
  type: 'object',
398
415
  properties: {
399
416
  root: ROOT_ANY,
400
417
  prompt: str('User requirement or requested behavior to compare with governed requirement lineages.'),
401
418
  topK: num('Maximum displayed candidate lineages (default 10, clamped to 1..20).'),
402
- 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.'),
403
420
  },
404
421
  required: ['root', 'prompt'],
405
422
  },
@@ -648,7 +665,7 @@ exports.TOOL_SCHEMAS = {
648
665
  objective: str('High-level objective or problem statement.'),
649
666
  filesToTouch: strArray('List of source/test file paths to be touched by this slice.'),
650
667
  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.',
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.',
652
669
  properties: { digest: str('Content-addressed triage evidence digest.'), promptDigest: str('Digest of the exact authoring prompt.') },
653
670
  required: ['digest', 'promptDigest'],
654
671
  },
@@ -218,6 +218,18 @@ function judgeObject(path, schema, value, out) {
218
218
  : `외 ${quoteAll('', us.slice(1))}은(는) 알 수 없는 키입니다 — ${target}을(를) 잘못 쓴 것 아닙니까`,
219
219
  });
220
220
  }
221
+ // @implements A-SPEC-732 (round 3) — `additionalProperties: false` is a contract that NO other
222
+ // key is accepted; only near-typos were refused, so `{...intent, root}` passed approval_commit.
223
+ // Keys already named through a typo line above are not named twice.
224
+ if (schema.additionalProperties === false) {
225
+ const strays = unknownKeys.filter((u) => !assign.has(u)).sort();
226
+ if (strays.length > 0) {
227
+ out.push({
228
+ path: path ? `${path}.${strays[0]}` : strays[0],
229
+ message: `${strays.length > 1 ? ` 외 ${quoteAll('', strays.slice(1))}` : ''}은(는) 이 도구가 받지 않는 키입니다 (additionalProperties: false)`,
230
+ });
231
+ }
232
+ }
221
233
  for (const [key, prop] of Object.entries(props)) {
222
234
  const v = value[key];
223
235
  if (v === undefined || v === null)
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Bounded I/O shared by every caller on a hook, MCP or scan path (A-SPEC-734 round 12).
3
+ *
4
+ * A git child without a timeout, a git child with Node's 1 MiB default output buffer, or a plain
5
+ * `readFileSync` of a path that could be a FIFO each turned into a hang or a silently skipped check
6
+ * somewhere in the tree (measured: a FIFO `.gitattributes` blocked `git log --name-only` inside
7
+ * `maintenance_analyze`; `include.path` pointing at a FIFO blocked `git rev-parse` in every hook; a
8
+ * status larger than 1 MiB made the Stop hook's ART-1 check read "no signal"). The bounds live here
9
+ * so they are one decision, and a census test reads the tree for every git child.
10
+ */
11
+ import { type SpawnSyncReturns } from 'node:child_process';
12
+ /** A git child on a hook, MCP or scan path. */
13
+ export declare const GIT_TIMEOUT_MS = 5000;
14
+ /** Replay and integration tooling that walks whole histories or object stores. */
15
+ export declare const GIT_LONG_TIMEOUT_MS = 120000;
16
+ /** Output a git child may produce before it counts as a failure (Node's default is 1 MiB). */
17
+ export declare const GIT_MAX_BUFFER: number;
18
+ /**
19
+ * @implements A-SPEC-734 (round 13) — the memory is kept per KIND of query. `repo` queries read only the
20
+ * configuration, refs and the index (`rev-parse`, `worktree list`, `ls-files -s`); `worktree` queries also read
21
+ * work-tree files, attributes or ignore rules (`status`, `diff`, `log` with paths, `ls-files -o`,
22
+ * `check-ignore`). A `worktree` timeout blocks `worktree` queries only; a `repo` timeout blocks both — the
23
+ * configuration itself does not load. One shared stamp made a slow status (`core.fsmonitor`, a FIFO
24
+ * `.gitattributes`) silence `worktree list` for 60 s, and the Stop hook walked three registered agent
25
+ * worktrees and blocked on ART-9 in their files (measured).
26
+ */
27
+ export type GitKind = 'repo' | 'worktree';
28
+ /**
29
+ * Whether a git child of this kind for `root` timed out within the last minute (every caller then answers
30
+ * "no signal" at once). The default kind is `worktree`, the one every timeout blocks.
31
+ */
32
+ export declare function gitRootBlocked(root: string, kind?: GitKind): boolean;
33
+ /**
34
+ * Records a git failure for `root` when it was a timeout (other failures are ordinary answers). The default
35
+ * kind is `worktree`: a caller that does not say is never allowed to silence the `repo` queries.
36
+ */
37
+ export declare function noteGitFailure(root: string, err: unknown, kind?: GitKind): void;
38
+ /**
39
+ * @implements A-SPEC-734 (round 13) — one bounded git child that consults and feeds the memory: a blocked
40
+ * root answers at once with `status: null` and `error.code: 'EBLOCKED'`. The Stop hook's git children go
41
+ * through it (five of its call sites neither consulted nor fed the memory: `include.path` → FIFO took
42
+ * 27–32 s — measured).
43
+ */
44
+ export declare function gitOnce(root: string, args: string[], kind: GitKind, opts?: {
45
+ cwd?: string;
46
+ input?: string;
47
+ timeout?: number;
48
+ env?: NodeJS.ProcessEnv;
49
+ }): SpawnSyncReturns<string>;
50
+ /** Test seam: forget every blocked root. */
51
+ export declare function resetGitBlocked(): void;
52
+ /**
53
+ * A file read only when it is a REGULAR file: opened non-blocking, so a FIFO in its place returns at once
54
+ * instead of waiting for a writer, then refused with everything else that is not a regular file (a device
55
+ * such as `/dev/zero` included). Throws like `readFileSync` does, so callers keep their error handling.
56
+ */
57
+ export declare function readRegularFileSync(p: string): Buffer;
58
+ /** `readRegularFileSync` as UTF-8 text. */
59
+ export declare function readRegularTextSync(p: string): string;
60
+ /**
61
+ * @implements A-SPEC-734 (round 15) — what a git result means: `answered` (exit 0), `no-repository` (git SAYS the
62
+ * directory is not a repository, or there is no git at all), or `unanswered` — every other failure: a timeout, an
63
+ * overflow, a blocked root, or a refusal inside a repository (dubious ownership, an unknown `extensions.*`, a
64
+ * corrupt index — all exit 128, and were read as "no repository": `rm -r src` was allowed — measured). Accepts a
65
+ * `spawnSync` result or a thrown `execFileSync` error; the caller must have piped stderr for a refusal to be told
66
+ * apart from "not a repository" (without it, a failure is `unanswered`, the stricter reading).
67
+ */
68
+ export type GitAnswer = 'answered' | 'no-repository' | 'unanswered';
69
+ /**
70
+ * @implements A-SPEC-734 (round 16) — with `dir`, "no repository" is decided by the TREE: no `.git` entry in `dir` or
71
+ * any ancestor. Round 15 read git's English message — a translated git (Linux/Homebrew git under `LANG=ko_KR`) turned
72
+ * every non-git project into "did not answer", and `not a git repository: <gitdir>` (a submodule without its modules
73
+ * directory, a linked worktree whose main repository moved) read as "no repository" (measured).
74
+ */
75
+ export declare function gitAnswerOf(r: {
76
+ error?: unknown;
77
+ status?: number | null;
78
+ stderr?: unknown;
79
+ code?: unknown;
80
+ }, dir?: string): GitAnswer;
81
+ /** Whether `dir` or an ancestor holds a `.git` entry (file, directory or link) — the tree's own answer to "is this a repository". */
82
+ export declare function gitEntryAbove(dir: string): boolean;
83
+ /**
84
+ * @implements A-SPEC-734 (round 16) — the variables that relocate the repository a git child reads. An exported
85
+ * dotfiles `GIT_DIR` made the rm gate judge the project by that repository (measured).
86
+ */
87
+ export declare const REPO_LOCATING_GIT_VARS: readonly ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_NAMESPACE", "GIT_CEILING_DIRECTORIES", "GIT_DISCOVERY_ACROSS_FILESYSTEM"];
88
+ /**
89
+ * @implements A-SPEC-734 (round 17) — `full` (a porcelain path from the repository root) relative to the project whose
90
+ * `rev-parse --show-prefix` is `prefix`, compared segment by segment NFC and case-folded; null when it lies elsewhere.
91
+ * A `-- .` pathspec is matched case-sensitively by git, so a package whose directory case differs between the index and
92
+ * a case-folding disk read clean (measured).
93
+ */
94
+ export declare function underGitPrefix(full: string, prefix: string): string | null;
95
+ /** A git child's environment: the caller's, without the variables that relocate the repository (round 17). */
96
+ export declare function gitEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
97
+ /** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
98
+ export declare function gitUnanswered(r: {
99
+ error?: unknown;
100
+ status?: number | null;
101
+ stderr?: unknown;
102
+ }, dir?: string): boolean;