@holmes-lab/holmes-kit 0.27.0 → 0.29.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 (62) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +21 -17
  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 +29 -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/cpg/ast-mutation.d.ts +2 -0
  26. package/dist/holmes/cpg/ast-mutation.js +4 -2
  27. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  28. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  29. package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
  30. package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
  31. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
  32. package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
  33. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  34. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  35. package/dist/holmes/mcp/handlers.d.ts +157 -46
  36. package/dist/holmes/mcp/handlers.js +16 -3
  37. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
  38. package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
  39. package/dist/holmes/mcp/tool-schemas.js +19 -1
  40. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  41. package/dist/holmes/project/workspace-checkout.js +74 -0
  42. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  43. package/dist/holmes/project/workspace-preflight.js +99 -0
  44. package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
  45. package/dist/holmes/review/condition-hunk-replay.js +112 -0
  46. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  47. package/dist/holmes/review/condition-hunk-resolution.js +207 -0
  48. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  49. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  50. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  51. package/dist/holmes/review/requirement-triage.js +143 -0
  52. package/dist/holmes/semantic/local-model.d.ts +3 -3
  53. package/dist/holmes/semantic/local-model.js +10 -12
  54. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  55. package/dist/holmes/semantic/model-cache.js +77 -21
  56. package/dist/holmes/semantic/tier.d.ts +5 -1
  57. package/dist/holmes/semantic/tier.js +7 -6
  58. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  59. package/dist/holmes/semantic/vector-coverage.js +37 -0
  60. package/docs/install-guide.md +73 -24
  61. package/package.json +1 -1
  62. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
@@ -33,35 +33,91 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.LOCAL_REVISION = exports.LOCAL_MODEL = void 0;
36
37
  exports.modelCacheDir = modelCacheDir;
38
+ exports.modelCacheFingerprint = modelCacheFingerprint;
39
+ exports.readLocalModelReadiness = readLocalModelReadiness;
40
+ exports.writeVerifiedModelReceipt = writeVerifiedModelReceipt;
37
41
  exports.modelCacheReady = modelCacheReady;
38
- // @implements A-SPEC-594
39
- /**
40
- * Where the local model's assets live, and whether they are actually there.
41
- *
42
- * A leaf on purpose: `tier.ts` must consult readiness, and `local-model.ts` already imports
43
- * `tier.ts`, so putting this in either one closes an import cycle. Nothing here imports
44
- * anything of ours.
45
- */
42
+ // @implements A-SPEC-594, A-SPEC-712
43
+ /** Shared local-model cache and its lightweight verified-readiness receipt. */
44
+ const crypto = __importStar(require("node:crypto"));
45
+ const fs = __importStar(require("node:fs"));
46
46
  const os = __importStar(require("node:os"));
47
47
  const path = __importStar(require("node:path"));
48
- const fs = __importStar(require("node:fs"));
48
+ exports.LOCAL_MODEL = 'Xenova/bge-m3';
49
+ exports.LOCAL_REVISION = '4de13258303883538bd53b696b452bf8099f0858';
50
+ const RECEIPT_FILE = '.holmes-bge-m3-readiness.json';
51
+ const RECEIPT_SCHEMA = 'holmes-local-model-readiness/1';
49
52
  function modelCacheDir(env = process.env, home = os.homedir()) {
50
53
  return path.resolve(env.HOLMES_MODEL_CACHE || path.join(home, '.holmes', 'models'));
51
54
  }
52
- /**
53
- * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
54
- * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
55
- * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
56
- * doctor calls this on every run and must stay cheap and offline.
57
- */
58
- function modelCacheReady(cacheDir = modelCacheDir()) {
59
- if (cacheDir === '')
60
- return false;
55
+ function assetEntries(cacheDir) {
56
+ try {
57
+ const rows = [];
58
+ const visit = (dir, prefix) => {
59
+ for (const name of fs.readdirSync(dir).sort()) {
60
+ if (prefix === '' && name === RECEIPT_FILE)
61
+ continue;
62
+ const absolute = path.join(dir, name), relative = prefix ? `${prefix}/${name}` : name, stat = fs.statSync(absolute);
63
+ if (stat.isDirectory())
64
+ visit(absolute, relative);
65
+ else if (stat.isFile())
66
+ rows.push(`${relative}:${stat.size}:${Math.floor(stat.mtimeMs)}`);
67
+ }
68
+ };
69
+ visit(cacheDir, '');
70
+ return rows;
71
+ }
72
+ catch {
73
+ return null;
74
+ }
75
+ }
76
+ /** A metadata fingerprint cheap enough for offline tier resolution. */
77
+ function modelCacheFingerprint(cacheDir = modelCacheDir()) {
78
+ const entries = assetEntries(cacheDir);
79
+ return entries === null || entries.length === 0 ? null
80
+ : `sha256:${crypto.createHash('sha256').update(entries.join('\n')).digest('hex')}`;
81
+ }
82
+ const receiptPath = (cacheDir) => path.join(cacheDir, RECEIPT_FILE);
83
+ /** Missing or malformed proof is never promoted to readiness. */
84
+ function readLocalModelReadiness(cacheDir = modelCacheDir()) {
85
+ const fingerprint = modelCacheFingerprint(cacheDir);
86
+ if (fingerprint === null)
87
+ return { ready: false, state: 'missing-cache', recovery: 'Run holmes-kit semantic-setup to download and verify BGE-M3.' };
88
+ let receipt;
89
+ try {
90
+ receipt = JSON.parse(fs.readFileSync(receiptPath(cacheDir), 'utf8'));
91
+ }
92
+ catch {
93
+ return { ready: false, state: 'unverified-cache', recovery: 'Run holmes-kit semantic-setup to verify the existing BGE-M3 cache offline.' };
94
+ }
95
+ if (receipt.schema !== RECEIPT_SCHEMA || receipt.model !== exports.LOCAL_MODEL || receipt.revision !== exports.LOCAL_REVISION || typeof receipt.fingerprint !== 'string') {
96
+ return { ready: false, state: 'invalid-receipt', recovery: 'Run holmes-kit semantic-setup to replace the invalid BGE-M3 readiness receipt.' };
97
+ }
98
+ if (receipt.fingerprint !== fingerprint)
99
+ return { ready: false, state: 'stale-receipt', recovery: 'Run holmes-kit semantic-setup to re-verify the changed BGE-M3 cache.' };
100
+ return { ready: true, state: 'verified', recovery: '' };
101
+ }
102
+ /** Only successful actual inference may write the same-directory atomic receipt. */
103
+ function writeVerifiedModelReceipt(cacheDir = modelCacheDir()) {
104
+ const fingerprint = modelCacheFingerprint(cacheDir);
105
+ if (fingerprint === null)
106
+ return { ready: false, state: 'missing-cache', recovery: 'Run holmes-kit semantic-setup to download and verify BGE-M3.' };
107
+ const target = receiptPath(cacheDir), temp = `${target}.${process.pid}.tmp`;
61
108
  try {
62
- return fs.readdirSync(cacheDir).length > 0;
109
+ fs.mkdirSync(cacheDir, { recursive: true });
110
+ fs.writeFileSync(temp, JSON.stringify({ schema: RECEIPT_SCHEMA, model: exports.LOCAL_MODEL, revision: exports.LOCAL_REVISION, fingerprint }));
111
+ fs.renameSync(temp, target);
63
112
  }
64
113
  catch {
65
- return false;
66
- } // absent, unreadable, not a directory — none of them are ready
114
+ try {
115
+ fs.rmSync(temp, { force: true });
116
+ }
117
+ catch { /* best effort */ }
118
+ return { ready: false, state: 'invalid-receipt', recovery: 'Check HOLMES_MODEL_CACHE permissions, then run holmes-kit semantic-setup.' };
119
+ }
120
+ return readLocalModelReadiness(cacheDir);
67
121
  }
122
+ /** Compatibility boolean: actual verified inference, never directory presence. */
123
+ function modelCacheReady(cacheDir = modelCacheDir()) { return readLocalModelReadiness(cacheDir).ready; }
@@ -11,8 +11,9 @@
11
11
  * network; presence signals only, so doctor can call it offline.
12
12
  */
13
13
  import { type CredentialOpts, type KeySource } from './credentials';
14
+ import { LOCAL_MODEL, type LocalModelReadiness } from './model-cache';
14
15
  /** The local tier's model. CLS-pooled — see POOLING_OF. */
15
- export declare const LOCAL_MODEL = "Xenova/bge-m3";
16
+ export { LOCAL_MODEL };
16
17
  /** The opt-in cloud tier's model (S-491 four-arm winner). */
17
18
  export declare const CLOUD_MODEL = "gemini-embedding-001";
18
19
  export interface SemanticTier {
@@ -28,6 +29,8 @@ export interface SemanticTier {
28
29
  * because reporting this one as 'local' claims a recall the tier cannot deliver.
29
30
  */
30
31
  localRuntimePresent?: boolean;
32
+ /** Why local BGE-M3 was not activated, when readiness was observed. */
33
+ localState?: LocalModelReadiness['state'];
31
34
  }
32
35
  /**
33
36
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
@@ -40,5 +43,6 @@ export declare function resolveSemanticTier(opts?: {
40
43
  env?: NodeJS.ProcessEnv;
41
44
  hasLocalModule?: boolean;
42
45
  hasLocalModel?: boolean;
46
+ localReadiness?: LocalModelReadiness;
43
47
  credentials?: CredentialOpts;
44
48
  }): SemanticTier;
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-476
2
+ // @implements A-SPEC-476, A-SPEC-712
3
3
  /**
4
4
  * The semantic layer's tier structure — the owner's two-lever design made a contract:
5
5
  * maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
@@ -18,8 +18,7 @@ exports.POOLING_OF = POOLING_OF;
18
18
  exports.resolveSemanticTier = resolveSemanticTier;
19
19
  const credentials_1 = require("./credentials");
20
20
  const model_cache_1 = require("./model-cache");
21
- /** The local tier's model. CLS-pooled — see POOLING_OF. */
22
- exports.LOCAL_MODEL = 'Xenova/bge-m3';
21
+ Object.defineProperty(exports, "LOCAL_MODEL", { enumerable: true, get: function () { return model_cache_1.LOCAL_MODEL; } });
23
22
  /** The opt-in cloud tier's model (S-491 four-arm winner). */
24
23
  exports.CLOUD_MODEL = 'gemini-embedding-001';
25
24
  /**
@@ -53,8 +52,10 @@ function resolveSemanticTier(opts = {}) {
53
52
  // discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
54
53
  // presence is not readiness.
55
54
  const hasModule = opts.hasLocalModule ?? localModulePresent();
56
- const hasModel = opts.hasLocalModel ?? (0, model_cache_1.modelCacheReady)();
55
+ const observed = opts.localReadiness ?? (opts.hasLocalModel === undefined ? (0, model_cache_1.readLocalModelReadiness)() : undefined);
56
+ const hasModel = opts.hasLocalModel ?? observed?.ready ?? false;
57
57
  if (hasModule && hasModel)
58
- return { tier: 'local', model: exports.LOCAL_MODEL, egress: false };
59
- return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}) };
58
+ return { tier: 'local', model: model_cache_1.LOCAL_MODEL, egress: false };
59
+ return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}),
60
+ ...(hasModule && observed && !observed.ready ? { localState: observed.state } : {}) };
60
61
  }
@@ -20,6 +20,15 @@ export interface ScannedLike {
20
20
  qualifiedName: string;
21
21
  }>;
22
22
  }
23
+ /** The governed fields which contribute to a requirement-document vector. */
24
+ export interface RequirementDocumentLike {
25
+ id: string;
26
+ type: string;
27
+ title: string;
28
+ status: string;
29
+ dependsOn?: readonly string[];
30
+ sections?: Readonly<Record<string, string>>;
31
+ }
23
32
  export type CoverageState = 'covered' | 'inert' | 'not-adopted' | 'unknown';
24
33
  export interface CoverageInput {
25
34
  /** The RESOLVED tier. `none` is the shipped default (zero egress) and means never opted in. */
@@ -50,6 +59,14 @@ export declare const DOC_TEXT_LIMIT = 2000;
50
59
  export declare function docTextOf(file: ScannedLike): string;
51
60
  /** The same text, indexed by source path — the form the three ranking passes consume. */
52
61
  export declare function docTextIndex(scanned: ReadonlyArray<ScannedLike>): Map<string, string>;
62
+ /** A requirement vector has its own versioned namespace and cannot share a source-file key. */
63
+ export declare function canonicalRequirementDocument(doc: RequirementDocumentLike, lineageId: string): string;
64
+ /** Every eligible REQ/H/A/T document paired with its REQ lineage and cache text. */
65
+ export declare function requirementDocumentTexts<T extends RequirementDocumentLike>(documents: readonly T[]): Array<{
66
+ document: T;
67
+ lineageId: string;
68
+ text: string;
69
+ }>;
53
70
  /**
54
71
  * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
55
72
  * without a cache on disk, and it cannot be wrong about ordering or locking.
@@ -52,6 +52,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
52
52
  exports.COVERAGE_STATE_FILE = exports.DOC_TEXT_LIMIT = void 0;
53
53
  exports.docTextOf = docTextOf;
54
54
  exports.docTextIndex = docTextIndex;
55
+ exports.canonicalRequirementDocument = canonicalRequirementDocument;
56
+ exports.requirementDocumentTexts = requirementDocumentTexts;
55
57
  exports.vectorCoverage = vectorCoverage;
56
58
  exports.coverageLine = coverageLine;
57
59
  exports.countCovered = countCovered;
@@ -77,6 +79,41 @@ function docTextOf(file) {
77
79
  function docTextIndex(scanned) {
78
80
  return new Map(scanned.map((f) => [f.sourcePath, docTextOf(f)]));
79
81
  }
82
+ /** A requirement vector has its own versioned namespace and cannot share a source-file key. */
83
+ function canonicalRequirementDocument(doc, lineageId) {
84
+ const sections = Object.entries(doc.sections ?? {})
85
+ .sort(([a], [b]) => a.localeCompare(b))
86
+ .map(([heading, body]) => `${heading}\n${body}`)
87
+ .join('\n');
88
+ return [
89
+ 'holmes-requirement-document/v1', `id:${doc.id}`, `kind:${doc.type}`,
90
+ `lineage:${lineageId}`, `status:${doc.status}`, `dependsOn:${[...(doc.dependsOn ?? [])].sort().join(',')}`,
91
+ `title:${doc.title}`, sections,
92
+ ].join('\n');
93
+ }
94
+ /** Every eligible REQ/H/A/T document paired with its REQ lineage and cache text. */
95
+ function requirementDocumentTexts(documents) {
96
+ const byId = new Map(documents.map((doc) => [doc.id, doc]));
97
+ const lineageOf = (id) => {
98
+ const seen = new Set();
99
+ let current = byId.get(id);
100
+ while (current) {
101
+ if (seen.has(current.id))
102
+ return null;
103
+ seen.add(current.id);
104
+ if (current.type === 'REQ')
105
+ return current.id;
106
+ current = (current.dependsOn ?? []).map((parent) => byId.get(parent)).find((parent) => parent !== undefined);
107
+ }
108
+ return null;
109
+ };
110
+ return documents.flatMap((document) => {
111
+ if (!['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC'].includes(document.type))
112
+ return [];
113
+ const lineageId = lineageOf(document.id);
114
+ return lineageId === null ? [] : [{ document, lineageId, text: canonicalRequirementDocument(document, lineageId) }];
115
+ });
116
+ }
80
117
  const isCount = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
81
118
  /**
82
119
  * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
@@ -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 |
@@ -196,37 +210,33 @@ The failure happens while npm is still installing dependencies — before Holmes
196
210
  `doctor` cannot diagnose it and this note is the only warning available. If `npm install` dies with
197
211
  `gyp ERR!` in `tree_sitter_runtime_binding`, switch to Node 20 or 22 on that machine.
198
212
 
199
- # Default local embeddings (Windows, macOS, Linux)
213
+ # Default local embeddings (macOS and Linux npm lifecycle)
200
214
 
201
- Holmes-Kit ships with the **Xenova/bge-m3** local tier available, but **preparing it is
202
- opt-in**: neither package installation, nor `holmes-kit init`, nor the Windows bootstrap
203
- downloads model assets on its own. Run one command when you want it:
215
+ Holmes-Kit prepares the pinned **Xenova/bge-m3** local tier by default when a normal npm
216
+ installation runs its lifecycle scripts. The package activates the tier only after an actual
217
+ offline inference produces a finite, normalized 1024-dimensional vector. `holmes-kit init` does
218
+ not add a second download path. Run this command to retry preparation or recover an unavailable
219
+ cache:
204
220
 
205
221
  ```text
206
222
  holmes-kit semantic-setup
207
223
  ```
208
224
 
209
- To prepare it during installation instead, set `HOLMES_AUTO_MODEL_INSTALL=1` before
210
- installing. `HOLMES_SKIP_MODEL_INSTALL=1` still refuses preparation and **outranks** the
211
- opt-in, so an explicit refusal is never overridden. All three harnesses and all three
212
- operating systems share this default — Windows does not prepare the model when macOS and
213
- Linux do not.
225
+ `HOLMES_SKIP_MODEL_INSTALL=1` explicitly refuses automatic preparation. It is the only automatic
226
+ opt-out and never prevents an explicit `semantic-setup` or `semantic-check`. The Node lifecycle
227
+ implementation is shared by the three harnesses. Windows PowerShell-bootstrap default-preparation
228
+ behavior is retained for separate consumer validation; do not treat this document as evidence that
229
+ that bootstrap path has completed the same acceptance run.
214
230
 
215
231
  The first setup downloads public model assets from Hugging Face; it sends no repository
216
232
  text. Normal embedding inference is offline and will not download missing assets.
217
233
  The model revision is pinned to `4de13258303883538bd53b696b452bf8099f0858`.
218
234
 
219
- Until the model is prepared, `doctor` reports the semantic tier as **none** and names what
220
- it costs — requests lexical search misses (measured 16.4%) have 0% recall — together with the
221
- command that changes it. A runtime that resolves is not a tier that answers, so an unprepared
222
- local runtime is never reported as the `local` tier.
223
-
224
- The Windows `scripts/install.ps1` bootstrap honours the same opt-in. With
225
- `HOLMES_AUTO_MODEL_INSTALL=1` it prepares the model after npm installation and when the
226
- requested Holmes-Kit version is already installed, printing readiness only after successful
227
- inference; failure prints `semantic-setup` / `semantic-check` recovery commands while preserving
228
- the installed graph tools. Without the opt-in it prepares nothing and names the command. Dry runs
229
- and the explicit skip flag do no model work.
235
+ When setup cannot run because lifecycle scripts are blocked, the network is unavailable, or the
236
+ cache fails verification, the package and BM25/citation/graph features stay usable. `doctor`
237
+ reports **unavailable** or **degraded** local semantics and tells the user whether
238
+ `semantic-setup` will download, verify, or re-verify the cache. A nonempty cache directory or a
239
+ resolvable runtime alone is never reported as a local embedding tier.
230
240
 
231
241
  Run `holmes-kit semantic-check` after installation. Success means an actual CPU inference
232
242
  produced a finite, normalized 1024-dimensional vector. `doctor` deliberately reports local
@@ -238,10 +248,9 @@ hide successful lifecycle output, so use `--foreground-scripts` when inspecting
238
248
 
239
249
  Models are shared between projects in `~/.holmes/models` (Windows:
240
250
  `%USERPROFILE%\.holmes\models`). Set `HOLMES_MODEL_CACHE` to override this directory,
241
- including for a prepopulated offline cache. Set `HOLMES_SKIP_MODEL_INSTALL=1` to refuse
242
- automatic preparation explicitly; it outranks `HOLMES_AUTO_MODEL_INSTALL=1` and does not
243
- disable an explicit setup/check command. An empty cache directory counts as not prepared —
244
- an interrupted download leaves exactly that, and reading it as ready would be a false PASS.
251
+ including for a prepopulated offline cache. An empty, unverified, malformed, or changed cache
252
+ receipt counts as unavailable/degraded — only a receipt written after successful offline inference
253
+ activates the local tier.
245
254
  For source checkouts, build first, then run `node bin/holmes-kit.js semantic-setup`.
246
255
 
247
256
  If npm blocks lifecycle scripts, run `npm install-scripts ls`, review the blocked versions,
@@ -266,3 +275,43 @@ implementation, but this Windows session did not execute platform-native tests t
266
275
  The optional cloud credential file uses a protected current-user-only NTFS DACL on Windows.
267
276
  Permission setup is verified before a new key is written; failure preserves the prior key and
268
277
  refuses the new value. The macOS keychain and POSIX 0700/0600 fallback remain available.
278
+ # Keeping AGENTS.md guidance current
279
+
280
+ Holmes-Kit generates common operating rules inside `holmes-kit:managed:begin/end`
281
+ markers. Keep project-specific rules outside that block. The development repository
282
+ uses the same renderer as installed packages; consumer checks compare against the
283
+ package executing the command, not unreleased upstream prose.
284
+
285
+ ```sh
286
+ holmes-kit guidance check --target .
287
+ holmes-kit guidance refresh --target . --dry-run
288
+ holmes-kit guidance refresh --target .
289
+ ```
290
+
291
+ `check` never writes: exit 0 means current, 1 means missing or recognized outdated
292
+ guidance, and 2 means a conflict or read failure. `refresh` only changes AGENTS.md;
293
+ dry-run prints the before/proposed contents and writes nothing. Successful refresh
294
+ returns 0, refusal returns 2. The target directory must already exist.
295
+
296
+ Known historical generated sections can migrate automatically. Unknown edits,
297
+ malformed markers, and obsolete prohibitions outside the block require review;
298
+ neither `--force` on init nor upgrade overrides a guidance conflict. Preserve local
299
+ instructions, inspect the installed template, and resolve the conflicting sections
300
+ before retrying. `doctor` reports these states with the installed package version.
301
+ It does not rewrite the file or prove that hooks are running.
302
+
303
+ Updating a file does not replace instructions already loaded by an agent. Reload
304
+ instructions or start a new session. Common guidance is the same for Claude Code,
305
+ Codex CLI, and Antigravity; actual enforcement requires evidence from that session.
306
+
307
+ For maintainers, a common-text change requires a new guidance revision and an
308
+ immutable baseline in `agents-guidance-history.ts`; preserve previous baselines.
309
+ The root consistency check refuses a renderer change without that registration.
310
+ Then refresh the development AGENTS.md with the same command used by consumers.
311
+
312
+ Publication compares the original bytes again before renaming a temporary file.
313
+ This detects observed concurrent changes but is not an atomic compare-and-swap
314
+ against an unrelated writer racing the final rename. Serialize edits to AGENTS.md
315
+ during refresh. On ownership conflicts, dry-run shows the preserved original and
316
+ the expected block as a reference for manual review; it does not guess which custom
317
+ 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.29.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.