@holmes-lab/holmes-kit 0.27.0 โ†’ 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +2 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-command.d.ts +9 -0
  5. package/dist/holmes/cli/agents-guidance-command.js +61 -0
  6. package/dist/holmes/cli/agents-guidance-file.d.ts +7 -0
  7. package/dist/holmes/cli/agents-guidance-file.js +86 -0
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +10 -0
  9. package/dist/holmes/cli/agents-guidance-history.js +35 -0
  10. package/dist/holmes/cli/agents-guidance-plan.d.ts +11 -0
  11. package/dist/holmes/cli/agents-guidance-plan.js +81 -0
  12. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  13. package/dist/holmes/cli/agents-guidance.js +40 -0
  14. package/dist/holmes/cli/agents.d.ts +3 -19
  15. package/dist/holmes/cli/agents.js +12 -108
  16. package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
  17. package/dist/holmes/cli/doctor-guidance.js +61 -0
  18. package/dist/holmes/cli/doctor.d.ts +2 -0
  19. package/dist/holmes/cli/doctor.js +5 -1
  20. package/dist/holmes/cli/index.js +31 -3
  21. package/dist/holmes/cli/init.js +32 -5
  22. package/dist/holmes/cli/upgrade.js +23 -26
  23. package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
  24. package/dist/holmes/cli/worktree-readiness.js +81 -0
  25. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  26. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  27. package/dist/holmes/mcp/handlers.d.ts +50 -46
  28. package/dist/holmes/mcp/handlers.js +6 -3
  29. package/dist/holmes/mcp/tool-schemas.js +6 -1
  30. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  31. package/dist/holmes/project/workspace-checkout.js +74 -0
  32. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  33. package/dist/holmes/project/workspace-preflight.js +99 -0
  34. package/docs/install-guide.md +54 -0
  35. package/package.json +1 -1
  36. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
package/CHANGELOG.md CHANGED
@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.28.0] - 2026-09-21
9
+
10
+ Holmes-Kit can now keep its governed operating discipline consistent while a
11
+ team uses Superpowers across Claude Code, Codex CLI, and Antigravity.
12
+
13
+ ### Added
14
+ - **Managed common `AGENTS.md` guidance across all three harnesses**
15
+ (A-SPEC-707 through A-SPEC-711). `holmes-kit guidance check` reports an
16
+ outdated or locally conflicted managed block, and `guidance refresh` plans
17
+ then applies only the Holmes-owned block while retaining repository-local
18
+ additions. `doctor` includes the same check, so an installed project sees
19
+ guidance drift before an agent starts work.
20
+ - **Workspace binding preflight and readiness diagnostics** (A-SPEC-703,
21
+ A-SPEC-704). `workspace_preflight` reads the server's bound root and store
22
+ before an edit and reports a foreign caller as a mismatch without registering
23
+ or rebinding it. `holmes-kit doctor --agent <claude|codex|antigravity>`
24
+ checks local wiring prerequisites and labels live hook enforcement as
25
+ unverified until it is actually observed.
26
+ - **A governed Superpowers compatibility playbook and coexistence coverage**
27
+ (A-SPEC-705, A-SPEC-706). The packaged playbook maps Superpowers design,
28
+ worktree, TDD, review, and finishing steps to the Holmes spec, evidence, and
29
+ approval chain. Deterministic harness fixtures and built-MCP subprocess tests
30
+ preserve neighboring configuration and isolate foreign roots. They do not
31
+ claim a live linked-worktree, paid harness session, or an unobserved
32
+ Antigravity multi-replace payload passed.
33
+
8
34
  ## [0.27.0] - 2026-09-20
9
35
 
10
36
  A repository can now say, as a number anyone can reproduce, how much of it is governed.
package/README.md CHANGED
@@ -23,6 +23,8 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) โ€” reproduce with `hol
23
23
 
24
24
  ### ๐Ÿ›ก๏ธ Currently Supported Features (Production Features)
25
25
 
26
+ - ๐Ÿงญ **One governed operating contract survives every harness** *(new in 0.28.0)*: the common managed block in `AGENTS.md` carries the same No Spec, No Code rules to Claude Code, Codex CLI, and Antigravity while leaving the repository's own rules outside the block intact. `holmes-kit guidance check` names a stale or locally conflicted managed block, `guidance refresh` first plans the change and then replaces only the Holmes-owned region, and `doctor` runs the same check. An installer or upgrader cannot silently discard local guidance.
27
+ - ๐Ÿงท **A worktree can prove which workspace the MCP server serves before an edit** *(new in 0.28.0)*: `workspace_preflight` returns the bound root/store identity and reports a foreign caller as a mismatch without registering, rebinding, or writing anything. `holmes-kit doctor --agent claude|codex|antigravity` checks each harness's local wiring prerequisites and states that preparation is not evidence of live hook enforcement. This is paired with a packaged Superpowers compatibility playbook that preserves Holmes specifications, RED/GREEN evidence, review closure, and finish/reconciliation requirements through the corresponding Superpowers workflow. Fixture and subprocess coverage preserve neighboring configuration and foreign-root isolation; live linked-worktree and paid-harness acceptance remain explicitly unverified until observed.
26
28
  - ๐Ÿ“ **Say how much of the repository is governed โ€” as a number, not a label** *(new in 0.27.0)*: `holmes-kit attest` reports how many scanned source files are anchored to an **approved** spec, beside how many approved A-SPECs are anchored from code, and says where that is true (commit, plus a digest of the approved specs) so anyone can reproduce it. No new judgement: the scanner's files, the anchors, the existing link census. A per-file "generated under holmes-kit" header was declined โ€” it is a claim that survives an ungoverned edit, and line 1 already carries the anchor a gate verifies. `--exclude a,b` names vendored trees at a path boundary and is echoed in every output; what cannot be measured is `n/a`, never `0%`; `100` appears only when every file is traced. `--badge` writes a self-contained local SVG, and `--readme` rewrites **only** the region between the `holmes-kit:attest` markers โ€” a README without them is never touched, and a half marker is refused. A statement, not a gate: the numbers never change the exit code.
27
29
  - ๐Ÿค **The collision plan runs under one approval** *(new in 0.26.2)*: 0.26.1 saw a spec number another machine took and printed the plan; carrying it out was still one `spec_renumber` call per family, and that tool's apply asks for no approval although it rewrites approved documents and source anchors. `spec_reconcile` `plan` is read-only and returns the moves, what each rewrites, the re-seal order, the prose it will **not** touch, and a `target` derived from the plan's content alone. `apply` rebuilds the plan inside the store hold, refuses `plan-changed` if a fetch moved it since you looked, demands one `config-write` approval bound to that `target`, and runs every move through the path `spec_renumber` already uses. Forged `moves` are never read โ€” what runs is the recomputed plan. It never seals: `spec_approve` stays the only sealer. No remote is an answer, not a refusal.
28
30
  - ๐Ÿ”ข **A spec number another machine took is seen before the merge** *(new in 0.26.1)*: two checkouts allocated `REQ-694` thirteen minutes apart, neither could see the other, and it surfaced only as an add/add conflict after the push was refused โ€” a rebuilt slice and five out-of-band approvals. `doctor --target` now reads each remote-tracking ref **as last fetched** (no network) and judges only the documents each side *added* since they parted, so a spec one side merely edited is divergence, not an alarm. On a collision the advice is the plan: `Before merging โ€” move 901 โ†’ 903: spec_renumber(oldBase=901, newBase=903); then re-seal`. The side that moves is the one not published yet, the destination is free on both sides, and "published" means equal content โ€” never path, because a spec's path is its number.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 4ec4b788-mu9vw1zt
1
+ d3435c3a-muahvazn
@@ -0,0 +1,9 @@
1
+ import type { GuidancePlan } from './agents-guidance-plan';
2
+ export declare function runGuidanceCommand(args: {
3
+ target: string;
4
+ operation: 'check' | 'refresh';
5
+ dryRun: boolean;
6
+ }): {
7
+ exitCode: number;
8
+ plan: GuidancePlan;
9
+ };
@@ -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.runGuidanceCommand = runGuidanceCommand;
37
+ // @implements A-SPEC-709
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 runGuidanceCommand(args) {
43
+ const file = path.join(args.target, 'AGENTS.md');
44
+ let plan;
45
+ try {
46
+ if (!fs.statSync(args.target).isDirectory())
47
+ throw new Error('Target must be an existing directory');
48
+ plan = (0, agents_guidance_plan_1.planGuidance)((0, agents_guidance_file_1.readGuidanceFile)(file));
49
+ }
50
+ catch (e) {
51
+ return { exitCode: 2, plan: { state: 'conflict', before: null, after: null, reasons: [`${file}: ${String(e)}`], preserved: [] } };
52
+ }
53
+ if (plan.after === null)
54
+ return { exitCode: 2, plan };
55
+ if (args.operation === 'check')
56
+ return { exitCode: plan.state === 'current' ? 0 : 1, plan };
57
+ if (args.dryRun)
58
+ return { exitCode: 0, plan };
59
+ const applied = (0, agents_guidance_file_1.applyGuidancePlan)(file, plan);
60
+ return applied.ok ? { exitCode: 0, plan } : { exitCode: 2, plan: { ...plan, after: null, reasons: [applied.reason ?? 'Publication failed'] } };
61
+ }
@@ -0,0 +1,7 @@
1
+ import type { GuidancePlan } from './agents-guidance-plan';
2
+ export declare function readGuidanceFile(file: string): string | null;
3
+ export declare function applyGuidancePlan(file: string, plan: GuidancePlan): {
4
+ ok: boolean;
5
+ changed: boolean;
6
+ reason?: string;
7
+ };
@@ -0,0 +1,86 @@
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.readGuidanceFile = readGuidanceFile;
37
+ exports.applyGuidancePlan = applyGuidancePlan;
38
+ // @implements A-SPEC-709
39
+ const fs = __importStar(require("node:fs"));
40
+ const path = __importStar(require("node:path"));
41
+ const node_crypto_1 = require("node:crypto");
42
+ function readGuidanceFile(file) {
43
+ try {
44
+ const stat = fs.lstatSync(file);
45
+ if (!stat.isFile() || stat.isSymbolicLink())
46
+ throw new Error(`Refusing nonregular guidance target: ${file}`);
47
+ return fs.readFileSync(file, 'utf8');
48
+ }
49
+ catch (e) {
50
+ if (e.code === 'ENOENT')
51
+ return null;
52
+ throw e;
53
+ }
54
+ }
55
+ function applyGuidancePlan(file, plan) {
56
+ let temp;
57
+ try {
58
+ if (plan.after === null)
59
+ throw new Error(plan.reasons.join(' '));
60
+ if (readGuidanceFile(file) !== plan.before)
61
+ throw new Error(`Guidance changed since planning: ${file}`);
62
+ if (plan.after === plan.before)
63
+ return { ok: true, changed: false };
64
+ const mode = plan.before === null ? 0o644 : fs.statSync(file).mode & 0o777;
65
+ temp = path.join(path.dirname(file), `.holmes-guidance-${(0, node_crypto_1.randomUUID)()}.tmp`);
66
+ fs.writeFileSync(temp, plan.after, { flag: 'wx', mode });
67
+ if (plan.before !== null)
68
+ fs.chmodSync(temp, mode);
69
+ if (readGuidanceFile(file) !== plan.before)
70
+ throw new Error(`Guidance changed before publication: ${file}`);
71
+ fs.renameSync(temp, file);
72
+ temp = undefined;
73
+ return { ok: true, changed: true };
74
+ }
75
+ catch (e) {
76
+ return { ok: false, changed: false, reason: e instanceof Error ? e.message : String(e) };
77
+ }
78
+ finally {
79
+ if (temp) {
80
+ try {
81
+ fs.unlinkSync(temp);
82
+ }
83
+ catch { /* only our exclusive temporary file */ }
84
+ }
85
+ }
86
+ }
@@ -0,0 +1,10 @@
1
+ export declare const GUIDANCE_HISTORY: readonly {
2
+ source: string;
3
+ enforced: boolean;
4
+ body: string;
5
+ }[];
6
+ export declare const CURRENT_GUIDANCE_REVISION = 1;
7
+ export declare const GUIDANCE_REVISIONS: readonly {
8
+ revision: number;
9
+ body: string;
10
+ }[];
@@ -0,0 +1,35 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.GUIDANCE_REVISIONS = exports.CURRENT_GUIDANCE_REVISION = exports.GUIDANCE_HISTORY = void 0;
4
+ // @implements A-SPEC-708
5
+ // Immutable migration evidence from Git; never regenerate from the current renderer.
6
+ exports.GUIDANCE_HISTORY = [
7
+ {
8
+ "source": "d23b65cf^",
9
+ "enforced": true,
10
+ "body": "# Holmes-Kit โ€” Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - Use only `spec_slice_init`, `spec_slice_approve`, `spec_create`, and `spec_approve` MCP tools to author and seal specs.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - 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.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. Run `spec_slice_init` or `spec_create` to author REQ -> H-SPEC -> A-SPEC.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **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.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `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.\n\n## Enforcement in this Harness\n\nGates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.\n"
11
+ },
12
+ {
13
+ "source": "d23b65cf^",
14
+ "enforced": false,
15
+ "body": "# Holmes-Kit โ€” Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - Use only `spec_slice_init`, `spec_slice_approve`, `spec_create`, and `spec_approve` MCP tools to author and seal specs.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - 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.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. Run `spec_slice_init` or `spec_create` to author REQ -> H-SPEC -> A-SPEC.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **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.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `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.\n\n## Enforcement in this Harness\n\nThis harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.\n"
16
+ },
17
+ {
18
+ "source": "d23b65cf",
19
+ "enforced": true,
20
+ "body": "# Holmes-Kit โ€” Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - `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.\n - **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.\n - 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.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - 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.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. 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.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **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.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `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.\n\n## Enforcement in this Harness\n\nGates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.\n"
21
+ },
22
+ {
23
+ "source": "d23b65cf",
24
+ "enforced": false,
25
+ "body": "# Holmes-Kit โ€” Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - `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.\n - **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.\n - 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.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - 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.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. 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.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **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.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `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.\n\n## Enforcement in this Harness\n\nThis harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.\n"
26
+ }
27
+ ];
28
+ // Revisioned generated baseline captured from 68611c61; append, never overwrite, on policy changes.
29
+ exports.CURRENT_GUIDANCE_REVISION = 1;
30
+ exports.GUIDANCE_REVISIONS = [
31
+ {
32
+ "revision": 1,
33
+ "body": "# Holmes-Kit โ€” Workspace Operational Discipline\n\nThis repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.\n\n## 3 Core Operational Rules\n\n1. **Tool-First Principle (NO Workaround Scripts)**:\n - Creating or mutating `.ax/specs` or governance ledgers via arbitrary temporary scripts (`/tmp/*.js`) is strictly forbidden.\n - `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.\n - **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.\n - 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.\n\n2. **Anchor-First Principle (Mandatory Code Anchors)**:\n - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: `// @` + `implements A-SPEC-XXX`.\n\n3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:\n - 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.\n - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the `spec_remediate` MCP tool / `holmes-remediation` playbook skill.\n\n## Procedure\n\n1. 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.\n2. Approve specs via `spec_slice_approve` or `spec_approve`.\n3. **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.\n4. **Write tests first** and verify failure (RED stage).\n5. Approve the mirroring T-SPEC (`A-SPEC-188` -> `T-SPEC-188`).\n6. Implement source code (GREEN stage).\n\nUse `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.\n\n## Enforcement in this Harness\n\nHook enforcement depends on the active harness and loaded configuration. Preparation diagnostics do not prove live enforcement; verify the current session before relying on gates. Unresolved critical findings block completion.\n"
34
+ }
35
+ ];
@@ -0,0 +1,11 @@
1
+ export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
2
+ export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
3
+ export type GuidanceState = 'current' | 'missing' | 'outdated-known' | 'legacy-known' | 'conflict' | 'invalid-markers';
4
+ export interface GuidancePlan {
5
+ state: GuidanceState;
6
+ before: string | null;
7
+ after: string | null;
8
+ reasons: string[];
9
+ preserved: string[];
10
+ }
11
+ export declare function planGuidance(existing: string | null): GuidancePlan;
@@ -0,0 +1,81 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MANAGED_END = exports.MANAGED_BEGIN = void 0;
4
+ exports.planGuidance = planGuidance;
5
+ // @implements A-SPEC-708
6
+ const node_crypto_1 = require("node:crypto");
7
+ const agents_guidance_1 = require("./agents-guidance");
8
+ const agents_guidance_history_1 = require("./agents-guidance-history");
9
+ exports.MANAGED_BEGIN = '<!-- holmes-kit:managed:begin -->';
10
+ exports.MANAGED_END = '<!-- holmes-kit:managed:end -->';
11
+ const lf = (s) => s.replace(/\r\n/g, '\n');
12
+ const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(lf(s)).digest('hex');
13
+ const obsolete = (s) => /only[^\r\n]*to author and seal specs/i.test(s);
14
+ const splitSections = (s) => s.split(/(?=^## )/m);
15
+ function planGuidance(existing) {
16
+ const body = (0, agents_guidance_1.renderCommonGuidance)();
17
+ const metadata = `<!-- holmes-kit:guidance format=1 revision=${agents_guidance_history_1.CURRENT_GUIDANCE_REVISION} sha256=${digest(body)} -->`;
18
+ const inner = `${metadata}\n${body}`;
19
+ const block = `${exports.MANAGED_BEGIN}\n${inner}${exports.MANAGED_END}`;
20
+ const result = (state, after, reasons = [], preserved = []) => ({ state, before: existing, after, reasons, preserved });
21
+ if (!agents_guidance_history_1.GUIDANCE_REVISIONS.some(r => r.revision === agents_guidance_history_1.CURRENT_GUIDANCE_REVISION && r.body === body))
22
+ return result('conflict', null, ['Renderer changed without a registered guidance revision; update the versioned baseline before shipping.']);
23
+ if (existing === null || existing === '')
24
+ return result('missing', `${block}\n`);
25
+ const begins = existing.split(exports.MANAGED_BEGIN).length - 1;
26
+ const ends = existing.split(exports.MANAGED_END).length - 1;
27
+ if (begins || ends) {
28
+ const b = existing.indexOf(exports.MANAGED_BEGIN), e = existing.indexOf(exports.MANAGED_END);
29
+ if (begins !== 1 || ends !== 1 || e < b)
30
+ return result('invalid-markers', null, ['AGENTS.md requires exactly one ordered managed marker pair. Repair markers before refresh.']);
31
+ const prefix = existing.slice(0, b), suffix = existing.slice(e + exports.MANAGED_END.length);
32
+ if (obsolete(prefix + '\n' + suffix))
33
+ return result('conflict', null, ['Obsolete authoring prohibition outside the managed block; review project instructions.']);
34
+ const raw = lf(existing.slice(b + exports.MANAGED_BEGIN.length, e));
35
+ if (!raw.startsWith('\n'))
36
+ return result('invalid-markers', null, ['Managed begin marker must end its line.']);
37
+ const content = raw.slice(1);
38
+ if (content === inner)
39
+ return result('current', existing);
40
+ if (content.startsWith('<!-- holmes-kit:guidance')) {
41
+ const match = /^<!-- holmes-kit:guidance format=(\d+) revision=(\d+) sha256=([a-f0-9]{64}) -->\n([\s\S]*)$/.exec(content);
42
+ if (!match || match[1] !== '1' || digest(match[4]) !== match[3] || !agents_guidance_history_1.GUIDANCE_REVISIONS.some(r => String(r.revision) === match[2] && lf(r.body) === match[4]))
43
+ return result('conflict', null, ['Unknown or edited guidance revision/digest; review the managed body before refresh.']);
44
+ }
45
+ else if (content !== body && !agents_guidance_history_1.GUIDANCE_HISTORY.some(h => lf(h.body) === content)) {
46
+ return result('conflict', null, ['Managed body differs from all known generated versions; preserve and review local edits.']);
47
+ }
48
+ return result('outdated-known', prefix + block + suffix, ['Replace recognized generated guidance.']);
49
+ }
50
+ // Match complete sections in order. A modified section is never reduced to matching lines.
51
+ // Preserve offsets from the original text so custom sections retain their line endings.
52
+ const actual = splitSections(existing);
53
+ const histories = [...agents_guidance_history_1.GUIDANCE_HISTORY.map(h => h.body), body];
54
+ for (const historical of histories) {
55
+ const expected = splitSections(historical);
56
+ let next = 0;
57
+ const custom = [];
58
+ let bad = false;
59
+ const headings = new Set(expected.map(s => lf(s).split('\n')[0]));
60
+ for (const section of actual) {
61
+ const normalized = lf(section).trimEnd();
62
+ if (next < expected.length && normalized === lf(expected[next]).trimEnd()) {
63
+ next++;
64
+ continue;
65
+ }
66
+ const heading = lf(section).split('\n')[0];
67
+ if (headings.has(heading) || section.includes('# Holmes-Kit โ€” Workspace Operational Discipline')) {
68
+ bad = true;
69
+ break;
70
+ }
71
+ custom.push(section);
72
+ }
73
+ if (!bad && next === expected.length) {
74
+ const outside = custom.join('');
75
+ if (obsolete(outside))
76
+ return result('conflict', null, ['Obsolete authoring prohibition in a project section; review before migration.']);
77
+ return result('legacy-known', `${block}\n${outside ? '\n' + outside : ''}`, ['Migrate recognized complete historical sections.'], custom.map(s => s.split(/\r?\n/)[0]));
78
+ }
79
+ }
80
+ return result('conflict', null, ['Unrecognized or mixed legacy guidance; review a managed-block migration without deleting project instructions.']);
81
+ }
@@ -0,0 +1 @@
1
+ export declare const renderCommonGuidance: () => string;
@@ -0,0 +1,40 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.renderCommonGuidance = void 0;
4
+ // @implements A-SPEC-707
5
+ // Pure common discipline; runtime capabilities belong to the harness registry.
6
+ const renderCommonGuidance = () => `# Holmes-Kit โ€” Workspace Operational Discipline
7
+
8
+ This repository operates under **No Spec, No Code** governance. An approved specification MUST exist before writing source or test code.
9
+
10
+ ## 3 Core Operational Rules
11
+
12
+ 1. **Tool-First Principle (NO Workaround Scripts)**:
13
+ - Creating or mutating \`.ax/specs\` or governance ledgers via arbitrary temporary scripts (\`/tmp/*.js\`) is strictly forbidden.
14
+ - \`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.
15
+ - **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.
16
+ - 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.
17
+
18
+ 2. **Anchor-First Principle (Mandatory Code Anchors)**:
19
+ - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: \`// @\` + \`implements A-SPEC-XXX\`.
20
+
21
+ 3. **Remediation Protocol (NO Guardrail Reverse Engineering)**:
22
+ - 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.
23
+ - Immediately follow the 3-step remediation instructions provided in the refusal message or invoke the \`spec_remediate\` MCP tool / \`holmes-remediation\` playbook skill.
24
+
25
+ ## Procedure
26
+
27
+ 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.
28
+ 2. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
29
+ 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.
30
+ 4. **Write tests first** and verify failure (RED stage).
31
+ 5. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
32
+ 6. Implement source code (GREEN stage).
33
+
34
+ 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.
35
+
36
+ ## Enforcement in this Harness
37
+
38
+ Hook enforcement depends on the active harness and loaded configuration. Preparation diagnostics do not prove live enforcement; verify the current session before relying on gates. Unresolved critical findings block completion.
39
+ `;
40
+ exports.renderCommonGuidance = renderCommonGuidance;
@@ -70,25 +70,9 @@ export declare function shortPathIfSpaced(p: string): string;
70
70
  * space, or win32 where 8.3 resolved it).
71
71
  */
72
72
  export declare function antigravityHookWarnings(packageRoot: string): string[];
73
- export declare const AGENTS_MD: (enforced: boolean) => string;
74
- export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
75
- export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
76
- /**
77
- * @implements A-SPEC-576.2
78
- * The regeneration that keeps what it did not write.
79
- *
80
- * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
81
- * commit had added the day before โ€” and said nothing, so the loss was found weeks later by grep.
82
- * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
83
- * whose repository this is.
84
- *
85
- * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
86
- * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 ยง9).
87
- *
88
- * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
89
- * would be the same silent loss in a new costume.
90
- */
91
- export declare function mergeAgentsMd(existing: string | null, generated: string): {
73
+ export declare const AGENTS_MD: (_enforced: boolean) => string;
74
+ export { MANAGED_BEGIN, MANAGED_END } from './agents-guidance-plan';
75
+ export declare function mergeAgentsMd(existing: string | null, _generated: string): {
92
76
  content: string;
93
77
  preserved: string[];
94
78
  note: string | null;
@@ -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,2 @@
1
+ import type { Check } from './doctor-check';
2
+ export declare function guidanceChecks(packageRoot: string, target: string): Check[];