@holmes-lab/holmes-kit 0.26.2 → 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 (41) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +10 -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/attest.d.ts +15 -0
  17. package/dist/holmes/cli/attest.js +168 -0
  18. package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
  19. package/dist/holmes/cli/doctor-guidance.js +61 -0
  20. package/dist/holmes/cli/doctor.d.ts +2 -0
  21. package/dist/holmes/cli/doctor.js +5 -1
  22. package/dist/holmes/cli/index.d.ts +1 -0
  23. package/dist/holmes/cli/index.js +51 -4
  24. package/dist/holmes/cli/init.js +32 -5
  25. package/dist/holmes/cli/upgrade.js +23 -26
  26. package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
  27. package/dist/holmes/cli/worktree-readiness.js +81 -0
  28. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  29. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  30. package/dist/holmes/mcp/handlers.d.ts +50 -46
  31. package/dist/holmes/mcp/handlers.js +6 -3
  32. package/dist/holmes/mcp/tool-schemas.js +6 -1
  33. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  34. package/dist/holmes/project/workspace-checkout.js +74 -0
  35. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  36. package/dist/holmes/project/workspace-preflight.js +99 -0
  37. package/dist/holmes/rtm/traced-files.d.ts +83 -0
  38. package/dist/holmes/rtm/traced-files.js +207 -0
  39. package/docs/install-guide.md +54 -0
  40. package/package.json +1 -1
  41. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
@@ -44,9 +44,11 @@ exports.mergeMarketplaceJson = mergeMarketplaceJson;
44
44
  exports.mergeWiringFile = mergeWiringFile;
45
45
  exports.agentFiles = agentFiles;
46
46
  exports.agentLinks = agentLinks;
47
- // @implements A-SPEC-202, A-SPEC-250, A-SPEC-341
47
+ // @implements A-SPEC-708, A-SPEC-707, A-SPEC-202, A-SPEC-250, A-SPEC-341
48
48
  // @implements A-SPEC-442
49
49
  // @implements A-SPEC-193
50
+ const agents_guidance_plan_1 = require("./agents-guidance-plan");
51
+ const agents_guidance_1 = require("./agents-guidance");
50
52
  const path = __importStar(require("node:path"));
51
53
  const node_child_process_1 = require("node:child_process");
52
54
  const mcp_launcher_1 = require("./mcp-launcher");
@@ -193,117 +195,19 @@ const hooksJson = (packageRoot) => `${JSON.stringify({
193
195
  Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js')],
194
196
  },
195
197
  }, null, 2)}\n`;
196
- const AGENTS_MD = (enforced) => `# Holmes-Kit — Workspace Operational Discipline
197
-
198
- This repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.
199
-
200
- ## 3 Core Operational Rules
201
-
202
- 1. **Tool-First Principle (NO Workaround Scripts)**:
203
- - Creating or mutating \`.ax/specs\` or governance ledgers via arbitrary temporary scripts (\`/tmp/*.js\`) is strictly forbidden.
204
- - \`spec_slice_init\` and \`spec_create\` SCAFFOLD spec documents; \`spec_slice_approve\` and \`spec_approve\` SEAL them. Use these tools for those two acts — never a script.
205
- - **Writing the body is editing the file.** After scaffolding, fill the \`TODO\` placeholders by editing the generated spec markdown in \`.ax/specs/\` with your normal editor. This is the expected authoring path, not a workaround — no MCP tool takes section text.
206
- - A REQ's \`## Success Criteria\` is scaffolded EMPTY on purpose, because a generator must not invent what "satisfied" means. Approval is refused until you write observable criteria there.
207
-
208
- 2. **Anchor-First Principle (Mandatory Code Anchors)**:
209
- - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: \`// @\` + \`implements A-SPEC-XXX\`.
210
-
211
- 3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:
212
- - When a tool call is denied by a hook gate, DO NOT inspect guardrail source code (\`pre-tool-use.ts\`, \`phase.ts\`) or attempt to write bypass code.
213
- - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the \`spec_remediate\` MCP tool / \`holmes-remediation\` playbook skill.
214
-
215
- ## Procedure
216
-
217
- 1. Run \`spec_slice_init\` or \`spec_create\` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every \`TODO\` and to write the REQ's Success Criteria.
218
- 2. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
219
- 3. **Before editing source**, run \`maintenance_analyze({ root, request, persist: true })\` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.
220
- 4. **Write tests first** and verify failure (RED stage).
221
- 5. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
222
- 6. Implement source code (GREEN stage).
223
-
224
- Use \`spec_next\` to check the next required governance step. Use \`phase_check\` to verify action permissions ahead of execution. Use \`impact_gate_check\` to ask what the pre-edit evidence gate would say about an edit — it is advisory and blocks nothing, so it answers the same way in every harness.
225
-
226
- ## Enforcement in this Harness
227
-
228
- ${enforced
229
- ? `Gates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.`
230
- : `This harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.`}
231
- `;
198
+ const AGENTS_MD = (_enforced) => (0, agents_guidance_1.renderCommonGuidance)();
232
199
  exports.AGENTS_MD = AGENTS_MD;
233
- exports.MANAGED_BEGIN = '<!-- holmes-kit:managed:begin -->';
234
- exports.MANAGED_END = '<!-- holmes-kit:managed:end -->';
235
- const PRESERVED_NOTE = '<!-- kept from this file by holmes-kit init — holmes-kit does not write below this line -->';
236
- /**
237
- * @implements A-SPEC-576.2
238
- * The regeneration that keeps what it did not write.
239
- *
240
- * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
241
- * commit had added the day before — and said nothing, so the loss was found weeks later by grep.
242
- * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
243
- * whose repository this is.
244
- *
245
- * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
246
- * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 §9).
247
- *
248
- * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
249
- * would be the same silent loss in a new costume.
250
- */
251
- function mergeAgentsMd(existing, generated) {
252
- const block = exports.MANAGED_BEGIN + '\n' + (generated.endsWith('\n') ? generated : generated + '\n') + exports.MANAGED_END + '\n';
253
- if (existing === null || existing === '')
254
- return { content: block, preserved: [], note: null };
255
- const b = existing.indexOf(exports.MANAGED_BEGIN);
256
- const e = existing.indexOf(exports.MANAGED_END);
257
- if (b !== -1 && e > b) {
258
- // The ordinary case once a file has been through here: swap the block, and do not touch a
259
- // single byte on either side of it.
260
- const body = generated.endsWith('\n') ? generated : generated + '\n';
261
- return {
262
- content: existing.slice(0, b) + exports.MANAGED_BEGIN + '\n' + body + exports.MANAGED_END + existing.slice(e + exports.MANAGED_END.length),
263
- preserved: [],
264
- note: null,
265
- };
266
- }
267
- // LEGACY: a file written before the markers existed — every AGENTS.md in the field today. Its
268
- // lines are compared to the generated ones, and whatever the generator never wrote is carried
269
- // below the block. Line terminators are kept as read, so a CRLF checkout stays CRLF.
270
- const known = new Set(generated.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== ''));
271
- const lines = existing.split(/(?<=\n)/);
272
- const runs = [];
273
- let run = [];
274
- let pendingBlanks = [];
275
- for (const line of lines) {
276
- const t = line.trim();
277
- if (t === '') {
278
- if (run.length > 0)
279
- pendingBlanks.push(line);
280
- continue;
281
- }
282
- if (known.has(t)) {
283
- run = closeRun(runs, run);
284
- pendingBlanks = [];
285
- continue;
286
- }
287
- // A blank line INSIDE a run is part of it; blanks trailing a run are not.
288
- run.push(...pendingBlanks, line);
289
- pendingBlanks = [];
290
- }
291
- closeRun(runs, run);
292
- if (runs.length === 0)
293
- return { content: block, preserved: [], note: null };
294
- const preserved = runs.map((r) => (r.find((l) => l.trim() !== '') ?? '').trim());
200
+ var agents_guidance_plan_2 = require("./agents-guidance-plan");
201
+ Object.defineProperty(exports, "MANAGED_BEGIN", { enumerable: true, get: function () { return agents_guidance_plan_2.MANAGED_BEGIN; } });
202
+ Object.defineProperty(exports, "MANAGED_END", { enumerable: true, get: function () { return agents_guidance_plan_2.MANAGED_END; } });
203
+ function mergeAgentsMd(existing, _generated) {
204
+ const plan = (0, agents_guidance_plan_1.planGuidance)(existing);
295
205
  return {
296
- content: block + '\n' + PRESERVED_NOTE + '\n\n' + runs.map((r) => r.join('')).join('\n'),
297
- preserved,
298
- note: `kept ${runs.length} section(s) this generator did not write`,
206
+ content: plan.after ?? existing ?? '', preserved: plan.preserved,
207
+ note: plan.after === null ? `guidance conflict: ${plan.reasons.join(' ')}`
208
+ : plan.reasons.length ? plan.reasons.join(' ') : null,
299
209
  };
300
210
  }
301
- /** Close the current run into `runs` (dropping an empty one) and hand back a fresh one. */
302
- function closeRun(runs, run) {
303
- if (run.length > 0)
304
- runs.push(run);
305
- return [];
306
- }
307
211
  const HOLMES = 'holmes-kit';
308
212
  /** Parse, or explain why not. An unreadable file is never replaced: silently deleting it is the defect. */
309
213
  function parseOr(before, ours, what) {
@@ -0,0 +1,15 @@
1
+ import { type AttestReport } from '../rtm/traced-files';
2
+ export interface AttestOptions {
3
+ root: string;
4
+ exclude: string[];
5
+ json: boolean;
6
+ badge: boolean;
7
+ readme: boolean;
8
+ }
9
+ export interface AttestIo {
10
+ stdout(s: string): void;
11
+ stderr(s: string): void;
12
+ }
13
+ export declare const BADGE_REL: string;
14
+ export declare function buildAttestReport(root: string, exclude: string[]): Promise<AttestReport>;
15
+ export declare function runAttest(o: AttestOptions, io: AttestIo): Promise<number>;
@@ -0,0 +1,168 @@
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.BADGE_REL = void 0;
37
+ exports.buildAttestReport = buildAttestReport;
38
+ exports.runAttest = runAttest;
39
+ // @implements A-SPEC-702
40
+ /**
41
+ * `holmes-kit attest` — the surface that calls `rtm/traced-files`.
42
+ *
43
+ * Reads: one scan, the spec store, git (optional — REQ-128). Writes: AT MOST two files, and only
44
+ * when asked: the badge (`--badge`) and the region between the README markers (`--readme`). A README
45
+ * without markers is never written: placing the markers is the consent. Nothing reaches the network,
46
+ * and the measured numbers never change the exit code — this is a statement, not a gate.
47
+ */
48
+ const fs = __importStar(require("node:fs"));
49
+ const path = __importStar(require("node:path"));
50
+ const node_child_process_1 = require("node:child_process");
51
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
52
+ const spec_store_1 = require("../spec/spec-store");
53
+ const root_1 = require("../project/root");
54
+ const test_scope_1 = require("../rtm/test-scope");
55
+ const file_anchors_1 = require("../rtm/file-anchors");
56
+ const link_census_1 = require("../rtm/link-census");
57
+ const traced_files_1 = require("../rtm/traced-files");
58
+ exports.BADGE_REL = path.join('.ax', 'badges', 'traced.svg');
59
+ const SPECS_REL = path.join('.ax', 'specs');
60
+ const git = (root, args) => {
61
+ try {
62
+ return (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env) }).toString('utf8');
63
+ }
64
+ catch {
65
+ return undefined;
66
+ }
67
+ };
68
+ /**
69
+ * `+dirty` only when something that DECIDES the number is uncommitted: a scanned source file or a
70
+ * spec. The badge and the README are outputs of this very command, and a session ledger is always
71
+ * moving — counting them would make a committed badge say `+dirty` forever.
72
+ */
73
+ function decidingPathsDirty(root, scanned) {
74
+ const out = git(root, ['status', '--porcelain', '-z', '--untracked-files=all']);
75
+ if (out === undefined)
76
+ return false;
77
+ const specs = SPECS_REL.split(path.sep).join('/') + '/';
78
+ for (const entry of out.split('\0')) {
79
+ if (entry.length < 4)
80
+ continue;
81
+ const p = entry.slice(3);
82
+ if (p.startsWith(specs) || scanned.has(p))
83
+ return true;
84
+ }
85
+ return false;
86
+ }
87
+ async function buildAttestReport(root, exclude) {
88
+ const scanned = new cpg_scanner_1.CpgScanner().scan(root, root);
89
+ const specs = await new spec_store_1.LocalMarkdownRepository(path.join(root, SPECS_REL)).list();
90
+ const approved = specs.filter((s) => s.status === 'approved');
91
+ const files = scanned.map((f) => ({ path: f.sourcePath.split(path.sep).join('/'), anchors: f.implementsSpecs ?? [] }));
92
+ // The spec axis, the way the dashboard computes it (A-SPEC-655). `weakMentions` stays empty: it
93
+ // only splits the REASON a spec is unlinked, and this command reports the count.
94
+ const excludes = (0, traced_files_1.normalizeExcludes)(exclude);
95
+ const kept = files.filter((f) => !excludes.some((e) => f.path.startsWith(e)));
96
+ const census = (0, link_census_1.linkCensus)({
97
+ approvedIds: approved.filter((s) => s.id.startsWith('A-SPEC')).map((s) => s.id),
98
+ implemented: new Set(kept.flatMap((f) => f.anchors)),
99
+ testAnchors: (0, test_scope_1.scanTestAnchors)(root),
100
+ fileAnchors: (0, file_anchors_1.scanFileAnchors)(root),
101
+ weakMentions: {},
102
+ });
103
+ const commit = git(root, ['rev-parse', 'HEAD'])?.trim();
104
+ return {
105
+ files: (0, traced_files_1.tracedFiles)({ files, approvedIds: approved.map((s) => s.id), exclude }),
106
+ specs: { total: census.total, linked: census.codeLinked },
107
+ provenance: (0, traced_files_1.attestProvenance)({
108
+ commit,
109
+ dirty: commit ? decidingPathsDirty(root, new Set(files.map((f) => f.path))) : false,
110
+ approved: approved.map((s) => ({ id: s.id, digest: String(s.frontmatter.approved_digest ?? '') })),
111
+ exclude,
112
+ }),
113
+ };
114
+ }
115
+ async function runAttest(o, io) {
116
+ if (!fs.existsSync(o.root) || !fs.statSync(o.root).isDirectory()) {
117
+ io.stderr(`attest: ${o.root} is not a directory\n`);
118
+ return 2;
119
+ }
120
+ const report = await buildAttestReport(o.root, o.exclude);
121
+ io.stdout(o.json ? (0, traced_files_1.renderAttestJson)(report) : (0, traced_files_1.renderAttestText)(report));
122
+ let code = 0;
123
+ const note = (s) => { if (!o.json)
124
+ io.stdout(s);
125
+ else
126
+ io.stderr(s); };
127
+ if (o.badge) {
128
+ const file = path.join(o.root, exports.BADGE_REL);
129
+ const svg = (0, traced_files_1.renderAttestSvg)(report);
130
+ let same = false;
131
+ try {
132
+ same = fs.readFileSync(file, 'utf8') === svg;
133
+ }
134
+ catch { /* absent */ }
135
+ if (!same) {
136
+ fs.mkdirSync(path.dirname(file), { recursive: true });
137
+ fs.writeFileSync(file, svg);
138
+ }
139
+ note(`badge ${exports.BADGE_REL.split(path.sep).join('/')}${same ? ' (unchanged)' : ' written'}\n`);
140
+ }
141
+ if (o.readme) {
142
+ const file = path.join(o.root, 'README.md');
143
+ let text;
144
+ try {
145
+ text = fs.readFileSync(file, 'utf8');
146
+ }
147
+ catch {
148
+ text = undefined;
149
+ }
150
+ if (text === undefined)
151
+ note('readme README.md not found — nothing written\n');
152
+ else {
153
+ const r = (0, traced_files_1.replaceMarkerRegion)(text, (0, traced_files_1.renderAttestMarker)(report));
154
+ if (r.ok) {
155
+ if (r.changed)
156
+ fs.writeFileSync(file, r.text);
157
+ note(`readme marker region ${r.changed ? 'updated' : 'unchanged'}\n`);
158
+ }
159
+ else if (r.reason === 'no-marker')
160
+ note('readme no marker in README.md — nothing written (add the begin/end markers to opt in)\n');
161
+ else {
162
+ io.stderr('attest: README.md has an unbalanced holmes-kit:attest marker (each must appear exactly once, begin first) — nothing written\n');
163
+ code = 1;
164
+ }
165
+ }
166
+ }
167
+ return code;
168
+ }
@@ -0,0 +1,2 @@
1
+ import type { Check } from './doctor-check';
2
+ export declare function guidanceChecks(packageRoot: string, target: string): Check[];
@@ -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
  }
@@ -4,6 +4,7 @@
4
4
  * Commands:
5
5
  * init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
6
6
  * doctor [--target dir] [--json]
7
+ * attest [--target dir] [--exclude a,b] [--json] [--badge] [--readme]
7
8
  */
8
9
  /**
9
10
  * The installed package root. From `dist/holmes/cli/index.js` that is three levels up. Node resolves
@@ -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");
@@ -55,6 +56,7 @@ const colophon_1 = require("./colophon");
55
56
  * Commands:
56
57
  * init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
57
58
  * doctor [--target dir] [--json]
59
+ * attest [--target dir] [--exclude a,b] [--json] [--badge] [--readme]
58
60
  */
59
61
  /**
60
62
  * The installed package root. From `dist/holmes/cli/index.js` that is three levels up. Node resolves
@@ -75,9 +77,12 @@ function packageRoot() {
75
77
  * REQ-144's "cannot decide is not permission", applied to CLI arguments.
76
78
  */
77
79
  const KNOWN_FLAGS = {
80
+ guidance: ['help', 'target', 'dry-run'],
78
81
  init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher', 'autonomy', 'no-autonomy'],
79
82
  autonomy: ['help', 'target', 'for'],
80
- doctor: ['help', 'target', 'json'],
83
+ doctor: ['help', 'target', 'json', 'agent'],
84
+ // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
85
+ attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
81
86
  skills: ['help', 'target'],
82
87
  ci: ['help', 'target', 'specs-dir', 'json'],
83
88
  serve: ['help', 'target', 'port'],
@@ -119,7 +124,7 @@ class UnknownFlagError extends Error {
119
124
  * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
120
125
  * --force). A boolean flag must never consume a token.
121
126
  */
122
- const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy']); // A-SPEC-650: --status
127
+ const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy']); // A-SPEC-650: --status
123
128
  function parseFlags(argv, known) {
124
129
  const flags = {};
125
130
  const positionals = [];
@@ -239,6 +244,16 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
239
244
  --target <dir> also verify that target's wiring points at this install
240
245
  --json machine-readable output
241
246
 
247
+ holmes-kit attest [flags] say how many source files trace to an APPROVED spec (a statement, not a gate)
248
+ --target <dir> the project to measure (default: current directory)
249
+ --exclude <a,b> path prefixes that are not this project's source (vendored trees); echoed in the output
250
+ --json machine-readable output
251
+ --badge write a self-contained SVG to .ax/badges/traced.svg
252
+ --readme update ONLY the region between the holmes-kit:attest markers in README.md;
253
+ a README without the markers is never written
254
+
255
+ holmes-kit guidance check|refresh --target <dir> [--dry-run] inspect or update AGENTS.md only
256
+
242
257
  holmes-kit upgrade [flags] install the latest and re-pin every recorded workspace (one command)
243
258
  --dry-run show the plan (current→latest, workspaces to re-pin), change nothing
244
259
  --yes skip the confirmation prompt (required in a non-interactive shell)
@@ -285,7 +300,7 @@ async function main(argv) {
285
300
  }
286
301
  // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
287
302
  // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
288
- const expected = cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
303
+ const expected = cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
289
304
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
290
305
  : cmd === 'autonomy' ? ['status', 'on', 'off'] : [];
291
306
  const unexpected = positionals.filter((p) => !expected.includes(p));
@@ -323,6 +338,25 @@ async function main(argv) {
323
338
  process.stdout.write((0, colophon_1.colophon)());
324
339
  return 0;
325
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
+ }
326
360
  if (cmd === 'semantic-setup' || cmd === 'semantic-check') {
327
361
  const { runModelSetup } = await Promise.resolve().then(() => __importStar(require('../semantic/local-model')));
328
362
  return runModelSetup({ offline: cmd === 'semantic-check' });
@@ -376,6 +410,14 @@ async function main(argv) {
376
410
  }
377
411
  return reported.code;
378
412
  }
413
+ // @implements A-SPEC-702 — reads one scan and the spec store; writes only the badge and the README's
414
+ // marker region, and only when asked. The numbers never change the exit code.
415
+ if (cmd === 'attest') {
416
+ const { runAttest } = require('./attest');
417
+ const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
418
+ const exclude = typeof flags.exclude === 'string' ? flags.exclude.split(',') : [];
419
+ return runAttest({ root: target, exclude, json: flags.json === true, badge: flags.badge === true, readme: flags.readme === true }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
420
+ }
379
421
  if (cmd === 'doctor') {
380
422
  // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
381
423
  // (round-6) — the typo is the diagnosis, so say it.
@@ -386,7 +428,12 @@ async function main(argv) {
386
428
  return 2;
387
429
  }
388
430
  }
389
- 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 });
390
437
  process.stdout.write(flags.json ? JSON.stringify(checks, null, 2) + '\n' : (0, doctor_1.formatChecks)(checks) + '\n');
391
438
  return checks.some((c) => c.level === 'FAIL') ? 1 : 0;
392
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: [