@holmes-lab/holmes-kit 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +21 -17
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-command.d.ts +9 -0
  5. package/dist/holmes/cli/agents-guidance-command.js +61 -0
  6. package/dist/holmes/cli/agents-guidance-file.d.ts +7 -0
  7. package/dist/holmes/cli/agents-guidance-file.js +86 -0
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +10 -0
  9. package/dist/holmes/cli/agents-guidance-history.js +35 -0
  10. package/dist/holmes/cli/agents-guidance-plan.d.ts +11 -0
  11. package/dist/holmes/cli/agents-guidance-plan.js +81 -0
  12. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  13. package/dist/holmes/cli/agents-guidance.js +40 -0
  14. package/dist/holmes/cli/agents.d.ts +3 -19
  15. package/dist/holmes/cli/agents.js +12 -108
  16. package/dist/holmes/cli/doctor-guidance.d.ts +2 -0
  17. package/dist/holmes/cli/doctor-guidance.js +61 -0
  18. package/dist/holmes/cli/doctor.d.ts +2 -0
  19. package/dist/holmes/cli/doctor.js +29 -1
  20. package/dist/holmes/cli/index.js +31 -3
  21. package/dist/holmes/cli/init.js +32 -5
  22. package/dist/holmes/cli/upgrade.js +23 -26
  23. package/dist/holmes/cli/worktree-readiness.d.ts +6 -0
  24. package/dist/holmes/cli/worktree-readiness.js +81 -0
  25. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  26. package/dist/holmes/cpg/ast-mutation.js +4 -2
  27. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  28. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  29. package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
  30. package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
  31. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
  32. package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
  33. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +9 -0
  34. package/dist/holmes/mcp/handlers/workspace-preflight.js +13 -0
  35. package/dist/holmes/mcp/handlers.d.ts +157 -46
  36. package/dist/holmes/mcp/handlers.js +16 -3
  37. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
  38. package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
  39. package/dist/holmes/mcp/tool-schemas.js +19 -1
  40. package/dist/holmes/project/workspace-checkout.d.ts +8 -0
  41. package/dist/holmes/project/workspace-checkout.js +74 -0
  42. package/dist/holmes/project/workspace-preflight.d.ts +24 -0
  43. package/dist/holmes/project/workspace-preflight.js +99 -0
  44. package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
  45. package/dist/holmes/review/condition-hunk-replay.js +112 -0
  46. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  47. package/dist/holmes/review/condition-hunk-resolution.js +207 -0
  48. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  49. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  50. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  51. package/dist/holmes/review/requirement-triage.js +143 -0
  52. package/dist/holmes/semantic/local-model.d.ts +3 -3
  53. package/dist/holmes/semantic/local-model.js +10 -12
  54. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  55. package/dist/holmes/semantic/model-cache.js +77 -21
  56. package/dist/holmes/semantic/tier.d.ts +5 -1
  57. package/dist/holmes/semantic/tier.js +7 -6
  58. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  59. package/dist/holmes/semantic/vector-coverage.js +37 -0
  60. package/docs/install-guide.md +73 -24
  61. package/package.json +1 -1
  62. package/playbooks/superpowers-compat/PLAYBOOK.md +46 -0
package/CHANGELOG.md CHANGED
@@ -5,6 +5,70 @@ 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.29.0] - 2026-09-22
9
+
10
+ Holmes-Kit now prepares a local semantic layer by default and can compare a
11
+ new prompt with governed requirement lineage before an agent starts a new spec.
12
+
13
+ ### Added
14
+
15
+ - **Verified local BGE-M3 semantic preparation** (A-SPEC-712). Normal package
16
+ installation prepares the pinned public local model in the shared user cache
17
+ and activates it only after offline inference verification. The explicit
18
+ HOLMES_SKIP_MODEL_INSTALL=1 opt-out remains available. A blocked install
19
+ script, offline download, corrupt cache, or failed inference keeps the
20
+ package usable and reports a precise unavailable or degraded recovery path;
21
+ repository text never leaves the machine through this tier.
22
+ - **Read-only requirement lifecycle triage** (A-SPEC-713). The new
23
+ requirement_triage MCP tool ranks governed REQ/H-SPEC/A-SPEC/T-SPEC
24
+ lineages with deterministic BM25 and additive cached semantic candidates,
25
+ then uses content, approval, implementation-anchor, exact-HEAD execution,
26
+ and published-graph evidence to recommend fulfilled, existing-change, new,
27
+ or ambiguous. It can persist a content-addressed evidence artifact but
28
+ cannot create, edit, approve, unseal, retire, or open a source-edit gate.
29
+ - **Condition hunk advisory evidence** (A-SPEC-661). A separate, opt-in
30
+ advisory resolver maps a zero-context diff hunk through a symbol to CFG
31
+ predicate provenance and reports only locally demonstrable relaxed,
32
+ narrowed, or unknown direction. It does not change changedFiles, scanner
33
+ output, hooks, or gates. The recorded 20-commit replay found 21 resolved
34
+ predicate records from 102 symbol candidates; its measured heavy-path cost
35
+ stays outside the synchronous scanner.
36
+
37
+ ### Changed
38
+
39
+ - **Requirement-triage measurement is preregistered, not overstated.** A
40
+ 12-case frozen prompt corpus and analyst protocol record retrieval coverage,
41
+ human-choice agreement, false reuse/new, evidence completeness, ambiguity
42
+ preservation, and elapsed time as comparison/gap metrics only. No
43
+ human-superiority or release-gate claim is made before an independent blind
44
+ run supplies analyst records.
45
+
46
+ ## [0.28.0] - 2026-09-21
47
+
48
+ Holmes-Kit can now keep its governed operating discipline consistent while a
49
+ team uses Superpowers across Claude Code, Codex CLI, and Antigravity.
50
+
51
+ ### Added
52
+ - **Managed common `AGENTS.md` guidance across all three harnesses**
53
+ (A-SPEC-707 through A-SPEC-711). `holmes-kit guidance check` reports an
54
+ outdated or locally conflicted managed block, and `guidance refresh` plans
55
+ then applies only the Holmes-owned block while retaining repository-local
56
+ additions. `doctor` includes the same check, so an installed project sees
57
+ guidance drift before an agent starts work.
58
+ - **Workspace binding preflight and readiness diagnostics** (A-SPEC-703,
59
+ A-SPEC-704). `workspace_preflight` reads the server's bound root and store
60
+ before an edit and reports a foreign caller as a mismatch without registering
61
+ or rebinding it. `holmes-kit doctor --agent <claude|codex|antigravity>`
62
+ checks local wiring prerequisites and labels live hook enforcement as
63
+ unverified until it is actually observed.
64
+ - **A governed Superpowers compatibility playbook and coexistence coverage**
65
+ (A-SPEC-705, A-SPEC-706). The packaged playbook maps Superpowers design,
66
+ worktree, TDD, review, and finishing steps to the Holmes spec, evidence, and
67
+ approval chain. Deterministic harness fixtures and built-MCP subprocess tests
68
+ preserve neighboring configuration and isolate foreign roots. They do not
69
+ claim a live linked-worktree, paid harness session, or an unobserved
70
+ Antigravity multi-replace payload passed.
71
+
8
72
  ## [0.27.0] - 2026-09-20
9
73
 
10
74
  A repository can now say, as a number anyone can reproduce, how much of it is governed.
package/README.md CHANGED
@@ -23,6 +23,9 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - 🧾 **A new prompt is checked against governed intent before it becomes a new spec** *(new in 0.29.0)*: `requirement_triage` reads the approved REQ/H-SPEC/A-SPEC/T-SPEC lineage, its current RTM graph, code anchors, and exact-HEAD execution evidence before recommending `fulfilled`, `existing-change`, `new`, or `ambiguous`. BM25 is always present; a verified local BGE-M3 cache and explicit Gemini opt-in only add candidates and never decide the outcome alone. A cold, stale, unreadable, or absent evidence lane remains visible as ambiguity. `rtm_reindex` is the only operation that warms versioned requirement-document vectors; optional persistence writes one content-addressed advisory artifact and never changes a spec or opens an edit gate.
27
+ - 🧭 **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.
28
+ - 🧷 **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
29
  - 📏 **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
30
  - 🤝 **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
31
  - 🔢 **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.
@@ -71,7 +74,7 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
71
74
  - 🤖 **Autonomous approval — three layers, always bounded** *(0.8.0, reworked 0.13.0)*: a project default (`init --autonomy`) and an expiring per-session envelope let the agent seal **low-risk** specs itself under an `autonomous:<client>` actor; every governance-critical, high-risk or irreversible decision is refused and routed to the out-of-band `holmes-kit approve` queue. The agent can never grant it to itself, the posture is surfaced at every session start, and off is byte-identical to a fully human-gated project.
72
75
  - 🧭 **Compatibility and evolution gates** *(0.14.0, 0.15.0)*: a new A-SPEC seals only with `harness_impact:` and `os_impact:` declared and machine-cross-checked against Files-to-Touch; separately, a changed in-scope source that **newly introduces an external dependency** raises a spec-reappraisal — a warning when manual, a queued item under autonomy, never a blocked turn.
73
76
  - 🚢 **Release autonomy + docs-currency gate** *(0.13.0, machine-checked in 0.23.2)*: `npm publish` stays **human-approved by default** while a deterministic classifier lets a low-risk release self-publish under the ledger; a major bump or any gate-behavior/security/architecture spec forces HITL. The publish gate refuses a release whose docs never caught up — a stale doc is a false claim.
74
- - 🧠 **3-tier semantic layer** *(0.3.0)*: an explicit consent ladder — `none` (default, **zero egress**), `local` (bge-m3, no egress), `cloud` (gemini-embedding-001, opt-in). Measured on 305 traceability cases: recall 0.486 → 0.667 → **0.887**; on lexical-zero requests 0% → 52% → **92%**. Surfaced additively, never as a hard filter.
77
+ - 🧠 **3-tier semantic layer** *(local preparation default in 0.29.0)*: BGE-M3 is prepared and verified locally during a normal npm installation (zero repository-text egress); `HOLMES_SKIP_MODEL_INSTALL=1` is the explicit opt-out. `cloud` remains the opt-in `gemini-embedding-001` tier. Measured on 305 traceability cases: recall 0.486 → 0.667 → **0.887**; on lexical-zero requests 0% → 52% → **92%**. Surfaced additively, never as a hard filter.
75
78
  - 🎯 **Graded impact surface** *(0.3.0)*: `rankedImpact` (personalized PageRank over the spec/code graph) beat its pre-registered naive baseline on **both** recall and precision across 3 corpora (×1.6–×17) — measured before claimed.
76
79
  - 🐞 **Causal defect localization & CPG** *(equalized in 0.5–0.7)*: AST code property graph (CFG/DDG/CDG) and dataflow taint reachability across 7 languages — **42 language×layer cells graded on measured evidence** (11 corpora, 39,344 functions, zero invariant violations; C++ conditional on 67.9% parse coverage, disclosed in the matrix).
77
80
  - 📏 **Measured, not claimed** *(0.3.x)*: performance is judged against a pre-registered modeled-human band (R 0.67–0.78 / P ≈0.9±). Current official grade: **band entry on recall; division-of-labor precision 0.727 = 81% of the modeled human**, reproduced by an independent context-free judge on a fresh blind window. No superhuman claims until both metrics exceed the band.
@@ -178,28 +181,29 @@ npx holmes-kit doctor
178
181
  ```
179
182
  *If everything is green, your project is governed and ready for AI pair-programming!*
180
183
 
181
- ### 4. Optional: Enable the Semantic Layer (Tier `local` / Tier `cloud`)
184
+ ### 4. Local semantic layer by default; cloud remains optional
182
185
 
183
- Out of the box Holmes-Kit runs tier **`none`** — lexical + citation + graph search, **zero
184
- egress**. Two opt-in tiers raise recall on requests your vocabulary can't reach (measured on 305
185
- traceability cases — see the feature list above):
186
+ During a normal npm installation, Holmes-Kit prepares the public pinned BGE-M3 assets in a shared
187
+ user cache and enables tier **`local`** only after a real offline inference check succeeds. Local
188
+ inference has **zero repository-text egress**. BM25, citation, and graph search remain available
189
+ whether preparation succeeds or not. The optional cloud tier raises recall further on requests
190
+ your vocabulary cannot reach (measured on 305 traceability cases — see the feature list above):
186
191
 
187
- **Tier `local` — no egress, no account.** The embedding runtime ships with holmes-kit as of
188
- 0.19.4, so nothing extra to install. Preparing the model is **opt-in**: neither installation nor
189
- `init` downloads it, because a large download nobody asked for is not a default. One command:
192
+ **Tier `local` — no egress, no account.** The embedding runtime ships with holmes-kit. Package
193
+ installation attempts setup once by default; run these commands later to retry or prove readiness:
190
194
  ```bash
191
195
  npx holmes-kit semantic-setup # downloads the public bge-m3 assets once, shared across projects
192
196
  npx holmes-kit semantic-check # verifies OFFLINE inference — a real 1024-dim normalized vector
193
197
  npx holmes-kit doctor # → semantic tier: local (no egress)
194
198
  ```
195
- Until it is prepared, `doctor` reports tier **`none`** and names what that costs — requests lexical
196
- search misses (measured 16.4%) have 0% recall — together with the command that changes it. A runtime
197
- that resolves is not a tier that answers.
198
-
199
- To prepare during installation instead, set `HOLMES_AUTO_MODEL_INSTALL=1` before installing.
200
- `HOLMES_SKIP_MODEL_INSTALL=1` refuses preparation and **outranks** the opt-in, so an explicit refusal
201
- is never overridden. Models live in `~/.holmes/models` (`%USERPROFILE%\.holmes\models` on Windows);
202
- `HOLMES_MODEL_CACHE` overrides that, including for a prepopulated offline cache.
199
+ `HOLMES_SKIP_MODEL_INSTALL=1` explicitly declines automatic preparation. It never blocks an
200
+ explicit `semantic-setup` or `semantic-check`. Models live in `~/.holmes/models`
201
+ (`%USERPROFILE%\.holmes\models` on Windows); `HOLMES_MODEL_CACHE` overrides that, including for a
202
+ prepopulated offline cache. A cache activates the local tier only after successful offline inference
203
+ writes a current readiness receipt. If lifecycle scripts are blocked, the download fails, or the
204
+ cache is unverified or changed, the package remains usable: `doctor` reports **unavailable** or
205
+ **degraded** and names `semantic-setup` as the recovery command. A runtime or nonempty directory is
206
+ never treated as a working embedding tier.
203
207
 
204
208
  > **Security note.** This package's dependency chain pulls `protobufjs@6.x` through
205
209
  > `@xenova/transformers → onnxruntime-web → onnx-proto`, which carries a critical advisory. npm's
@@ -273,7 +277,7 @@ flowchart LR
273
277
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
274
278
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
275
279
  | `holmes-kit autonomy off` | End session autonomy immediately |
276
- | `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (opt-in; shared across projects) |
280
+ | `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (retry/recovery; shared across projects) |
277
281
  | `holmes-kit semantic-check` | Verify local inference **offline**, without downloading anything |
278
282
  | `holmes-kit semantic-key set` | Store the cloud-tier key outside the tree (stdin only, never argv) |
279
283
  | `holmes-kit approve --status` | The whole approval picture: workspace, delegation, per-request risk/run/subject/grant preview, recent outcomes |
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 4ec4b788-mu9vw1zt
1
+ 5fc87d4f-mubu528k
@@ -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;