@holmes-lab/holmes-kit 0.28.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +24 -21
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  5. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  6. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  7. package/dist/holmes/cli/agents-guidance.js +11 -8
  8. package/dist/holmes/cli/codex-toml.d.ts +23 -1
  9. package/dist/holmes/cli/codex-toml.js +151 -4
  10. package/dist/holmes/cli/doctor.d.ts +11 -1
  11. package/dist/holmes/cli/doctor.js +113 -13
  12. package/dist/holmes/cli/init.d.ts +2 -0
  13. package/dist/holmes/cli/init.js +20 -40
  14. package/dist/holmes/cli/interactive-prompt.js +2 -2
  15. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  16. package/dist/holmes/cli/worktree-readiness.js +17 -3
  17. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  18. package/dist/holmes/cpg/ast-mutation.js +4 -2
  19. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  20. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  21. package/dist/holmes/governance/autonomy.d.ts +9 -0
  22. package/dist/holmes/governance/autonomy.js +28 -1
  23. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  24. package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
  25. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  26. package/dist/holmes/hooks/rtm-refresh.js +56 -15
  27. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  28. package/dist/holmes/mcp/approval-adapters.js +21 -0
  29. package/dist/holmes/mcp/approval-commit.d.ts +21 -0
  30. package/dist/holmes/mcp/approval-commit.js +92 -0
  31. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  32. package/dist/holmes/mcp/approval-intent.js +67 -0
  33. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  34. package/dist/holmes/mcp/approval-policy.js +18 -0
  35. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  36. package/dist/holmes/mcp/elicit-approval.js +5 -2
  37. package/dist/holmes/mcp/handlers/graph-operations.d.ts +24 -1
  38. package/dist/holmes/mcp/handlers/graph-operations.js +38 -6
  39. package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
  40. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +142 -0
  41. package/dist/holmes/mcp/handlers/requirement-triage.js +220 -0
  42. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  43. package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
  44. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
  45. package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
  46. package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
  47. package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
  48. package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
  49. package/dist/holmes/mcp/handlers.d.ts +153 -0
  50. package/dist/holmes/mcp/handlers.js +67 -13
  51. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  52. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  53. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +45 -0
  54. package/dist/holmes/mcp/requirement-triage-evidence.js +149 -0
  55. package/dist/holmes/mcp/server.js +5 -3
  56. package/dist/holmes/mcp/supervisor.js +7 -3
  57. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  58. package/dist/holmes/mcp/tool-schemas.js +44 -1
  59. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  60. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  61. package/dist/holmes/review/condition-hunk-replay.d.ts +45 -0
  62. package/dist/holmes/review/condition-hunk-replay.js +122 -0
  63. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  64. package/dist/holmes/review/condition-hunk-resolution.js +258 -0
  65. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  66. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  67. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  68. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  69. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  70. package/dist/holmes/review/requirement-triage.js +143 -0
  71. package/dist/holmes/review/scope.js +6 -1
  72. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  73. package/dist/holmes/review/test-outcomes.js +90 -1
  74. package/dist/holmes/semantic/local-model.d.ts +3 -3
  75. package/dist/holmes/semantic/local-model.js +10 -12
  76. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  77. package/dist/holmes/semantic/model-cache.js +77 -21
  78. package/dist/holmes/semantic/tier.d.ts +5 -1
  79. package/dist/holmes/semantic/tier.js +7 -6
  80. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  81. package/dist/holmes/semantic/vector-coverage.js +37 -0
  82. package/docs/install-guide.md +19 -24
  83. package/package.json +1 -1
@@ -49,11 +49,13 @@ exports.wiringSpawnCheck = wiringSpawnCheck;
49
49
  exports.pushGateCheck = pushGateCheck;
50
50
  exports.ciMatrixCheck = ciMatrixCheck;
51
51
  exports.formatChecks = formatChecks;
52
+ exports.codexWiredTarget = codexWiredTarget;
52
53
  exports.wiringHandshakeChecks = wiringHandshakeChecks;
53
54
  exports.semanticCoverageCheck = semanticCoverageCheck;
54
55
  exports.semanticTierVerdict = semanticTierVerdict;
55
56
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
56
- // @implements A-SPEC-704, A-SPEC-710
57
+ // @implements A-SPEC-721
58
+ // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712
57
59
  const doctor_guidance_1 = require("./doctor-guidance");
58
60
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
59
61
  // @implements A-SPEC-594
@@ -288,6 +290,31 @@ function observe(file, args) {
288
290
  return undefined;
289
291
  }
290
292
  }
293
+ /**
294
+ * A plugin snapshot is installation evidence, not live-session evidence. Codex owns the cache and
295
+ * CLI registry, so inspect its JSON response instead of inferring installation from a project
296
+ * manifest. A missing CLI, malformed response, remote plugin, or another workspace's local source
297
+ * is deliberately unobserved rather than mistaken for this target's installed gate.
298
+ */
299
+ function installedCodexPluginForTarget(target, readPluginList) {
300
+ const raw = readPluginList?.() ?? observe('codex', ['plugin', 'list', '--marketplace', agents_1.CODEX_MARKETPLACE, '--json']);
301
+ if (raw === undefined)
302
+ return false;
303
+ try {
304
+ const body = JSON.parse(raw);
305
+ const expectedSource = path.resolve(target, agents_1.CODEX_PLUGIN_DIR);
306
+ return (body.installed ?? []).some((entry) => entry.name === 'holmes-kit'
307
+ && entry.marketplaceName === agents_1.CODEX_MARKETPLACE
308
+ && entry.installed === true
309
+ && entry.enabled === true
310
+ && entry.source?.source === 'local'
311
+ && typeof entry.source.path === 'string'
312
+ && path.resolve(entry.source.path) === expectedSource);
313
+ }
314
+ catch {
315
+ return false;
316
+ }
317
+ }
291
318
  /**
292
319
  * @implements A-SPEC-580
293
320
  * Everything observable about the better-sqlite3 install, gathered for `nativeVerdict`. Each probe
@@ -534,7 +561,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
534
561
  // prove the wiring each harness will really run reaches a server. Measured: 367ms for three.
535
562
  // A doctor run with no target has no harness wiring to prove — skipped, not failed.
536
563
  if (target)
537
- checks.push(...await wiringHandshakeChecks(target));
564
+ checks.push(...await wiringHandshakeChecks(target, opts?.codexConfigPath));
538
565
  }
539
566
  // 7. Target wiring — do the configured commands point at THIS installed package and exist?
540
567
  if (target) {
@@ -1131,19 +1158,36 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1131
1158
  // `.codex/mcp_config.json` (JSON) this project used to write and Codex never read. Same A-SPEC-193
1132
1159
  // principle: no file → no diagnosis; a present file is judged for whether it resolves to THIS
1133
1160
  // install. A leftover JSON with no config.toml is a stale wiring in a location Codex ignores → WARN.
1134
- const cdxToml = path.join(target, '.codex', 'config.toml');
1161
+ const cdxToml = opts?.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)();
1135
1162
  const cdxJson = path.join(target, '.codex', 'mcp_config.json');
1163
+ // @implements A-SPEC-721 — the active config is user-level and shared by every workspace. It is
1164
+ // judged for THIS target only when it carries Holmes's table or the target is Codex-wired;
1165
+ // otherwise a Claude- or Antigravity-only workspace would inherit another tool's diagnosis.
1166
+ const targetWantsCodex = codexWiredTarget(target);
1167
+ let cdxRaw;
1136
1168
  if (fs.existsSync(cdxToml)) {
1137
- let raw = null;
1138
1169
  try {
1139
- raw = fs.readFileSync(cdxToml, 'utf8');
1170
+ cdxRaw = fs.readFileSync(cdxToml, 'utf8');
1171
+ }
1172
+ catch {
1173
+ cdxRaw = null;
1140
1174
  }
1141
- catch { /* handled below */ }
1175
+ }
1176
+ const cdxHolmes = typeof cdxRaw === 'string' && (0, codex_toml_1.mentionsHolmes)(cdxRaw);
1177
+ if ((cdxRaw === null && targetWantsCodex) || cdxHolmes) {
1178
+ const raw = cdxRaw ?? null;
1142
1179
  if (raw === null) {
1143
1180
  add('codex wiring', 'FAIL', `${cdxToml} cannot be read`, 'Check the file permissions, or delete it and rewire.');
1144
1181
  }
1145
1182
  else {
1183
+ if ((0, codex_toml_1.unownedHolmesShape)(raw)) {
1184
+ add('codex wiring shape', 'WARN', `${cdxToml} configures ${init_1.SERVER_NAME} in a shape holmes-kit does not own (dotted keys, an inline table under [mcp_servers], or a ${init_1.SERVER_NAME} subtable outside its table) — rewriting it would declare the table twice and Codex would reject the whole shared file`, `Edit ${cdxToml} by hand to a single [mcp_servers.${init_1.SERVER_NAME}] table (or remove the ${init_1.SERVER_NAME} settings), then run holmes-kit init --target <dir> --agent codex.`);
1185
+ }
1146
1186
  const entry = (0, codex_toml_1.readCodexHolmesEntry)(raw);
1187
+ const fixedSpecs = (0, codex_toml_1.readCodexFixedSpecs)(raw);
1188
+ if (fixedSpecs !== null && (path.isAbsolute(fixedSpecs) || path.win32.isAbsolute(fixedSpecs))) {
1189
+ add('codex wiring env', 'WARN', `${cdxToml} pins HOLMES_SPECS to ${fixedSpecs} — this config is shared by every workspace, so every Codex session is bound to that one project's specs`, 'Rewire with holmes-kit init --target <dir> --agent codex --force; the entry it writes omits HOLMES_SPECS so the server follows the session workspace.');
1190
+ }
1147
1191
  // @implements A-SPEC-585 — an invalid basic-string escape (a raw Windows backslash path is the
1148
1192
  // measured case) is not "half-done": Codex refuses the whole file, and the reader must not
1149
1193
  // hand doctor a mangled path to judge. Name the escape and the line.
@@ -1199,6 +1243,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1199
1243
  // two install commands, so PASS is not available here — the presence of files is not the
1200
1244
  // presence of a gate. That inference is what A-SPEC-441 got wrong, and reporting PASS for
1201
1245
  // it made the tool agree with the mistake.
1246
+ // @implements A-SPEC-721 — judged whenever the shared entry exists: every Codex session in this
1247
+ // workspace receives the tools, so a missing plugin gate is true here (A-SPEC-423).
1202
1248
  const cdxPluginJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, '.codex-plugin', 'plugin.json');
1203
1249
  const cdxHooksJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, 'hooks.json');
1204
1250
  // @implements A-SPEC-533.3 — codex-cli 0.152.x reads the marketplace manifest at
@@ -1218,6 +1264,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1218
1264
  const p2 = (0, settings_merge_1.hookScriptPath)(c);
1219
1265
  return !resolvesToPackage(p2, packageRoot);
1220
1266
  });
1267
+ const installedPlugin = installedCodexPluginForTarget(target, opts?.readCodexPluginList);
1268
+ if (installedPlugin) {
1269
+ add('codex plugin install', 'PASS', 'The Holmes-Kit plugin snapshot is installed and enabled for this workspace. This proves new Codex sessions can load the plugin, not that the current live session already loaded its hooks.');
1270
+ }
1221
1271
  if (stale.length > 0) {
1222
1272
  add('codex gate', 'FAIL', `hook command(s) not pointing at this install: ${stale.join(' | ')}`, 'Run holmes-kit init --target <dir> --agent codex --force to refresh the absolute paths.');
1223
1273
  }
@@ -1232,7 +1282,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1232
1282
  add('codex gate', 'WARN', `.claude-plugin/marketplace.json (read by codex 0.152.x) is missing — only the old location (.agents/plugins/marketplace.json) is present, so codex plugin marketplace add fails with "no manifest" (0.151.x reads .agents/plugins/, 0.152.x reads .claude-plugin/)`, 'Rewiring with holmes-kit init --target <dir> --agent codex --force places the manifest in both locations.');
1233
1283
  }
1234
1284
  else {
1235
- add('codex gate', 'WARN', 'The plugin wiring is correct — but the gate is not enforced until it is installed (Codex only loads plugins from an installed marketplace, and doctor cannot verify installation offline)', `Run ${installCmds}, then use it in a new session.`);
1285
+ add('codex gate', 'WARN', installedPlugin
1286
+ ? 'The installed plugin is available to new Codex sessions, but this process cannot prove that the current live session loaded its hooks.'
1287
+ : 'The plugin wiring is correct — but the gate is not enforced until it is installed (Codex only loads plugins from an installed marketplace, and doctor cannot verify installation offline)', installedPlugin ? 'Start a new Codex session in this workspace and run workspace_preflight.' : `Run ${installCmds}, then use it in a new session.`);
1236
1288
  }
1237
1289
  }
1238
1290
  catch {
@@ -1240,12 +1292,15 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1240
1292
  }
1241
1293
  }
1242
1294
  else {
1243
- add('codex gate', 'WARN', 'The codex plugin wiring (.agents/plugins/marketplace.json, .holmes/codex-plugin/holmes-kit) is missing — only the MCP tools work; the gate is not enforced', `Wire it with holmes-kit init --target <dir> --agent codex, then install with ${installCmds}.`);
1295
+ add('codex gate', 'WARN', `The codex plugin wiring (.claude-plugin/marketplace.json, ${agents_1.CODEX_PLUGIN_DIR}) is missing — only the MCP tools work; the gate is not enforced`, `Wire it with holmes-kit init --target <dir> --agent codex, then install with ${installCmds}.`);
1244
1296
  }
1245
1297
  }
1246
1298
  }
1247
1299
  else if (fs.existsSync(cdxJson)) {
1248
- add('codex wiring', 'WARN', `codex wiring sits in a legacy location Codex does not read (${cdxJson}) — it must move to config.toml`, 'Rewiring with holmes-kit init --target <dir> --agent codex migrates it to config.toml and cleans up the legacy file.');
1300
+ add('codex wiring', 'WARN', `codex wiring sits in a legacy location Codex does not read (${cdxJson}); the active entry belongs in ${cdxToml}`, `Run holmes-kit init --target <dir> --agent codex to write the active entry to ${cdxToml}; it leaves the legacy file in place for you to delete.`);
1301
+ }
1302
+ else if (targetWantsCodex) {
1303
+ add('codex wiring', 'WARN', `this workspace is wired for Codex, but ${cdxToml} (the config Codex loads) has no [mcp_servers.${init_1.SERVER_NAME}] entry — Holmes MCP tools are not active in Codex sessions`, 'Run holmes-kit init --target <dir> --agent codex.');
1249
1304
  }
1250
1305
  try {
1251
1306
  const sp = wiredSettingsPath(target);
@@ -1326,7 +1381,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1326
1381
  if (ci)
1327
1382
  checks.push(ci);
1328
1383
  }
1329
- checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent }));
1384
+ checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent, codexConfigPath: opts?.codexConfigPath }));
1330
1385
  if (extraChecks) {
1331
1386
  checks.push(...extraChecks);
1332
1387
  }
@@ -1684,14 +1739,24 @@ function formatChecks(checks) {
1684
1739
  * The `node` fast-path is gone. Existence survives as a fast FAIL, because spending a 30s deadline on
1685
1740
  * a path that does not exist tells nobody anything new.
1686
1741
  */
1687
- async function wiringHandshakeChecks(target) {
1742
+ /**
1743
+ * @implements A-SPEC-721 — the target itself carries Codex wiring (plugin directory, or a legacy
1744
+ * repository-local config/JSON). The active config is shared by every workspace, so only such a
1745
+ * target is told that the shared file lacks a Holmes entry.
1746
+ */
1747
+ function codexWiredTarget(target) {
1748
+ return fs.existsSync(path.join(target, agents_1.CODEX_PLUGIN_DIR))
1749
+ || fs.existsSync(path.join(target, '.codex', 'config.toml'))
1750
+ || fs.existsSync(path.join(target, '.codex', 'mcp_config.json'));
1751
+ }
1752
+ async function wiringHandshakeChecks(target, codexConfigPath = (0, codex_toml_1.defaultCodexConfigPath)()) {
1688
1753
  const wirings = [
1689
1754
  {
1690
1755
  label: 'claude', file: path.join(target, '.mcp.json'),
1691
1756
  read: (raw) => entryOf(JSON.parse(raw)?.mcpServers?.[init_1.SERVER_NAME]),
1692
1757
  },
1693
1758
  {
1694
- label: 'codex', file: path.join(target, '.codex', 'config.toml'),
1759
+ label: 'codex', file: codexConfigPath,
1695
1760
  read: (raw) => entryOf((0, codex_toml_1.readCodexHolmesEntry)(raw)),
1696
1761
  },
1697
1762
  {
@@ -1705,9 +1770,20 @@ async function wiringHandshakeChecks(target) {
1705
1770
  if (!fs.existsSync(wiring.file))
1706
1771
  continue;
1707
1772
  const name = `${wiring.label} wiring handshake`;
1773
+ let raw = null;
1774
+ try {
1775
+ raw = fs.readFileSync(wiring.file, 'utf8');
1776
+ }
1777
+ catch {
1778
+ raw = null;
1779
+ }
1780
+ // @implements A-SPEC-721 — Codex's config is user-level and shared: without Holmes's table it is
1781
+ // another tool's file, not a dead Holmes wiring (runDoctor names a Codex-wired target's gap).
1782
+ if (wiring.label === 'codex' && raw !== null && !(0, codex_toml_1.mentionsHolmes)(raw) && !codexWiredTarget(target))
1783
+ continue;
1708
1784
  let entry = null;
1709
1785
  try {
1710
- entry = wiring.read(fs.readFileSync(wiring.file, 'utf8'));
1786
+ entry = raw === null ? null : wiring.read(raw);
1711
1787
  }
1712
1788
  catch {
1713
1789
  entry = null;
@@ -1812,6 +1888,30 @@ function semanticTierVerdict(t) {
1812
1888
  fix: 'Run holmes-kit semantic-check for actual offline inference; if unavailable, run holmes-kit semantic-setup.',
1813
1889
  };
1814
1890
  }
1891
+ // @implements A-SPEC-712 — a cache directory is only a candidate. The receipt is written after
1892
+ // successful offline inference, so its absence or a fingerprint mismatch is degraded rather than
1893
+ // a normal first-install state. Tell the user whether setup will verify existing assets or must
1894
+ // fetch them, without pretending the local tier can answer meanwhile.
1895
+ if (t.localRuntimePresent && t.localState) {
1896
+ const changed = t.localState === 'stale-receipt';
1897
+ const invalid = t.localState === 'invalid-receipt';
1898
+ const missing = t.localState === 'missing-cache';
1899
+ const detail = missing
1900
+ ? 'Semantic search tier: unavailable — the local runtime is installed but the BGE-M3 cache is absent.'
1901
+ : changed
1902
+ ? 'Semantic search tier: degraded — the changed BGE-M3 cache no longer matches its verified-inference receipt.'
1903
+ : invalid
1904
+ ? 'Semantic search tier: degraded — the BGE-M3 readiness receipt is invalid, so cached assets are not trusted.'
1905
+ : 'Semantic search tier: degraded — an existing BGE-M3 cache has not completed verified offline inference.';
1906
+ const fix = missing
1907
+ ? 'Run `holmes-kit semantic-setup` to download and verify BGE-M3 offline.'
1908
+ : changed
1909
+ ? 'Run `holmes-kit semantic-setup` to re-verify the changed BGE-M3 cache offline.'
1910
+ : invalid
1911
+ ? 'Run `holmes-kit semantic-setup` to replace the invalid BGE-M3 readiness receipt.'
1912
+ : 'Run `holmes-kit semantic-setup` to verify the existing BGE-M3 cache offline.';
1913
+ return { level: 'WARN', detail, fix };
1914
+ }
1815
1915
  // @implements A-SPEC-594 — two different 'none' states need two different sentences. When the
1816
1916
  // runtime is already installed, telling the user to install it is noise; the missing piece is
1817
1917
  // the model, and the command that fetches it is the whole fix. Both stay PASS: a user who never
@@ -31,6 +31,8 @@ export interface InitOptions {
31
31
  agents?: Agent[];
32
32
  allowAdditive?: boolean;
33
33
  mcpLauncher?: LauncherMode;
34
+ /** Test/integration override for Codex's default user configuration path. */
35
+ codexConfigPath?: string;
34
36
  autonomy?: boolean;
35
37
  autonomyInteractive?: boolean;
36
38
  }
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
+ // @implements A-SPEC-724, A-SPEC-721
39
40
  // @implements A-SPEC-709
40
41
  // @implements A-SPEC-340
41
42
  // @implements A-SPEC-100.2
@@ -375,18 +376,15 @@ function runInit(opts) {
375
376
  }
376
377
  messages.push('Restart Claude Code — hooks and MCP servers are read at session start.');
377
378
  }
378
- // @implements A-SPEC-266 — Codex reads MCP servers from `.codex/config.toml` (TOML
379
- // `[mcp_servers.*]`), NOT the `.codex/mcp_config.json` (JSON) this project used to write and Codex
380
- // never loaded. That file also holds the user's other Codex settings, so — like `.mcp.json` — we
381
- // MERGE only our table. The obsolete JSON is migrated away so no dead wiring is left behind.
382
- let codexJsonToMigrate = null; // deleted only after the write loop confirms config.toml
383
- {
384
- const codexDir = path.join(opts.target, '.codex');
385
- const codexTomlPath = path.join(codexDir, 'config.toml');
386
- const codexJsonPath = path.join(codexDir, 'mcp_config.json');
387
- // A `.codex/config.toml` we cannot read (a directory, a permission wall, a dangling symlink) is
388
- // NOT touched — reading it eagerly with readFileSync threw and crashed the whole init. Mirror the
389
- // `.mcp.json` "refusing to touch it" discipline: skip codex wiring and say so, migrate nothing.
379
+ // @implements A-SPEC-721 — Codex CLI loads its default user config, not a table merely placed in
380
+ // the repository. The owned server table is merged there and has no fixed HOLMES_SPECS binding.
381
+ // The active file is a user-level resource, not a target artifact: merely removing Claude/AGY
382
+ // wiring must not probe or mutate it. Explicit `--agent codex` is the authority for both merge
383
+ // and owned-table removal, so tests and consumers can safely operate without a writable home.
384
+ if ((opts.agents ?? []).includes('codex')) {
385
+ const codexTomlPath = opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)();
386
+ // An active config we cannot read is NOT touched. A legacy project artifact is deliberately
387
+ // preserved: deleting a file Codex does not load would add surprise without restoring wiring.
390
388
  let codexTomlBefore = null;
391
389
  let codexUnreadable = false;
392
390
  if (fs.existsSync(codexTomlPath)) {
@@ -397,25 +395,15 @@ function runInit(opts) {
397
395
  codexUnreadable = true;
398
396
  }
399
397
  }
400
- const wantsCodex = (opts.agents ?? []).includes('codex') && !codexUnreadable;
398
+ const wantsCodex = !codexUnreadable;
401
399
  if (codexUnreadable)
402
400
  messages.push(`Refusing to touch ${codexTomlPath} — it is not a readable file. Fix or remove it, then re-run.`);
403
- // @implements A-SPEC-266 (round-2 F3) — the obsolete JSON is deleted AFTER the config.toml write is
404
- // confirmed, never before: an eager delete followed by a failed toml write left the user with NO
405
- // codex wiring at all (and a message claiming nothing was lost). Here we only PLAN the migration;
406
- // the deletion runs post-write-loop (dry-run just previews it in `removals`).
407
- const migrateAwayCodexJson = () => {
408
- if (!fs.existsSync(codexJsonPath))
409
- return;
410
- if (opts.dryRun) {
411
- removals.push(codexJsonPath);
412
- return;
413
- }
414
- codexJsonToMigrate = codexJsonPath;
415
- };
416
401
  if (opts.remove) {
417
402
  if (codexTomlBefore !== null) {
418
403
  const after = (0, codex_toml_1.removeCodexToml)(codexTomlBefore);
404
+ // @implements A-SPEC-721 — the active entry is user-level: say so before anyone is surprised.
405
+ if (after !== codexTomlBefore)
406
+ messages.push(`${codexTomlPath} is Codex's user-level config: removing its holmes-kit entry turns Holmes MCP off in Codex for every workspace, not only ${opts.target}. Re-run holmes-kit init --agent codex in any workspace to restore it.`);
419
407
  if (after.trim() === '' && after !== codexTomlBefore) {
420
408
  // Our table was the only content — delete the file rather than leave it empty.
421
409
  if (opts.dryRun)
@@ -429,7 +417,11 @@ function runInit(opts) {
429
417
  changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
430
418
  }
431
419
  }
432
- migrateAwayCodexJson();
420
+ }
421
+ else if (wantsCodex && opts.mcp && codexTomlBefore !== null && (0, codex_toml_1.unownedHolmesShape)(codexTomlBefore)) {
422
+ // @implements A-SPEC-721 — merging our table into a file that already configures holmes-kit in
423
+ // another spelling would declare it twice; Codex would then reject the whole shared config.
424
+ messages.push(`Refusing to rewrite ${codexTomlPath}: it configures holmes-kit in a shape holmes-kit does not own (dotted keys, an inline table under [mcp_servers], or a holmes-kit subtable outside its table). Edit it by hand to a single [mcp_servers.holmes-kit] table, then re-run.`);
433
425
  }
434
426
  else if (wantsCodex && opts.mcp) {
435
427
  const mcpBin = path.join(opts.packageRoot, 'bin', 'holmes-mcp.js');
@@ -437,7 +429,7 @@ function runInit(opts) {
437
429
  const after = (0, codex_toml_1.mergeCodexToml)(codexTomlBefore, (0, codex_toml_1.codexMcpBlock)(entry, opts.specsDir));
438
430
  if (after !== codexTomlBefore)
439
431
  changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
440
- migrateAwayCodexJson();
432
+ messages.push(`Codex MCP wiring is active from ${codexTomlPath}; restart Codex in the target workspace.`);
441
433
  }
442
434
  }
443
435
  if (opts.dryRun) {
@@ -567,18 +559,6 @@ function runInit(opts) {
567
559
  ] };
568
560
  }
569
561
  }
570
- // @implements A-SPEC-266 (round-2 F3) — the config.toml write above is confirmed now, so it is
571
- // safe to remove the obsolete JSON. Doing it earlier risked deleting codex's only wiring and then
572
- // failing the toml write.
573
- if (codexJsonToMigrate !== null && fs.existsSync(codexJsonToMigrate)) {
574
- try {
575
- fs.rmSync(codexJsonToMigrate, { force: true });
576
- messages.push(`Removed obsolete ${codexJsonToMigrate} (Codex never read it — MCP wiring now lives in config.toml).`);
577
- }
578
- catch (e) {
579
- messages.push(`Could not remove obsolete ${codexJsonToMigrate}: ${e instanceof Error ? e.message : String(e)}`);
580
- }
581
- }
582
562
  if (!opts.remove && opts.mode === 'governed') {
583
563
  for (const d of SPEC_SUBDIRS)
584
564
  fs.mkdirSync(path.join(opts.target, opts.specsDir, d), { recursive: true });
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.parseAgentList = parseAgentList;
37
37
  exports.promptAgentSelection = promptAgentSelection;
38
38
  exports.promptAutonomy = promptAutonomy;
39
- // @implements A-SPEC-200
39
+ // @implements A-SPEC-724, A-SPEC-200
40
40
  const readline = __importStar(require("node:readline"));
41
41
  const agents_1 = require("./agents");
42
42
  /**
@@ -92,7 +92,7 @@ async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWi
92
92
  }
93
93
  else if (item === 'codex') {
94
94
  isChecked = selected.has('codex');
95
- label = '💻 Codex CLI (.codex/config.toml)';
95
+ label = '💻 Codex CLI (~/.codex/config.toml)';
96
96
  }
97
97
  const box = isChecked ? '[X]' : '[ ]';
98
98
  const line = `${prefix}${box} ${label}\n`;
@@ -3,4 +3,5 @@ import type { Check } from './doctor-check';
3
3
  /** Disk preparation evidence for one selected harness. It never observes a client's loaded config. */
4
4
  export declare function worktreeReadinessChecks(packageRoot: string, target: string, opts?: {
5
5
  agent?: Agent;
6
+ codexConfigPath?: string;
6
7
  }): Check[];
@@ -34,16 +34,27 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.worktreeReadinessChecks = worktreeReadinessChecks;
37
- // @implements A-SPEC-704
37
+ // @implements A-SPEC-724, A-SPEC-704
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const workspace_checkout_1 = require("../project/workspace-checkout");
41
41
  const workspace_identity_1 = require("../project/workspace-identity");
42
+ const codex_toml_1 = require("./codex-toml");
43
+ // Codex's MCP entry lives in its user-level config (A-SPEC-721), judged separately below; the
44
+ // repository-local .codex/config.toml is inactive and init no longer writes it (A-SPEC-724).
42
45
  const WIRING = {
43
46
  claude: ['.mcp.json'],
44
- codex: ['.codex/config.toml', '.claude-plugin/marketplace.json'],
47
+ codex: ['.claude-plugin/marketplace.json'],
45
48
  antigravity: ['.agents/mcp_config.json', '.agents/hooks.json'],
46
49
  };
50
+ function codexActiveEntryPresent(configPath) {
51
+ try {
52
+ return (0, codex_toml_1.hasCodexHolmesTable)(fs.readFileSync(configPath, 'utf8'));
53
+ }
54
+ catch {
55
+ return false;
56
+ }
57
+ }
47
58
  /** Disk preparation evidence for one selected harness. It never observes a client's loaded config. */
48
59
  function worktreeReadinessChecks(packageRoot, target, opts = {}) {
49
60
  const agent = opts.agent;
@@ -63,12 +74,15 @@ function worktreeReadinessChecks(packageRoot, target, opts = {}) {
63
74
  }
64
75
  const files = WIRING[agent];
65
76
  const missing = files.filter((file) => !fs.existsSync(path.join(target, file)));
77
+ const codexConfig = opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)();
78
+ if (agent === 'codex' && !codexActiveEntryPresent(codexConfig))
79
+ missing.unshift(`holmes-kit entry in the active Codex config ${codexConfig}`);
66
80
  const build = fs.existsSync(path.join(packageRoot, 'dist', 'holmes', 'mcp', 'server.js'));
67
81
  const level = missing.length || identityWarning || checkout.kind === 'unknown' || !build ? 'WARN' : 'PASS';
68
82
  const repair = `Run holmes-kit init --target ${target} --agent ${agent}, then restart that harness session.`;
69
83
  const detail = [
70
84
  `disk preparation only: ${agent}; checkout=${checkout.kind}${checkout.detached ? ' (detached)' : ''}; identity=${identity}.`,
71
- missing.length ? `missing local wiring: ${missing.join(', ')}.` : `local wiring present: ${files.join(', ')}.`,
85
+ missing.length ? `missing local wiring: ${missing.join(', ')}.` : `local wiring present: ${[...(agent === 'codex' ? [codexConfig] : []), ...files].join(', ')}.`,
72
86
  build ? 'package build is present.' : 'package build is absent.',
73
87
  'This does not prove whether a current client loaded hooks or MCP configuration.',
74
88
  ].join(' ');
@@ -17,6 +17,8 @@ export interface MutationResult {
17
17
  mutationScorePct: number;
18
18
  mutants: AstMutant[];
19
19
  }
20
+ /** Shared mutation vocabulary used by mutation scoring and condition-direction advisories. */
21
+ export declare const MUTATION_MAP: Readonly<Record<MutationOperator, Readonly<Record<string, readonly string[]>>>>;
20
22
  /**
21
23
  * Generate AST mutants for static CPG scanned files.
22
24
  *
@@ -1,8 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MUTATION_MAP = void 0;
3
4
  exports.generateAstMutants = generateAstMutants;
4
5
  exports.evaluateMutationScore = evaluateMutationScore;
5
- const MUTATION_MAP = {
6
+ /** Shared mutation vocabulary used by mutation scoring and condition-direction advisories. */
7
+ exports.MUTATION_MAP = {
6
8
  relational: {
7
9
  '>': ['<', '>='],
8
10
  '<': ['>', '<='],
@@ -47,7 +49,7 @@ function generateAstMutants(scannedFiles, operators) {
47
49
  for (const sym of symbols) {
48
50
  let mutIndex = 0;
49
51
  for (const opType of targetOps) {
50
- const opRules = MUTATION_MAP[opType];
52
+ const opRules = exports.MUTATION_MAP[opType];
51
53
  if (!opRules)
52
54
  continue;
53
55
  for (const [origToken, replacements] of Object.entries(opRules)) {
@@ -23,6 +23,14 @@ export interface CfgEdge {
23
23
  to: number;
24
24
  kind: EdgeKind;
25
25
  }
26
+ /** Source provenance for a TS/JS predicate-bearing branch; absent where the language/source cannot prove it. */
27
+ export interface CfgConditionBranch {
28
+ conditionText?: string;
29
+ startOffset?: number;
30
+ endOffset?: number;
31
+ astKind?: string;
32
+ branchLabel: 'true' | 'false' | 'case' | 'default';
33
+ }
26
34
  export interface Cfg {
27
35
  blocks: CfgBlock[];
28
36
  edges: CfgEdge[];
@@ -34,6 +42,8 @@ export interface Cfg {
34
42
  ipostdom: Int32Array;
35
43
  /** Blocks not reachable from ENTRY (dead code after return etc.) — lint material, not an error. */
36
44
  unreachable: number[];
45
+ /** Additive condition facts. Existing blocks and edge labels retain their original contract. */
46
+ conditionBranches?: CfgConditionBranch[];
37
47
  }
38
48
  export interface FunctionRef {
39
49
  nodeIndex: number;
@@ -1085,7 +1085,33 @@ function cfgOf(ast, fn, source) {
1085
1085
  link(e.from, EXIT, e.kind === 'seq' ? 'seq' : e.kind);
1086
1086
  if (pendingBreaks.length > 0)
1087
1087
  throw new Unsupported('unresolved break label');
1088
- return finalize(stmtsOf, edges, ENTRY, EXIT);
1088
+ const cfg = finalize(stmtsOf, edges, ENTRY, EXIT);
1089
+ // Predicate provenance is deliberately narrower than CFG support: this slice has verified the
1090
+ // tree shapes only for TS/JS, and an absent fact is safer than a guessed condition in another
1091
+ // language. It is attached beside edges, never changes their labels or connectivity.
1092
+ if (source !== undefined && (ast.lang === 'typescript' || ast.lang === 'tsx')) {
1093
+ const conditions = [];
1094
+ const bodyTypes = new Set(['statement_block', 'else_clause', 'switch_body']);
1095
+ for (const edge of cfg.edges) {
1096
+ if (!['true', 'false', 'case', 'default'].includes(edge.kind))
1097
+ continue;
1098
+ const stmt = cfg.blocks[edge.from]?.stmts[0];
1099
+ if (stmt === undefined)
1100
+ continue;
1101
+ const type = ast.nodes[stmt]?.type;
1102
+ if (!['if_statement', 'while_statement', 'do_statement', 'for_statement', 'for_in_statement', 'switch_statement'].includes(type))
1103
+ continue;
1104
+ const condition = kids.of(stmt).find((child) => ast.nodes[child].named && !bodyTypes.has(ast.nodes[child].type));
1105
+ if (condition === undefined)
1106
+ continue;
1107
+ conditions.push({ conditionText: source.slice(ast.nodes[condition].start, ast.nodes[condition].end),
1108
+ startOffset: ast.nodes[condition].start, endOffset: ast.nodes[condition].end,
1109
+ astKind: ast.nodes[condition].type, branchLabel: edge.kind });
1110
+ }
1111
+ if (conditions.length > 0)
1112
+ cfg.conditionBranches = conditions;
1113
+ }
1114
+ return cfg;
1089
1115
  }
1090
1116
  catch (e) {
1091
1117
  if (e instanceof Unsupported)
@@ -26,6 +26,15 @@ export declare function descendantAspecs(spec: Spec, all: Spec[]): Spec[];
26
26
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
27
27
  */
28
28
  export declare function specApprovalAutonomy(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): ApprovalAutonomy;
29
+ /**
30
+ * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
31
+ * presented in-session while autonomous mode is enabled. This is intentionally narrower than
32
+ * `specApprovalAutonomy(...) === 'hitl'`: an upstream REQ/H-SPEC with no implemented A-SPEC is
33
+ * not identified as high-risk yet, so autonomous mode queues it without interrupting the agent.
34
+ * Architecture, an explicitly high-risk A-SPEC, and an upstream document leading to either remain
35
+ * visible to a human; their direct-form timeout is handled separately as an autonomous timeout.
36
+ */
37
+ export declare function requiresAutonomousApprovalPrompt(spec: Spec, descendants?: Spec[]): boolean;
29
38
  export declare const SESSION_AUTONOMY_MARKER: readonly [".ax", "state", "autonomy.json"];
30
39
  export declare function sessionAutonomyActive(root: string, now: string): boolean;
31
40
  /** Whether autonomous approval is enabled — the out-of-band env switch, OR a valid session envelope
@@ -37,6 +37,7 @@ exports.SESSION_AUTONOMY_MARKER = exports.AUTONOMY_ENV = void 0;
37
37
  exports.isHighRiskPath = isHighRiskPath;
38
38
  exports.descendantAspecs = descendantAspecs;
39
39
  exports.specApprovalAutonomy = specApprovalAutonomy;
40
+ exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
40
41
  exports.sessionAutonomyActive = sessionAutonomyActive;
41
42
  exports.projectDefaultAutonomy = projectDefaultAutonomy;
42
43
  exports.autonomousApprovalEnabled = autonomousApprovalEnabled;
@@ -44,7 +45,7 @@ exports.autonomyBanner = autonomyBanner;
44
45
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
45
46
  exports.versionBumpKind = versionBumpKind;
46
47
  exports.releaseAutonomy = releaseAutonomy;
47
- // @implements A-SPEC-532.1
48
+ // @implements A-SPEC-532.1, A-SPEC-718
48
49
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
49
50
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
50
51
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -190,6 +191,32 @@ function specApprovalAutonomy(spec, resolveParent, descendants) {
190
191
  return 'hitl'; // unknown kind: fail-safe to human
191
192
  }
192
193
  }
194
+ /**
195
+ * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
196
+ * presented in-session while autonomous mode is enabled. This is intentionally narrower than
197
+ * `specApprovalAutonomy(...) === 'hitl'`: an upstream REQ/H-SPEC with no implemented A-SPEC is
198
+ * not identified as high-risk yet, so autonomous mode queues it without interrupting the agent.
199
+ * Architecture, an explicitly high-risk A-SPEC, and an upstream document leading to either remain
200
+ * visible to a human; their direct-form timeout is handled separately as an autonomous timeout.
201
+ */
202
+ function requiresAutonomousApprovalPrompt(spec, descendants) {
203
+ switch (spec.type) {
204
+ case 'T-SPEC':
205
+ return false;
206
+ case 'C-SPEC':
207
+ case 'ADR':
208
+ return true;
209
+ case 'REQ':
210
+ case 'H-SPEC': {
211
+ const below = (descendants ?? []).filter((s) => s.type === 'A-SPEC');
212
+ return below.some((a) => requiresAutonomousApprovalPrompt(a));
213
+ }
214
+ case 'A-SPEC':
215
+ return specApprovalAutonomy(spec, () => null) !== 'auto';
216
+ default:
217
+ return true;
218
+ }
219
+ }
193
220
  // @implements A-SPEC-553.1 — the per-session autonomy envelope. A protected marker (an agent cannot
194
221
  // write `.ax/state/`, measured) with an absolute expiry lets a HITL-default project self-drive
195
222
  // low-risk specs for ONE bounded, audited session. Read at decision time; fail-closed on anything
@@ -1 +1,22 @@
1
- export {};
1
+ import { FreshnessLane, FreshnessReceipt } from '../refresh/freshness-coordinator';
2
+ /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
3
+ export declare function recordRefreshFailure(root: string, generation: string, head: string | null, now: Date): FreshnessReceipt | null;
4
+ export interface RefreshChildDeps {
5
+ head: (root: string) => string | null;
6
+ refreshGraph: (root: string) => Promise<unknown>;
7
+ refreshSource: (root: string) => Promise<{
8
+ lane: FreshnessLane;
9
+ }>;
10
+ refreshRequirement: (root: string) => Promise<{
11
+ status: string;
12
+ }>;
13
+ }
14
+ /**
15
+ * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
16
+ * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
17
+ * failure — synchronous module load included — is published as bounded retry for this generation
18
+ * rather than left as a `refreshing` lease that only expiry can clear (A-SPEC-719).
19
+ */
20
+ export declare function runRefreshChild(root: string, generation: string, deps: RefreshChildDeps): Promise<void>;
21
+ /** The production phases: the scan/build machinery, loaded only inside the detached child. */
22
+ export declare function defaultRefreshChildDeps(env?: NodeJS.ProcessEnv): RefreshChildDeps;