@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,74 @@
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.inspectWorkspaceCheckout = inspectWorkspaceCheckout;
37
+ // @implements A-SPEC-703
38
+ const path = __importStar(require("node:path"));
39
+ const node_child_process_1 = require("node:child_process");
40
+ const root_1 = require("./root");
41
+ function inspectWorkspaceCheckout(root) {
42
+ const result = { kind: 'unknown', root, gitTopLevel: null, branch: null, detached: null };
43
+ const env = (0, root_1.cleanSubprocessEnv)();
44
+ // A caller's Git overrides must not redirect inspection to another checkout.
45
+ for (const key of Object.keys(env))
46
+ if (key.startsWith('GIT_'))
47
+ delete env[key];
48
+ const git = (...args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], {
49
+ encoding: 'utf8', timeout: 5000, maxBuffer: 1024 * 1024, env,
50
+ stdio: ['ignore', 'pipe', 'pipe'],
51
+ }).trim();
52
+ try {
53
+ result.gitTopLevel = (0, root_1.canonicalPath)(git('rev-parse', '--show-toplevel'));
54
+ const gitDir = (0, root_1.canonicalPath)(git('rev-parse', '--absolute-git-dir'));
55
+ const common = (0, root_1.canonicalPath)(path.resolve(root, git('rev-parse', '--git-common-dir')));
56
+ const superproject = git('rev-parse', '--show-superproject-working-tree');
57
+ result.kind = superproject ? 'submodule' : gitDir !== common ? 'worktree' : 'main';
58
+ try {
59
+ result.branch = git('symbolic-ref', '--quiet', '--short', 'HEAD');
60
+ result.detached = false;
61
+ }
62
+ catch (e) {
63
+ if (e.status === 1)
64
+ result.detached = true;
65
+ else
66
+ throw e;
67
+ }
68
+ }
69
+ catch (e) {
70
+ const err = e;
71
+ result.kind = err.status === 128 && String(err.stderr).includes('not a git repository') ? 'non-git' : 'unknown';
72
+ }
73
+ return result;
74
+ }
@@ -0,0 +1,24 @@
1
+ import { WorkspaceIdentityStatus } from './workspace-identity';
2
+ import { CheckoutInfo } from './workspace-checkout';
3
+ export type { CheckoutInfo } from './workspace-checkout';
4
+ export type PreflightCheck = {
5
+ id: string;
6
+ status: 'pass' | 'blocked' | 'unknown';
7
+ detail: string;
8
+ actions: string[];
9
+ };
10
+ export type WorkspacePreflight = {
11
+ schema: 'holmes-workspace-preflight/1';
12
+ requestedRoot: string | null;
13
+ boundRoot: string | null;
14
+ boundSpecsRoot: string | null;
15
+ binding: 'matched' | 'mismatch' | 'unbound' | 'invalid';
16
+ identity: WorkspaceIdentityStatus | null;
17
+ checkout: CheckoutInfo | null;
18
+ checks: PreflightCheck[];
19
+ nextActions: string[];
20
+ };
21
+ export declare function inspectWorkspacePreflight(input: {
22
+ requestedRoot: string;
23
+ storeRoot?: string;
24
+ }): WorkspacePreflight;
@@ -0,0 +1,99 @@
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.inspectWorkspacePreflight = inspectWorkspacePreflight;
37
+ // @implements A-SPEC-703
38
+ const fs = __importStar(require("node:fs"));
39
+ const path = __importStar(require("node:path"));
40
+ const root_1 = require("./root");
41
+ const workspace_identity_1 = require("./workspace-identity");
42
+ const workspace_checkout_1 = require("./workspace-checkout");
43
+ function inspectWorkspacePreflight(input) {
44
+ const out = { schema: 'holmes-workspace-preflight/1', requestedRoot: null,
45
+ boundRoot: null, boundSpecsRoot: null, binding: 'invalid', identity: null, checkout: null, checks: [], nextActions: [] };
46
+ const check = (id, status, detail, actions = []) => {
47
+ out.checks.push({ id, status, detail, actions });
48
+ out.nextActions.push(...actions);
49
+ };
50
+ try {
51
+ if (typeof input.requestedRoot !== 'string' || !path.isAbsolute(input.requestedRoot)) {
52
+ check('root', 'blocked', 'An absolute existing workspace directory is required.');
53
+ return out;
54
+ }
55
+ out.requestedRoot = (0, root_1.resolveProjectRoot)(input.requestedRoot, { includeGit: false }).root;
56
+ if (!input.storeRoot) {
57
+ out.binding = 'unbound';
58
+ check('binding', 'unknown', 'The server has no file-backed spec store.');
59
+ return out;
60
+ }
61
+ let existing = path.resolve(input.storeRoot);
62
+ while (!fs.existsSync(existing) && path.dirname(existing) !== existing)
63
+ existing = path.dirname(existing);
64
+ out.boundSpecsRoot = path.join((0, root_1.canonicalPath)(existing), path.relative(existing, path.resolve(input.storeRoot)));
65
+ out.boundRoot = (0, root_1.resolveProjectRoot)(existing, { includeGit: false }).root;
66
+ if (out.requestedRoot !== out.boundRoot) {
67
+ out.binding = 'mismatch';
68
+ check('binding', 'blocked', 'Requested workspace differs from the live server store.', ['Restart the MCP server with HOLMES_SPECS pointing to the intended workspace, then rerun workspace_preflight.']);
69
+ return out;
70
+ }
71
+ // Only after binding matches may we inspect checkout metadata or identity.
72
+ const requestedCheckout = (0, workspace_checkout_1.inspectWorkspaceCheckout)((0, root_1.canonicalPath)(input.requestedRoot));
73
+ if (requestedCheckout.gitTopLevel && requestedCheckout.gitTopLevel !== out.boundRoot) {
74
+ check('workspace-marker', 'blocked', 'The requested checkout inherits a different workspace marker.', ['Prepare the intended checkout explicitly; do not copy local replica state.']);
75
+ return out;
76
+ }
77
+ out.identity = (0, workspace_identity_1.workspaceIdentity)(out.boundRoot, 'status');
78
+ out.checkout = (0, workspace_checkout_1.inspectWorkspaceCheckout)(out.boundRoot);
79
+ out.binding = 'matched';
80
+ check('binding', 'pass', 'Requested workspace matches the live server store.');
81
+ if (out.identity.state === 'initialized')
82
+ check('identity', 'blocked', 'Canonical identity exists but this replica is unregistered.', ['Use workspace_identity operation register for this checkout before governed writes.']);
83
+ else
84
+ check('identity', 'pass', `Workspace identity is ${out.identity.state}.`);
85
+ check('checkout', out.checkout.kind === 'unknown' ? 'unknown' : 'pass', `Checkout kind: ${out.checkout.kind}.`);
86
+ check('runtime-enforcement', 'unknown', 'Binding and disk inspection do not prove current client hook enforcement.');
87
+ return out;
88
+ }
89
+ catch (e) {
90
+ const error = e;
91
+ if (!(e instanceof workspace_identity_1.WorkspaceIdentityError) && !error.holmesRefusal && !['ENOENT', 'EACCES', 'EPERM', 'ENOTDIR'].includes(error.code ?? ''))
92
+ throw e;
93
+ out.binding = 'invalid';
94
+ out.identity = null;
95
+ out.checkout = null;
96
+ check('inspection', 'blocked', error.message, ['Preserve existing records and repair the reported path or identity explicitly.']);
97
+ return out;
98
+ }
99
+ }
@@ -164,6 +164,7 @@ from the registry or from a packed tarball.
164
164
  ```
165
165
  npx holmes-kit doctor # local install
166
166
  holmes-kit doctor # global install
167
+ holmes-kit doctor --target . --agent claude # selected-harness preparation
167
168
  ```
168
169
 
169
170
  Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured `12 pass, 4 warn,
@@ -175,6 +176,19 @@ Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured
175
176
  (`scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error) and the fix
176
177
  is the exact command for your install layout
177
178
 
179
+ For a worktree or resumed project, choose one harness explicitly: `--agent claude`,
180
+ `--agent codex`, or `--agent antigravity`. The resulting readiness lines inspect only
181
+ local checkout, identity, build and wiring evidence. A missing file means preparation
182
+ is incomplete; it does not prove a running client did or did not load a hook. The
183
+ separate `mcp wiring spawn` result is also a probe process, not the current conversation's
184
+ MCP binding. Restart the selected harness in the target workspace, then use its live
185
+ `workspace_preflight` result to verify binding.
186
+
187
+ When Superpowers is available, `holmes-superpowers-compat` is installed with the Holmes
188
+ playbook skills. It is optional guidance: it maps design, worktree, TDD, review, and finish
189
+ stages to the existing Holmes approval and evidence gates, without installing Superpowers or
190
+ claiming that a local configuration proves a live session loaded it.
191
+
178
192
  ## What we deliberately do NOT do
179
193
 
180
194
  | Idea | Why not |
@@ -266,3 +280,43 @@ implementation, but this Windows session did not execute platform-native tests t
266
280
  The optional cloud credential file uses a protected current-user-only NTFS DACL on Windows.
267
281
  Permission setup is verified before a new key is written; failure preserves the prior key and
268
282
  refuses the new value. The macOS keychain and POSIX 0700/0600 fallback remain available.
283
+ # Keeping AGENTS.md guidance current
284
+
285
+ Holmes-Kit generates common operating rules inside `holmes-kit:managed:begin/end`
286
+ markers. Keep project-specific rules outside that block. The development repository
287
+ uses the same renderer as installed packages; consumer checks compare against the
288
+ package executing the command, not unreleased upstream prose.
289
+
290
+ ```sh
291
+ holmes-kit guidance check --target .
292
+ holmes-kit guidance refresh --target . --dry-run
293
+ holmes-kit guidance refresh --target .
294
+ ```
295
+
296
+ `check` never writes: exit 0 means current, 1 means missing or recognized outdated
297
+ guidance, and 2 means a conflict or read failure. `refresh` only changes AGENTS.md;
298
+ dry-run prints the before/proposed contents and writes nothing. Successful refresh
299
+ returns 0, refusal returns 2. The target directory must already exist.
300
+
301
+ Known historical generated sections can migrate automatically. Unknown edits,
302
+ malformed markers, and obsolete prohibitions outside the block require review;
303
+ neither `--force` on init nor upgrade overrides a guidance conflict. Preserve local
304
+ instructions, inspect the installed template, and resolve the conflicting sections
305
+ before retrying. `doctor` reports these states with the installed package version.
306
+ It does not rewrite the file or prove that hooks are running.
307
+
308
+ Updating a file does not replace instructions already loaded by an agent. Reload
309
+ instructions or start a new session. Common guidance is the same for Claude Code,
310
+ Codex CLI, and Antigravity; actual enforcement requires evidence from that session.
311
+
312
+ For maintainers, a common-text change requires a new guidance revision and an
313
+ immutable baseline in `agents-guidance-history.ts`; preserve previous baselines.
314
+ The root consistency check refuses a renderer change without that registration.
315
+ Then refresh the development AGENTS.md with the same command used by consumers.
316
+
317
+ Publication compares the original bytes again before renaming a temporary file.
318
+ This detects observed concurrent changes but is not an atomic compare-and-swap
319
+ against an unrelated writer racing the final rename. Serialize edits to AGENTS.md
320
+ during refresh. On ownership conflicts, dry-run shows the preserved original and
321
+ the expected block as a reference for manual review; it does not guess which custom
322
+ instructions should be removed or present that reference as an approved replacement.
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.27.0",
4
+ "version": "0.28.0",
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",
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: holmes-superpowers-compat
3
+ description: Use when Superpowers design, worktree, TDD, review, subagent, verification, or finishing workflows operate in a Holmes-Kit governed project, including a "Preceding REQ not found." refusal.
4
+ ---
5
+
6
+ # Superpowers workflow under Holmes governance
7
+
8
+ Superpowers organizes work; Holmes authorizes governed source changes and records evidence. A Superpowers task, plan approval, passing command, reviewer parking, or branch finish does not replace an approved Holmes slice or its execution evidence.
9
+
10
+ ## Start, resume, or change checkout
11
+
12
+ 1. In the actual client session call `workspace_preflight` for the intended root. If it reports `mismatch`, stop: restart/reconnect MCP with that workspace's spec store, then call it again. Never author specs through a main-bound server for another checkout.
13
+ 2. Run `holmes-kit doctor --target <root> --agent claude|codex|antigravity`. This observes local preparation only. A missing file is not proof that a live hook is absent; a doctor-spawned MCP is not this session's MCP.
14
+ 3. Read `workspace_identity`. Legacy stays supported. For initialized-but-unregistered replicas, register only through the official workflow; do not copy `.ax/state`. A child checkout inheriting a parent marker is blocked until its binding is explicit.
15
+
16
+ ## Governed implementation sequence
17
+
18
+ | Superpowers stage | Holmes requirement before proceeding |
19
+ |---|---|
20
+ | `brainstorming`, `writing-plans` | Design/plan are evidence, then scaffold and approve REQ → H-SPEC → A-SPEC for the actual slice. Bounded chat approval alone does not permit source edits. |
21
+ | `using-git-worktrees`, restart | Repeat live binding and selected-harness preparation in the new session. Worktree placement is the user's decision. |
22
+ | `test-driven-development`, `tdd-slice` | Persist `maintenance_analyze`, place first-line anchors, write a real assertion test, observe `red-assertion` with `test_run`, then approve the matching T-SPEC. `red-error` is setup failure, not RED. |
23
+ | implementation | Change only approved files, then use `test_run` for GREEN. Do not make an unapproved stub just to compile a test. |
24
+ | `systematic-debugging`, `diagnosing-superpowers` | Preserve the refusal, runtime and tool transcript. Use Holmes remediation for a gate refusal; do not inspect or bypass guardrails. |
25
+ | `dispatching-parallel-agents`, `subagent-driven-development` | Give each child its root, bound store, slice, edit ownership, persisted-analysis digest, test command and refusal procedure. Each child verifies its own binding. Serialize implementation/evidence in one checkout. |
26
+ | `requesting-code-review`, `receiving-code-review` | Record material findings with `review_record`; a parked critical remains open. Confirm `review_status` after a real resolution. |
27
+ | `verification-before-completion`, `finishing-a-development-branch` | Run required evidence for final code, perform store-appropriate reconciliation, confirm approval/review status, then make the authorized integration or cleanup decision. Preserve evidence before deleting a worktree or helper artifact. |
28
+
29
+ ## Boundaries that must stay visible
30
+
31
+ - `using-superpowers`, `executing-plans`, `writing-skills`, and visual/helper artifacts remain their own workflow artifacts. Do not copy task-start/task-done or review-package state into the Holmes ledger.
32
+ - `verification-before-completion` is necessary evidence, but it does not seal specs or resolve a critical finding.
33
+ - Claude, Codex, and Antigravity use the same governance sequence. Disk wiring, AGY links, and Codex discovery are preparation observations; only an actual session transcript proves active loading or hook inheritance.
34
+ - External diagnosis uploads, browser/visual artifacts, paid sessions, merge, push, publish, and discard retain their existing user-authorization boundaries.
35
+
36
+ ## Stop conditions and next action
37
+
38
+ | Observation | Next action |
39
+ |---|---|
40
+ | main-bound MCP, requested worktree | reconnect/restart for the requested root and rerun preflight |
41
+ | import or collection failure | diagnose until an assertion RED exists; do not call it valid RED |
42
+ | two writers in one checkout | serialize evidence or use separately bound checkouts |
43
+ | parked critical | keep it open and resolve/review it under the approved slice |
44
+ | Superpowers task says done | obtain Holmes review, reconciliation, final evidence, then an authorized finish decision |
45
+
46
+ This playbook is advisory guidance. It does not prove agent compliance or active enforcement; inspect the live session and official Holmes evidence.