@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
@@ -37,7 +37,7 @@ exports.readEntityGitIndex = readEntityGitIndex;
37
37
  exports.readEntityGitBlobs = readEntityGitBlobs;
38
38
  exports.readEntityGitInputs = readEntityGitInputs;
39
39
  exports.readEntityGitSnapshot = readEntityGitSnapshot;
40
- // @implements A-SPEC-629.1, A-SPEC-629
40
+ // @implements A-SPEC-629.1, A-SPEC-629, A-SPEC-734
41
41
  // @implements A-SPEC-636
42
42
  // @implements A-SPEC-637
43
43
  const fs = __importStar(require("node:fs"));
@@ -45,6 +45,7 @@ const node_child_process_1 = require("node:child_process");
45
45
  const node_crypto_1 = require("node:crypto");
46
46
  const spec_parser_1 = require("./spec-parser");
47
47
  const entity_transaction_1 = require("./entity-transaction");
48
+ const bounded_io_1 = require("../project/bounded-io");
48
49
  /** Version of the workspace-scoped logical stage inventory, not the on-disk index bytes/stat cache. */
49
50
  function readEntityGitIndex(root) {
50
51
  const git = gitReader(root);
@@ -153,7 +154,7 @@ function gitReader(root) {
153
154
  env.GIT_OPTIONAL_LOCKS = '0';
154
155
  return (args, input, failure = 'Git snapshot read failed: unavailable revision/object, unsupported repository or 64 MiB response limit.') => {
155
156
  try {
156
- return (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { env, input, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
157
+ return (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS, env, input, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
157
158
  }
158
159
  catch {
159
160
  return fail(failure);
@@ -41,7 +41,7 @@ exports.planEntityGitSources = planEntityGitSources;
41
41
  exports.planEntityGitDocuments = planEntityGitDocuments;
42
42
  exports.planEntityGitNumbering = planEntityGitNumbering;
43
43
  exports.classifyEntityGitChanges = classifyEntityGitChanges;
44
- // @implements A-SPEC-629.1, A-SPEC-629
44
+ // @implements A-SPEC-629.1, A-SPEC-629, A-SPEC-734
45
45
  // @implements A-SPEC-636
46
46
  // @implements A-SPEC-637
47
47
  const entity_git_snapshot_1 = require("./entity-git-snapshot");
@@ -60,6 +60,7 @@ const fs = __importStar(require("node:fs"));
60
60
  const os = __importStar(require("node:os"));
61
61
  const node_child_process_1 = require("node:child_process");
62
62
  const node_crypto_1 = require("node:crypto");
63
+ const bounded_io_1 = require("../project/bounded-io");
63
64
  const REGULAR = new Set(['100644', '100755']);
64
65
  /**
65
66
  * @implements A-SPEC-637 — non-regular entries (symlinks, gitlinks) identical in base, left and right:
@@ -307,7 +308,7 @@ function mergeEntityGitFile(base, left, right) {
307
308
  for (const [name, version] of Object.entries({ base, left, right }))
308
309
  fs.writeFileSync(path.join(scratch, name), version.bytes, { mode: 0o600 });
309
310
  const env = mergeToolEnv(process.env, scratch);
310
- const merged = (0, node_child_process_1.spawnSync)('git', ['merge-file', '--stdout', '--diff3', '-L', 'left', '-L', 'base', '-L', 'right', '--', 'left', 'base', 'right'], { cwd: scratch, env, maxBuffer: limit });
311
+ const merged = (0, node_child_process_1.spawnSync)('git', ['merge-file', '--stdout', '--diff3', '-L', 'left', '-L', 'base', '-L', 'right', '--', 'left', 'base', 'right'], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS, cwd: scratch, env, maxBuffer: limit });
311
312
  if (merged.error || merged.status === null || merged.status > 127)
312
313
  return conflict('merge-tool-failure');
313
314
  if (merged.status !== 0)
@@ -33,6 +33,25 @@ export interface EntityRenumberPlan {
33
33
  steps: RenumberStep[];
34
34
  }
35
35
  export declare function entityRenumberTarget(plan: EntityRenumberPlan): string;
36
+ /**
37
+ * @implements A-SPEC-733 (round 4) — whether `file` is the renumbered store's own document or `.ax/`
38
+ * state: judged on the posix-normalized path case-insensitively, and on the real path of an existing
39
+ * file (measured: `.AX/specs/…` on a case-insensitive disk slipped a string compare, was recorded, and
40
+ * wedged the store with a lost seal).
41
+ */
42
+ export declare function isRenumberOwnPath(root: string, storeLocator: string, file: string): boolean;
43
+ /**
44
+ * @implements A-SPEC-733 — the compatibility reader a renumber gives the transition policy.
45
+ * Round 3: the store's own documents (and `.ax/`) are what this act rewrites, not code with an OS
46
+ * character; recording their version made recovery and the completed re-apply recompute a different
47
+ * plan and refuse (measured, bisected). Round 6 (measured): a case-variant spelling of a source this
48
+ * act rewrites was read from disk and recorded apart, then changed under the act — a wedge; the act's
49
+ * own sources are matched by fold (normalized, NFC, upper case) and recorded under their own spelling.
50
+ */
51
+ export declare function renumberPolicyReader(root: string, storeLocator: string, originalSources: ReadonlyMap<string, string>, files: ReadonlyArray<{
52
+ file: string;
53
+ after: string;
54
+ }>, policyFiles: Map<string, string | null>): (file: string) => string | null;
36
55
  /** Build candidates through the same transition policy as the ordinary official tools. No writes. */
37
56
  export declare function prepareEntityRenumberPlan(root: string, snapshot: Snapshot, changes: EntityRenumberChange[], sources: SourceRenumberInventory, operationId?: string, originalSources?: ReadonlyMap<string, string>): EntityRenumberPlan;
38
57
  export declare function validateEntityRenumberPlan(value: unknown): EntityRenumberPlan;
@@ -37,6 +37,8 @@ exports.entitySourcePublicationOwner = void 0;
37
37
  exports.withEntitySourceInspection = withEntitySourceInspection;
38
38
  exports.withRecoveredSourcePublication = withRecoveredSourcePublication;
39
39
  exports.entityRenumberTarget = entityRenumberTarget;
40
+ exports.isRenumberOwnPath = isRenumberOwnPath;
41
+ exports.renumberPolicyReader = renumberPolicyReader;
40
42
  exports.prepareEntityRenumberPlan = prepareEntityRenumberPlan;
41
43
  exports.validateEntityRenumberPlan = validateEntityRenumberPlan;
42
44
  exports.entityRenumberRecoveryTarget = entityRenumberRecoveryTarget;
@@ -45,7 +47,7 @@ exports.planEntityRenumberRecovery = planEntityRenumberRecovery;
45
47
  exports.abandonEntityRenumber = abandonEntityRenumber;
46
48
  exports.recoverEntityRenumber = recoverEntityRenumber;
47
49
  exports.applyEntityRenumber = applyEntityRenumber;
48
- // @implements A-SPEC-629, A-SPEC-628
50
+ // @implements A-SPEC-629, A-SPEC-628, A-SPEC-733
49
51
  // @implements A-SPEC-641
50
52
  // @implements A-SPEC-640
51
53
  // @implements A-SPEC-639
@@ -61,6 +63,7 @@ const spec_parser_1 = require("./spec-parser");
61
63
  const transition_policy_1 = require("./transition-policy");
62
64
  const entity_transaction_1 = require("./entity-transaction");
63
65
  const workspace_identity_1 = require("../project/workspace-identity");
66
+ const linear_match_1 = require("../guardrail/linear-match");
64
67
  // A reserved coordination namespace, independent of every configured spec store (A-SPEC-634: the value lives in entity-transaction).
65
68
  const sourcePublication = entity_transaction_1.SOURCE_PUBLICATION_LOCATOR;
66
69
  const entitySourcePublicationOwner = (root) => (0, entity_transaction_1.entityLockOwner)(root, sourcePublication);
@@ -145,6 +148,79 @@ function safeRead(root, file) {
145
148
  function entityRenumberTarget(plan) {
146
149
  return 'entity-store:renumber:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan));
147
150
  }
151
+ /**
152
+ * @implements A-SPEC-733 (round 4) — whether `file` is the renumbered store's own document or `.ax/`
153
+ * state: judged on the posix-normalized path case-insensitively, and on the real path of an existing
154
+ * file (measured: `.AX/specs/…` on a case-insensitive disk slipped a string compare, was recorded, and
155
+ * wedged the store with a lost seal).
156
+ */
157
+ function isRenumberOwnPath(root, storeLocator, file) {
158
+ // Round 5 (measured): `ſpecs/…` and an NFD spelling of an NFC store slipped a lower-case compare, and
159
+ // a destination that does not exist yet had no real path. Fold NFC + upper case, and judge a new
160
+ // path by the real path of its nearest existing ancestor.
161
+ const norm = (p) => path.posix.normalize(p.replace(/\\/g, '/')).replace(/\/$/, '').normalize('NFC').toUpperCase();
162
+ const f = norm(file), store = norm(storeLocator);
163
+ const under = (p, dir) => p === dir || p.startsWith(dir + '/');
164
+ if (under(f, store) || under(f, '.AX'))
165
+ return true;
166
+ try {
167
+ const real = realOrAncestor(path.join(root, file));
168
+ for (const dir of [storeLocator, '.ax']) {
169
+ let base;
170
+ try {
171
+ base = fs.realpathSync.native(path.join(root, dir));
172
+ }
173
+ catch {
174
+ continue;
175
+ }
176
+ const r = real.normalize('NFC').toUpperCase(), b = base.normalize('NFC').toUpperCase();
177
+ if (r === b || r.startsWith(b + path.sep.toUpperCase()))
178
+ return true;
179
+ }
180
+ }
181
+ catch { /* absent: the string judgement above stands */ }
182
+ return false;
183
+ }
184
+ /**
185
+ * @implements A-SPEC-733 — the compatibility reader a renumber gives the transition policy.
186
+ * Round 3: the store's own documents (and `.ax/`) are what this act rewrites, not code with an OS
187
+ * character; recording their version made recovery and the completed re-apply recompute a different
188
+ * plan and refuse (measured, bisected). Round 6 (measured): a case-variant spelling of a source this
189
+ * act rewrites was read from disk and recorded apart, then changed under the act — a wedge; the act's
190
+ * own sources are matched by fold (normalized, NFC, upper case) and recorded under their own spelling.
191
+ */
192
+ function renumberPolicyReader(root, storeLocator, originalSources, files, policyFiles) {
193
+ // Round 7: Windows resolves `foo.ts.` to `foo.ts` (trailing dots and spaces drop from each segment).
194
+ const winTrim = (p) => (process.platform === 'win32' ? p.split('/').map((seg) => (0, linear_match_1.trimTrailing)(seg, '. ') || seg).join('/') : p);
195
+ const foldRel = (p) => winTrim(path.posix.normalize(p.replace(/\\/g, '/'))).normalize('NFC').toUpperCase();
196
+ const byFold = new Map();
197
+ for (const f of [...originalSources.keys(), ...files.map(x => x.file)])
198
+ byFold.set(foldRel(f), f);
199
+ return (file) => {
200
+ if (isRenumberOwnPath(root, storeLocator, file))
201
+ return null;
202
+ const at = byFold.get(foldRel(file)) ?? file;
203
+ const bytes = originalSources.has(at) ? Buffer.from(originalSources.get(at)) : safeRead(root, at);
204
+ policyFiles.set(at, version(bytes));
205
+ return files.find(source => source.file === at)?.after ?? bytes?.toString('utf8') ?? null;
206
+ };
207
+ }
208
+ /** The real path of `p`, or of its nearest existing ancestor with the rest appended. */
209
+ function realOrAncestor(p) {
210
+ let cur = path.resolve(p);
211
+ const rest = [];
212
+ for (;;) {
213
+ try {
214
+ return path.join(fs.realpathSync.native(cur), ...rest.reverse());
215
+ }
216
+ catch { /* keep climbing */ }
217
+ const parent = path.dirname(cur);
218
+ if (parent === cur)
219
+ throw new Error('no existing ancestor');
220
+ rest.push(path.basename(cur));
221
+ cur = parent;
222
+ }
223
+ }
148
224
  /** Build candidates through the same transition policy as the ordinary official tools. No writes. */
149
225
  function prepareEntityRenumberPlan(root, snapshot, changes, sources, operationId = (0, node_crypto_1.randomUUID)(), originalSources = new Map()) {
150
226
  const proposal = (0, entity_renumber_1.planEntityRenumber)(snapshot.entries, changes);
@@ -200,13 +276,10 @@ function prepareEntityRenumberPlan(root, snapshot, changes, sources, operationId
200
276
  }
201
277
  for (const source of sources.files)
202
278
  add('source', source.file, encoded(source.before), encoded(source.after));
279
+ const policyReader = renumberPolicyReader(root, snapshot.storeLocator, originalSources, sources.files, policyFiles);
203
280
  for (const id of proposal.approveOrder) {
204
281
  const entry = proposal.entries.find(e => e.newId === id), before = texts.get(entry.entityId);
205
- const prepared = (0, transition_policy_1.prepareApprovedSpec)((0, spec_parser_1.parseSpec)(before), specs(), all => parent => all.find(s => s.id === parent) ?? null, file => {
206
- const bytes = originalSources.has(file) ? Buffer.from(originalSources.get(file)) : safeRead(root, file);
207
- policyFiles.set(file, version(bytes));
208
- return sources.files.find(source => source.file === file)?.after ?? bytes?.toString('utf8') ?? null;
209
- });
282
+ const prepared = (0, transition_policy_1.prepareApprovedSpec)((0, spec_parser_1.parseSpec)(before), specs(), all => parent => all.find(s => s.id === parent) ?? null, policyReader);
210
283
  // A-SPEC-641: a multi-document act names the document it refuses on.
211
284
  if (!prepared.ok)
212
285
  throw new entity_transaction_1.EntityStoreError('spec-policy-refused', id + ': ' + prepared.reason);
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
37
37
  exports.collectLocalSpecEntries = collectLocalSpecEntries;
38
- // @implements A-SPEC-254.2
38
+ // @implements A-SPEC-254.2, A-SPEC-734
39
39
  /**
40
40
  * The merge-time half of REQ-254: which spec documents did each remote-tracking ref ADD since this
41
41
  * checkout and that ref parted?
@@ -63,8 +63,9 @@ const path = __importStar(require("node:path"));
63
63
  const spec_parser_1 = require("./spec-parser");
64
64
  const id_collision_1 = require("./id-collision");
65
65
  const root_1 = require("../project/root");
66
+ const bounded_io_1 = require("../project/bounded-io");
66
67
  const SPECS = '.ax/specs';
67
- const defaultGit = (root, args, input) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], {
68
+ const defaultGit = (root, args, input) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS,
68
69
  input, stdio: ['pipe', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env), maxBuffer: 256 * 1024 * 1024,
69
70
  });
70
71
  const lines = (buf) => buf.toString('utf8').split('\n').map((l) => l.trim()).filter((l) => l !== '');
@@ -200,9 +200,13 @@ async function planSourceRenumber(root, pairs, storeLocator, originalSources = n
200
200
  const file = path.join(root, '.gitignore');
201
201
  if (fs.lstatSync(file).isSymbolicLink())
202
202
  throw new Error('Symlinked ignore policy');
203
- const bytes = fs.readFileSync(file);
204
- ignoreText = bytes.toString('utf8');
205
- result.ignoreVersion = digest(bytes);
203
+ // @implements A-SPEC-734 (round 10) — the same non-blocking, regular-file, capped read as loadIgnore
204
+ // (a FIFO named .gitignore hung this plan — measured).
205
+ const read = (0, ignore_1.readIgnoreFileSafely)(root);
206
+ if (read.bytes === null)
207
+ throw Object.assign(new Error(read.reason), { code: read.reason === 'missing' ? 'ENOENT' : 'EUNSAFE' });
208
+ ignoreText = read.bytes.toString('utf8');
209
+ result.ignoreVersion = digest(read.bytes);
206
210
  }
207
211
  catch (error) {
208
212
  if (error.code !== 'ENOENT')
@@ -237,6 +241,10 @@ async function planSourceRenumber(root, pairs, storeLocator, originalSources = n
237
241
  if (entry.isDirectory()) {
238
242
  if (fs.existsSync(path.join(abs, 'pyvenv.cfg')))
239
243
  continue;
244
+ // @implements A-SPEC-734 (round 10) — a nested tree is another checkout (the plan rewrote an agent
245
+ // worktree's files — measured).
246
+ if ((0, cpg_scanner_1.isNestedWorkTree)(abs, root))
247
+ continue;
240
248
  await walkSources(file);
241
249
  continue;
242
250
  }
@@ -454,7 +462,7 @@ function applyRenumber(root, plan) {
454
462
  */
455
463
  const SOURCE_DIRS = ['src', 'scripts'];
456
464
  const SOURCE_EXT = /\.(ts|js|mjs|cjs|ps1|sh)$/;
457
- function walk(dir, out = []) {
465
+ function walk(dir, root, out = []) {
458
466
  let entries;
459
467
  try {
460
468
  entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -464,11 +472,12 @@ function walk(dir, out = []) {
464
472
  }
465
473
  for (const e of entries) {
466
474
  const p = path.join(dir, e.name);
475
+ // @implements A-SPEC-734 (round 10) — nested trees skipped, regular files only (a FIFO hung spec_renumber).
467
476
  if (e.isDirectory()) {
468
- if (e.name !== 'node_modules')
469
- walk(p, out);
477
+ if (e.name !== 'node_modules' && !(0, cpg_scanner_1.isNestedWorkTree)(p, root))
478
+ walk(p, root, out);
470
479
  }
471
- else if (SOURCE_EXT.test(e.name))
480
+ else if (SOURCE_EXT.test(e.name) && (0, cpg_scanner_1.isRegularSource)(e, p, root))
472
481
  out.push(p);
473
482
  }
474
483
  return out;
@@ -477,7 +486,7 @@ function walk(dir, out = []) {
477
486
  function readSourcesForRenumber(projectRoot) {
478
487
  const out = [];
479
488
  for (const d of SOURCE_DIRS) {
480
- for (const abs of walk(path.join(projectRoot, d))) {
489
+ for (const abs of walk(path.join(projectRoot, d), projectRoot)) {
481
490
  try {
482
491
  out.push({
483
492
  file: path.relative(projectRoot, abs).split(path.sep).join('/'),
@@ -500,7 +509,7 @@ function readSourcesForRenumber(projectRoot) {
500
509
  function readSpecsForRenumber(specsRoot) {
501
510
  const out = [];
502
511
  const unreadable = [];
503
- for (const abs of walk(specsRoot).concat((function md(dir, acc = []) {
512
+ for (const abs of walk(specsRoot, specsRoot).concat((function md(dir, acc = []) {
504
513
  let entries;
505
514
  try {
506
515
  entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -512,7 +521,13 @@ function readSpecsForRenumber(specsRoot) {
512
521
  const p = path.join(dir, e.name);
513
522
  if (e.isDirectory())
514
523
  md(p, acc);
515
- else if (e.name.endsWith('.md'))
524
+ // A-SPEC-734 (round 10): a regular spec (or a link to one) only — a FIFO hung the reader.
525
+ else if (e.name.endsWith('.md') && (e.isFile() || (e.isSymbolicLink() && (() => { try {
526
+ return fs.statSync(p).isFile();
527
+ }
528
+ catch {
529
+ return false;
530
+ } })())))
516
531
  acc.push(p);
517
532
  }
518
533
  return acc;
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.parseDependsOn = parseDependsOn;
37
37
  exports.parseSpec = parseSpec;
38
38
  exports.serializeSpec = serializeSpec;
39
+ // @implements A-SPEC-733
39
40
  const yaml = __importStar(require("js-yaml"));
40
41
  // @implements A-SPEC-574.3 — from the shared module, not from `legacy-format`, which imports
41
42
  // this file's `Spec` type. That pair was a cycle over one string constant.
@@ -73,7 +74,10 @@ function splitSections(body) {
73
74
  let inFence = false;
74
75
  let currentHeading = null;
75
76
  let currentContent = [];
76
- const headingRegex = /^##\s+(.+?)\s*$/;
77
+ // @implements A-SPEC-733 (round 9) — `(.+?)\s*$` rescanned a blank run from every lazy step: a 100 KB
78
+ // heading line cost every Edit/Write 6.4 s (the gate parses the store per call — measured). The
79
+ // capture is greedy and the caller trims it, which is the same section name.
80
+ const headingRegex = /^##\s+(\S.*)$/;
77
81
  for (const line of lines) {
78
82
  // Toggle fence state on lines matching /^\s*```/
79
83
  if (/^\s*```/.test(line)) {
@@ -83,7 +87,9 @@ function splitSections(body) {
83
87
  continue;
84
88
  }
85
89
  // Check for section heading only when not in fence
86
- const headingMatch = !inFence ? headingRegex.exec(line) : null;
90
+ // Round 10: trimmed by index first — a heading ending in a lone `\r` (the `\r\r\n` artifact) lost
91
+ // its section under `(\S.*)$`, which the retired `\s*$` accepted.
92
+ const headingMatch = !inFence ? headingRegex.exec(line.trimEnd()) : null;
87
93
  if (headingMatch) {
88
94
  // Save previous section if exists
89
95
  if (currentHeading !== null) {
@@ -147,6 +153,6 @@ function serializeSpec(spec) {
147
153
  // leading whitespace makes serialization idempotent; the trailing blank line is restored so the
148
154
  // preamble stays separated from the first section.
149
155
  const head = (spec.preamble ?? '').replace(/^\s+/, '');
150
- const preamble = head ? `${head.replace(/\s+$/, '')}\n\n` : '';
156
+ const preamble = head ? `${head.trimEnd()}\n\n` : '';
151
157
  return `---\n${yaml.dump(fm)}---\n\n${preamble}${body}`;
152
158
  }
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.yamlScalar = yamlScalar;
4
- // @implements A-SPEC-298
4
+ // @implements A-SPEC-733, A-SPEC-298
5
5
  /**
6
6
  * Render a string so it can be pasted into YAML frontmatter and read back unchanged.
7
7
  *
@@ -30,7 +30,7 @@ function yamlScalar(value, indent = 0) {
30
30
  if (value.includes('\n')) {
31
31
  // A block scalar keeps the line breaks readable in the file instead of turning them into \n.
32
32
  // A line with trailing whitespace cannot survive one, so those fall through to double quotes.
33
- if (value.split('\n').some((line) => line !== line.replace(/\s+$/, '')))
33
+ if (value.split('\n').some((line) => line !== line.trimEnd()))
34
34
  return JSON.stringify(value);
35
35
  const pad = ' '.repeat(indent + 2);
36
36
  return `|-\n${value.split('\n').map((line) => `${pad}${line}`).join('\n')}`;
@@ -21,6 +21,11 @@ export declare function parseLatest(body: string): string | null;
21
21
  * caller's decision — this always attempts.
22
22
  */
23
23
  export declare function refreshCache(opts: RefreshOpts): Promise<boolean>;
24
+ /**
25
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
26
+ * with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
27
+ */
28
+ export declare function queryRegistryLatest(timeoutMs?: number): Promise<string | null>;
24
29
  export interface SpawnRefreshOpts {
25
30
  home: string;
26
31
  env: NodeJS.ProcessEnv;
@@ -36,9 +36,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.REGISTRY_URL = void 0;
37
37
  exports.parseLatest = parseLatest;
38
38
  exports.refreshCache = refreshCache;
39
+ exports.queryRegistryLatest = queryRegistryLatest;
39
40
  exports.shouldRefreshCache = shouldRefreshCache;
40
41
  exports.maybeSpawnRefresh = maybeSpawnRefresh;
41
42
  // @implements A-SPEC-547.1
43
+ // @implements A-SPEC-251.1
42
44
  const path = __importStar(require("node:path"));
43
45
  const update_notice_1 = require("./update-notice");
44
46
  /** The npm registry document for this scoped package — `dist-tags.latest` is the published latest. */
@@ -51,7 +53,8 @@ exports.REGISTRY_URL = 'https://registry.npmjs.org/@holmes-lab%2Fholmes-kit';
51
53
  function parseLatest(body) {
52
54
  try {
53
55
  const latest = JSON.parse(body)?.['dist-tags']?.latest;
54
- return typeof latest === 'string' ? latest : null;
56
+ // A-SPEC-251.1 (round 27): only a strict semver is cached (upgrade installs `PKG@<latest>`).
57
+ return (0, update_notice_1.isStrictSemver)(latest) ? latest : null;
55
58
  }
56
59
  catch {
57
60
  return null;
@@ -78,6 +81,28 @@ async function refreshCache(opts) {
78
81
  opts.writeFile(path.join(dir, 'update-check.json'), JSON.stringify({ latest, checkedAt: opts.now }));
79
82
  return true;
80
83
  }
84
+ /**
85
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
86
+ * with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
87
+ */
88
+ function queryRegistryLatest(timeoutMs = 5000) {
89
+ return new Promise((resolve) => {
90
+ try {
91
+ const https = require('node:https');
92
+ const req = https.get(exports.REGISTRY_URL, { headers: { accept: 'application/vnd.npm.install-v1+json' } }, (res) => {
93
+ let d = '';
94
+ res.on('data', (c) => (d += c));
95
+ res.on('end', () => resolve(res.statusCode === 200 ? parseLatest(d) : null));
96
+ res.on('error', () => resolve(null));
97
+ });
98
+ req.on('error', () => resolve(null));
99
+ req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
100
+ }
101
+ catch {
102
+ resolve(null);
103
+ }
104
+ });
105
+ }
81
106
  /**
82
107
  * @implements A-SPEC-547.2
83
108
  * Pure: whether a network refresh should fire now — network allowed (not opted out / not CI) AND the
@@ -13,6 +13,12 @@ export interface BannerInput {
13
13
  }
14
14
  /** -1 if a<b, 0 if equal, 1 if a>b — NUMERIC per field, so 0.9.0 < 0.10.0 (a string compare fails). */
15
15
  export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
16
+ /**
17
+ * @implements A-SPEC-251.1 (round 27) — a version this kit installs or names: `MAJOR.MINOR.PATCH` with an optional
18
+ * `-pre`/`+build`, at most 64 characters. `upgrade` handed a cached `latest` of `9.0.0.tgz` to `npm i -D`, which read it
19
+ * as a local file, ran its install script and disarmed the gate (measured).
20
+ */
21
+ export declare function isStrictSemver(v: unknown): v is string;
16
22
  /** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
17
23
  export declare function readCache(home: string, readFile: (p: string) => string): UpdateCache | null;
18
24
  /** The one-line update guidance, branched by install mode. `source` returns null (git updates it). */
@@ -35,12 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.NPM_URL = void 0;
37
37
  exports.compareSemver = compareSemver;
38
+ exports.isStrictSemver = isStrictSemver;
38
39
  exports.readCache = readCache;
39
40
  exports.installModeGuide = installModeGuide;
40
41
  exports.composeBanner = composeBanner;
41
42
  exports.shouldQuery = shouldQuery;
42
43
  exports.cacheIsStale = cacheIsStale;
43
44
  // @implements A-SPEC-531.1
45
+ // @implements A-SPEC-251.1
44
46
  // The session banner and update notice, as a PURE core. Every side channel — the filesystem, the
45
47
  // clock, the environment — is a parameter, so the whole module verifies offline. The delivery
46
48
  // points (SessionStart hook, MCP instructions, init wiring) consume this in A-SPEC-531.2.
@@ -70,6 +72,18 @@ function compareSemver(a, b) {
70
72
  }
71
73
  return 0;
72
74
  }
75
+ /**
76
+ * @implements A-SPEC-251.1 (round 27) — a version this kit installs or names: `MAJOR.MINOR.PATCH` with an optional
77
+ * `-pre`/`+build`, at most 64 characters. `upgrade` handed a cached `latest` of `9.0.0.tgz` to `npm i -D`, which read it
78
+ * as a local file, ran its install script and disarmed the gate (measured).
79
+ */
80
+ function isStrictSemver(v) {
81
+ // Round 28: no build metadata (it names no published version), and never a value npm types as a local FILE — its
82
+ // file-name test is a `.tgz`/`.tar.gz`/`.tar` ending (`9.0.0-x.tgz` passed and ran its install script — measured).
83
+ return typeof v === 'string' && v.length <= 64
84
+ && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(v)
85
+ && !/[.](?:tgz|tar\.gz|tar)$/i.test(v);
86
+ }
73
87
  /** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
74
88
  function readCache(home, readFile) {
75
89
  let raw;
@@ -84,7 +98,7 @@ function readCache(home, readFile) {
84
98
  try {
85
99
  const v = JSON.parse(raw);
86
100
  if (v && typeof v === 'object'
87
- && typeof v.latest === 'string'
101
+ && isStrictSemver(v.latest)
88
102
  && typeof v.checkedAt === 'number') {
89
103
  return { latest: v.latest, checkedAt: v.checkedAt };
90
104
  }
@@ -129,5 +143,8 @@ function shouldQuery(env) {
129
143
  function cacheIsStale(cached, now, ttlMs = DEFAULT_TTL_MS) {
130
144
  if (!cached)
131
145
  return true;
146
+ // A-SPEC-251.1 (round 27): a check dated in the future never went stale.
147
+ if (cached.checkedAt > now)
148
+ return true;
132
149
  return now - cached.checkedAt > ttlMs;
133
150
  }
@@ -23,7 +23,35 @@ export declare function planUpgrade(a: {
23
23
  latest: string | null;
24
24
  registry: Registry;
25
25
  installMode: InstallMode;
26
+ /** Where latest came from (`describeLatest`), appended to a noop reason. */
27
+ latestNote?: string;
26
28
  }): UpgradePlan;
29
+ /** Where `upgrade` found latest: the registry just now, the update cache (with its age), or nowhere. */
30
+ export type ResolvedLatest = {
31
+ latest: string;
32
+ source: 'registry';
33
+ } | {
34
+ latest: string;
35
+ source: 'cache';
36
+ ageMs: number;
37
+ } | {
38
+ latest: null;
39
+ source: 'none';
40
+ };
41
+ /**
42
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
43
+ * and keeps its age; with neither latest is unknown.
44
+ */
45
+ export declare function resolveLatest(a: {
46
+ fresh: string | null;
47
+ cached: {
48
+ latest: string;
49
+ checkedAt: number;
50
+ } | null;
51
+ now: number;
52
+ }): ResolvedLatest;
53
+ /** The words for where latest came from — the note `planUpgrade` appends. */
54
+ export declare function describeLatest(r: ResolvedLatest): string;
27
55
  /** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
28
56
  export declare const NO_AUTO_REPIN_ENV = "HOLMES_NO_AUTO_REPIN";
29
57
  /**
@@ -2,6 +2,8 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.NO_AUTO_REPIN_ENV = void 0;
4
4
  exports.planUpgrade = planUpgrade;
5
+ exports.resolveLatest = resolveLatest;
6
+ exports.describeLatest = describeLatest;
5
7
  exports.repinDecision = repinDecision;
6
8
  // @implements A-SPEC-543.2
7
9
  const update_notice_1 = require("./update-notice");
@@ -13,14 +15,41 @@ const update_notice_1 = require("./update-notice");
13
15
  * (install-only, first machine).
14
16
  */
15
17
  function planUpgrade(a) {
18
+ const note = a.latestNote ? ` ${a.latestNote}` : '';
16
19
  if (a.latest === null) {
17
20
  return { kind: 'noop', reason: 'latest version unknown (registry unreachable and no cache) — nothing to plan' };
18
21
  }
19
- if ((0, update_notice_1.compareSemver)(a.latest, a.current) <= 0) {
20
- return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})` };
22
+ const order = (0, update_notice_1.compareSemver)(a.latest, a.current);
23
+ // A-SPEC-543.2 (amendment 2026-09-29): an installed version newer than latest means latest is stale — it is not
24
+ // "already up to date" (the report read `current 0.31.0, latest 0.30.0` from a cache that predated the release).
25
+ if (order < 0)
26
+ return { kind: 'noop', reason: `installed ${a.current} is newer than the latest ${a.latest}${note}` };
27
+ if (order === 0) {
28
+ return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})${note}` };
21
29
  }
22
30
  return { kind: 'run', current: a.current, latest: a.latest, installMode: a.installMode, repins: a.registry.workspaces };
23
31
  }
32
+ /**
33
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
34
+ * and keeps its age; with neither latest is unknown.
35
+ */
36
+ function resolveLatest(a) {
37
+ if (a.fresh !== null)
38
+ return { latest: a.fresh, source: 'registry' };
39
+ if (a.cached !== null)
40
+ return { latest: a.cached.latest, source: 'cache', ageMs: Math.max(0, a.now - a.cached.checkedAt) };
41
+ return { latest: null, source: 'none' };
42
+ }
43
+ /** The words for where latest came from — the note `planUpgrade` appends. */
44
+ function describeLatest(r) {
45
+ if (r.source === 'registry')
46
+ return '(registry)';
47
+ if (r.source === 'none')
48
+ return '';
49
+ const minutes = Math.round(r.ageMs / 60_000);
50
+ const age = minutes < 60 ? `${minutes} min` : `${Math.round(r.ageMs / 3_600_000)} h`;
51
+ return `(cached check from ${age} ago — the registry could not be reached)`;
52
+ }
24
53
  /** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
25
54
  exports.NO_AUTO_REPIN_ENV = 'HOLMES_NO_AUTO_REPIN';
26
55
  /**
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.30.0",
4
+ "version": "0.31.1",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",
@@ -63,12 +63,20 @@
63
63
  "setupFilesAfterEnv": [
64
64
  "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts"
65
65
  ],
66
- "maxWorkers": "50%"
66
+ "maxWorkers": "50%",
67
+ "roots": [
68
+ "<rootDir>/src"
69
+ ],
70
+ "testPathIgnorePatterns": [
71
+ "/node_modules/"
72
+ ]
67
73
  },
68
74
  "dependencies": {
69
75
  "@modelcontextprotocol/sdk": "^1.29.0",
76
+ "@xenova/transformers": "^2.17.2",
70
77
  "better-sqlite3": "^12.9.0",
71
78
  "js-yaml": "^4.1.1",
79
+ "smol-toml": "1.8.0",
72
80
  "tree-sitter": "^0.21.1",
73
81
  "tree-sitter-c-sharp": "^0.21.3",
74
82
  "tree-sitter-cpp": "^0.21.0",
@@ -78,8 +86,7 @@
78
86
  "tree-sitter-rust": "^0.21.0",
79
87
  "tree-sitter-typescript": "^0.21.2",
80
88
  "typescript": "^5.0.0",
81
- "web-tree-sitter": "0.27.0",
82
- "@xenova/transformers": "^2.17.2"
89
+ "web-tree-sitter": "0.27.0"
83
90
  },
84
91
  "repository": {
85
92
  "type": "git",