domain-knowledge-kit 0.2.16 → 0.2.19

package/dist/features/agent/settings-prune.js

@@ -0,0 +1,70 @@
+/**
+ * Prune DKK-owned entries from a Claude `settings.json` payload.
+ *
+ * Used by `dkk update` to clear stale entries (e.g. hooks for scripts that
+ * have been renamed or removed) before re-applying the additive merge with
+ * the new template. User-authored entries are preserved untouched.
+ *
+ * Decision boundaries (see [[dkk-artifacts]] for the predicate source of
+ * truth):
+ *
+ * - A `permissions.allow` entry is DKK-owned iff it appears verbatim in
+ *   the bundled template's allow list. Exact string equality is the right
+ *   bar because the template's allow patterns are stable identifiers.
+ * - A `hooks.<event>` sub-entry is DKK-owned iff **every** `hooks[].command`
+ *   inside it resolves via {@link extractHookBasename} to a DKK basename.
+ *   Mixed entries (some DKK, some user-authored) are left intact and
+ *   reported as warnings — pruning them partially would mutate
+ *   user-authored data.
+ */
+import { extractHookBasename } from "./commands/init.js";
+export function pruneDkkEntries(settings, dkkAllow, dkkHookBasenames) {
+    // Deep-clone so callers can compare before/after without surprise.
+    const pruned = JSON.parse(JSON.stringify(settings));
+    const removed = [];
+    const mixedHookWarnings = [];
+    // permissions.allow — drop exact-string matches.
+    if (Array.isArray(pruned.permissions?.allow)) {
+        const before = pruned.permissions.allow;
+        const kept = [];
+        for (const entry of before) {
+            if (dkkAllow.has(entry)) {
+                removed.push(`permissions.allow: ${entry}`);
+            }
+            else {
+                kept.push(entry);
+            }
+        }
+        pruned.permissions.allow = kept;
+    }
+    // hooks.* — drop entries whose every command resolves to a DKK basename.
+    if (pruned.hooks && typeof pruned.hooks === "object") {
+        for (const [event, entries] of Object.entries(pruned.hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            const kept = [];
+            for (const entry of entries) {
+                const commands = entry.hooks ?? [];
+                if (commands.length === 0) {
+                    kept.push(entry);
+                    continue;
+                }
+                const basenames = commands.map((h) => extractHookBasename(h.command));
+                const dkkOwned = basenames.filter((b) => b !== null && dkkHookBasenames.has(b));
+                const allDkk = basenames.every((b) => b !== null && dkkHookBasenames.has(b));
+                const someDkk = dkkOwned.length > 0;
+                if (allDkk) {
+                    removed.push(`hooks.${event}: ${basenames.filter(Boolean).join(", ")}`);
+                    continue;
+                }
+                if (someDkk) {
+                    mixedHookWarnings.push(`hooks.${event}: mixed DKK/user commands left intact (DKK: ${dkkOwned.join(", ")})`);
+                }
+                kept.push(entry);
+            }
+            pruned.hooks[event] = kept;
+        }
+    }
+    return { pruned, removed, mixedHookWarnings };
+}
+//# sourceMappingURL=settings-prune.js.map

package/dist/features/agent/settings-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-prune.js","sourceRoot":"","sources":["../../../src/features/agent/settings-prune.ts"],"names":[],"mappings":"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"}

package/dist/features/agent/tests/settings-prune.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings-prune.test.d.ts.map

package/dist/features/agent/tests/settings-prune.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-prune.test.d.ts","sourceRoot":"","sources":["../../../../src/features/agent/tests/settings-prune.test.ts"],"names":[],"mappings":""}

package/dist/features/agent/tests/settings-prune.test.js

@@ -0,0 +1,118 @@
+/**
+ * Tests for the settings.json prune logic used by `dkk update`.
+ *
+ * Covers the three scenarios the update flow cares about:
+ *   1. DKK-only `permissions.allow` entries are removed; user entries stay.
+ *   2. Hook entries whose every command is DKK-owned are removed; mixed
+ *      entries (DKK + user) are kept with a warning.
+ *   3. Empty settings are handled without throwing.
+ */
+import { pruneDkkEntries } from "../settings-prune.js";
+let passed = 0;
+let failed = 0;
+function assert(label, condition, detail) {
+    if (condition) {
+        console.log(`  OK: ${label}`);
+        passed++;
+    }
+    else {
+        console.error(`FAIL: ${label}${detail ? ` — ${detail}` : ""}`);
+        failed++;
+    }
+}
+// Canonical DKK identifiers (subset — enough to exercise the prune logic).
+const DKK_ALLOW = new Set([
+    "Bash(dkk list:*)",
+    "Bash(dkk show:*)",
+    "Bash(dkk validate:*)",
+]);
+const DKK_HOOKS = new Set([
+    "session-start-prime.mjs",
+    "post-edit-validate.mjs",
+]);
+console.log("\n=== prune: removes only DKK-owned permissions.allow entries ===");
+{
+    const input = {
+        permissions: {
+            allow: [
+                "Bash(dkk list:*)", // DKK-owned
+                "Bash(dkk show:*)", // DKK-owned
+                "Bash(myproject build:*)", // user-authored
+                "Bash(custom thing:*)", // user-authored
+            ],
+        },
+    };
+    const { pruned, removed } = pruneDkkEntries(input, DKK_ALLOW, DKK_HOOKS);
+    assert("user entries preserved", pruned.permissions?.allow?.includes("Bash(myproject build:*)") === true &&
+        pruned.permissions?.allow?.includes("Bash(custom thing:*)") === true);
+    assert("DKK entries removed from permissions.allow", pruned.permissions?.allow?.includes("Bash(dkk list:*)") === false &&
+        pruned.permissions?.allow?.includes("Bash(dkk show:*)") === false);
+    assert("removed list reports DKK entries", removed.length === 2);
+}
+console.log("\n=== prune: removes hook entries whose every command is DKK ===");
+{
+    const input = {
+        hooks: {
+            SessionStart: [
+                {
+                    // DKK-only entry — should be dropped.
+                    hooks: [
+                        { type: "command", command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-prime.mjs"' },
+                    ],
+                },
+                {
+                    // User-only entry — should be preserved.
+                    hooks: [{ type: "command", command: "echo user-hook" }],
+                },
+            ],
+        },
+    };
+    const { pruned } = pruneDkkEntries(input, DKK_ALLOW, DKK_HOOKS);
+    const remaining = pruned.hooks?.SessionStart ?? [];
+    assert("DKK-only hook entry removed", remaining.length === 1);
+    assert("user hook entry preserved", remaining[0]?.hooks?.[0]?.command === "echo user-hook");
+}
+console.log("\n=== prune: leaves mixed hook entries alone with a warning ===");
+{
+    const input = {
+        hooks: {
+            SessionStart: [
+                {
+                    hooks: [
+                        { type: "command", command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-prime.mjs"' },
+                        { type: "command", command: "echo also-user-hook" },
+                    ],
+                },
+            ],
+        },
+    };
+    const { pruned, mixedHookWarnings } = pruneDkkEntries(input, DKK_ALLOW, DKK_HOOKS);
+    assert("mixed entry preserved verbatim", pruned.hooks?.SessionStart?.length === 1);
+    assert("mixed warning emitted", mixedHookWarnings.length === 1);
+    assert("mixed warning names the DKK hook", mixedHookWarnings[0].includes("session-start-prime.mjs"));
+}
+console.log("\n=== prune: tolerates empty / missing fields ===");
+{
+    const empty = {};
+    const { pruned, removed, mixedHookWarnings } = pruneDkkEntries(empty, DKK_ALLOW, DKK_HOOKS);
+    assert("empty settings → no removed entries", removed.length === 0);
+    assert("empty settings → no mixed warnings", mixedHookWarnings.length === 0);
+    // Deep clone returns an object that's structurally equivalent (also empty).
+    assert("empty settings round-trip", JSON.stringify(pruned) === "{}");
+}
+console.log("\n=== prune: drops empty allow list entries cleanly ===");
+{
+    const input = {
+        permissions: {
+            allow: ["Bash(dkk list:*)", "Bash(dkk show:*)", "Bash(dkk validate:*)"],
+        },
+    };
+    const { pruned, removed } = pruneDkkEntries(input, DKK_ALLOW, DKK_HOOKS);
+    assert("all DKK entries removed", pruned.permissions?.allow?.length === 0);
+    assert("removed list has 3 entries", removed.length === 3);
+}
+// ── Summary ───────────────────────────────────────────────────────────
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0)
+    process.exit(1);
+//# sourceMappingURL=settings-prune.test.js.map

package/dist/features/agent/tests/settings-prune.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-prune.test.js","sourceRoot":"","sources":["../../../../src/features/agent/tests/settings-prune.test.ts"],"names":[],"mappings":"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"}

package/dist/features/scaffold/commands/new-domain.d.ts

@@ -8,7 +8,29 @@
  *     context.yml, events/, commands/, aggregates/, policies/, read-models/
  *
  * Errors if `.dkk/domain/` already exists (use `--force` to overwrite).
+ *
+ * The scaffold logic is also exported as `scaffoldDomain()` so `dkk init`
+ * can bootstrap the same structure during project initialization.
  */
 import type { Command as Cmd } from "commander";
+export type ScaffoldDomainStatus = "created" | "skipped" | "replaced";
+export interface ScaffoldDomainResult {
+    status: ScaffoldDomainStatus;
+    path: string;
+}
+/**
+ * Scaffold `.dkk/domain/` with sample content.
+ *
+ * - If the directory does not exist, creates it (`status: "created"`).
+ * - If it exists and `force` is false, leaves it untouched (`status: "skipped"`).
+ * - If it exists and `force` is true, removes it entirely first, then
+ *   creates a fresh scaffold (`status: "replaced"`).
+ */
+export declare function scaffoldDomain(opts?: {
+    root?: string;
+    force?: boolean;
+}): ScaffoldDomainResult;
+/** Files created by a successful scaffold — used by callers that print their own report. */
+export declare const SCAFFOLD_DOMAIN_FILES: readonly string[];
 export declare function registerNewDomain(program: Cmd): void;
 //# sourceMappingURL=new-domain.d.ts.map

package/dist/features/scaffold/commands/new-domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"new-domain.d.ts","sourceRoot":"","sources":["../../../../src/features/scaffold/commands/new-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AA0DhD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CA6DpD"}
+{"version":3,"file":"new-domain.d.ts","sourceRoot":"","sources":["../../../../src/features/scaffold/commands/new-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AA0DhD,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,oBAAoB,CA0BlG;AAED,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAOlD,CAAC;AAIF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAmCpD"}

package/dist/features/scaffold/commands/new-domain.js

@@ -45,6 +45,45 @@ emits:
   events:
     - SampleCreated
 `;
+/**
+ * Scaffold `.dkk/domain/` with sample content.
+ *
+ * - If the directory does not exist, creates it (`status: "created"`).
+ * - If it exists and `force` is false, leaves it untouched (`status: "skipped"`).
+ * - If it exists and `force` is true, removes it entirely first, then
+ *   creates a fresh scaffold (`status: "replaced"`).
+ */
+export function scaffoldDomain(opts = {}) {
+    const dir = domainDir(opts.root);
+    if (existsSync(dir) && !opts.force) {
+        return { status: "skipped", path: dir };
+    }
+    const replaced = existsSync(dir) && (opts.force ?? false);
+    if (replaced) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    const contextsBase = join(dir, "contexts", "sample");
+    const subDirs = ["events", "commands", "aggregates", "policies", "read-models"];
+    for (const sub of subDirs) {
+        mkdirSync(join(contextsBase, sub), { recursive: true });
+    }
+    writeFileSync(join(dir, "index.yml"), INDEX_YML, "utf-8");
+    writeFileSync(join(dir, "actors.yml"), ACTORS_YML, "utf-8");
+    writeFileSync(join(contextsBase, "context.yml"), CONTEXT_YML, "utf-8");
+    writeFileSync(join(contextsBase, "events", "SampleCreated.yml"), SAMPLE_EVENT, "utf-8");
+    writeFileSync(join(contextsBase, "commands", "CreateSample.yml"), SAMPLE_COMMAND, "utf-8");
+    writeFileSync(join(contextsBase, "aggregates", "Sample.yml"), SAMPLE_AGGREGATE, "utf-8");
+    return { status: replaced ? "replaced" : "created", path: dir };
+}
+/** Files created by a successful scaffold — used by callers that print their own report. */
+export const SCAFFOLD_DOMAIN_FILES = [
+    "index.yml",
+    "actors.yml",
+    "contexts/sample/context.yml",
+    "contexts/sample/events/SampleCreated.yml",
+    "contexts/sample/commands/CreateSample.yml",
+    "contexts/sample/aggregates/Sample.yml",
+];
 // ── Registration ──────────────────────────────────────────────────────
 export function registerNewDomain(program) {
     program
@@ -56,44 +95,21 @@ export function registerNewDomain(program) {
         .option("--minify", "Minify JSON")
         .action((opts) => {
         const dir = domainDir(opts.root);
-        // Guard: refuse to overwrite unless --force
         if (existsSync(dir) && !opts.force) {
             console.error(`Error: ${dir} already exists. Use --force to replace it entirely.`);
             process.exit(1);
         }
-        // --force: remove the entire domain directory so the scaffold is applied
-        // to a clean slate (no silent merging of pre-existing content).
-        if (existsSync(dir) && opts.force) {
-            rmSync(dir, { recursive: true, force: true });
-        }
-        // Create directory structure
-        const contextsBase = join(dir, "contexts", "sample");
-        const subDirs = ["events", "commands", "aggregates", "policies", "read-models"];
-        for (const sub of subDirs) {
-            mkdirSync(join(contextsBase, sub), { recursive: true });
-        }
-        // Write files
-        writeFileSync(join(dir, "index.yml"), INDEX_YML, "utf-8");
-        writeFileSync(join(dir, "actors.yml"), ACTORS_YML, "utf-8");
-        writeFileSync(join(contextsBase, "context.yml"), CONTEXT_YML, "utf-8");
-        writeFileSync(join(contextsBase, "events", "SampleCreated.yml"), SAMPLE_EVENT, "utf-8");
-        writeFileSync(join(contextsBase, "commands", "CreateSample.yml"), SAMPLE_COMMAND, "utf-8");
-        writeFileSync(join(contextsBase, "aggregates", "Sample.yml"), SAMPLE_AGGREGATE, "utf-8");
+        const result = scaffoldDomain({ root: opts.root, force: opts.force });
         if (opts.json) {
             console.log(JSON.stringify({
-                path: dir,
-                success: true
+                path: result.path,
+                success: true,
             }, null, opts.minify ? 0 : 2));
             return;
         }
         console.log("Created .dkk/domain/ with sample content:");
-        console.log("  index.yml");
-        console.log("  actors.yml");
-        console.log("  contexts/sample/");
-        console.log("    context.yml");
-        console.log("    events/SampleCreated.yml");
-        console.log("    commands/CreateSample.yml");
-        console.log("    aggregates/Sample.yml");
+        for (const f of SCAFFOLD_DOMAIN_FILES)
+            console.log(`  ${f}`);
         console.log("\nRun `dkk render` to validate and generate documentation.");
     });
 }

package/dist/features/scaffold/commands/new-domain.js.map

@@ -1 +1 @@
-{"version":3,"file":"new-domain.js","sourceRoot":"","sources":["../../../../src/features/scaffold/commands/new-domain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"new-domain.js","sourceRoot":"","sources":["../../../../src/features/scaffold/commands/new-domain.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+export declare const pkgVersion: string;
+/** Name of the package on the npm registry. Used by `dkk update`. */
+export declare const pkgName = "domain-knowledge-kit";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,UAAU,QAEd,CAAC;AAEV,qEAAqE;AACrE,eAAO,MAAM,OAAO,yBAAyB,CAAC"}

package/dist/version.js

@@ -0,0 +1,15 @@
+/**
+ * Package version, read at runtime from `package.json`.
+ *
+ * Works in both dev (`src/version.ts`) and build (`dist/version.js`) because
+ * `package.json` is one level above either entrypoint. Computed once at
+ * module load.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../package.json");
+export const pkgVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+/** Name of the package on the npm registry. Used by `dkk update`. */
+export const pkgName = "domain-knowledge-kit";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,OAAO,GAAG,OAAO,CACrB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,iBAAiB,CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GACrB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CACzC,CAAC,OAAO,CAAC;AAEV,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-knowledge-kit",
-  "version": "0.2.16",
+  "version": "0.2.19",
   "description": "Domain Knowledge Pack — YAML + ADR links + deterministic search + generated docs",
   "type": "module",
   "repository": {
@@ -39,7 +39,6 @@
   "keywords": [],
   "license": "Elastic-2.0",
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "eslint": "^10.0.1",
     "tsx": "^4.7.0",
@@ -49,9 +48,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/better-sqlite3": "^7.6.13",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^12.10.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.2",
     "handlebars": "^4.7.8",

package/tools/dkk/claude/hooks/post-edit-validate.mjs

@@ -9,8 +9,6 @@
  * Stays silent for unrelated edits (no-op, exit 0).
  */
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
 
 let raw = "";
 process.stdin.on("data", (d) => (raw += d));
@@ -32,18 +30,37 @@ process.stdin.on("end", () => {
   if (!isDomainYaml) process.exit(0);
 
   const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-  const cliEntry = resolve(repoRoot, "src/cli.ts");
 
-  const [cmd, args] = existsSync(cliEntry)
-    ? ["npx", ["tsx", cliEntry, "validate", "--json", "--minify"]]
-    : ["dkk", ["validate", "--json", "--minify"]];
+  const res = spawnSync("dkk", ["validate", "--json", "--minify"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  // Tooling problem (dkk not on PATH, spawn error, etc.) — surface a clear
+  // setup error to the user, but don't block the agent with a phantom
+  // "validation failure" it has no way to fix.
+  if (res.error?.code === "ENOENT") {
+    process.stderr.write(
+      "dkk post-edit hook: 'dkk' CLI not found on PATH — install with `npm i -g domain-knowledge-kit` to enable auto-validation.\n",
+    );
+    process.exit(1);
+  }
+  if (res.error) {
+    process.stderr.write(
+      `dkk post-edit hook: failed to invoke validator — ${res.error.message}\n`,
+    );
+    process.exit(1);
+  }
 
-  const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
   // If validate fails, surface the JSON output to the model via stderr (exit 2
   // makes Claude Code feed stderr back as a tool-result correction signal).
   if (res.status !== 0) {
+    const body =
+      res.stdout ||
+      res.stderr ||
+      "(validator exited non-zero with no output — likely a tooling/wiring problem, not a domain issue)";
     process.stderr.write(
-      `dkk validate failed after edit to ${filePath}:\n${res.stdout || res.stderr || ""}\n`,
+      `dkk validate failed after edit to ${filePath}:\n${body}\n`,
     );
     process.exit(2);
   }

package/tools/dkk/claude/hooks/session-start-prime.mjs

@@ -8,26 +8,13 @@
  * so a missing domain model never blocks session start.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
 
 const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-const cliEntry = resolve(repoRoot, "src/cli.ts");
 
-let cmd, args;
-if (existsSync(cliEntry)) {
-  // Local DKK development: run via tsx.
-  cmd = "npx";
-  args = ["tsx", cliEntry, "prime"];
-} else {
-  // Downstream consumer: rely on the published `dkk` binary.
-  cmd = "dkk";
-  args = ["prime"];
-}
-
-const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
+const res = spawnSync("dkk", ["prime"], { cwd: repoRoot, encoding: "utf8" });
 if (res.status === 0 && res.stdout) {
   process.stdout.write(res.stdout);
 }
-// Always exit 0 — never block session start over a missing/empty model.
+// Always exit 0 — never block session start over a missing `dkk` binary or
+// an empty/absent domain model. Priming is a best-effort context boost.
 process.exit(0);

package/tools/dkk/claude/hooks/stop-validate.mjs

@@ -28,19 +28,38 @@ process.stdin.on("end", () => {
   }
 
   const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-  const cliEntry = resolve(repoRoot, "src/cli.ts");
 
   // No domain model? Nothing to gate on.
   if (!existsSync(resolve(repoRoot, ".dkk/domain"))) process.exit(0);
 
-  const [cmd, args] = existsSync(cliEntry)
-    ? ["npx", ["tsx", cliEntry, "validate", "--json", "--minify"]]
-    : ["dkk", ["validate", "--json", "--minify"]];
+  const res = spawnSync("dkk", ["validate", "--json", "--minify"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  // Tooling problem (dkk not on PATH, spawn error, etc.) — surface a clear
+  // setup error to the user, but don't block the agent with a phantom
+  // "domain failure" it has no way to fix.
+  if (res.error?.code === "ENOENT") {
+    process.stderr.write(
+      "dkk stop hook: 'dkk' CLI not found on PATH — install with `npm i -g domain-knowledge-kit` to enable the domain validation gate.\n",
+    );
+    process.exit(1);
+  }
+  if (res.error) {
+    process.stderr.write(
+      `dkk stop hook: failed to invoke validator — ${res.error.message}\n`,
+    );
+    process.exit(1);
+  }
 
-  const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
   if (res.status !== 0) {
+    const body =
+      res.stdout ||
+      res.stderr ||
+      "(validator exited non-zero with no output — likely a tooling/wiring problem, not a domain issue)";
     process.stderr.write(
-      `Domain validation failed — fix these before ending the turn:\n${res.stdout || res.stderr || ""}\n`,
+      `Domain validation failed — fix these before ending the turn:\n${body}\n`,
     );
     process.exit(2);
   }