@holmes-lab/holmes-kit 0.30.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 (136) hide show
  1. package/CHANGELOG.md +494 -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 +23 -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 +13 -0
  31. package/dist/holmes/cli/upgrade.js +116 -23
  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.js +3 -1
  134. package/dist/holmes/update/update-notice.d.ts +6 -0
  135. package/dist/holmes/update/update-notice.js +18 -1
  136. package/package.json +11 -4
@@ -44,6 +44,8 @@ export interface SpecApprovalContext {
44
44
  risk?: string;
45
45
  }): string;
46
46
  foreignRootReason(root?: string): string | null;
47
+ /** @implements A-SPEC-732 — why no in-session route was offered (unattested server), or ''. */
48
+ approvalRouteNote?(): string;
47
49
  }
48
50
  export declare function createSpecApprovalHandlers(context: SpecApprovalContext): {
49
51
  /**
@@ -133,3 +135,10 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
133
135
  reason?: undefined;
134
136
  }>;
135
137
  };
138
+ /**
139
+ * @implements A-SPEC-733 (round 3) — the approval act reads a Files-to-Touch path only when it is a
140
+ * regular file inside the project, at most 2 MB. Measured: a FIFO named there blocked approval, and a
141
+ * `../` path read a file outside the project. The descriptor is opened non-blocking and judged by
142
+ * fstat, so a path swapped between check and read is judged as what was opened.
143
+ */
144
+ export declare function readProjectFile(root: string, rel: string): string | null;
@@ -34,9 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createSpecApprovalHandlers = createSpecApprovalHandlers;
37
- // @implements A-SPEC-718, A-SPEC-551.1, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
38
- // @implements A-SPEC-631
37
+ exports.readProjectFile = readProjectFile;
38
+ // @implements A-SPEC-718, A-SPEC-551.1, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245, A-SPEC-729
39
+ // @implements A-SPEC-631, A-SPEC-733
39
40
  const fs = __importStar(require("node:fs"));
41
+ const compat_impact_1 = require("../../spec/compat-impact");
40
42
  const path = __importStar(require("node:path"));
41
43
  const spec_store_1 = require("../../spec/spec-store");
42
44
  const transition_policy_1 = require("../../spec/transition-policy");
@@ -50,6 +52,7 @@ const version_conflict_1 = require("../../spec/version-conflict");
50
52
  const ledger_store_1 = require("../../governance/ledger-store");
51
53
  const provenance_chain_1 = require("../../governance/provenance-chain");
52
54
  const review_targets_1 = require("../../review/review-targets");
55
+ const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
53
56
  const approval_policy_1 = require("../approval-policy");
54
57
  function createSpecApprovalHandlers(context) {
55
58
  const { store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval } = context;
@@ -86,6 +89,24 @@ function createSpecApprovalHandlers(context) {
86
89
  let elicitExpiredMs;
87
90
  let risk;
88
91
  let subject;
92
+ // @implements A-SPEC-732 (round 2) — the digest a person or the autonomy grade decided on; the
93
+ // seal must be built from that same content.
94
+ let decidedSubject;
95
+ // A continuation is offered or spent only on a call that can land in this bound project.
96
+ const bindingOk = () => {
97
+ try {
98
+ if (store instanceof spec_store_1.LocalMarkdownRepository) {
99
+ const derived = context.projectRootOf(store.specsRoot);
100
+ if (fs.existsSync(path.join(derived, '.ax'))) {
101
+ return typeof a.root !== 'string' || a.root === '' || (0, write_target_1.resolveTarget)(context.projectRootOf(a.root), '.') === (0, write_target_1.resolveTarget)(derived, '.');
102
+ }
103
+ }
104
+ return typeof a.root === 'string' && a.root !== '';
105
+ }
106
+ catch {
107
+ return false;
108
+ }
109
+ };
89
110
  if (approveResolved === undefined) {
90
111
  const target = await store.read(a.id).catch(() => null);
91
112
  // @implements A-SPEC-649 — the digest of what the operator will read rides the request.
@@ -94,9 +115,11 @@ function createSpecApprovalHandlers(context) {
94
115
  const targetSubject = (0, spec_digest_1.specDigest)(target.spec);
95
116
  // A host-gated commit is a continuation of this exact original action. It is checked
96
117
  // before presentation and is memory-only, so a bare retry never carries authority.
97
- const hostApproval = context.consumeHostApproval({ kind: action.kind, target: action.target, subject: targetSubject, root: a.root });
98
- if (hostApproval)
118
+ const hostApproval = bindingOk() ? context.consumeHostApproval({ kind: action.kind, target: action.target, subject: targetSubject, root: a.root }) : undefined;
119
+ if (hostApproval) {
99
120
  approveResolved = { approval: hostApproval, source: 'elicitation' };
121
+ decidedSubject = targetSubject;
122
+ }
100
123
  if (approveResolved !== undefined) {
101
124
  // The rest of the existing seal path owns all validation and audit behavior.
102
125
  }
@@ -110,7 +133,15 @@ function createSpecApprovalHandlers(context) {
110
133
  // exceptions; an unclassified upstream request is intentionally queued instead.
111
134
  // @implements A-SPEC-553.1 — autonomy is the out-of-band env switch OR a valid, non-expired
112
135
  // session envelope marker under this project's `.ax/state/` (which an agent cannot write).
113
- const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
136
+ // @implements A-SPEC-732 (round 2) — at the PROJECT root: a raw root under .ax/specs let a planted
137
+ // marker switch autonomy on.
138
+ const autonomyRoot = (() => { try {
139
+ return context.projectRootOf(a.root ?? store.specsRoot);
140
+ }
141
+ catch {
142
+ return undefined;
143
+ } })();
144
+ const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, autonomyRoot, new Date().toISOString());
114
145
  // @implements A-SPEC-587 — an upstream REQ/H-SPEC is graded by the A-SPECs beneath it, so
115
146
  // the store is consulted for its descendants (only then: the list is a cost the auto-grade
116
147
  // A-SPEC/T-SPEC path does not pay). Unknown scope (none yet) keeps the human answer.
@@ -118,8 +149,24 @@ function createSpecApprovalHandlers(context) {
118
149
  const below = upstream ? (0, autonomy_1.descendantAspecs)(target.spec, await store.list()) : undefined;
119
150
  // @implements A-SPEC-649 — the grade is recorded on the request either way (the screen shows it).
120
151
  risk = (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below);
152
+ // @implements A-SPEC-729 (round 5) — a REQ never sealed and never admitted through the
153
+ // triage intake is not the agent's to seal: a human route may, an autonomous one may not.
154
+ // @implements A-SPEC-729 (round 6) — "never sealed" from the LEDGER: a hand-written
155
+ // approved_digest in a draft made a REQ look sealed and skip this rule (measured).
156
+ const noIntake = target.spec.type === 'REQ' && (() => {
157
+ try {
158
+ const intakeRoot = context.projectRootOf(a.root ?? store.specsRoot);
159
+ return !(0, requirement_triage_evidence_1.everSealedInLedger)(intakeRoot, a.id) && !(0, requirement_triage_evidence_1.hasRequirementIntakeRecord)(intakeRoot, a.id, target.spec.frontmatter.triage_evidence);
160
+ }
161
+ catch {
162
+ return true;
163
+ }
164
+ })();
165
+ if (noIntake)
166
+ risk = 'hitl';
121
167
  if (autonomyOn && risk === 'auto') {
122
168
  approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
169
+ decidedSubject = targetSubject;
123
170
  }
124
171
  else if (autonomyOn && !(0, autonomy_1.requiresAutonomousApprovalPrompt)(target.spec, below)) {
125
172
  // @implements A-SPEC-551.1 — autonomous mode does not turn an ordinary HITL request
@@ -131,16 +178,18 @@ function createSpecApprovalHandlers(context) {
131
178
  // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
132
179
  // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
133
180
  // more consequential act) as a first approval. The cap cuts the title, never the marker.
134
- const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`, autonomyOn ? 'autonomous-approve' : 'queue');
181
+ const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}${noIntake ? ' (triage 기록 없음)' : ''}`, autonomyOn ? 'autonomous-approve' : 'queue');
135
182
  const presentation = out.kind === 'answered'
136
183
  ? (out.decision.granted ? { kind: 'approve', reason: out.decision.reason } : { kind: 'deny', reason: out.decision.reason })
137
184
  : out.kind === 'expired' ? { kind: 'timeout' } : { kind: 'unavailable' };
138
185
  const decision = (0, approval_policy_1.resolveApprovalPresentation)(presentation, { autonomous: autonomyOn, harness: context.approvalHarness() });
139
186
  if (decision.kind === 'approved' && presentation.kind === 'approve') {
140
187
  approveResolved = { approval: elicitApproval(out.kind === 'answered' ? out.decision.reason : undefined), source: 'elicitation' };
188
+ decidedSubject = targetSubject;
141
189
  }
142
190
  else if (decision.kind === 'approved' && presentation.kind === 'timeout') {
143
191
  approveResolved = { approval: autonomousApproval(undefined, 'timeout'), source: 'autonomous' };
192
+ decidedSubject = targetSubject;
144
193
  }
145
194
  else if (out.kind === 'answered') {
146
195
  // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
@@ -153,7 +202,7 @@ function createSpecApprovalHandlers(context) {
153
202
  // OFF keeps the established fail-closed expiry + queue behavior.
154
203
  elicitExpiredMs = out.waitedMs;
155
204
  }
156
- else if (out.kind === 'silent' && context.approvalAdapter().kind === 'host-gated-tool') {
205
+ else if (out.kind === 'silent' && context.approvalAdapter().kind === 'host-gated-tool' && bindingOk()) {
157
206
  // The adapter's sensitive `approval_commit` invocation is rendered in the same agent
158
207
  // session. Its complete immutable payload is what the host shows and what the server
159
208
  // checks before a retry can consume it; it is never a config/env authorization.
@@ -180,7 +229,7 @@ function createSpecApprovalHandlers(context) {
180
229
  catch {
181
230
  refusedGrants = '';
182
231
  }
183
- return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '') + refusedGrants
232
+ return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '') + refusedGrants + (context.approvalRouteNote?.() ?? '')
184
233
  + 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
185
234
  + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', ...(subject ? { subject } : {}), ...(risk ? { risk } : {}) }) };
186
235
  }
@@ -263,6 +312,10 @@ function createSpecApprovalHandlers(context) {
263
312
  // @implements A-SPEC-649 — a grant bound to a subject opens only for THAT subject: the digest of
264
313
  // the spec read now (the same read the seal is based on) must equal the one the operator read.
265
314
  // Measured 2026-09-14: a grant read against "Original title" sealed "CHANGED after the grant".
315
+ if (cur && decidedSubject !== undefined && (0, spec_digest_1.specDigest)(cur.spec) !== decidedSubject) {
316
+ return { ok: false, reason: `spec_approve: ${a.id} changed after the decision was made — the content decided on is not the content that would be sealed. Nothing was sealed; ask again.`
317
+ + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', subject: (0, spec_digest_1.specDigest)(cur.spec) }) };
318
+ }
266
319
  if (cur && approveResolved.source === 'grant') {
267
320
  const bound = approveResolved.approval;
268
321
  if (typeof bound.subject === 'string' && bound.subject !== '' && bound.subject !== (0, spec_digest_1.specDigest)(cur.spec)) {
@@ -281,14 +334,7 @@ function createSpecApprovalHandlers(context) {
281
334
  return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
282
335
  }
283
336
  const spec = cur.spec;
284
- const prepared = (0, transition_policy_1.prepareApprovedSpec)(spec, specs, resolver, (rel) => {
285
- try {
286
- return a.root ? fs.readFileSync(path.join(a.root, rel), 'utf8') : null;
287
- }
288
- catch {
289
- return null;
290
- }
291
- });
337
+ const prepared = (0, transition_policy_1.prepareApprovedSpec)(spec, specs, resolver, (rel) => (a.root ? readProjectFile(a.root, rel) : null));
292
338
  if (!prepared.ok)
293
339
  return prepared;
294
340
  const { candidate, digest } = prepared;
@@ -391,7 +437,7 @@ function createSpecApprovalHandlers(context) {
391
437
  try {
392
438
  const ftt = filesToTouch(candidate);
393
439
  const gap = declaredImpactGap(ftt, graph, (rel) => { try {
394
- return fs.readFileSync(path.join(a.root, rel), 'utf8');
440
+ return readProjectFile(a.root, rel);
395
441
  }
396
442
  catch {
397
443
  return null;
@@ -613,3 +659,50 @@ function createSpecApprovalHandlers(context) {
613
659
  },
614
660
  };
615
661
  }
662
+ /** Largest Files-to-Touch file the approval act reads (A-SPEC-733 round 3). */
663
+ const PROJECT_READ_LIMIT = 2 * 1024 * 1024;
664
+ /**
665
+ * @implements A-SPEC-733 (round 3) — the approval act reads a Files-to-Touch path only when it is a
666
+ * regular file inside the project, at most 2 MB. Measured: a FIFO named there blocked approval, and a
667
+ * `../` path read a file outside the project. The descriptor is opened non-blocking and judged by
668
+ * fstat, so a path swapped between check and read is judged as what was opened.
669
+ */
670
+ function readProjectFile(root, rel) {
671
+ let tooLarge = -1;
672
+ const text = readProjectFileOnce(root, rel, (n) => { tooLarge = n; });
673
+ if (tooLarge >= 0)
674
+ throw new compat_impact_1.FileTooLargeError(rel, tooLarge);
675
+ return text;
676
+ }
677
+ function readProjectFileOnce(root, rel, onTooLarge) {
678
+ let tooLarge = -1;
679
+ let fd;
680
+ try {
681
+ const realRoot = fs.realpathSync(root);
682
+ const real = fs.realpathSync(path.resolve(realRoot, rel));
683
+ if (!real.startsWith(realRoot + path.sep))
684
+ return null;
685
+ fd = fs.openSync(real, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
686
+ const st = fs.fstatSync(fd);
687
+ if (!st.isFile())
688
+ return null;
689
+ // @implements A-SPEC-733 (round 5) — too large is reported, not skipped.
690
+ if (st.size > PROJECT_READ_LIMIT) {
691
+ tooLarge = st.size;
692
+ return null;
693
+ }
694
+ return fs.readFileSync(fd, 'utf8');
695
+ }
696
+ catch {
697
+ return null;
698
+ }
699
+ finally {
700
+ if (fd !== undefined)
701
+ try {
702
+ fs.closeSync(fd);
703
+ }
704
+ catch { /* already closed */ }
705
+ if (tooLarge >= 0)
706
+ onTooLarge(tooLarge);
707
+ }
708
+ }
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createSpecAuthoringHandlers = createSpecAuthoringHandlers;
37
- // @implements A-SPEC-724, A-SPEC-719
37
+ // @implements A-SPEC-729, A-SPEC-724, A-SPEC-719
38
38
  // @implements A-SPEC-618, A-SPEC-100.2, A-SPEC-128, A-SPEC-151, A-SPEC-169, A-SPEC-189, A-SPEC-420, A-SPEC-174, A-SPEC-252, A-SPEC-188, A-SPEC-146, A-SPEC-184
39
39
  const fs = __importStar(require("node:fs"));
40
40
  const path = __importStar(require("node:path"));
@@ -258,6 +258,12 @@ function createSpecAuthoringHandlers(context) {
258
258
  const intake = root ? (0, requirement_triage_evidence_1.validateRequirementIntake)(root, triage_evidence) : (0, requirement_triage_evidence_1.validateRequirementIntake)('', undefined);
259
259
  if (!intake.ok)
260
260
  return { ok: false, reason: intake.reason };
261
+ // @implements A-SPEC-729 — spend it on THIS REQ (atomic), and let the REQ say what admitted it.
262
+ const digest = triage_evidence.digest;
263
+ const spent = (0, requirement_triage_evidence_1.consumeRequirementTriageEvidence)(root, digest, id);
264
+ if (!spent.ok)
265
+ return { ok: false, reason: spent.reason };
266
+ spec.frontmatter = { ...spec.frontmatter, triage_evidence: digest };
261
267
  }
262
268
  try {
263
269
  await store.write(spec);
@@ -265,13 +271,22 @@ function createSpecAuthoringHandlers(context) {
265
271
  catch (e) {
266
272
  // The pre-write path check above makes this a narrow race backstop; the store guard is the
267
273
  // authority and this act relays it in the same wording the other writers use.
274
+ // @implements A-SPEC-729 — a failure after the spend leaves the evidence spent: say so.
275
+ const spentNote = type === 'REQ' ? ' 이 triage evidence는 이미 소비되었습니다 — requirement_triage(persist:true)를 다시 실행해 새 증거를 받으십시오.' : '';
268
276
  if (e instanceof spec_store_1.TargetPathOccupiedError) {
269
277
  return {
270
278
  ok: false,
271
279
  reason: `${id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
272
- + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오.',
280
+ + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오.' + spentNote,
273
281
  };
274
282
  }
283
+ // Only a raw filesystem error becomes a plain refusal; a structured refusal keeps its shape
284
+ // (code, holmesRefusal) and carries the spent note in its message.
285
+ if (spentNote && e && typeof e === 'object' && 'syscall' in e) {
286
+ return { ok: false, reason: `${id} could not be written (${e instanceof Error ? e.message : String(e)}).${spentNote}` };
287
+ }
288
+ if (spentNote && e instanceof Error)
289
+ e.message += spentNote;
275
290
  throw e;
276
291
  }
277
292
  return { created: id };
@@ -4,6 +4,11 @@ export interface SpecQueryContext {
4
4
  assertStoreReachable(tool: string, root: unknown): void;
5
5
  resolver(specs: Spec[]): (id: string) => Spec | null;
6
6
  }
7
+ type NextAction = {
8
+ id: string;
9
+ action: 'seal' | 'fill-then-seal' | 'fix-then-seal' | 'after-parent' | 'create-parent' | 'author-tspec';
10
+ reason: string;
11
+ };
7
12
  export declare function createSpecQueryHandlers(context: SpecQueryContext): {
8
13
  spec_validate(a: any): Promise<{
9
14
  ok: boolean;
@@ -22,9 +27,40 @@ export declare function createSpecQueryHandlers(context: SpecQueryContext): {
22
27
  status: "draft" | "review" | "approved" | "outdated";
23
28
  }[];
24
29
  }>;
25
- spec_next(): Promise<{
26
- next: import("../../spec/spec-types").SpecType;
30
+ spec_next(a?: {
31
+ id?: string;
32
+ }): Promise<{
33
+ ok: boolean;
34
+ reason: string;
35
+ next?: undefined;
36
+ actions?: undefined;
37
+ actionsTotal?: undefined;
38
+ chain?: undefined;
39
+ chainTotal?: undefined;
40
+ note?: undefined;
41
+ } | {
42
+ next: import("../../spec/spec-types").SpecType | null;
43
+ actions: NextAction[];
44
+ actionsTotal: number;
45
+ chain: {
46
+ id: string;
47
+ type: import("../../spec/spec-types").SpecType;
48
+ status: "draft" | "review" | "approved" | "outdated";
49
+ sealed: boolean;
50
+ }[];
51
+ chainTotal: number;
52
+ note: string;
53
+ ok?: undefined;
54
+ reason?: undefined;
27
55
  } | {
28
- next: null;
56
+ next: import("../../spec/spec-types").SpecType | null;
57
+ actions: NextAction[];
58
+ actionsTotal: number;
59
+ note: string;
60
+ ok?: undefined;
61
+ reason?: undefined;
62
+ chain?: undefined;
63
+ chainTotal?: undefined;
29
64
  }>;
30
65
  };
66
+ export {};
@@ -4,6 +4,102 @@ exports.createSpecQueryHandlers = createSpecQueryHandlers;
4
4
  const validator_1 = require("../../spec/validator");
5
5
  const legacy_format_1 = require("../../spec/legacy-format");
6
6
  const spec_types_1 = require("../../spec/spec-types");
7
+ const spec_digest_1 = require("../../spec/spec-digest");
8
+ const approval_blockers_1 = require("../../spec/approval-blockers");
9
+ const ACTIONS_SHOWN = 20;
10
+ const CHAIN_ACTIONS_SHOWN = 50;
11
+ const CHAIN_ROWS_SHOWN = 200;
12
+ const NEXT_NOTE = '`next` is the first kind with no approved instance anywhere in the store (a v0.1 heuristic, not a step); '
13
+ + '`actions` is what a slice needs now — pass `id` for one chain.';
14
+ const idOrder = (a, b) => a.localeCompare(b, 'en', { numeric: true });
15
+ function nextActions(specs, only) {
16
+ // @implements A-SPEC-736 (round 2) — judged against the WHOLE store even when only a chain is
17
+ // reported (the chain alone named an existing T-SPEC to author and an existing parent as missing),
18
+ // and with every lookup precomputed (the per-spec `specs.some` scan was quadratic).
19
+ const byId = new Map();
20
+ const idCount = new Map();
21
+ for (const s of specs) {
22
+ byId.set(s.id, s);
23
+ idCount.set(s.id, (idCount.get(s.id) ?? 0) + 1);
24
+ }
25
+ const withLiveT = new Set();
26
+ for (const t of specs)
27
+ if (t.type === 'T-SPEC' && t.status !== 'outdated')
28
+ for (const d of t.dependsOn ?? [])
29
+ withLiveT.add(d);
30
+ const sealed = (s) => !!(0, spec_digest_1.sealOf)(s).approvedDigest;
31
+ const parentsOf = (s) => (s.dependsOn ?? []).filter((d) => d !== s.id); // self-dependency ignored
32
+ const out = [];
33
+ for (const s of specs) {
34
+ if ((only && !only.has(s.id)) || s.status === 'outdated')
35
+ continue;
36
+ if (!sealed(s)) {
37
+ const missing = parentsOf(s).find((d) => !byId.has(d));
38
+ const retired = parentsOf(s).map((d) => byId.get(d)).find((p) => !!p && p.status === 'outdated');
39
+ const waiting = parentsOf(s).map((d) => byId.get(d)).find((p) => !!p && p.status !== 'outdated' && !sealed(p));
40
+ const holes = (0, approval_blockers_1.placeholderSections)(s);
41
+ if (missing)
42
+ out.push({ id: s.id, action: 'create-parent', reason: `depends on ${missing}, which does not exist — create it (spec_create) or correct depends_on` });
43
+ else if (retired)
44
+ out.push({ id: s.id, action: 'create-parent', reason: `depends on ${retired.id}, which is retired (outdated) — depend on its successor or correct depends_on` });
45
+ else if (waiting && parentsOf(waiting).includes(s.id))
46
+ out.push({ id: s.id, action: 'fix-then-seal', reason: `dependency cycle: ${s.id} and ${waiting.id} depend on each other — correct depends_on` });
47
+ else if (waiting)
48
+ out.push({ id: s.id, action: 'after-parent', reason: `seal ${waiting.id} first — a child cannot be sealed under an unsealed parent` });
49
+ else if (holes.length > 0)
50
+ out.push({ id: s.id, action: 'fill-then-seal', reason: `fill the placeholder section(s) ${holes.join(', ')}, then spec_approve` });
51
+ else {
52
+ // `seal` only when nothing spec_approve checks would refuse it: the gate's blockers, the
53
+ // actionable-criteria rule and a unique id (measured: both refused where `seal` was said).
54
+ const blockers = (0, approval_blockers_1.approvalBlockers)(s, (x) => byId.get(x) ?? null);
55
+ const criteria = (0, approval_blockers_1.unactionableCriteriaBlocker)(s);
56
+ if (criteria)
57
+ blockers.push(criteria);
58
+ if ((idCount.get(s.id) ?? 0) > 1)
59
+ blockers.push(`${s.id} exists more than once in the store — resolve the duplicate first`);
60
+ if (blockers.length > 0)
61
+ out.push({ id: s.id, action: 'fix-then-seal', reason: blockers.slice(0, 2).join('; ').slice(0, 400) });
62
+ else
63
+ out.push({ id: s.id, action: 'seal', reason: 'every parent is sealed and nothing blocks approval — spec_approve' });
64
+ }
65
+ }
66
+ else if (s.type === 'A-SPEC' && s.status === 'approved' && s.id.startsWith('A-SPEC-') && !withLiveT.has(s.id)) {
67
+ const tspec = `T-SPEC-${s.id.slice('A-SPEC-'.length)}`;
68
+ const mirror = byId.get(tspec);
69
+ out.push(mirror
70
+ ? { id: tspec, action: 'author-tspec', reason: `${tspec} exists but is ${mirror.status} and no live T-SPEC depends on ${s.id} — author a new T-SPEC depending on ${s.id}, write the tests, seal it` }
71
+ : { id: tspec, action: 'author-tspec', reason: `${s.id} is sealed and no T-SPEC depends on it — spec_create ${tspec} (depends_on ${s.id}), write the tests, seal it` });
72
+ }
73
+ }
74
+ return out;
75
+ }
76
+ function chainOf(specs, id) {
77
+ const byId = new Map(specs.map((s) => [s.id, s]));
78
+ const children = new Map();
79
+ for (const s of specs)
80
+ for (const d of s.dependsOn ?? []) {
81
+ const list = children.get(d);
82
+ if (list)
83
+ list.push(s);
84
+ else
85
+ children.set(d, [s]);
86
+ }
87
+ const seen = new Set([id]);
88
+ const walk = (start, step) => {
89
+ const todo = [start];
90
+ while (todo.length > 0) {
91
+ for (const n of step(todo.pop()))
92
+ if (!seen.has(n)) {
93
+ seen.add(n);
94
+ todo.push(n);
95
+ }
96
+ }
97
+ };
98
+ walk(id, (x) => (byId.get(x)?.dependsOn ?? []).filter((d) => byId.has(d)));
99
+ walk(id, (x) => (children.get(x) ?? []).map((c) => c.id));
100
+ const rank = (s) => { const i = spec_types_1.SPEC_ORDER.indexOf(s.type); return i < 0 ? spec_types_1.SPEC_ORDER.length : i; };
101
+ return [...seen].map((x) => byId.get(x)).sort((a, b) => rank(a) - rank(b) || idOrder(a.id, b.id));
102
+ }
7
103
  function createSpecQueryHandlers(context) {
8
104
  return {
9
105
  async spec_validate(a) {
@@ -60,15 +156,26 @@ function createSpecQueryHandlers(context) {
60
156
  }),
61
157
  };
62
158
  },
63
- async spec_next() {
159
+ async spec_next(a) {
64
160
  const specs = await context.listSpecs();
65
- // 다음에 작성 가능한 첫 미승인 단계
66
- for (const t of spec_types_1.SPEC_ORDER) {
67
- const has = specs.some((s) => s.type === t && s.status === 'approved');
68
- if (!has)
69
- return { next: t };
161
+ // 다음에 작성 가능한 첫 미승인 단계 (v0.1 — kept for existing callers; see NEXT_NOTE)
162
+ const next = spec_types_1.SPEC_ORDER.find((t) => !specs.some((s) => s.type === t && s.status === 'approved')) ?? null;
163
+ if (typeof a?.id === 'string' && a.id !== '') {
164
+ if (!specs.some((s) => s.id === a.id))
165
+ return { ok: false, reason: `spec ${a.id} not found in the governed store` };
166
+ const chain = chainOf(specs, a.id);
167
+ const rank = new Map(chain.map((s, i) => [s.id, i]));
168
+ const actions = nextActions(specs, new Set(chain.map((s) => s.id)))
169
+ .sort((x, y) => (rank.get(x.id) ?? rank.get(x.id.replace(/^T-/, 'A-')) ?? 0) - (rank.get(y.id) ?? rank.get(y.id.replace(/^T-/, 'A-')) ?? 0));
170
+ return {
171
+ next, actions: actions.slice(0, CHAIN_ACTIONS_SHOWN), actionsTotal: actions.length,
172
+ chain: chain.slice(0, CHAIN_ROWS_SHOWN).map((s) => ({ id: s.id, type: s.type, status: s.status, sealed: !!(0, spec_digest_1.sealOf)(s).approvedDigest })),
173
+ chainTotal: chain.length,
174
+ note: NEXT_NOTE,
175
+ };
70
176
  }
71
- return { next: null };
177
+ const all = nextActions([...specs].sort((x, y) => idOrder(x.id, y.id))).filter((x) => x.action !== 'after-parent');
178
+ return { next, actions: all.slice(0, ACTIONS_SHOWN), actionsTotal: all.length, note: NEXT_NOTE };
72
179
  },
73
180
  };
74
181
  }
@@ -34,10 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createTestExecutionHandlers = createTestExecutionHandlers;
37
- // @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
37
+ // @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, A-SPEC-734
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const node_child_process_1 = require("node:child_process");
41
+ const cpg_scanner_1 = require("../../cpg/cpg-scanner");
41
42
  const change_source_1 = require("../../project/change-source");
42
43
  const root_1 = require("../../project/root");
43
44
  const ignore_1 = require("../../project/ignore");
@@ -53,6 +54,7 @@ const kills_check_1 = require("../../review/kills-check");
53
54
  const test_evidence_1 = require("../../review/test-evidence");
54
55
  const test_outcomes_1 = require("../../review/test-outcomes");
55
56
  const maintenance_evidence_1 = require("../maintenance-evidence");
57
+ const bounded_io_1 = require("../../project/bounded-io");
56
58
  // @implements A-SPEC-534.8
57
59
  // The governed source file a `kills` mutation targets: one that @implements the A-SPEC AND contains
58
60
  // the `where` literal. Bounded walk, skips vendored/test/hidden dirs. null when none qualifies.
@@ -78,12 +80,16 @@ function sourceFileWithMutation(root, aspecId, where) {
78
80
  || e.name === 'vendor' || e.name === 'third_party' || e.name.startsWith('.'))
79
81
  continue;
80
82
  const p = path.join(d, e.name);
83
+ // @implements A-SPEC-734 (round 10) — a foreign clone sorting first could become the mutation target.
81
84
  if (e.isDirectory()) {
82
- walk(p);
85
+ if (!(0, cpg_scanner_1.isNestedWorkTree)(p, root))
86
+ walk(p);
83
87
  continue;
84
88
  }
85
89
  if (!SOURCE.test(e.name) || /\.test\./.test(e.name))
86
90
  continue;
91
+ if (!(0, cpg_scanner_1.isRegularSource)(e, p, root))
92
+ continue;
87
93
  let text;
88
94
  try {
89
95
  text = fs.readFileSync(p, 'utf8');
@@ -159,7 +165,7 @@ function createTestExecutionHandlers(context) {
159
165
  const executedByAspec = (0, test_evidence_1.computeExecutedByAspec)(result.executedByFile ?? {}, anchors);
160
166
  let head = '';
161
167
  try {
162
- head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
168
+ 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', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
163
169
  }
164
170
  catch { /* non-git */ }
165
171
  // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as