@holmes-lab/holmes-kit 0.27.0 → 0.28.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 (36) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +2 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-command.d.ts +9 -0
  5. package/dist/holmes/cli/agents-guidance-command.js +61 -0
  6. package/dist/holmes/cli/agents-guidance-file.d.ts +7 -0
  7. package/dist/holmes/cli/agents-guidance-file.js +86 -0
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +10 -0
  9. package/dist/holmes/cli/agents-guidance-history.js +35 -0
  10. package/dist/holmes/cli/agents-guidance-plan.d.ts +11 -0
  11. package/dist/holmes/cli/agents-guidance-plan.js +81 -0
  12. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  13. package/dist/holmes/cli/agents-guidance.js +40 -0
  14. package/dist/holmes/cli/agents.d.ts +3 -19
  15. package/dist/holmes/cli/agents.js +12 -108
  16. package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
  17. package/dist/holmes/cli/doctor-guidance.js +61 -0
  18. package/dist/holmes/cli/doctor.d.ts +2 -0
  19. package/dist/holmes/cli/doctor.js +5 -1
  20. package/dist/holmes/cli/index.js +31 -3
  21. package/dist/holmes/cli/init.js +32 -5
  22. package/dist/holmes/cli/upgrade.js +23 -26
  23. package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
  24. package/dist/holmes/cli/worktree-readiness.js +81 -0
  25. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  26. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  27. package/dist/holmes/mcp/handlers.d.ts +50 -46
  28. package/dist/holmes/mcp/handlers.js +6 -3
  29. package/dist/holmes/mcp/tool-schemas.js +6 -1
  30. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  31. package/dist/holmes/project/workspace-checkout.js +74 -0
  32. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  33. package/dist/holmes/project/workspace-preflight.js +99 -0
  34. package/docs/install-guide.md +54 -0
  35. package/package.json +1 -1
  36. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
@@ -0,0 +1,61 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.guidanceChecks = guidanceChecks;
37
+ // @implements A-SPEC-710
38
+ const fs = __importStar(require("node:fs"));
39
+ const path = __importStar(require("node:path"));
40
+ const agents_guidance_plan_1 = require("./agents-guidance-plan");
41
+ const agents_guidance_file_1 = require("./agents-guidance-file");
42
+ function guidanceChecks(packageRoot, target) {
43
+ const file = path.join(target, 'AGENTS.md');
44
+ let version = 'unknown';
45
+ try {
46
+ version = String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
47
+ }
48
+ catch { /* report unknown version explicitly */ }
49
+ try {
50
+ const plan = (0, agents_guidance_plan_1.planGuidance)((0, agents_guidance_file_1.readGuidanceFile)(file));
51
+ const level = plan.after === null ? 'FAIL' : plan.state === 'current' ? 'PASS' : 'WARN';
52
+ return [{ name: 'managed AGENTS guidance', level,
53
+ detail: `${file}: ${plan.state}; installed package ${version}. ${plan.reasons.join(' ')} File currency does not prove active-session loading or hook enforcement.`,
54
+ ...(level === 'PASS' ? {} : { fix: plan.after === null
55
+ ? `Review the named conflict in ${file}; preserve project rules, then run guidance check --target "${target}".`
56
+ : `holmes-kit guidance refresh --target "${target}" --dry-run; review, then run without --dry-run.` }) }];
57
+ }
58
+ catch (e) {
59
+ return [{ name: 'managed AGENTS guidance', level: 'FAIL', detail: `${file}: ${String(e)}; installed package ${version}.` }];
60
+ }
61
+ }
@@ -13,9 +13,11 @@ export declare function resolvesToPackage(filePath: string, packageRoot: string)
13
13
  */
14
14
  import type { Check, Level } from './doctor-check';
15
15
  export type { Check, Level } from './doctor-check';
16
+ import type { Agent } from './agents';
16
17
  export interface DoctorOptions {
17
18
  run?: ProbeRunner;
18
19
  autoFix?: boolean;
20
+ agent?: Agent;
19
21
  }
20
22
  /**
21
23
  * Environment variables removed before spawning a probe.
@@ -53,6 +53,8 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
53
53
  exports.semanticCoverageCheck = semanticCoverageCheck;
54
54
  exports.semanticTierVerdict = semanticTierVerdict;
55
55
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
56
+ // @implements A-SPEC-704, A-SPEC-710
57
+ const doctor_guidance_1 = require("./doctor-guidance");
56
58
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
57
59
  // @implements A-SPEC-594
58
60
  // @implements A-SPEC-592
@@ -114,6 +116,7 @@ function resolvesToPackage(filePath, packageRoot) {
114
116
  return false;
115
117
  }
116
118
  }
119
+ const worktree_readiness_1 = require("./worktree-readiness");
117
120
  const GRAMMARS = [
118
121
  'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp', 'tree-sitter-java',
119
122
  'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
@@ -421,7 +424,7 @@ function resolveWiringPath(target, arg) {
421
424
  return path.isAbsolute(arg) ? arg : path.resolve(target, arg);
422
425
  }
423
426
  async function runDoctor(packageRoot, target, opts, extraChecks) {
424
- const checks = [];
427
+ const checks = (0, doctor_guidance_1.guidanceChecks)(packageRoot, target ?? process.cwd());
425
428
  const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
426
429
  // 1. Build output — also the "prepare didn't run" detector.
427
430
  const serverJs = path.join(packageRoot, 'dist', 'holmes', 'mcp', 'server.js');
@@ -1323,6 +1326,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1323
1326
  if (ci)
1324
1327
  checks.push(ci);
1325
1328
  }
1329
+ checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent }));
1326
1330
  if (extraChecks) {
1327
1331
  checks.push(...extraChecks);
1328
1332
  }
@@ -37,6 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
+ // @implements A-SPEC-704, A-SPEC-709
40
41
  // @implements A-SPEC-549.2
41
42
  // @implements A-SPEC-591, A-SPEC-626
42
43
  const cli_execution_1 = require("./cli-execution");
@@ -76,9 +77,10 @@ function packageRoot() {
76
77
  * REQ-144's "cannot decide is not permission", applied to CLI arguments.
77
78
  */
78
79
  const KNOWN_FLAGS = {
80
+ guidance: ['help', 'target', 'dry-run'],
79
81
  init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher', 'autonomy', 'no-autonomy'],
80
82
  autonomy: ['help', 'target', 'for'],
81
- doctor: ['help', 'target', 'json'],
83
+ doctor: ['help', 'target', 'json', 'agent'],
82
84
  // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
83
85
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
84
86
  skills: ['help', 'target'],
@@ -250,6 +252,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
250
252
  --readme update ONLY the region between the holmes-kit:attest markers in README.md;
251
253
  a README without the markers is never written
252
254
 
255
+ holmes-kit guidance check|refresh --target <dir> [--dry-run] inspect or update AGENTS.md only
256
+
253
257
  holmes-kit upgrade [flags] install the latest and re-pin every recorded workspace (one command)
254
258
  --dry-run show the plan (current→latest, workspaces to re-pin), change nothing
255
259
  --yes skip the confirmation prompt (required in a non-interactive shell)
@@ -296,7 +300,7 @@ async function main(argv) {
296
300
  }
297
301
  // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
298
302
  // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
299
- const expected = cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
303
+ const expected = cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
300
304
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
301
305
  : cmd === 'autonomy' ? ['status', 'on', 'off'] : [];
302
306
  const unexpected = positionals.filter((p) => !expected.includes(p));
@@ -334,6 +338,25 @@ async function main(argv) {
334
338
  process.stdout.write((0, colophon_1.colophon)());
335
339
  return 0;
336
340
  }
341
+ if (cmd === 'guidance') {
342
+ if (positionals.length !== 1 || !['check', 'refresh'].includes(positionals[0])) {
343
+ process.stderr.write('Use guidance check|refresh --target <dir> [--dry-run]\n');
344
+ return 2;
345
+ }
346
+ const { runGuidanceCommand } = await Promise.resolve().then(() => __importStar(require('./agents-guidance-command')));
347
+ const r = runGuidanceCommand({ target: path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd()), operation: positionals[0], dryRun: flags['dry-run'] === true });
348
+ process.stdout.write(`AGENTS.md: ${r.plan.state}\n${r.plan.reasons.join('\n')}\n`);
349
+ if (flags['dry-run'] && r.plan.after !== null && r.plan.after !== r.plan.before) {
350
+ process.stdout.write(`--- AGENTS.md (before)\n${r.plan.before ?? ''}\n+++ AGENTS.md (proposed)\n${r.plan.after}`);
351
+ }
352
+ if (flags['dry-run'] && r.plan.after === null && r.plan.before !== null) {
353
+ const { planGuidance } = await Promise.resolve().then(() => __importStar(require('./agents-guidance-plan')));
354
+ process.stdout.write(`--- AGENTS.md (preserved; manual review required)\n${r.plan.before}\n+++ Expected managed block (reference only; preserve project rules)\n${planGuidance(null).after ?? ''}`);
355
+ }
356
+ if (positionals[0] === 'refresh' && !flags['dry-run'] && r.exitCode === 0 && r.plan.before !== r.plan.after)
357
+ process.stdout.write('New reads use this guidance; reload instructions or restart existing agent sessions.\n');
358
+ return r.exitCode;
359
+ }
337
360
  if (cmd === 'semantic-setup' || cmd === 'semantic-check') {
338
361
  const { runModelSetup } = await Promise.resolve().then(() => __importStar(require('../semantic/local-model')));
339
362
  return runModelSetup({ offline: cmd === 'semantic-check' });
@@ -405,7 +428,12 @@ async function main(argv) {
405
428
  return 2;
406
429
  }
407
430
  }
408
- const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined);
431
+ const { AGENTS } = require('./agents');
432
+ if (flags.agent !== undefined && (typeof flags.agent !== 'string' || !AGENTS.includes(flags.agent))) {
433
+ process.stderr.write(`unknown --agent ${String(flags.agent)} (${AGENTS.join('|')})\n\n${USAGE}`);
434
+ return 2;
435
+ }
436
+ const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined, { agent: flags.agent });
409
437
  process.stdout.write(flags.json ? JSON.stringify(checks, null, 2) + '\n' : (0, doctor_1.formatChecks)(checks) + '\n');
410
438
  return checks.some((c) => c.level === 'FAIL') ? 1 : 0;
411
439
  }
@@ -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-709
39
40
  // @implements A-SPEC-340
40
41
  // @implements A-SPEC-100.2
41
42
  const fs = __importStar(require("node:fs"));
@@ -44,6 +45,8 @@ const settings_merge_1 = require("./settings-merge");
44
45
  const gitignore_merge_1 = require("./gitignore-merge");
45
46
  const settings_merge_2 = require("./settings-merge");
46
47
  const playbook_skills_1 = require("./playbook-skills");
48
+ const agents_guidance_plan_1 = require("./agents-guidance-plan");
49
+ const agents_guidance_file_1 = require("./agents-guidance-file");
47
50
  const agents_1 = require("./agents");
48
51
  const roles_readme_1 = require("./roles-readme");
49
52
  const mcp_launcher_1 = require("./mcp-launcher");
@@ -212,6 +215,18 @@ function runInit(opts) {
212
215
  const messages = [];
213
216
  const changes = [];
214
217
  const removals = [];
218
+ const guidanceFile = path.join(opts.target, 'AGENTS.md');
219
+ let guidance;
220
+ if (!opts.remove) {
221
+ try {
222
+ guidance = (0, agents_guidance_plan_1.planGuidance)((0, agents_guidance_file_1.readGuidanceFile)(guidanceFile));
223
+ }
224
+ catch (e) {
225
+ return { ok: false, exitCode: 2, changes, messages: [String(e)] };
226
+ }
227
+ if (guidance.after === null)
228
+ return { ok: false, exitCode: 2, changes, messages: guidance.reasons };
229
+ }
215
230
  const settingsPath = (0, exports.settingsPathOf)(opts.target, opts.settingsFile);
216
231
  const mcpPath = path.join(opts.target, '.mcp.json');
217
232
  const gitignorePath = path.join(opts.target, '.gitignore');
@@ -464,10 +479,13 @@ function runInit(opts) {
464
479
  // and said nothing. The merge runs in the COMPUTE phase so `--dry-run` predicts the same
465
480
  // bytes the write produces (A-SPEC-190 §9), and whatever it moves, it names.
466
481
  if (path.basename(f.path) === 'AGENTS.md') {
467
- const merged = (0, agents_1.mergeAgentsMd)(before, f.content);
468
- changes.push({ path: f.path, before, after: merged.content });
469
- if (merged.preserved.length > 0) {
470
- messages.push(`${f.path}: ${merged.note} — ${merged.preserved.join(' | ')}`);
482
+ if (!changes.some(c => c.path === f.path)) {
483
+ const planned = guidance ?? (0, agents_guidance_plan_1.planGuidance)(before);
484
+ if (planned.after === null)
485
+ return { ok: false, exitCode: 2, changes, messages: planned.reasons };
486
+ guidance = planned;
487
+ changes.push({ path: f.path, before, after: planned.after });
488
+ messages.push(...planned.reasons);
471
489
  }
472
490
  continue;
473
491
  }
@@ -522,6 +540,9 @@ function runInit(opts) {
522
540
  }
523
541
  }
524
542
  }
543
+ if (guidance && !changes.some(c => c.path === guidanceFile)) {
544
+ changes.push({ path: guidanceFile, before: guidance.before, after: guidance.after });
545
+ }
525
546
  if (!opts.dryRun) {
526
547
  // @implements A-SPEC-190 §17/§18 (round 13) — a write we refuse to make (unreadable original)
527
548
  // or cannot finish (rename failure) is a REFUSAL with a next action, not a raw Node stack. The
@@ -530,7 +551,13 @@ function runInit(opts) {
530
551
  if (c.after === null)
531
552
  continue;
532
553
  try {
533
- writeFileSafe(c.path, c.after);
554
+ if (c.path === guidanceFile && guidance) {
555
+ const applied = (0, agents_guidance_file_1.applyGuidancePlan)(c.path, guidance);
556
+ if (!applied.ok)
557
+ throw new Error(applied.reason);
558
+ }
559
+ else
560
+ writeFileSafe(c.path, c.after);
534
561
  }
535
562
  catch (e) {
536
563
  return { ok: false, exitCode: 2, changes, messages: [
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runUpgrade = runUpgrade;
37
+ // @implements A-SPEC-709
37
38
  // @implements A-SPEC-543.2
38
39
  const fs = __importStar(require("node:fs"));
39
40
  const os = __importStar(require("node:os"));
@@ -133,8 +134,18 @@ async function runUpgrade(io) {
133
134
  }
134
135
  catch { /* cache clear is best-effort */ }
135
136
  // (3) re-pin every registered workspace that still exists.
136
- const { runInit } = require('./init');
137
- const newRoot = packageRoot(); // may differ after a global install; re-resolve
137
+ // Load the newly installed package in a fresh process: the caller already cached old init.
138
+ let newCli;
139
+ try {
140
+ const modulesRoot = (0, node_child_process_1.execFileSync)(npmBin(), ['root', ...(plan.installMode === 'global-npx' ? ['-g'] : [])], { cwd: process.cwd(), encoding: 'utf8' }).trim();
141
+ newCli = path.join(modulesRoot, PKG, 'bin', 'holmes-kit.js');
142
+ if (!fs.statSync(newCli).isFile())
143
+ throw new Error('new CLI is not a file');
144
+ }
145
+ catch (e) {
146
+ io.stderr(`Installed package CLI could not be resolved; no workspace re-pinned: ${String(e)}\n`);
147
+ return 1;
148
+ }
138
149
  let repinned = 0, skipped = 0, failed = 0;
139
150
  io.stdout('\nRe-pinning workspaces:\n');
140
151
  for (const w of registry.workspaces) {
@@ -144,34 +155,20 @@ async function runUpgrade(io) {
144
155
  continue;
145
156
  }
146
157
  try {
147
- const res = runInit({
148
- target: w.target,
149
- packageRoot: newRoot,
150
- mode: 'guardrail',
151
- specsDir: '.ax/specs',
152
- settingsFile: 'local',
153
- mcp: true,
154
- dryRun: false,
155
- force: true,
156
- remove: false,
157
- agents: w.agents,
158
- allowAdditive: true,
159
- });
160
- if (res.ok) {
161
- io.stdout(` re-pinned: ${w.target}\n`);
162
- repinned++;
163
- }
164
- else {
165
- io.stdout(` failed: ${w.target}\n`);
166
- failed++;
167
- }
158
+ const agents = w.agents.length ? w.agents.join(',') : 'claude';
159
+ const output = (0, node_child_process_1.execFileSync)(process.execPath, [newCli, 'init', '--target', w.target,
160
+ '--agent', agents, '--mode', 'guardrail', '--mcp-launcher', 'npx'], { cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
161
+ io.stdout(output);
162
+ io.stdout(` re-pinned: ${w.target}\n`);
163
+ repinned++;
168
164
  }
169
- catch {
170
- io.stdout(` failed: ${w.target}\n`);
165
+ catch (e) {
166
+ const failure = e;
167
+ io.stdout(` failed: ${w.target}: ${String(failure.stderr ?? failure.message ?? e)}\n`);
171
168
  failed++;
172
169
  }
173
170
  }
174
171
  io.stdout(`\nUpgraded to ${plan.latest}. re-pinned ${repinned} · skipped ${skipped} · failed ${failed}. A new session's hooks/MCP will read the new wiring.\n`);
175
172
  io.stdout(`(You can re-wire any individual workspace at any time with ${(0, npx_bin_1.npxBin)()} holmes-kit init --agent <…> --force.)\n`);
176
- return 0;
173
+ return failed > 0 ? 1 : 0;
177
174
  }
@@ -0,0 +1,6 @@
1
+ import type { Agent } from './agents';
2
+ import type { Check } from './doctor-check';
3
+ /** Disk preparation evidence for one selected harness. It never observes a client's loaded config. */
4
+ export declare function worktreeReadinessChecks(packageRoot: string, target: string, opts?: {
5
+ agent?: Agent;
6
+ }): Check[];
@@ -0,0 +1,81 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.worktreeReadinessChecks = worktreeReadinessChecks;
37
+ // @implements A-SPEC-704
38
+ const fs = __importStar(require("node:fs"));
39
+ const path = __importStar(require("node:path"));
40
+ const workspace_checkout_1 = require("../project/workspace-checkout");
41
+ const workspace_identity_1 = require("../project/workspace-identity");
42
+ const WIRING = {
43
+ claude: ['.mcp.json'],
44
+ codex: ['.codex/config.toml', '.claude-plugin/marketplace.json'],
45
+ antigravity: ['.agents/mcp_config.json', '.agents/hooks.json'],
46
+ };
47
+ /** Disk preparation evidence for one selected harness. It never observes a client's loaded config. */
48
+ function worktreeReadinessChecks(packageRoot, target, opts = {}) {
49
+ const agent = opts.agent;
50
+ if (!agent)
51
+ return [];
52
+ const checkout = (0, workspace_checkout_1.inspectWorkspaceCheckout)(target);
53
+ let identity = 'unavailable';
54
+ let identityWarning = false;
55
+ try {
56
+ const status = (0, workspace_identity_1.workspaceIdentity)(target, 'status');
57
+ identity = status.state;
58
+ identityWarning = status.state === 'initialized';
59
+ }
60
+ catch (e) {
61
+ identityWarning = true;
62
+ identity = `unavailable (${e instanceof Error ? e.message : String(e)})`;
63
+ }
64
+ const files = WIRING[agent];
65
+ const missing = files.filter((file) => !fs.existsSync(path.join(target, file)));
66
+ const build = fs.existsSync(path.join(packageRoot, 'dist', 'holmes', 'mcp', 'server.js'));
67
+ const level = missing.length || identityWarning || checkout.kind === 'unknown' || !build ? 'WARN' : 'PASS';
68
+ const repair = `Run holmes-kit init --target ${target} --agent ${agent}, then restart that harness session.`;
69
+ const detail = [
70
+ `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(', ')}.`,
72
+ build ? 'package build is present.' : 'package build is absent.',
73
+ 'This does not prove whether a current client loaded hooks or MCP configuration.',
74
+ ].join(' ');
75
+ return [
76
+ { name: `${agent} worktree readiness`, level, detail, fix: level === 'PASS' ? undefined : repair },
77
+ { name: `${agent} live session enforcement`, level: 'WARN',
78
+ detail: 'unknown: disk preparation and a doctor-spawned MCP probe are separate-process evidence, not proof of this client session.',
79
+ fix: 'Restart the selected harness in this workspace and run workspace_preflight from that live session.' },
80
+ ];
81
+ }
@@ -0,0 +1,9 @@
1
+ import { Agent } from '../../cli/agents';
2
+ export declare function createWorkspacePreflightHandlers(context: {
3
+ storeRoot?: string;
4
+ }): {
5
+ workspace_preflight(a: {
6
+ root: string;
7
+ harness?: Agent;
8
+ }): Promise<import("../../project/workspace-preflight").WorkspacePreflight>;
9
+ };
@@ -0,0 +1,13 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createWorkspacePreflightHandlers = createWorkspacePreflightHandlers;
4
+ // @implements A-SPEC-703
5
+ const agents_1 = require("../../cli/agents");
6
+ const workspace_preflight_1 = require("../../project/workspace-preflight");
7
+ function createWorkspacePreflightHandlers(context) {
8
+ return { async workspace_preflight(a) {
9
+ if (a?.harness !== undefined && !agents_1.AGENTS.includes(a.harness))
10
+ throw new Error('Unsupported harness.');
11
+ return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot });
12
+ } };
13
+ }
@@ -349,52 +349,6 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
349
349
  code: string;
350
350
  reason: string;
351
351
  }>;
352
- ledger_reconcile: (a: {
353
- root?: string;
354
- nonce: string;
355
- rationale?: string;
356
- }) => Promise<{
357
- ok: boolean;
358
- reason: string;
359
- reconciled?: undefined;
360
- nonce?: undefined;
361
- pending?: undefined;
362
- code?: undefined;
363
- events?: undefined;
364
- remaining?: undefined;
365
- } | {
366
- ok: boolean;
367
- reconciled: boolean;
368
- nonce: string;
369
- pending: string[];
370
- reason: string;
371
- code?: undefined;
372
- events?: undefined;
373
- remaining?: undefined;
374
- } | {
375
- ok: boolean;
376
- code: string;
377
- reason: string;
378
- reconciled?: undefined;
379
- nonce?: undefined;
380
- pending?: undefined;
381
- events?: undefined;
382
- remaining?: undefined;
383
- } | {
384
- ok: boolean;
385
- reconciled: boolean;
386
- nonce: string;
387
- events: {
388
- replicaId: string | null;
389
- seq: number;
390
- hash: string;
391
- ts: string;
392
- }[];
393
- remaining: string[];
394
- reason?: undefined;
395
- pending?: undefined;
396
- code?: undefined;
397
- }>;
398
352
  spec_reconcile: (a: {
399
353
  root?: string;
400
354
  operation?: string;
@@ -633,6 +587,56 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
633
587
  reason: string;
634
588
  }[];
635
589
  }>;
590
+ workspace_preflight(a: {
591
+ root: string;
592
+ harness?: import("../cli/agents").Agent;
593
+ }): Promise<import("../project/workspace-preflight").WorkspacePreflight>;
594
+ ledger_reconcile: (a: {
595
+ root?: string;
596
+ nonce: string;
597
+ rationale?: string;
598
+ }) => Promise<{
599
+ ok: boolean;
600
+ reason: string;
601
+ reconciled?: undefined;
602
+ nonce?: undefined;
603
+ pending?: undefined;
604
+ code?: undefined;
605
+ events?: undefined;
606
+ remaining?: undefined;
607
+ } | {
608
+ ok: boolean;
609
+ reconciled: boolean;
610
+ nonce: string;
611
+ pending: string[];
612
+ reason: string;
613
+ code?: undefined;
614
+ events?: undefined;
615
+ remaining?: undefined;
616
+ } | {
617
+ ok: boolean;
618
+ code: string;
619
+ reason: string;
620
+ reconciled?: undefined;
621
+ nonce?: undefined;
622
+ pending?: undefined;
623
+ events?: undefined;
624
+ remaining?: undefined;
625
+ } | {
626
+ ok: boolean;
627
+ reconciled: boolean;
628
+ nonce: string;
629
+ events: {
630
+ replicaId: string | null;
631
+ seq: number;
632
+ hash: string;
633
+ ts: string;
634
+ }[];
635
+ remaining: string[];
636
+ reason?: undefined;
637
+ pending?: undefined;
638
+ code?: undefined;
639
+ }>;
636
640
  maintenance_outcome(a: {
637
641
  root: string;
638
642
  digest: string;
@@ -38,7 +38,7 @@ exports.isHandlerRefusal = isHandlerRefusal;
38
38
  exports.unreadableAmong = unreadableAmong;
39
39
  exports.makeHandlers = makeHandlers;
40
40
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627
41
+ // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627
42
42
  // @implements A-SPEC-643
43
43
  // @implements A-SPEC-642
44
44
  // @implements A-SPEC-642
@@ -68,6 +68,7 @@ const spec_authoring_1 = require("./handlers/spec-authoring");
68
68
  const spec_lifecycle_1 = require("./handlers/spec-lifecycle");
69
69
  const spec_approval_1 = require("./handlers/spec-approval");
70
70
  const workspace_identity_2 = require("./handlers/workspace-identity");
71
+ const workspace_preflight_1 = require("./handlers/workspace-preflight");
71
72
  const operator_inspection_1 = require("./handlers/operator-inspection");
72
73
  const phase_queries_1 = require("./handlers/phase-queries");
73
74
  const risk_assessment_1 = require("./handlers/risk-assessment");
@@ -533,7 +534,8 @@ function makeHandlers(store, opts) {
533
534
  const wrapped = {};
534
535
  const run = (0, execution_context_1.createExecutionScope)(store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : undefined, opts?.observeInvocation);
535
536
  for (const [name, fn] of Object.entries(raw)) {
536
- const scoped = name === 'workspace_identity' ? fn : async (a) => {
537
+ const diagnostic = name === 'workspace_preflight';
538
+ const scoped = name === 'workspace_identity' || diagnostic ? fn : async (a) => {
537
539
  try {
538
540
  return await run(a?.root, () => fn(a));
539
541
  }
@@ -545,7 +547,7 @@ function makeHandlers(store, opts) {
545
547
  throw e;
546
548
  }
547
549
  };
548
- wrapped[name] = (0, basis_1.withBasis)(scoped, (a) => basisFor(a?.root));
550
+ wrapped[name] = (0, basis_1.withBasis)(scoped, (a) => basisFor(diagnostic ? undefined : a?.root));
549
551
  }
550
552
  wrapped.basis_detail = async (a) => {
551
553
  const b = basisFor(a?.root, true);
@@ -930,6 +932,7 @@ function makeRawHandlers(store, opts) {
930
932
  // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
931
933
  // rtm_impact+4, rtm_reindex..review_record, review_prepare..risk_check, risk_check±, and the tail).
932
934
  ledger_reconcile: operatorInspection.ledger_reconcile,
935
+ ...(0, workspace_preflight_1.createWorkspacePreflightHandlers)({ storeRoot: store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : undefined }),
933
936
  // @implements A-SPEC-700.2 — same unpinned slot: `spec_retire..spec_unseal` is a pinned run.
934
937
  spec_reconcile: specLifecycle.spec_reconcile,
935
938
  rtm_impact: graphOperations.rtm_impact,
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627
4
+ // @implements A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627
5
5
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
6
6
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
7
7
  // @implements A-SPEC-642
@@ -11,6 +11,7 @@ exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
11
11
  // @implements A-SPEC-269
12
12
  // @implements A-SPEC-267
13
13
  const spec_types_1 = require("../spec/spec-types");
14
+ const agents_1 = require("../cli/agents");
14
15
  const phase_1 = require("../guardrail/phase");
15
16
  const str = (description) => ({ type: 'string', description });
16
17
  const num = (description) => ({ type: 'number', description });
@@ -51,6 +52,10 @@ exports.TOOL_SCHEMAS = {
51
52
  description: 'Inspect or plan entity adoption without writes by default. Explicit adopt requires config-write approval for the exact returned plan and preserves sealed document bytes. Adopted stores retain entity identity through journaled document creation, edits and classification moves. recovery-plan reports interrupted targets without changing them. recover requires separate exact-plan approval to complete interrupted transactions or release locks for verified completed writes. Sealing, unsealing and retirement additionally require current spec-approve authority for the affected ID and the same transition policy as official spec tools. Live or unknown owners, external changes and noncanonical transitions refuse. Recovery audit completion across crashes remains under development.',
52
53
  inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['status', 'plan-adoption', 'adopt', 'recovery-plan', 'recover'] }, plan: { type: 'object', description: 'The complete unmodified plan returned by plan-adoption or recovery-plan.' } } },
53
54
  },
55
+ workspace_preflight: {
56
+ description: 'Read-only diagnosis of this live MCP server workspace binding. Mismatched roots are not scanned. Identity and checkout are inspected only for a matching root. Does not rebind, initialize, register or prove client hook enforcement.',
57
+ inputSchema: { type: 'object', properties: { root: ROOT_ANY, harness: { type: 'string', enum: [...agents_1.AGENTS] } }, required: ['root'] },
58
+ },
54
59
  workspace_identity: {
55
60
  description: 'Inspect canonical workspace and local replica identity without writes by default. Explicit initialize creates a Git-shareable .ax/workspace.json and registers this checkout; register requires an existing canonical identity. Preserve legacy specs and ledgers; these identifiers grant no approval authority. Share the manifest through Git and keep .ax/state local. Registered MCP writes include holmes-execution/1 provenance and require a reader supporting that schema; matching package versions alone do not establish this capability.',
56
61
  inputSchema: {
@@ -0,0 +1,8 @@
1
+ export type CheckoutInfo = {
2
+ kind: 'main' | 'worktree' | 'submodule' | 'non-git' | 'unknown';
3
+ root: string;
4
+ gitTopLevel: string | null;
5
+ branch: string | null;
6
+ detached: boolean | null;
7
+ };
8
+ export declare function inspectWorkspaceCheckout(root: string): CheckoutInfo;