@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.
- package/CHANGELOG.md +64 -0
- package/README.md +21 -17
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/agents-guidance-command.d.ts +9 -0
- package/dist/holmes/cli/agents-guidance-command.js +61 -0
- package/dist/holmes/cli/agents-guidance-file.d.ts +7 -0
- package/dist/holmes/cli/agents-guidance-file.js +86 -0
- package/dist/holmes/cli/agents-guidance-history.d.ts +10 -0
- package/dist/holmes/cli/agents-guidance-history.js +35 -0
- package/dist/holmes/cli/agents-guidance-plan.d.ts +11 -0
- package/dist/holmes/cli/agents-guidance-plan.js +81 -0
- package/dist/holmes/cli/agents-guidance.d.ts +1 -0
- package/dist/holmes/cli/agents-guidance.js +40 -0
- package/dist/holmes/cli/agents.d.ts +3 -19
- package/dist/holmes/cli/agents.js +12 -108
- package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
- package/dist/holmes/cli/doctor-guidance.js +61 -0
- package/dist/holmes/cli/doctor.d.ts +2 -0
- package/dist/holmes/cli/doctor.js +29 -1
- package/dist/holmes/cli/index.js +31 -3
- package/dist/holmes/cli/init.js +32 -5
- package/dist/holmes/cli/upgrade.js +23 -26
- package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
- package/dist/holmes/cli/worktree-readiness.js +81 -0
- package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
- package/dist/holmes/cpg/ast-mutation.js +4 -2
- package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
- package/dist/holmes/cpg/foundation/cfg.js +27 -1
- package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
- package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
- package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
- package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
- package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
- package/dist/holmes/mcp/handlers.d.ts +157 -46
- package/dist/holmes/mcp/handlers.js +16 -3
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
- package/dist/holmes/mcp/tool-schemas.js +19 -1
- package/dist/holmes/project/workspace-checkout.d.ts +8 -0
- package/dist/holmes/project/workspace-checkout.js +74 -0
- package/dist/holmes/project/workspace-preflight.d.ts +24 -0
- package/dist/holmes/project/workspace-preflight.js +99 -0
- package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
- package/dist/holmes/review/condition-hunk-replay.js +112 -0
- package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
- package/dist/holmes/review/condition-hunk-resolution.js +207 -0
- package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
- package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
- package/dist/holmes/review/requirement-triage.d.ts +61 -0
- package/dist/holmes/review/requirement-triage.js +143 -0
- package/dist/holmes/semantic/local-model.d.ts +3 -3
- package/dist/holmes/semantic/local-model.js +10 -12
- package/dist/holmes/semantic/model-cache.d.ts +15 -6
- package/dist/holmes/semantic/model-cache.js +77 -21
- package/dist/holmes/semantic/tier.d.ts +5 -1
- package/dist/holmes/semantic/tier.js +7 -6
- package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
- package/dist/holmes/semantic/vector-coverage.js +37 -0
- package/docs/install-guide.md +73 -24
- package/package.json +1 -1
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
66
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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:
|
|
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
|
package/docs/install-guide.md
CHANGED
|
@@ -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 (
|
|
213
|
+
# Default local embeddings (macOS and Linux npm lifecycle)
|
|
200
214
|
|
|
201
|
-
Holmes-Kit
|
|
202
|
-
|
|
203
|
-
|
|
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
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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.
|
|
242
|
-
|
|
243
|
-
|
|
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.
|
|
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.
|