contract-driven-delivery 2.1.2 → 2.2.0

package/dist/cli/index.js

@@ -101,8 +101,9 @@ var init_logger = __esm({
 // src/utils/mcp-hint.ts
 function logRecommendedMcpSetup() {
   log.info("Recommended for AI agents: enable the cdd-kit MCP server.");
-  log.dim("  MCP server command: cdd-kit");
-  log.dim('  MCP server args: ["mcp"]');
+  log.dim("  Claude Code user-scope setup: claude mcp add --scope user cdd-kit -- cdd-kit mcp");
+  log.dim("  Verify in Claude Code: /mcp or `claude mcp list`");
+  log.dim("  Note: Claude Code CLI reads MCP servers from ~/.claude.json; ~/.claude/settings.json is not enough.");
   log.dim("  Tools exposed: cdd_graph_context, cdd_graph_query, cdd_graph_impact, cdd_index_query, cdd_index_impact");
   log.dim("  Use MCP graph tools before source reads; CLI fallback: cdd-kit graph/index.");
 }
@@ -118,26 +119,26 @@ var code_map_hook_exports = {};
 __export(code_map_hook_exports, {
   installCodeMapHook: () => installCodeMapHook
 });
-import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync, chmodSync, mkdirSync as mkdirSync2 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2, chmodSync, mkdirSync as mkdirSync2 } from "fs";
+import { join as join5 } from "path";
 async function installCodeMapHook(cwd) {
-  const gitDir = join4(cwd, ".git");
-  if (!existsSync3(gitDir)) {
+  const gitDir = join5(cwd, ".git");
+  if (!existsSync4(gitDir)) {
     log.warn("not a git repository (no .git/ found); skipping code-map hook installation");
     return;
   }
-  const hooksDir = join4(gitDir, "hooks");
+  const hooksDir = join5(gitDir, "hooks");
   mkdirSync2(hooksDir, { recursive: true });
-  const dest = join4(hooksDir, "pre-commit");
+  const dest = join5(hooksDir, "pre-commit");
   let final;
-  if (!existsSync3(dest)) {
+  if (!existsSync4(dest)) {
     final = `#!/bin/sh
 set -e
 
 ${CODE_MAP_BLOCK}
 `;
   } else {
-    const existing = readFileSync2(dest, "utf8");
+    const existing = readFileSync3(dest, "utf8");
     const startIdx = existing.indexOf(START_MARKER);
     const endIdx = existing.indexOf(END_MARKER);
     if (startIdx >= 0 && endIdx > startIdx) {
@@ -149,15 +150,15 @@ ${CODE_MAP_BLOCK}
       final = trimmed + "\n\n" + CODE_MAP_BLOCK + "\n";
     }
   }
-  writeFileSync(dest, final, "utf8");
+  writeFileSync2(dest, final, "utf8");
   try {
     chmodSync(dest, 493);
   } catch {
   }
   try {
-    const cddDir = join4(cwd, ".cdd");
+    const cddDir = join5(cwd, ".cdd");
     mkdirSync2(cddDir, { recursive: true });
-    writeFileSync(join4(cddDir, ".hooks-installed"), `installed: ${(/* @__PURE__ */ new Date()).toISOString()}
+    writeFileSync2(join5(cddDir, ".hooks-installed"), `installed: ${(/* @__PURE__ */ new Date()).toISOString()}
 `, "utf8");
   } catch {
   }
@@ -191,27 +192,217 @@ ${END_MARKER}`;
   }
 });
 
-// src/utils/provider.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+// src/commands/install-agent-hooks.ts
+var install_agent_hooks_exports = {};
+__export(install_agent_hooks_exports, {
+  installAgentHooks: () => installAgentHooks
+});
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3, copyFileSync as copyFileSync2, chmodSync as chmodSync2, mkdirSync as mkdirSync3 } from "fs";
 import { join as join6 } from "path";
+async function installAgentHooks(opts = {}) {
+  const mode = opts.graphFirst ?? "advisory";
+  if (mode !== "advisory" && mode !== "strict") {
+    log.error(`invalid mode: ${mode}. Use 'advisory' or 'strict'.`);
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const srcHook = join6(ASSET.hooks, HOOK_FILENAME);
+  if (!existsSync5(srcHook)) {
+    if (opts.fromInit) {
+      log.warn(`graph-first hook not armed: bundled hook missing (${srcHook}). Reinstall the package, then run \`cdd-kit install-agent-hooks\`.`);
+      return;
+    }
+    log.error(`bundled hook not found: ${srcHook}. Reinstall the cdd-kit package.`);
+    process.exit(1);
+  }
+  const destHook = join6(cwd, HOOK_REL_PATH);
+  mkdirSync3(join6(cwd, ".claude", "hooks"), { recursive: true });
+  copyFileSync2(srcHook, destHook);
+  try {
+    chmodSync2(destHook, 493);
+  } catch {
+  }
+  const settingsPath = join6(cwd, SETTINGS_REL_PATH);
+  let settings = {};
+  if (existsSync5(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync4(settingsPath, "utf8"));
+    } catch (err) {
+      if (opts.fromInit) {
+        log.warn(`graph-first hook not armed: ${SETTINGS_REL_PATH} is not valid JSON (${err.message}). Fix it, then run \`cdd-kit install-agent-hooks\`.`);
+        return;
+      }
+      log.error(`${SETTINGS_REL_PATH} is not valid JSON: ${err.message}. Fix or remove it, then re-run.`);
+      process.exit(1);
+    }
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+      if (opts.fromInit) {
+        log.warn(`graph-first hook not armed: ${SETTINGS_REL_PATH} must be a JSON object. Fix it, then run \`cdd-kit install-agent-hooks\`.`);
+        return;
+      }
+      log.error(`${SETTINGS_REL_PATH} must be a JSON object.`);
+      process.exit(1);
+    }
+  }
+  settings.hooks = settings.hooks ?? {};
+  const preTool = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const isOurHandler = (h) => typeof h?.command === "string" && h.command.includes(HOOK_MARKER);
+  const preserved = [];
+  for (const e of preTool) {
+    if (typeof e?.command === "string" && e.command.includes(HOOK_MARKER) && !Array.isArray(e?.hooks)) {
+      continue;
+    }
+    if (Array.isArray(e?.hooks) && e.hooks.some(isOurHandler)) {
+      const others = e.hooks.filter((h) => !isOurHandler(h));
+      if (others.length === 0)
+        continue;
+      preserved.push({ ...e, hooks: others });
+      continue;
+    }
+    preserved.push(e);
+  }
+  const invoke = `./${HOOK_REL_PATH}`;
+  const command = mode === "strict" ? `CDD_GRAPH_FIRST_STRICT=1 ${invoke}` : invoke;
+  preserved.push({ matcher: "Read", hooks: [{ type: "command", command }] });
+  settings.hooks.PreToolUse = preserved;
+  mkdirSync3(join6(cwd, ".claude"), { recursive: true });
+  writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  log.ok(`graph-first PreToolUse hook installed (${mode}) at ${SETTINGS_REL_PATH}`);
+  log.info(`hook script: ${HOOK_REL_PATH}`);
+  if (mode === "advisory") {
+    log.info("advisory mode: reminds agents to use `cdd-kit index query --with-source` before Read; does not block.");
+    log.info("re-run with `--graph-first strict` to hard-block source Reads when a code-map exists.");
+  } else {
+    log.info("strict mode: blocks source-file Read when .cdd/code-map.yml exists, steering to graph/index queries.");
+    log.info("re-run with `--graph-first advisory` to downgrade to reminders only.");
+  }
+}
+var HOOK_FILENAME, HOOK_REL_PATH, SETTINGS_REL_PATH, HOOK_MARKER;
+var init_install_agent_hooks = __esm({
+  "src/commands/install-agent-hooks.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    HOOK_FILENAME = "pre-tool-use-graph-first.sh";
+    HOOK_REL_PATH = `.claude/hooks/${HOOK_FILENAME}`;
+    SETTINGS_REL_PATH = ".claude/settings.json";
+    HOOK_MARKER = "pre-tool-use-graph-first";
+  }
+});
+
+// src/commands/install-hooks.ts
+var install_hooks_exports = {};
+__export(install_hooks_exports, {
+  installHooks: () => installHooks
+});
+import { existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync4, chmodSync as chmodSync3, mkdirSync as mkdirSync4, statSync as statSync2 } from "fs";
+import { join as join7, resolve } from "path";
+import { spawnSync } from "child_process";
+function resolveHooksDir(cwd, gitPath, fromInit) {
+  const res = spawnSync("git", ["rev-parse", "--git-path", "hooks"], { cwd, encoding: "utf8" });
+  if (res.status === 0 && res.stdout.trim()) {
+    return resolve(cwd, res.stdout.trim());
+  }
+  let gitIsDir = false;
+  try {
+    gitIsDir = statSync2(gitPath).isDirectory();
+  } catch {
+  }
+  if (gitIsDir)
+    return join7(gitPath, "hooks");
+  const why = "`.git` is a worktree/submodule pointer and git could not resolve the hooks path";
+  if (fromInit) {
+    log.warn(`pre-commit gate not armed: ${why}. Run \`cdd-kit install-hooks\` in the main checkout.`);
+    return null;
+  }
+  log.error(`cannot resolve hooks dir: ${why}. Run this in the main checkout.`);
+  process.exit(1);
+}
+async function installHooks(opts = {}) {
+  const cwd = process.cwd();
+  const gitPath = join7(cwd, ".git");
+  if (!existsSync6(gitPath)) {
+    if (opts.fromInit) {
+      log.warn("pre-commit gate not armed: not a git repository yet. Run `cdd-kit install-hooks` after `git init`.");
+      return;
+    }
+    log.error("not a git repository (no .git/ found in cwd)");
+    process.exit(1);
+  }
+  const hooksDir = resolveHooksDir(cwd, gitPath, opts.fromInit ?? false);
+  if (hooksDir === null)
+    return;
+  mkdirSync4(hooksDir, { recursive: true });
+  const dest = join7(hooksDir, "pre-commit");
+  const ourHook = readFileSync5(join7(ASSET.hooks, "pre-commit"), "utf8");
+  let final;
+  if (!existsSync6(dest)) {
+    final = ourHook;
+  } else {
+    const existing = readFileSync5(dest, "utf8");
+    const startIdx = existing.indexOf(START_MARKER2);
+    const endIdx = existing.indexOf(END_MARKER2);
+    if (startIdx >= 0 && endIdx > startIdx) {
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx + END_MARKER2.length);
+      const ourStart = ourHook.indexOf(START_MARKER2);
+      const ourEnd = ourHook.indexOf(END_MARKER2) + END_MARKER2.length;
+      const ourBlock = ourHook.slice(ourStart, ourEnd);
+      final = before + ourBlock + after;
+    } else {
+      const ourStart = ourHook.indexOf(START_MARKER2);
+      const ourEnd = ourHook.indexOf(END_MARKER2) + END_MARKER2.length;
+      const ourBlock = ourHook.slice(ourStart, ourEnd);
+      if (existing.startsWith("#!")) {
+        const firstNewline = existing.indexOf("\n");
+        const shebang = existing.slice(0, firstNewline + 1);
+        const rest = existing.slice(firstNewline + 1);
+        final = shebang + "\n" + ourBlock + "\n" + rest;
+      } else {
+        final = "#!/bin/sh\n" + ourBlock + "\n" + existing;
+      }
+    }
+  }
+  writeFileSync4(dest, final, "utf8");
+  try {
+    chmodSync3(dest, 493);
+  } catch {
+  }
+  log.ok(`pre-commit hook installed at ${dest}`);
+  log.info("cdd-kit gate will now run automatically before each commit affecting specs/changes/");
+}
+var START_MARKER2, END_MARKER2;
+var init_install_hooks = __esm({
+  "src/commands/install-hooks.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    START_MARKER2 = "# cdd-kit-managed-block-start";
+    END_MARKER2 = "# cdd-kit-managed-block-end";
+  }
+});
+
+// src/utils/provider.ts
+import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
+import { join as join9 } from "path";
 function validateProviderOption(provider) {
   return provider === "auto" || provider === "claude" || provider === "codex" || provider === "both";
 }
 function inferProvider(cwd, requested = "auto") {
   if (requested !== "auto")
     return requested;
-  const modelPolicyPath = join6(cwd, ".cdd", "model-policy.json");
-  if (existsSync5(modelPolicyPath)) {
+  const modelPolicyPath = join9(cwd, ".cdd", "model-policy.json");
+  if (existsSync8(modelPolicyPath)) {
     try {
-      const policy = JSON.parse(readFileSync4(modelPolicyPath, "utf8"));
+      const policy = JSON.parse(readFileSync7(modelPolicyPath, "utf8"));
       if (policy.provider === "claude" || policy.provider === "codex" || policy.provider === "both") {
         return policy.provider;
       }
     } catch {
     }
   }
-  const hasClaude = existsSync5(join6(cwd, "CLAUDE.md")) || existsSync5(join6(cwd, "AGENTS.md"));
-  const hasCodex = existsSync5(join6(cwd, "CODEX.md"));
+  const hasClaude = existsSync8(join9(cwd, "CLAUDE.md")) || existsSync8(join9(cwd, "AGENTS.md"));
+  const hasCodex = existsSync8(join9(cwd, "CODEX.md"));
   if (hasClaude && hasCodex)
     return "both";
   if (hasCodex)
@@ -225,27 +416,27 @@ var init_provider = __esm({
 });
 
 // src/commands/update.ts
-import { join as join7 } from "path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readdirSync as readdirSync3, copyFileSync as copyFileSync2, readFileSync as readFileSync5 } from "fs";
+import { join as join10 } from "path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readdirSync as readdirSync3, copyFileSync as copyFileSync3, readFileSync as readFileSync8 } from "fs";
 import { createHash } from "crypto";
 import { homedir as homedir2 } from "os";
 function fileHash(filePath) {
-  const buf = readFileSync5(filePath);
+  const buf = readFileSync8(filePath);
   return createHash("sha256").update(buf).digest("hex");
 }
 function diffDir(src, dest) {
   const entries = [];
-  if (!existsSync6(src))
+  if (!existsSync9(src))
     return entries;
   function walk(currentSrc, currentDest) {
     const items = readdirSync3(currentSrc, { withFileTypes: true });
     for (const item of items) {
-      const srcPath = join7(currentSrc, item.name);
-      const destPath = join7(currentDest, item.name);
+      const srcPath = join10(currentSrc, item.name);
+      const destPath = join10(currentDest, item.name);
       if (item.isDirectory()) {
         walk(srcPath, destPath);
       } else {
-        if (!existsSync6(destPath)) {
+        if (!existsSync9(destPath)) {
           entries.push({ src: srcPath, dest: destPath, action: "add" });
         } else if (fileHash(srcPath) !== fileHash(destPath)) {
           entries.push({ src: srcPath, dest: destPath, action: "overwrite" });
@@ -263,33 +454,33 @@ function applyDir(entries) {
   for (const e of entries) {
     if (e.action === "skip")
       continue;
-    mkdirSync3(join7(e.dest, ".."), { recursive: true });
-    copyFileSync2(e.src, e.dest);
+    mkdirSync5(join10(e.dest, ".."), { recursive: true });
+    copyFileSync3(e.src, e.dest);
     count += 1;
   }
   return count;
 }
 function backupDir(dir, backupDest) {
-  if (!existsSync6(dir))
+  if (!existsSync9(dir))
     return;
-  mkdirSync3(backupDest, { recursive: true });
+  mkdirSync5(backupDest, { recursive: true });
   function walk(src, dst) {
     const items = readdirSync3(src, { withFileTypes: true });
     for (const item of items) {
-      const s = join7(src, item.name);
-      const d = join7(dst, item.name);
+      const s = join10(src, item.name);
+      const d = join10(dst, item.name);
       if (item.isDirectory()) {
-        mkdirSync3(d, { recursive: true });
+        mkdirSync5(d, { recursive: true });
         walk(s, d);
       } else
-        copyFileSync2(s, d);
+        copyFileSync3(s, d);
     }
   }
   walk(dir, backupDest);
 }
 async function update(opts) {
   if (opts.postinstall) {
-    if (!existsSync6(join7(SKILLS_HOME, "contract-driven-delivery"))) {
+    if (!existsSync9(join10(SKILLS_HOME, "contract-driven-delivery"))) {
       return;
     }
     opts.yes = true;
@@ -307,7 +498,7 @@ async function update(opts) {
   const provider = inferProvider(cwd, requestedProvider);
   const updateClaudeAssets = provider === "claude" || provider === "both";
   const agentDiff = updateClaudeAssets ? diffDir(ASSET.agents, AGENTS_HOME) : [];
-  const skillDiff = updateClaudeAssets ? readdirSync3(ASSET.skills, { withFileTypes: true }).filter((d) => d.isDirectory()).flatMap((d) => diffDir(join7(ASSET.skills, d.name), join7(SKILLS_HOME, d.name))) : [];
+  const skillDiff = updateClaudeAssets ? readdirSync3(ASSET.skills, { withFileTypes: true }).filter((d) => d.isDirectory()).flatMap((d) => diffDir(join10(ASSET.skills, d.name), join10(SKILLS_HOME, d.name))) : [];
   const toWrite = [...agentDiff, ...skillDiff].filter((e) => e.action !== "skip");
   const toAdd = toWrite.filter((e) => e.action === "add");
   const toOver = toWrite.filter((e) => e.action === "overwrite");
@@ -345,13 +536,13 @@ async function update(opts) {
     return;
   }
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const backupRoot = join7(homedir2(), ".claude", ".cdd-kit-backup", timestamp);
+  const backupRoot = join10(homedir2(), ".claude", ".cdd-kit-backup", timestamp);
   if (!quiet) {
     log.blank();
     log.info(`Backing up to ${backupRoot} \u2026`);
   }
-  backupDir(AGENTS_HOME, join7(backupRoot, "agents"));
-  backupDir(SKILLS_HOME, join7(backupRoot, "skills"));
+  backupDir(AGENTS_HOME, join10(backupRoot, "agents"));
+  backupDir(SKILLS_HOME, join10(backupRoot, "skills"));
   if (!quiet)
     log.ok(`Backup complete: ${backupRoot}`);
   if (!quiet)
@@ -392,7 +583,7 @@ var init_update = __esm({
 });
 
 // src/utils/digest.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { createHash as createHash2 } from "crypto";
 function normalizeContentForHash(buf) {
   if (!buf.includes(13))
@@ -403,7 +594,7 @@ function normalizeContentForHash(buf) {
 function sha256OfFileNormalized(path) {
   let buf;
   try {
-    buf = readFileSync6(path);
+    buf = readFileSync9(path);
   } catch {
     return "";
   }
@@ -420,9 +611,9 @@ var context_scan_exports = {};
 __export(context_scan_exports, {
   contextScan: () => contextScan
 });
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync7, readdirSync as readdirSync4, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync10, readdirSync as readdirSync4, writeFileSync as writeFileSync6 } from "fs";
 import { createHash as createHash3 } from "crypto";
-import { basename, dirname as dirname3, join as join8, relative as relative2 } from "path";
+import { basename, dirname as dirname3, join as join11, relative as relative2 } from "path";
 function inputsDigest(paths, cwd) {
   const combined = paths.slice().sort().map((p) => {
     const rel = relative2(cwd, p).replace(/\\/g, "/");
@@ -435,10 +626,10 @@ function stripGlobSuffix(pattern) {
 }
 function getForbiddenPaths(cwd) {
   const forbidden = new Set(DEFAULT_FORBIDDEN);
-  const policyPath = join8(cwd, ".cdd", "context-policy.json");
+  const policyPath = join11(cwd, ".cdd", "context-policy.json");
   try {
-    if (existsSync7(policyPath)) {
-      const policy = JSON.parse(readFileSync7(policyPath, "utf8"));
+    if (existsSync10(policyPath)) {
+      const policy = JSON.parse(readFileSync10(policyPath, "utf8"));
       for (const pattern of policy.forbiddenPaths ?? []) {
         forbidden.add(stripGlobSuffix(pattern));
       }
@@ -467,7 +658,7 @@ function buildTree(dir, cwd, forbidden, stats, prefix = "", depth = 0) {
   });
   let output = "";
   const visible = entries.filter((entry) => {
-    const relPath = relative2(cwd, join8(dir, entry.name));
+    const relPath = relative2(cwd, join11(dir, entry.name));
     return !isForbidden(relPath, forbidden);
   });
   const truncated = visible.length > PER_DIR_ENTRY_CAP;
@@ -475,7 +666,7 @@ function buildTree(dir, cwd, forbidden, stats, prefix = "", depth = 0) {
   if (truncated)
     stats.truncatedDirs += 1;
   shown.forEach((entry, index2) => {
-    const fullPath = join8(dir, entry.name);
+    const fullPath = join11(dir, entry.name);
     const isLast = index2 === shown.length - 1 && !truncated;
     const connector = isLast ? "\\-- " : "|-- ";
     output += `${prefix}${connector}${entry.name}${entry.isDirectory() ? "/" : ""}
@@ -537,10 +728,10 @@ function parseContractMetadata(content) {
   return { title: firstHeading(content), summary, metadata };
 }
 function findContractFiles(dir, found = []) {
-  if (!existsSync7(dir))
+  if (!existsSync10(dir))
     return found;
   for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-    const fullPath = join8(dir, entry.name);
+    const fullPath = join11(dir, entry.name);
     if (entry.isDirectory())
       findContractFiles(fullPath, found);
     else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "INDEX.md" && entry.name !== "CHANGELOG.md")
@@ -550,14 +741,14 @@ function findContractFiles(dir, found = []) {
 }
 async function contextScan(opts = {}) {
   const cwd = process.cwd();
-  const specsContextDir = join8(cwd, "specs", "context");
-  mkdirSync4(specsContextDir, { recursive: true });
+  const specsContextDir = join11(cwd, "specs", "context");
+  mkdirSync6(specsContextDir, { recursive: true });
   const forbidden = getForbiddenPaths(cwd);
   const surface = opts.surface;
   let scanRoot = cwd;
   if (surface) {
-    const resolvedSurface = join8(cwd, surface);
-    if (!existsSync7(resolvedSurface)) {
+    const resolvedSurface = join11(cwd, surface);
+    if (!existsSync10(resolvedSurface)) {
       log.error(`--surface path not found: ${surface}`);
       process.exit(1);
     }
@@ -569,10 +760,10 @@ async function contextScan(opts = {}) {
   }
   const treeStats = { dirs: 0, files: 0, omittedDirs: 0, truncatedDirs: 0 };
   const tree = buildTree(scanRoot, cwd, forbidden, treeStats);
-  const policyPath = join8(cwd, ".cdd", "context-policy.json");
-  const projectMapInputs = [policyPath].filter(existsSync7);
-  writeFileSync3(
-    join8(specsContextDir, "project-map.md"),
+  const policyPath = join11(cwd, ".cdd", "context-policy.json");
+  const projectMapInputs = [policyPath].filter(existsSync10);
+  writeFileSync6(
+    join11(specsContextDir, "project-map.md"),
     [
       "---",
       "artifact: project-map",
@@ -605,14 +796,14 @@ async function contextScan(opts = {}) {
     "utf8"
   );
   log.ok("Created specs/context/project-map.md");
-  const contractFiles = findContractFiles(join8(cwd, "contracts")).sort((a, b) => relative2(cwd, a).localeCompare(relative2(cwd, b)));
+  const contractFiles = findContractFiles(join11(cwd, "contracts")).sort((a, b) => relative2(cwd, a).localeCompare(relative2(cwd, b)));
   const contractEntries = [];
   const inventoryRows = [];
   let missingSummary = 0;
   for (const file of contractFiles) {
     const relPath = relative2(cwd, file).replace(/\\/g, "/");
     const dir = dirname3(relPath).replace(/\\/g, "/");
-    const { title, summary, metadata } = parseContractMetadata(readFileSync7(file, "utf8"));
+    const { title, summary, metadata } = parseContractMetadata(readFileSync10(file, "utf8"));
     const contractType = deriveContractType(relPath, metadata);
     const owner = metadata.owner ?? "unknown";
     const surface2 = metadata.surface ?? dir;
@@ -667,7 +858,7 @@ async function contextScan(opts = {}) {
     "",
     ...contractEntries
   ].join("\n");
-  writeFileSync3(join8(specsContextDir, "contracts-index.md"), contractIndex, "utf8");
+  writeFileSync6(join11(specsContextDir, "contracts-index.md"), contractIndex, "utf8");
   if (missingSummary > 0) {
     log.warn(`Created specs/context/contracts-index.md with ${missingSummary} missing summary warning(s).`);
   } else {
@@ -3694,7 +3885,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve6.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3721,7 +3912,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve6(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -4297,7 +4488,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve6(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -4525,7 +4716,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve6,
       resolveComponent,
       equal,
       serialize,
@@ -7514,18 +7705,265 @@ var require_dist = __commonJS({
   }
 });
 
+// src/utils/tier-floor.ts
+import { existsSync as existsSync13, readFileSync as readFileSync12 } from "fs";
+import { join as join14 } from "path";
+function loadTierPolicy(cwd) {
+  const path = join14(cwd, ".cdd", "tier-policy.json");
+  if (!existsSync13(path))
+    return DEFAULT_TIER_POLICY;
+  try {
+    const raw = JSON.parse(readFileSync12(path, "utf8"));
+    if (typeof raw.enabled === "boolean" && raw.enabled === false) {
+      return { enabled: false, rules: [] };
+    }
+    if (!Array.isArray(raw.rules))
+      return DEFAULT_TIER_POLICY;
+    const rules = [];
+    for (const r of raw.rules) {
+      if (r && typeof r === "object" && typeof r.maxTier === "number" && Array.isArray(r.patterns)) {
+        const rule = r;
+        rules.push({
+          maxTier: rule.maxTier,
+          label: typeof rule.label === "string" ? rule.label : `tier ${rule.maxTier} surface`,
+          patterns: rule.patterns.filter((p) => typeof p === "string")
+        });
+      }
+    }
+    if (rules.length === 0)
+      return DEFAULT_TIER_POLICY;
+    return { enabled: raw.enabled !== false, rules };
+  } catch {
+    return DEFAULT_TIER_POLICY;
+  }
+}
+function patternToRegExp(pattern) {
+  try {
+    return new RegExp(`(?<![a-z0-9])(?:${pattern})(?![a-z0-9])`, "i");
+  } catch {
+    return null;
+  }
+}
+function computeTierFloor(text, policy = DEFAULT_TIER_POLICY, opts = {}) {
+  if (!policy.enabled) {
+    return { floorTier: null, label: null, matched: [] };
+  }
+  let floorTier = null;
+  let label = null;
+  const matched = /* @__PURE__ */ new Set();
+  const scan = (rules, haystack) => {
+    if (!haystack)
+      return;
+    for (const rule of rules) {
+      let ruleHit = false;
+      for (const pattern of rule.patterns) {
+        const re = patternToRegExp(pattern);
+        const hit = re ? re.exec(haystack) : null;
+        if (hit) {
+          ruleHit = true;
+          matched.add(hit[0].toLowerCase().replace(/\s+/g, " ").trim());
+        }
+      }
+      if (ruleHit && (floorTier === null || rule.maxTier < floorTier)) {
+        floorTier = rule.maxTier;
+        label = rule.label;
+      }
+    }
+  };
+  scan(policy.rules, text);
+  const paths = opts.paths ?? [];
+  if (paths.length > 0) {
+    scan(policy.rules.filter((r) => r.maxTier === 0), paths.join("\n"));
+  }
+  return { floorTier, label, matched: [...matched].sort() };
+}
+var DEFAULT_TIER_POLICY;
+var init_tier_floor = __esm({
+  "src/utils/tier-floor.ts"() {
+    "use strict";
+    DEFAULT_TIER_POLICY = {
+      enabled: true,
+      rules: [
+        {
+          maxTier: 0,
+          label: "critical surface (auth / payments / data migration / concurrency / secrets)",
+          patterns: [
+            "auth",
+            "authn",
+            "authz",
+            "authentication",
+            "authorization",
+            "authenticate",
+            "authorize",
+            "authenticated",
+            "authorized",
+            "login",
+            "logout",
+            "sign-?in",
+            "sign-?up",
+            "passwords?",
+            "passwd",
+            "credentials?",
+            "secrets?",
+            "api[- ]?keys?",
+            // Qualified so security tokens trip the floor but design/CSS "tokens" do not.
+            "(access|api|auth|session|bearer|refresh|csrf|id|reset)[- ]?tokens?",
+            "jwt",
+            "oauth",
+            "oidc",
+            "saml",
+            "sessions?",
+            "cookies?",
+            "payments?",
+            "billing",
+            "invoices?",
+            "charges?",
+            "refunds?",
+            "checkout",
+            "stripe",
+            "paypal",
+            "migrations?",
+            "migrate",
+            "alter table",
+            "drop table",
+            "drop column",
+            "schema change",
+            "concurrency",
+            "race condition",
+            "mutex",
+            "deadlock",
+            "transaction isolation",
+            "encrypt",
+            "decrypt",
+            "crypto",
+            "hashing",
+            "rbac",
+            "permissions?",
+            "access control",
+            "privileges?",
+            "pii",
+            "gdpr",
+            "hipaa",
+            "rate limit",
+            "csrf",
+            "xss",
+            "sql injection"
+          ]
+        },
+        {
+          maxTier: 2,
+          label: "behavioral surface (api / data shape / queue / cache / external integration)",
+          patterns: [
+            "endpoint",
+            "route",
+            "api contract",
+            "request schema",
+            "response schema",
+            "pagination",
+            "queue",
+            "worker",
+            "cron",
+            "scheduler",
+            "webhook",
+            "cache",
+            "redis",
+            "database",
+            "query",
+            "index",
+            "external service",
+            "third[- ]?party",
+            "integration",
+            "data shape",
+            "nullable",
+            "breaking change"
+          ]
+        }
+      ]
+    };
+  }
+});
+
+// src/utils/git-paths.ts
+import { spawnSync as spawnSync3 } from "child_process";
+function unquote(raw) {
+  return raw.trim().replace(/^"(.*)"$/, "$1");
+}
+function getTouchedPaths(cwd) {
+  let res;
+  try {
+    res = spawnSync3("git", ["status", "--porcelain", "--untracked-files=all"], { cwd, encoding: "utf8" });
+  } catch {
+    return [];
+  }
+  if (res.status !== 0 || !res.stdout)
+    return [];
+  const paths = [];
+  for (const line of res.stdout.split("\n")) {
+    if (!line.trim())
+      continue;
+    const body = line.slice(3);
+    const arrow = body.indexOf(" -> ");
+    if (arrow >= 0) {
+      for (const part of [body.slice(0, arrow), body.slice(arrow + 4)]) {
+        const clean = unquote(part);
+        if (clean)
+          paths.push(clean);
+      }
+    } else {
+      const clean = unquote(body);
+      if (clean)
+        paths.push(clean);
+    }
+  }
+  return paths;
+}
+function getStagedPaths(cwd) {
+  let res;
+  try {
+    res = spawnSync3("git", ["diff", "--cached", "--name-status", "--no-color"], { cwd, encoding: "utf8" });
+  } catch {
+    return [];
+  }
+  if (res.status !== 0 || !res.stdout)
+    return [];
+  const paths = [];
+  for (const line of res.stdout.split("\n")) {
+    if (!line.trim())
+      continue;
+    const parts = line.split("	");
+    const status = parts[0] ?? "";
+    if (/^[RC]/.test(status) && parts.length >= 3) {
+      for (const part of [parts[1], parts[2]]) {
+        const clean = unquote(part ?? "");
+        if (clean)
+          paths.push(clean);
+      }
+    } else if (parts[1]) {
+      const clean = unquote(parts[1]);
+      if (clean)
+        paths.push(clean);
+    }
+  }
+  return paths;
+}
+var init_git_paths = __esm({
+  "src/utils/git-paths.ts"() {
+    "use strict";
+  }
+});
+
 // src/utils/gitignore.ts
-import { existsSync as existsSync12, readFileSync as readFileSync11, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13 } from "path";
+import { existsSync as existsSync16, readFileSync as readFileSync15, writeFileSync as writeFileSync9 } from "fs";
+import { join as join16 } from "path";
 function ensureGitignoreEntry(cwd, entry, comment = "cdd-kit generated backups (do not commit)") {
-  const path = join13(cwd, ".gitignore");
+  const path = join16(cwd, ".gitignore");
   const trimmed = entry.trim();
   if (!trimmed)
     return false;
   const re = new RegExp(`^\\s*${trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
   let existing = "";
-  if (existsSync12(path))
-    existing = readFileSync11(path, "utf8");
+  if (existsSync16(path))
+    existing = readFileSync15(path, "utf8");
   if (re.test(existing))
     return false;
   const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
@@ -7535,7 +7973,7 @@ ${trimmed}
 # ${comment}
 ${trimmed}
 `;
-  writeFileSync6(path, existing + block, "utf8");
+  writeFileSync9(path, existing + block, "utf8");
   return true;
 }
 var init_gitignore = __esm({
@@ -7549,15 +7987,15 @@ var migrate_exports = {};
 __export(migrate_exports, {
   migrate: () => migrate
 });
-import { join as join14 } from "path";
-import { cpSync as cpSync2, existsSync as existsSync13, mkdirSync as mkdirSync6, readdirSync as readdirSync7, readFileSync as readFileSync12, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
+import { join as join17 } from "path";
+import { cpSync as cpSync2, existsSync as existsSync17, mkdirSync as mkdirSync8, readdirSync as readdirSync7, readFileSync as readFileSync16, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync10 } from "fs";
 import yaml2 from "js-yaml";
 function backupChangeDir(cwd, changeId, sessionStamp) {
-  const backupRoot = join14(cwd, ".cdd", "migrate-backup", sessionStamp);
-  const backupDir2 = join14(backupRoot, changeId);
-  mkdirSync6(backupRoot, { recursive: true });
-  const sourceDir = join14(cwd, "specs", "changes", changeId);
-  if (existsSync13(sourceDir)) {
+  const backupRoot = join17(cwd, ".cdd", "migrate-backup", sessionStamp);
+  const backupDir2 = join17(backupRoot, changeId);
+  mkdirSync8(backupRoot, { recursive: true });
+  const sourceDir = join17(cwd, "specs", "changes", changeId);
+  if (existsSync17(sourceDir)) {
     cpSync2(sourceDir, backupDir2, { recursive: true });
   }
   return backupDir2;
@@ -7690,16 +8128,16 @@ function parseLegacyTaskList(body) {
   return rows;
 }
 function migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pendingWrites, pendingDeletes) {
-  const newPath = join14(changeDir, "tasks.yml");
-  const legacyPath = join14(changeDir, "tasks.md");
-  if (existsSync13(newPath)) {
+  const newPath = join17(changeDir, "tasks.yml");
+  const legacyPath = join17(changeDir, "tasks.md");
+  if (existsSync17(newPath)) {
     return;
   }
-  if (!existsSync13(legacyPath)) {
+  if (!existsSync17(legacyPath)) {
     warnings.push("tasks.md not found and tasks.yml missing \u2014 skipping tasks migration");
     return;
   }
-  const raw = readFileSync12(legacyPath, "utf8");
+  const raw = readFileSync16(legacyPath, "utf8");
   const fm = parseLegacyFrontmatter(raw);
   const bodyMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
   const body = bodyMatch ? bodyMatch[1] : raw;
@@ -7783,17 +8221,17 @@ function parseLegacyAgentLog(content) {
   return data;
 }
 function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
-  const agentLogDir = join14(changeDir, "agent-log");
-  if (!existsSync13(agentLogDir))
+  const agentLogDir = join17(changeDir, "agent-log");
+  if (!existsSync17(agentLogDir))
     return;
   const mdLogs = readdirSync7(agentLogDir).filter((f) => f.endsWith(".md"));
   for (const f of mdLogs) {
-    const fullPath = join14(agentLogDir, f);
+    const fullPath = join17(agentLogDir, f);
     const yamlName = f.replace(/\.md$/, ".yml");
-    const yamlFull = join14(agentLogDir, yamlName);
-    if (existsSync13(yamlFull))
+    const yamlFull = join17(agentLogDir, yamlName);
+    if (existsSync17(yamlFull))
       continue;
-    const raw = readFileSync12(fullPath, "utf8");
+    const raw = readFileSync16(fullPath, "utf8");
     const parsed = parseLegacyAgentLog(raw);
     const yamlOut = yaml2.dump(parsed, { lineWidth: -1, noRefs: true });
     pendingWrites.push({ path: yamlFull, content: yamlOut });
@@ -7802,15 +8240,15 @@ function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
   }
 }
 function ensureImplementationPlanScaffold(changeId, changeDir, changed, warnings, pendingWrites) {
-  const planPath = join14(changeDir, "implementation-plan.md");
-  if (existsSync13(planPath))
+  const planPath = join17(changeDir, "implementation-plan.md");
+  if (existsSync17(planPath))
     return;
-  const templatePath = join14(ASSET.specsTemplates, "implementation-plan.md");
-  if (!existsSync13(templatePath)) {
+  const templatePath = join17(ASSET.specsTemplates, "implementation-plan.md");
+  if (!existsSync17(templatePath)) {
     warnings.push("implementation-plan.md template not found; run cdd-kit upgrade --yes after updating cdd-kit");
     return;
   }
-  const template = readFileSync12(templatePath, "utf8").replace(/<change-id>/g, changeId).replace(/<id>/g, changeId);
+  const template = readFileSync16(templatePath, "utf8").replace(/<change-id>/g, changeId).replace(/<id>/g, changeId);
   pendingWrites.push({ path: planPath, content: template });
   changed.push("implementation-plan.md: added scaffold");
   warnings.push("implementation-plan.md scaffold added; fill it before implementation agents continue");
@@ -7821,9 +8259,9 @@ function migrateOne(changeId, changeDir, enableContextGovernance) {
   const pending = [];
   const deletes = [];
   let detectedTier = null;
-  const classifPath = join14(changeDir, "change-classification.md");
-  if (existsSync13(classifPath)) {
-    const content = readFileSync12(classifPath, "utf8");
+  const classifPath = join17(changeDir, "change-classification.md");
+  if (existsSync17(classifPath)) {
+    const content = readFileSync16(classifPath, "utf8");
     const hasNewTierFormat = /^## Tier\s*\n\s*-\s*\d\s*$/m.test(content);
     const oldMatch = content.match(/\*\*Tier[:\*]+\s*(?:Tier\s*)?(\d)/i) ?? content.match(/^-?\s*Tier:\s*(?:Tier\s*)?(\d)/mi);
     if (oldMatch)
@@ -7854,8 +8292,8 @@ function migrateOne(changeId, changeDir, enableContextGovernance) {
   migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pending, deletes);
   ensureImplementationPlanScaffold(changeId, changeDir, changed, warnings, pending);
   migrateAgentLogs(changeDir, changed, pending, deletes);
-  const manifestPath = join14(changeDir, "context-manifest.md");
-  if (!existsSync13(manifestPath)) {
+  const manifestPath = join17(changeDir, "context-manifest.md");
+  if (!existsSync17(manifestPath)) {
     changed.push(enableContextGovernance ? "context-manifest.md: added context-governance v1 manifest scaffold" : "context-manifest.md: added legacy context manifest scaffold");
     pending.push({
       path: manifestPath,
@@ -7871,7 +8309,7 @@ function commitWritesAtomically(pending, deletes) {
   try {
     for (const write of pending) {
       const tmp = `${write.path}.cdd-migrate.tmp`;
-      writeFileSync7(tmp, write.content, "utf8");
+      writeFileSync10(tmp, write.content, "utf8");
       renames.push({ tmp, final: write.path });
     }
   } catch (err) {
@@ -7900,8 +8338,8 @@ async function migrate(changeId, opts = {}) {
   const noBackup = opts.noBackup ?? false;
   const idsToMigrate = [];
   if (opts.all) {
-    const changesDir = join14(cwd, "specs", "changes");
-    if (!existsSync13(changesDir)) {
+    const changesDir = join17(cwd, "specs", "changes");
+    if (!existsSync17(changesDir)) {
       log.info("No specs/changes/ directory found \u2014 nothing to migrate.");
       return;
     }
@@ -7909,8 +8347,8 @@ async function migrate(changeId, opts = {}) {
       ...readdirSync7(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     );
   } else if (changeId) {
-    const specificDir = join14(cwd, "specs", "changes", changeId);
-    if (!existsSync13(specificDir)) {
+    const specificDir = join17(cwd, "specs", "changes", changeId);
+    if (!existsSync17(specificDir)) {
       log.error(`Change not found: specs/changes/${changeId}`);
       process.exit(1);
     }
@@ -7930,10 +8368,10 @@ async function migrate(changeId, opts = {}) {
   const sessionStamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   let migratedCount = 0;
   let upToDateCount = 0;
-  const backupRoot = join14(cwd, ".cdd", "migrate-backup", sessionStamp);
+  const backupRoot = join17(cwd, ".cdd", "migrate-backup", sessionStamp);
   for (const id of idsToMigrate) {
-    const changeDir = join14(cwd, "specs", "changes", id);
-    if (!existsSync13(changeDir)) {
+    const changeDir = join17(cwd, "specs", "changes", id);
+    if (!existsSync17(changeDir)) {
       log.warn(`  ${id}: directory not found \u2014 skipping`);
       continue;
     }
@@ -7995,40 +8433,40 @@ var upgrade_exports = {};
 __export(upgrade_exports, {
   upgrade: () => upgrade
 });
-import { existsSync as existsSync14, mkdirSync as mkdirSync7, readdirSync as readdirSync8, copyFileSync as copyFileSync3, readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
-import { dirname as dirname4, join as join15, relative as relative4 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync9, readdirSync as readdirSync8, copyFileSync as copyFileSync4, readFileSync as readFileSync17, writeFileSync as writeFileSync11 } from "fs";
+import { dirname as dirname5, join as join18, relative as relative4 } from "path";
 function planMissingFiles(srcDir, destDir, label, planned) {
-  if (!existsSync14(srcDir))
+  if (!existsSync18(srcDir))
     return;
   for (const entry of readdirSync8(srcDir, { withFileTypes: true })) {
-    const src = join15(srcDir, entry.name);
-    const dest = join15(destDir, entry.name);
+    const src = join18(srcDir, entry.name);
+    const dest = join18(destDir, entry.name);
     if (entry.isDirectory()) {
-      planMissingFiles(src, dest, join15(label, entry.name), planned);
+      planMissingFiles(src, dest, join18(label, entry.name), planned);
       continue;
     }
-    if (!existsSync14(dest)) {
-      planned.push({ src, dest, rel: join15(label, relative4(srcDir, src)) });
+    if (!existsSync18(dest)) {
+      planned.push({ src, dest, rel: join18(label, relative4(srcDir, src)) });
     }
   }
 }
 function planProviderGuidance(cwd, provider, planned) {
   if (provider === "claude" || provider === "both") {
-    if (!existsSync14(join15(cwd, "CLAUDE.md"))) {
-      planned.push({ src: ASSET.claudeTemplate, dest: join15(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
+    if (!existsSync18(join18(cwd, "CLAUDE.md"))) {
+      planned.push({ src: ASSET.claudeTemplate, dest: join18(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
     }
-    if (!existsSync14(join15(cwd, "AGENTS.md"))) {
-      planned.push({ src: ASSET.agentsTemplate, dest: join15(cwd, "AGENTS.md"), rel: "AGENTS.md" });
+    if (!existsSync18(join18(cwd, "AGENTS.md"))) {
+      planned.push({ src: ASSET.agentsTemplate, dest: join18(cwd, "AGENTS.md"), rel: "AGENTS.md" });
     }
   }
-  if ((provider === "codex" || provider === "both") && !existsSync14(join15(cwd, "CODEX.md"))) {
-    planned.push({ src: ASSET.codexTemplate, dest: join15(cwd, "CODEX.md"), rel: "CODEX.md" });
+  if ((provider === "codex" || provider === "both") && !existsSync18(join18(cwd, "CODEX.md"))) {
+    planned.push({ src: ASSET.codexTemplate, dest: join18(cwd, "CODEX.md"), rel: "CODEX.md" });
   }
 }
 function applyCopy(plan) {
   for (const item of plan) {
-    mkdirSync7(dirname4(item.dest), { recursive: true });
-    copyFileSync3(item.src, item.dest);
+    mkdirSync9(dirname5(item.dest), { recursive: true });
+    copyFileSync4(item.src, item.dest);
   }
 }
 async function upgrade(opts = {}) {
@@ -8040,12 +8478,12 @@ async function upgrade(opts = {}) {
   }
   const provider = inferProvider(cwd, requestedProvider);
   const plan = [];
-  planMissingFiles(ASSET.contracts, join15(cwd, "contracts"), "contracts", plan);
-  planMissingFiles(ASSET.specsTemplates, join15(cwd, "specs", "templates"), "specs/templates", plan);
-  planMissingFiles(ASSET.testsTemplates, join15(cwd, "tests", "templates"), "tests/templates", plan);
-  planMissingFiles(ASSET.ci, join15(cwd, "ci"), "ci", plan);
-  planMissingFiles(ASSET.githubWorkflows, join15(cwd, ".github", "workflows"), ".github/workflows", plan);
-  planMissingFiles(ASSET.cddConfig, join15(cwd, ".cdd"), ".cdd", plan);
+  planMissingFiles(ASSET.contracts, join18(cwd, "contracts"), "contracts", plan);
+  planMissingFiles(ASSET.specsTemplates, join18(cwd, "specs", "templates"), "specs/templates", plan);
+  planMissingFiles(ASSET.testsTemplates, join18(cwd, "tests", "templates"), "tests/templates", plan);
+  planMissingFiles(ASSET.ci, join18(cwd, "ci"), "ci", plan);
+  planMissingFiles(ASSET.githubWorkflows, join18(cwd, ".github", "workflows"), ".github/workflows", plan);
+  planMissingFiles(ASSET.cddConfig, join18(cwd, ".cdd"), ".cdd", plan);
   planProviderGuidance(cwd, provider, plan);
   log.blank();
   log.info(`Upgrade provider: ${provider}`);
@@ -8082,11 +8520,11 @@ async function upgrade(opts = {}) {
     return;
   }
   applyCopy(plan);
-  const modelPolicyPath = join15(cwd, ".cdd", "model-policy.json");
-  if (existsSync14(modelPolicyPath)) {
+  const modelPolicyPath = join18(cwd, ".cdd", "model-policy.json");
+  if (existsSync18(modelPolicyPath)) {
     let existing = {};
     try {
-      existing = JSON.parse(readFileSync13(modelPolicyPath, "utf8"));
+      existing = JSON.parse(readFileSync17(modelPolicyPath, "utf8"));
     } catch {
     }
     const merged = {
@@ -8095,7 +8533,7 @@ async function upgrade(opts = {}) {
       generated_at: (/* @__PURE__ */ new Date()).toISOString(),
       roles: existing.roles && typeof existing.roles === "object" ? existing.roles : {}
     };
-    writeFileSync8(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    writeFileSync11(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
   }
   log.blank();
   log.ok(`Upgrade complete: ${plan.length} missing file(s) added.`);
@@ -8233,7 +8671,7 @@ function renderYaml(entries, opts) {
       }
     }
   }
-  const headerLineCount = opts.sourcesDigest ? 3 : 2;
+  const headerLineCount = 2 + (opts.sourcesDigest ? 1 : 0) + (opts.surfaceRoot ? 1 : 0);
   const mapLines = bodyLines.length + headerLineCount;
   const compression = totalSrc === 0 ? 0 : totalSrc / mapLines;
   const fileCount = entries.length;
@@ -8244,6 +8682,9 @@ function renderYaml(entries, opts) {
   if (opts.sourcesDigest) {
     header.push(`# sources-digest: ${opts.sourcesDigest}`);
   }
+  if (opts.surfaceRoot) {
+    header.push(`# surface-root: ${opts.surfaceRoot}`);
+  }
   return [...header, ...bodyLines].join("\n") + "\n";
 }
 var YAML_RESERVED;
@@ -8255,8 +8696,8 @@ var init_yaml_writer = __esm({
 });
 
 // src/code-map/config.ts
-import { existsSync as existsSync15, readFileSync as readFileSync14 } from "fs";
-import { join as join16 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync18 } from "fs";
+import { join as join19 } from "path";
 import { load as yamlLoad } from "js-yaml";
 function asStringArray(value, key, where) {
   if (value === void 0)
@@ -8272,8 +8713,8 @@ function asStringArray(value, key, where) {
   return value;
 }
 function loadCodeMapConfig(cwd) {
-  const filePath = join16(cwd, CONFIG_REL_PATH);
-  if (!existsSync15(filePath)) {
+  const filePath = join19(cwd, CONFIG_REL_PATH);
+  if (!existsSync19(filePath)) {
     return {
       include: [...BUILTIN_INCLUDE],
       exclude: [...BUILTIN_EXCLUDE],
@@ -8282,7 +8723,7 @@ function loadCodeMapConfig(cwd) {
   }
   let text;
   try {
-    text = readFileSync14(filePath, "utf8");
+    text = readFileSync18(filePath, "utf8");
   } catch (err) {
     throw new Error(`failed to read ${CONFIG_REL_PATH}: ${err.message}`);
   }
@@ -8352,8 +8793,8 @@ var init_config = __esm({
 });
 
 // src/code-map/include-exclude.ts
-import { readdirSync as readdirSync9, statSync as statSync2 } from "fs";
-import { join as join17 } from "path";
+import { readdirSync as readdirSync9, statSync as statSync3 } from "fs";
+import { join as join20 } from "path";
 import picomatch from "picomatch";
 function walkRepo(root, opts = {}) {
   const includes = opts.include ?? [];
@@ -8372,13 +8813,13 @@ function walkRepo(root, opts = {}) {
     }
     for (const entry of entries) {
       const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
-      const absPath = join17(dir, entry.name);
+      const absPath = join20(dir, entry.name);
       if (entry.isDirectory() || entry.isSymbolicLink()) {
         const dirPattern = `${relPath}/**`;
         if (isExcluded(relPath) || isExcluded(dirPattern))
           continue;
         try {
-          const stat = statSync2(absPath);
+          const stat = statSync3(absPath);
           if (stat.isDirectory()) {
             walk(absPath, relPath);
           }
@@ -8444,10 +8885,10 @@ var init_orchestrator = __esm({
 });
 
 // src/code-map/freshness.ts
-import { existsSync as existsSync16, readFileSync as readFileSync15, statSync as statSync3 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync19, statSync as statSync4 } from "fs";
+import { join as join21 } from "path";
 function checkCodeMapFreshness(cwd, mapRel = ".cdd/code-map.yml", include, exclude) {
-  const mapPath = join18(cwd, mapRel);
+  const mapPath = join21(cwd, mapRel);
   let cfg;
   try {
     cfg = loadCodeMapConfig(cwd);
@@ -8463,17 +8904,17 @@ function checkCodeMapFreshness(cwd, mapRel = ".cdd/code-map.yml", include, exclu
   const includeFinal = [...cfg.include, ...include ?? []];
   const excludeFinal = [...cfg.exclude, ...exclude ?? []];
   const sourceFiles = walkRepo(cwd, { include: includeFinal, exclude: excludeFinal });
-  if (!existsSync16(mapPath)) {
+  if (!existsSync20(mapPath)) {
     if (sourceFiles.length === 0) {
       return { status: "missing-greenfield", staleFiles: [], staleCount: 0, mapPath };
     }
     return { status: "missing-with-sources", staleFiles: [], staleCount: 0, mapPath };
   }
-  const mapMtime = statSync3(mapPath).mtimeMs;
+  const mapMtime = statSync4(mapPath).mtimeMs;
   const staleAll = [];
   for (const absPath of sourceFiles) {
     try {
-      const mtime = statSync3(absPath).mtimeMs;
+      const mtime = statSync4(absPath).mtimeMs;
       if (mtime > mapMtime) {
         const rel = absPath.replace(/\\/g, "/").replace(cwd.replace(/\\/g, "/") + "/", "");
         staleAll.push(rel);
@@ -8500,7 +8941,7 @@ function checkCodeMapFreshness(cwd, mapRel = ".cdd/code-map.yml", include, exclu
 }
 function readSourcesDigest(mapPath) {
   try {
-    const head = readFileSync15(mapPath, "utf8").slice(0, 2048);
+    const head = readFileSync19(mapPath, "utf8").slice(0, 2048);
     const m = head.match(/^# sources-digest:\s*([a-f0-9]+)/m);
     return m ? m[1] : null;
   } catch {
@@ -8517,7 +8958,7 @@ var init_freshness = __esm({
 });
 
 // src/code-map/index-reader.ts
-import { existsSync as existsSync17, readFileSync as readFileSync16 } from "fs";
+import { existsSync as existsSync21, readFileSync as readFileSync20 } from "fs";
 import yaml3 from "js-yaml";
 async function ensureCodeMapFresh(mapPath, refresh2) {
   if (!refresh2)
@@ -8555,13 +8996,13 @@ function sidecarPathFor(mapPath) {
 }
 function tryLoadSidecar(mapPath, mapText) {
   const sidecarPath = sidecarPathFor(mapPath);
-  if (!existsSync17(sidecarPath))
+  if (!existsSync21(sidecarPath))
     return null;
   const headerDigest = mapText.match(/^# sources-digest:\s*([a-f0-9]+)/m)?.[1];
   if (!headerDigest)
     return null;
   try {
-    const raw = JSON.parse(readFileSync16(sidecarPath, "utf8"));
+    const raw = JSON.parse(readFileSync20(sidecarPath, "utf8"));
     if (raw && raw.sourcesDigest === headerDigest && Array.isArray(raw.entries)) {
       return raw.entries;
     }
@@ -8570,10 +9011,10 @@ function tryLoadSidecar(mapPath, mapText) {
   return null;
 }
 function loadCodeMapEntries(mapPath) {
-  if (!existsSync17(mapPath)) {
+  if (!existsSync21(mapPath)) {
     throw new Error(`${mapPath} is missing; run \`cdd-kit code-map\` first.`);
   }
-  const text = readFileSync16(mapPath, "utf8");
+  const text = readFileSync20(mapPath, "utf8");
   const fromSidecar = tryLoadSidecar(mapPath, text);
   if (fromSidecar)
     return fromSidecar;
@@ -8945,7 +9386,7 @@ var init_builder = __esm({
 });
 
 // src/code-graph/reader.ts
-import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync21 } from "fs";
 function graphPathFor(mapPath) {
   const match = mapPath.match(/^(.*?)(?:code-map)(.*)\.ya?ml$/i);
   if (match)
@@ -8953,10 +9394,10 @@ function graphPathFor(mapPath) {
   return `${mapPath.replace(/\.ya?ml$/i, "")}.graph.json`;
 }
 function loadCodeGraph(graphPath) {
-  if (!existsSync18(graphPath)) {
+  if (!existsSync22(graphPath)) {
     throw new Error(`${graphPath} is missing; run \`cdd-kit code-map\` first.`);
   }
-  const raw = JSON.parse(readFileSync17(graphPath, "utf8"));
+  const raw = JSON.parse(readFileSync21(graphPath, "utf8"));
   if (!raw || raw.schema_version !== "1.0" || !Array.isArray(raw.nodes) || !Array.isArray(raw.edges)) {
     throw new Error(`${graphPath} is not a cdd-kit code graph v1 index.`);
   }
@@ -8974,9 +9415,9 @@ __export(worker_dispatch_exports, {
   scanLangWithWorkers: () => scanLangWithWorkers
 });
 import { execFile } from "child_process";
-import { writeFileSync as writeFileSync9, unlinkSync } from "fs";
+import { writeFileSync as writeFileSync12, unlinkSync } from "fs";
 import { randomBytes } from "crypto";
-import { join as join19 } from "path";
+import { join as join22 } from "path";
 import { tmpdir } from "os";
 function chunk(arr, parts) {
   const size = Math.ceil(arr.length / parts);
@@ -8986,15 +9427,15 @@ function chunk(arr, parts) {
   return out;
 }
 function scanChunkInChild(cliEntry, lang, files, repoRoot) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve6, reject) => {
     if (!ALLOWED_LANGS.has(lang)) {
       return reject(new Error(`refusing to spawn worker for unknown lang: ${lang}`));
     }
-    const listFile = join19(
+    const listFile = join22(
       tmpdir(),
       `cdd-cm-worker-${process.pid}-${randomBytes(12).toString("hex")}.txt`
     );
-    writeFileSync9(listFile, files.join("\n") + "\n", { encoding: "utf8", mode: 384 });
+    writeFileSync12(listFile, files.join("\n") + "\n", { encoding: "utf8", mode: 384 });
     execFile(
       process.execPath,
       [cliEntry, "__code-map-scan", "--lang", lang, "--batch-file", listFile, "--repo-root", repoRoot],
@@ -9008,7 +9449,7 @@ function scanChunkInChild(cliEntry, lang, files, repoRoot) {
           return reject(err);
         try {
           const parsed = JSON.parse(stdout);
-          resolve2({ entries: parsed.entries ?? [], warnings: parsed.warnings ?? [] });
+          resolve6({ entries: parsed.entries ?? [], warnings: parsed.warnings ?? [] });
         } catch (e) {
           reject(e);
         }
@@ -9066,15 +9507,15 @@ var python_exports = {};
 __export(python_exports, {
   pythonScanner: () => pythonScanner
 });
-import { spawnSync as spawnSync2 } from "child_process";
-import { writeFileSync as writeFileSync10, unlinkSync as unlinkSync2 } from "fs";
+import { spawnSync as spawnSync4 } from "child_process";
+import { writeFileSync as writeFileSync13, unlinkSync as unlinkSync2 } from "fs";
 import { randomBytes as randomBytes2 } from "crypto";
-import { join as join20 } from "path";
+import { join as join23 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 function detectPython2() {
   for (const candidate of ["python3", "python"]) {
     try {
-      const result = spawnSync2(candidate, ["--version"], {
+      const result = spawnSync4(candidate, ["--version"], {
         encoding: "utf8",
         timeout: 5e3
       });
@@ -9143,13 +9584,13 @@ var init_python = __esm({
         const entries = [];
         const warnings = [];
         const scriptPath = ASSET.codeMapPython;
-        const listFile = join20(tmpdir2(), `cdd-codemap-${process.pid}-${randomBytes2(12).toString("hex")}.txt`);
-        writeFileSync10(listFile, absolutePaths.join("\n") + "\n", { encoding: "utf8", mode: 384 });
+        const listFile = join23(tmpdir2(), `cdd-codemap-${process.pid}-${randomBytes2(12).toString("hex")}.txt`);
+        writeFileSync13(listFile, absolutePaths.join("\n") + "\n", { encoding: "utf8", mode: 384 });
         let stdout = "";
         let stderr = "";
         let exitCode = 0;
         try {
-          const result = spawnSync2(
+          const result = spawnSync4(
             interpreter,
             [scriptPath, "--batch-file", listFile, "--repo-root", repoRoot],
             {
@@ -9213,7 +9654,7 @@ var init_python = __esm({
           }
           const r = parsed;
           entries.push({
-            path: canonicalRelPath(join20(repoRoot, r.path), repoRoot),
+            path: canonicalRelPath(join23(repoRoot, r.path), repoRoot),
             total_lines: r.total_lines,
             imports: r.imports ?? [],
             constants: r.constants ?? [],
@@ -9263,7 +9704,7 @@ __export(javascript_exports, {
   parseJsSource: () => parseJsSource,
   parseSourceWithPlugins: () => parseSourceWithPlugins
 });
-import { readFileSync as readFileSync19 } from "fs";
+import { readFileSync as readFileSync23 } from "fs";
 import { parse } from "@babel/parser";
 function parseSourceWithPlugins(source, plugins) {
   return parse(source, {
@@ -9666,7 +10107,7 @@ var init_javascript = __esm({
       async scan(absolutePath, repoRoot) {
         let source;
         try {
-          source = readFileSync19(absolutePath, "utf8");
+          source = readFileSync23(absolutePath, "utf8");
         } catch (err) {
           throw err;
         }
@@ -9686,7 +10127,7 @@ var typescript_exports = {};
 __export(typescript_exports, {
   tsScanner: () => tsScanner
 });
-import { readFileSync as readFileSync20 } from "fs";
+import { readFileSync as readFileSync24 } from "fs";
 var TypeScriptScanner, tsScanner;
 var init_typescript = __esm({
   "src/code-map/scanners/typescript.ts"() {
@@ -9698,7 +10139,7 @@ var init_typescript = __esm({
       async scan(absolutePath, repoRoot) {
         let source;
         try {
-          source = readFileSync20(absolutePath, "utf8");
+          source = readFileSync24(absolutePath, "utf8");
         } catch (err) {
           throw err;
         }
@@ -9736,7 +10177,7 @@ var vue_exports = {};
 __export(vue_exports, {
   vueScanner: () => vueScanner
 });
-import { readFileSync as readFileSync21 } from "fs";
+import { readFileSync as readFileSync25 } from "fs";
 import { parse as parse2 } from "@vue/compiler-sfc";
 var VueScanner, vueScanner;
 var init_vue = __esm({
@@ -9749,7 +10190,7 @@ var init_vue = __esm({
       async scan(absolutePath, repoRoot) {
         let source;
         try {
-          source = readFileSync21(absolutePath, "utf8");
+          source = readFileSync25(absolutePath, "utf8");
         } catch (err) {
           throw err;
         }
@@ -9844,14 +10285,15 @@ var init_vue = __esm({
 var code_map_exports = {};
 __export(code_map_exports, {
   codeMap: () => codeMap,
-  computeSourcesDigest: () => computeSourcesDigest
+  computeSourcesDigest: () => computeSourcesDigest,
+  slugifySurface: () => slugifySurface
 });
-import { existsSync as existsSync19, mkdirSync as mkdirSync8, readFileSync as readFileSync22, writeFileSync as writeFileSync11 } from "fs";
-import { resolve, dirname as dirname5, relative as relative6 } from "path";
+import { existsSync as existsSync23, mkdirSync as mkdirSync10, readFileSync as readFileSync26, writeFileSync as writeFileSync14 } from "fs";
+import { resolve as resolve3, dirname as dirname6, relative as relative6 } from "path";
 import { createHash as createHash6 } from "crypto";
 import { createRequire } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join21 } from "path";
+import { join as join24 } from "path";
 function computeSourcesDigest(absolutePaths, cwd) {
   const lines = absolutePaths.slice().sort().map((p) => {
     const rel = relative6(cwd, p).replace(/\\/g, "/");
@@ -9866,14 +10308,15 @@ function slugifySurface(surface) {
 async function codeMap(opts) {
   const start = Date.now();
   if (opts.surface) {
-    const resolvedSurface = resolve(process.cwd(), opts.surface);
-    if (!existsSync19(resolvedSurface)) {
+    const resolvedSurface = resolve3(process.cwd(), opts.surface);
+    if (!existsSync23(resolvedSurface)) {
       log.error(`code-map --surface path not found: ${opts.surface}`);
       return 1;
     }
   }
   const scanPath = opts.surface ?? opts.path;
-  const root = resolve(process.cwd(), scanPath);
+  const root = resolve3(process.cwd(), scanPath);
+  const surfaceRoot = opts.surface ? relative6(process.cwd(), root).replace(/\\/g, "/") || "." : void 0;
   const out = opts.out ?? (opts.surface ? `.cdd/code-map.${slugifySurface(opts.surface)}.yml` : ".cdd/code-map.yml");
   let cfg;
   try {
@@ -9941,7 +10384,8 @@ async function codeMap(opts) {
   const sourcesDigest = computeSourcesDigest(files, root);
   const yamlBody = renderYaml(result.entries, {
     generator: `cdd-kit ${_pkg.version}`,
-    sourcesDigest
+    sourcesDigest,
+    surfaceRoot
   });
   const totalSrc = result.entries.reduce((s, e) => s + e.total_lines, 0);
   const mapLines = yamlBody.split("\n").length;
@@ -9952,7 +10396,7 @@ async function codeMap(opts) {
       log.warn(`${w.path}: ${w.message}`);
   }
   if (opts.check) {
-    const existing = existsSync19(out) ? readFileSync22(out, "utf8") : "";
+    const existing = existsSync23(out) ? readFileSync26(out, "utf8") : "";
     const normalize = (s) => s.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/^# generated: [^\n]+\n/m, "# generated: <normalized>\n");
     if (normalize(existing) !== normalize(yamlBody)) {
       if (!opts.silent)
@@ -9963,11 +10407,11 @@ async function codeMap(opts) {
       log.ok(`code-map up to date: ${out}`);
     return 0;
   }
-  mkdirSync8(dirname5(out), { recursive: true });
-  writeFileSync11(out, yamlBody, "utf8");
+  mkdirSync10(dirname6(out), { recursive: true });
+  writeFileSync14(out, yamlBody, "utf8");
   try {
     const sidecarPath = sidecarPathFor(out);
-    writeFileSync11(sidecarPath, JSON.stringify({ sourcesDigest, entries: result.entries }), "utf8");
+    writeFileSync14(sidecarPath, JSON.stringify({ sourcesDigest, entries: result.entries }), "utf8");
     const rel = relative6(process.cwd(), sidecarPath).replace(/\\/g, "/");
     if (!rel.startsWith("..")) {
       ensureGitignoreEntry(process.cwd(), rel, "cdd-kit local cache (do not commit)");
@@ -9977,7 +10421,7 @@ async function codeMap(opts) {
       generator: `cdd-kit ${_pkg.version}`,
       sourcesDigest
     });
-    writeFileSync11(graphPath, JSON.stringify(graph2, null, 2) + "\n", "utf8");
+    writeFileSync14(graphPath, JSON.stringify(graph2, null, 2) + "\n", "utf8");
     const graphRel = relative6(process.cwd(), graphPath).replace(/\\/g, "/");
     if (!graphRel.startsWith("..")) {
       ensureGitignoreEntry(process.cwd(), graphRel, "cdd-kit local cache (do not commit)");
@@ -10002,8 +10446,8 @@ var init_code_map = __esm({
     init_digest();
     init_gitignore();
     _require = createRequire(import.meta.url);
-    _pkgPath = join21(fileURLToPath2(import.meta.url), "..", "..", "..", "package.json");
-    _pkg = JSON.parse(readFileSync22(_pkgPath, "utf8"));
+    _pkgPath = join24(fileURLToPath2(import.meta.url), "..", "..", "..", "package.json");
+    _pkg = JSON.parse(readFileSync26(_pkgPath, "utf8"));
   }
 });
 
@@ -10012,15 +10456,15 @@ var refresh_exports = {};
 __export(refresh_exports, {
   refresh: () => refresh
 });
-import { existsSync as existsSync20, mkdirSync as mkdirSync9, readdirSync as readdirSync10, copyFileSync as copyFileSync4, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname6, join as join22, relative as relative7 } from "path";
+import { existsSync as existsSync24, mkdirSync as mkdirSync11, readdirSync as readdirSync10, copyFileSync as copyFileSync5, readFileSync as readFileSync27, writeFileSync as writeFileSync15 } from "fs";
+import { dirname as dirname7, join as join25, relative as relative7 } from "path";
 import { createHash as createHash7 } from "crypto";
 function fileHash2(filePath) {
-  return createHash7("sha256").update(readFileSync23(filePath)).digest("hex");
+  return createHash7("sha256").update(readFileSync27(filePath)).digest("hex");
 }
 function planForceRefresh(srcDir, destDir, sectionLabel) {
   const plan = [];
-  if (!existsSync20(srcDir))
+  if (!existsSync24(srcDir))
     return plan;
   function walk(curSrc, curDest) {
     let items;
@@ -10030,16 +10474,16 @@ function planForceRefresh(srcDir, destDir, sectionLabel) {
       return;
     }
     for (const item of items) {
-      const sp = join22(curSrc, item.name);
-      const dp = join22(curDest, item.name);
+      const sp = join25(curSrc, item.name);
+      const dp = join25(curDest, item.name);
       if (item.isDirectory()) {
         walk(sp, dp);
         continue;
       }
       if (!item.isFile())
         continue;
-      const rel = join22(sectionLabel, relative7(srcDir, sp)).replace(/\\/g, "/");
-      if (!existsSync20(dp)) {
+      const rel = join25(sectionLabel, relative7(srcDir, sp)).replace(/\\/g, "/");
+      if (!existsSync24(dp)) {
         plan.push({ src: sp, dest: dp, rel, action: "add" });
       } else if (fileHash2(sp) !== fileHash2(dp)) {
         plan.push({ src: sp, dest: dp, rel, action: "overwrite" });
@@ -10052,9 +10496,9 @@ function planForceRefresh(srcDir, destDir, sectionLabel) {
   return plan;
 }
 function planSingleFile(src, dest, rel) {
-  if (!existsSync20(src))
+  if (!existsSync24(src))
     return null;
-  if (!existsSync20(dest))
+  if (!existsSync24(dest))
     return { src, dest, rel, action: "add" };
   if (fileHash2(src) !== fileHash2(dest))
     return { src, dest, rel, action: "overwrite" };
@@ -10067,15 +10511,15 @@ function applyPlan(plan, backupRoot) {
     if (item.action === "skip")
       continue;
     if (item.action === "overwrite") {
-      const backupPath = join22(backupRoot, item.rel);
-      mkdirSync9(dirname6(backupPath), { recursive: true });
-      copyFileSync4(item.dest, backupPath);
+      const backupPath = join25(backupRoot, item.rel);
+      mkdirSync11(dirname7(backupPath), { recursive: true });
+      copyFileSync5(item.dest, backupPath);
       overwritten += 1;
     } else {
       added += 1;
     }
-    mkdirSync9(dirname6(item.dest), { recursive: true });
-    copyFileSync4(item.src, item.dest);
+    mkdirSync11(dirname7(item.dest), { recursive: true });
+    copyFileSync5(item.src, item.dest);
   }
   return { added, overwritten };
 }
@@ -10096,14 +10540,14 @@ function parseAgentFrontmatter(content) {
   return fm;
 }
 function resyncModelPolicy(cwd) {
-  const policyPath = join22(cwd, ".cdd", "model-policy.json");
+  const policyPath = join25(cwd, ".cdd", "model-policy.json");
   const result = { changed: false, diff: [], policyPath };
-  if (!existsSync20(AGENTS_HOME))
+  if (!existsSync24(AGENTS_HOME))
     return result;
   const desired = {};
   const agentFiles = readdirSync10(AGENTS_HOME, { withFileTypes: true }).filter((d) => d.isFile() && d.name.endsWith(".md"));
   for (const f of agentFiles) {
-    const content = readFileSync23(join22(AGENTS_HOME, f.name), "utf8");
+    const content = readFileSync27(join25(AGENTS_HOME, f.name), "utf8");
     const fm = parseAgentFrontmatter(content);
     if (fm.name && fm.model)
       desired[fm.name] = fm.model;
@@ -10111,9 +10555,9 @@ function resyncModelPolicy(cwd) {
   if (Object.keys(desired).length === 0)
     return result;
   let existing = {};
-  if (existsSync20(policyPath)) {
+  if (existsSync24(policyPath)) {
     try {
-      existing = JSON.parse(readFileSync23(policyPath, "utf8"));
+      existing = JSON.parse(readFileSync27(policyPath, "utf8"));
     } catch {
     }
   }
@@ -10133,8 +10577,8 @@ function resyncModelPolicy(cwd) {
     merged["schema-version"] = "0.2.0";
   if (!("provider" in merged))
     merged["provider"] = "claude";
-  mkdirSync9(dirname6(policyPath), { recursive: true });
-  writeFileSync12(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  mkdirSync11(dirname7(policyPath), { recursive: true });
+  writeFileSync15(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
   result.changed = true;
   return result;
 }
@@ -10142,21 +10586,21 @@ function planTemplateRefresh(cwd) {
   const sections = [];
   sections.push({
     name: "specs/templates",
-    plan: planForceRefresh(ASSET.specsTemplates, join22(cwd, "specs", "templates"), "specs/templates")
+    plan: planForceRefresh(ASSET.specsTemplates, join25(cwd, "specs", "templates"), "specs/templates")
   });
   sections.push({
     name: "tests/templates",
-    plan: planForceRefresh(ASSET.testsTemplates, join22(cwd, "tests", "templates"), "tests/templates")
+    plan: planForceRefresh(ASSET.testsTemplates, join25(cwd, "tests", "templates"), "tests/templates")
   });
-  const ciTemplatesAsset = join22(ASSET.ci, "..", "ci-templates");
-  if (existsSync20(ciTemplatesAsset)) {
+  const ciTemplatesAsset = join25(ASSET.ci, "..", "ci-templates");
+  if (existsSync24(ciTemplatesAsset)) {
     sections.push({
       name: "ci-templates",
-      plan: planForceRefresh(ciTemplatesAsset, join22(cwd, "ci-templates"), "ci-templates")
+      plan: planForceRefresh(ciTemplatesAsset, join25(cwd, "ci-templates"), "ci-templates")
     });
   }
-  const wfAsset = join22(ASSET.githubWorkflows, "contract-driven-gates.yml");
-  const wfDest = join22(cwd, ".github", "workflows", "contract-driven-gates.yml");
+  const wfAsset = join25(ASSET.githubWorkflows, "contract-driven-gates.yml");
+  const wfDest = join25(cwd, ".github", "workflows", "contract-driven-gates.yml");
   const wfPlan = planSingleFile(wfAsset, wfDest, ".github/workflows/contract-driven-gates.yml");
   if (wfPlan)
     sections.push({ name: ".github/workflows/contract-driven-gates.yml", plan: [wfPlan] });
@@ -10211,7 +10655,7 @@ async function refresh(opts) {
       }
       if (apply) {
         const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-        backupRoot = join22(cwd, ".cdd", ".refresh-backup", ts);
+        backupRoot = join25(cwd, ".cdd", ".refresh-backup", ts);
         const result = applyPlan(total, backupRoot);
         templateAdded = result.added;
         templateOverwritten = result.overwritten;
@@ -10231,8 +10675,8 @@ async function refresh(opts) {
   }
   log.blank();
   if (!opts.noHooks) {
-    const markerPath = join22(cwd, HOOKS_MARKER_PATH);
-    if (existsSync20(markerPath)) {
+    const markerPath = join25(cwd, HOOKS_MARKER_PATH);
+    if (existsSync24(markerPath)) {
       log.info("[4/6] re-install code-map pre-commit hook (marker found)");
       if (apply) {
         try {
@@ -10301,7 +10745,7 @@ async function refresh(opts) {
     logRecommendedMcpSetup();
   } else {
     log.info("Dry-run finished. Re-run with `--yes` to apply.");
-    log.info('After applying, configure MCP with command `cdd-kit` and args ["mcp"] so agents use graph/code-map tools directly.');
+    log.info("After applying, register MCP with `claude mcp add --scope user cdd-kit -- cdd-kit mcp` so agents use graph/code-map tools directly.");
   }
   log.blank();
 }
@@ -10328,8 +10772,8 @@ __export(lint_agents_exports, {
   lintAgentContent: () => lintAgentContent,
   lintAgents: () => lintAgents
 });
-import { readdirSync as readdirSync11, readFileSync as readFileSync24 } from "fs";
-import { join as join23 } from "path";
+import { readdirSync as readdirSync11, readFileSync as readFileSync28 } from "fs";
+import { join as join26 } from "path";
 import { load as yamlLoad2 } from "js-yaml";
 function extractRequiredArtifactsSection(content) {
   const match = content.match(
@@ -10458,7 +10902,7 @@ function lintAgentContent(filename, rawContent, opts = {}) {
   return violations;
 }
 function collectAgentViolations(cwd, opts = {}) {
-  const agentsDir = join23(cwd, ".claude", "agents");
+  const agentsDir = join26(cwd, ".claude", "agents");
   let files;
   try {
     files = readdirSync11(agentsDir).filter((f) => f.endsWith(".md")).sort();
@@ -10469,7 +10913,7 @@ function collectAgentViolations(cwd, opts = {}) {
   for (const filename of files) {
     let content;
     try {
-      content = readFileSync24(join23(agentsDir, filename), "utf8");
+      content = readFileSync28(join26(agentsDir, filename), "utf8");
     } catch {
       violations.push({
         file: filename,
@@ -10488,7 +10932,7 @@ async function lintAgents(opts) {
   const violations = collectAgentViolations(cwd, opts);
   if (violations === null) {
     log.error(
-      `lint-agents: cannot read ${join23(cwd, ".claude", "agents")} -- is this a cdd-kit project?`
+      `lint-agents: cannot read ${join26(cwd, ".claude", "agents")} -- is this a cdd-kit project?`
     );
     return 1;
   }
@@ -10513,22 +10957,132 @@ var init_lint_agents = __esm({
   }
 });
 
+// src/commands/chokepoints.ts
+import { existsSync as existsSync25, readFileSync as readFileSync29, readdirSync as readdirSync12 } from "fs";
+import { join as join27, resolve as resolve4 } from "path";
+import { spawnSync as spawnSync5 } from "child_process";
+function safeRead2(path) {
+  try {
+    return readFileSync29(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function probeGraphFirst(cwd) {
+  const settingsPath = join27(cwd, ".claude", "settings.json");
+  let live = false;
+  if (existsSync25(settingsPath)) {
+    try {
+      const settings = JSON.parse(safeRead2(settingsPath));
+      const entries = settings.hooks?.PreToolUse;
+      if (Array.isArray(entries)) {
+        live = entries.some(
+          (e) => Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes(GRAPH_FIRST_MARKER))
+        );
+      }
+    } catch {
+    }
+  }
+  return {
+    id: "graph-first-hook",
+    name: "graph-first exploration hook",
+    live,
+    detail: live ? "PreToolUse hook steers agents to graph/index queries before Read" : "dormant \u2014 run `cdd-kit install-agent-hooks --graph-first advisory` to stop agents defaulting to Read"
+  };
+}
+function resolveHooksDir2(cwd) {
+  try {
+    const res = spawnSync5("git", ["rev-parse", "--git-path", "hooks"], { cwd, encoding: "utf8" });
+    if (res.status === 0 && res.stdout.trim())
+      return resolve4(cwd, res.stdout.trim());
+  } catch {
+  }
+  return join27(cwd, ".git", "hooks");
+}
+function probePreCommitGate(cwd) {
+  const hookPath = join27(resolveHooksDir2(cwd), "pre-commit");
+  const live = existsSync25(hookPath) && safeRead2(hookPath).includes(PRECOMMIT_MARKER);
+  return {
+    id: "pre-commit-gate",
+    name: "pre-commit gate hook",
+    live,
+    detail: live ? "`cdd-kit gate` runs before each commit touching specs/contracts" : "dormant \u2014 run `cdd-kit install-hooks` to block commits that fail the gate"
+  };
+}
+function probeOpenApiGate(cwd) {
+  let where = "";
+  const pkgPath = join27(cwd, "package.json");
+  if (existsSync25(pkgPath)) {
+    try {
+      const pkg2 = JSON.parse(safeRead2(pkgPath));
+      const scripts = pkg2.scripts ?? {};
+      for (const [name, cmd] of Object.entries(scripts)) {
+        if (typeof cmd === "string" && cmd.includes(OPENAPI_CHECK_MARKER)) {
+          where = `package.json script \`${name}\``;
+          break;
+        }
+      }
+    } catch {
+    }
+  }
+  if (!where) {
+    const wfDir = join27(cwd, ".github", "workflows");
+    if (existsSync25(wfDir)) {
+      try {
+        for (const entry of readdirSync12(wfDir)) {
+          if (!/\.ya?ml$/.test(entry))
+            continue;
+          if (safeRead2(join27(wfDir, entry)).includes(OPENAPI_CHECK_MARKER)) {
+            where = `CI workflow ${entry}`;
+            break;
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  const live = where !== "";
+  return {
+    id: "openapi-sync-gate",
+    name: "OpenAPI sync gate",
+    live,
+    detail: live ? `\`cdd-kit openapi export --check\` runs in ${where}` : "dormant \u2014 wire `cdd-kit openapi export --check --out <artifact>` into CI or a package.json script (or run `cdd-kit init`)"
+  };
+}
+function detectChokepoints(cwd) {
+  return [
+    probeGraphFirst(cwd),
+    probePreCommitGate(cwd),
+    probeOpenApiGate(cwd)
+  ];
+}
+var GRAPH_FIRST_MARKER, PRECOMMIT_MARKER, OPENAPI_CHECK_MARKER;
+var init_chokepoints = __esm({
+  "src/commands/chokepoints.ts"() {
+    "use strict";
+    GRAPH_FIRST_MARKER = "pre-tool-use-graph-first";
+    PRECOMMIT_MARKER = "# cdd-kit-managed-block-start";
+    OPENAPI_CHECK_MARKER = "openapi export --check";
+  }
+});
+
 // src/commands/doctor.ts
 var doctor_exports = {};
 __export(doctor_exports, {
   doctor: () => doctor
 });
-import { existsSync as existsSync21, readdirSync as readdirSync12, readFileSync as readFileSync25 } from "fs";
+import { existsSync as existsSync26, readdirSync as readdirSync13, readFileSync as readFileSync30 } from "fs";
 import { createHash as createHash8 } from "crypto";
-import { join as join24, relative as relative8 } from "path";
+import { spawnSync as spawnSync6 } from "child_process";
+import { join as join28, relative as relative8 } from "path";
 function fileExists(cwd, relPath) {
-  return existsSync21(join24(cwd, relPath));
+  return existsSync26(join28(cwd, relPath));
 }
 function findFiles(dir, predicate, found = []) {
-  if (!existsSync21(dir))
+  if (!existsSync26(dir))
     return found;
-  for (const entry of readdirSync12(dir, { withFileTypes: true })) {
-    const fullPath = join24(dir, entry.name);
+  for (const entry of readdirSync13(dir, { withFileTypes: true })) {
+    const fullPath = join28(dir, entry.name);
     if (entry.isDirectory())
       findFiles(fullPath, predicate, found);
     else if (entry.isFile() && predicate(entry.name))
@@ -10544,9 +11098,9 @@ function inputDigest(paths, cwd) {
   return createHash8("sha256").update(combined).digest("hex");
 }
 function readContextIndexMetadata(filePath) {
-  if (!existsSync21(filePath))
+  if (!existsSync26(filePath))
     return {};
-  const text = readFileSync25(filePath, "utf8");
+  const text = readFileSync30(filePath, "utf8");
   const out = {};
   const digestMatch = text.match(/^inputs-digest:\s*([a-f0-9]+)/m);
   if (digestMatch)
@@ -10558,14 +11112,14 @@ function readContextIndexMetadata(filePath) {
 }
 function checkContextFreshness(cwd) {
   const findings = [];
-  const projectMap = join24(cwd, "specs", "context", "project-map.md");
-  const contractsIndex = join24(cwd, "specs", "context", "contracts-index.md");
-  const contextPolicy = join24(cwd, ".cdd", "context-policy.json");
+  const projectMap = join28(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join28(cwd, "specs", "context", "contracts-index.md");
+  const contextPolicy = join28(cwd, ".cdd", "context-policy.json");
   const contractFiles = findFiles(
-    join24(cwd, "contracts"),
+    join28(cwd, "contracts"),
     (name) => name.endsWith(".md") && name !== "INDEX.md" && name !== "CHANGELOG.md"
   );
-  if (!existsSync21(projectMap) || !existsSync21(contractsIndex)) {
+  if (!existsSync26(projectMap) || !existsSync26(contractsIndex)) {
     findings.push({
       level: "warning",
       message: "specs/context indexes are missing; run cdd-kit context-scan before classification"
@@ -10574,7 +11128,7 @@ function checkContextFreshness(cwd) {
   }
   const projectMapMeta = readContextIndexMetadata(projectMap);
   const contractsIndexMeta = readContextIndexMetadata(contractsIndex);
-  const projectInputDigest = inputDigest([contextPolicy].filter(existsSync21), cwd);
+  const projectInputDigest = inputDigest([contextPolicy].filter(existsSync26), cwd);
   if (projectMapMeta.inputsDigest === void 0) {
     findings.push({
       level: "warning",
@@ -10611,7 +11165,7 @@ function checkContextFreshness(cwd) {
 }
 function readAgentModel(path) {
   try {
-    const text = readFileSync25(path, "utf8");
+    const text = readFileSync30(path, "utf8");
     const m = text.match(/^model:\s*(\S+)/m);
     return m ? m[1] : null;
   } catch {
@@ -10619,12 +11173,12 @@ function readAgentModel(path) {
   }
 }
 function checkModelPolicyDrift(cwd) {
-  const policyPath = join24(cwd, ".cdd", "model-policy.json");
-  if (!existsSync21(policyPath))
+  const policyPath = join28(cwd, ".cdd", "model-policy.json");
+  if (!existsSync26(policyPath))
     return [];
   let policy;
   try {
-    policy = JSON.parse(readFileSync25(policyPath, "utf8"));
+    policy = JSON.parse(readFileSync30(policyPath, "utf8"));
   } catch {
     return [{ level: "warning", message: ".cdd/model-policy.json is not valid JSON" }];
   }
@@ -10636,18 +11190,18 @@ function checkModelPolicyDrift(cwd) {
     }];
   }
   const candidateDirs = [
-    join24(cwd, ".claude", "agents"),
-    process.env.HOME ? join24(process.env.HOME, ".claude", "agents") : "",
-    process.env.USERPROFILE ? join24(process.env.USERPROFILE, ".claude", "agents") : ""
-  ].filter((p) => p && existsSync21(p));
+    join28(cwd, ".claude", "agents"),
+    process.env.HOME ? join28(process.env.HOME, ".claude", "agents") : "",
+    process.env.USERPROFILE ? join28(process.env.USERPROFILE, ".claude", "agents") : ""
+  ].filter((p) => p && existsSync26(p));
   if (candidateDirs.length === 0)
     return [];
   const findings = [];
   for (const [role, expected] of Object.entries(roles)) {
     let foundAny = false;
     for (const dir of candidateDirs) {
-      const path = join24(dir, `${role}.md`);
-      if (!existsSync21(path))
+      const path = join28(dir, `${role}.md`);
+      if (!existsSync26(path))
         continue;
       foundAny = true;
       const actual = readAgentModel(path);
@@ -10667,14 +11221,14 @@ function checkModelPolicyDrift(cwd) {
   return findings;
 }
 function checkAgentLint(cwd) {
-  const agentsDir = join24(cwd, ".claude", "agents");
-  if (!existsSync21(agentsDir))
+  const agentsDir = join28(cwd, ".claude", "agents");
+  if (!existsSync26(agentsDir))
     return [];
   const violations = collectAgentViolations(cwd);
   if (violations === null) {
     return [{
       level: "warning",
-      message: `lint-agents: could not read ${join24(".claude", "agents")} -- agent prompts were not scanned`
+      message: `lint-agents: could not read ${join28(".claude", "agents")} -- agent prompts were not scanned`
     }];
   }
   const findings = violations.map((v) => ({
@@ -10688,8 +11242,8 @@ function checkAgentLint(cwd) {
 }
 function checkCodeMap(cwd) {
   const findings = [];
-  const mapPath = join24(cwd, ".cdd", "code-map.yml");
-  if (!existsSync21(mapPath)) {
+  const mapPath = join28(cwd, ".cdd", "code-map.yml");
+  if (!existsSync26(mapPath)) {
     const probe2 = checkCodeMapFreshness(cwd);
     if (probe2.status === "config-error") {
       findings.push({ level: "warning", message: `.cdd/code-map-config.yml is invalid: ${probe2.configError}` });
@@ -10708,7 +11262,7 @@ function checkCodeMap(cwd) {
     const more = probe.staleCount > 3 ? ` (+${probe.staleCount - 3} more)` : "";
     findings.push({ level: "warning", message: `code-map stale: ${top}${more}; run \`cdd-kit code-map\`` });
   }
-  const text = readFileSync25(mapPath, "utf8");
+  const text = readFileSync30(mapPath, "utf8");
   const m = text.match(/^# files: (\d+), src-lines: (\d+), map-lines: (\d+), compression: ([\d.]+)x/m);
   if (m) {
     findings.push({ level: "ok", message: `code-map: ${m[1]} files, ${m[4]}x compression` });
@@ -10717,6 +11271,68 @@ function checkCodeMap(cwd) {
   }
   return findings;
 }
+function checkApiConformance(cwd) {
+  const hasContract = existsSync26(join28(cwd, "contracts", "api", "api-contract.md"));
+  if (!hasContract)
+    return [];
+  const configPath = join28(cwd, ".cdd", "conformance.json");
+  if (!existsSync26(configPath)) {
+    return [{
+      level: "ok",
+      message: 'API conformance: not configured (add .cdd/conformance.json with "enabled": true to catch frontend/backend drift against the contract)'
+    }];
+  }
+  try {
+    const cfg = JSON.parse(readFileSync30(configPath, "utf8"));
+    return [{
+      level: "ok",
+      message: cfg.enabled ? "API conformance: enabled (cdd-kit validate --contracts checks code against the API contract)" : 'API conformance: present but disabled (set "enabled": true in .cdd/conformance.json to enforce code-vs-contract checks)'
+    }];
+  } catch {
+    return [{ level: "warning", message: ".cdd/conformance.json is not valid JSON" }];
+  }
+}
+function checkMcpRegistration(cwd, provider) {
+  if (provider !== "claude" && provider !== "both")
+    return [];
+  if (!existsSync26(join28(cwd, ".cdd")))
+    return [];
+  const bin = process.env.CDD_CLAUDE_BIN || "claude";
+  let result;
+  try {
+    result = bin.toLowerCase().endsWith(".js") ? spawnSync6(process.execPath, [bin, "mcp", "list"], { encoding: "utf8", timeout: 3e3 }) : spawnSync6(bin, ["mcp", "list"], { encoding: "utf8", timeout: 3e3 });
+  } catch {
+    result = { error: new Error("spawn failed") };
+  }
+  if (result.error || typeof result.status !== "number") {
+    return [{
+      level: "ok",
+      message: "MCP: could not run `claude mcp list` (Claude Code CLI not found); skip if you do not use Claude Code"
+    }];
+  }
+  if (result.status !== 0) {
+    return [{
+      level: "ok",
+      message: `MCP: \`claude mcp list\` exited ${result.status}; cannot verify cdd-kit registration`
+    }];
+  }
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  if (/\bcdd-kit\b/.test(output)) {
+    return [{ level: "ok", message: "MCP: cdd-kit server is registered with Claude Code" }];
+  }
+  return [{
+    level: "ok",
+    message: "MCP: cdd-kit not registered \u2014 agents will fall back to Read instead of graph/index tools; run `claude mcp add --scope user cdd-kit -- cdd-kit mcp`"
+  }];
+}
+function checkChokepoints(cwd) {
+  if (!existsSync26(join28(cwd, ".cdd")))
+    return [];
+  return detectChokepoints(cwd).map((c) => ({
+    level: "ok",
+    message: c.live ? `chokepoint ${c.name}: live \u2014 ${c.detail}` : `chokepoint ${c.name}: ${c.detail}`
+  }));
+}
 async function buildDoctorReport(cwd, opts) {
   const requestedProvider = opts.provider ?? "auto";
   if (!validateProviderOption(requestedProvider)) {
@@ -10742,6 +11358,9 @@ async function buildDoctorReport(cwd, opts) {
   findings.push(...checkModelPolicyDrift(cwd));
   findings.push(...checkAgentLint(cwd));
   findings.push(...checkCodeMap(cwd));
+  findings.push(...checkApiConformance(cwd));
+  findings.push(...checkMcpRegistration(cwd, provider));
+  findings.push(...checkChokepoints(cwd));
   const errors = findings.filter((finding) => finding.level === "error").length;
   const warnings = findings.filter((finding) => finding.level === "warning").length;
   return {
@@ -10784,11 +11403,11 @@ async function attemptAutoFixes(cwd, report) {
       }
     }
     if (/model-policy\.json has no role bindings/i.test(finding.message)) {
-      const policyPath = join24(cwd, ".cdd", "model-policy.json");
+      const policyPath = join28(cwd, ".cdd", "model-policy.json");
       try {
         let existing = {};
         try {
-          existing = JSON.parse(readFileSync25(policyPath, "utf8"));
+          existing = JSON.parse(readFileSync30(policyPath, "utf8"));
         } catch {
         }
         const merged = {
@@ -10813,8 +11432,8 @@ async function attemptAutoFixes(cwd, report) {
             "repo-context-scanner": "haiku"
           }
         };
-        const { writeFileSync: writeFileSync16 } = await import("fs");
-        writeFileSync16(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        const { writeFileSync: writeFileSync19 } = await import("fs");
+        writeFileSync19(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
         fixed.push(`populated .cdd/model-policy.json with default role bindings`);
         continue;
       } catch (err) {
@@ -10883,16 +11502,188 @@ var init_doctor = __esm({
     init_provider();
     init_freshness();
     init_lint_agents();
+    init_chokepoints();
     init_digest();
   }
 });
 
-// src/commands/code-map-scan-worker.ts
-var code_map_scan_worker_exports = {};
-__export(code_map_scan_worker_exports, {
-  runScanWorker: () => runScanWorker
+// src/commands/code-map-watch.ts
+var code_map_watch_exports = {};
+__export(code_map_watch_exports, {
+  codeMapWatch: () => codeMapWatch,
+  createDebouncedRunner: () => createDebouncedRunner,
+  generatedArtifactSet: () => generatedArtifactSet,
+  makeWatchExcludeFilter: () => makeWatchExcludeFilter
 });
-import { readFileSync as readFileSync26 } from "fs";
+import { watch } from "fs";
+import { resolve as resolve5 } from "path";
+import picomatch2 from "picomatch";
+function createDebouncedRunner(run, debounceMs) {
+  let timer = null;
+  let running = false;
+  let queued = false;
+  async function fire() {
+    if (running) {
+      queued = true;
+      return;
+    }
+    running = true;
+    try {
+      await run();
+    } finally {
+      running = false;
+      if (queued) {
+        queued = false;
+        void fire();
+      }
+    }
+  }
+  function trigger() {
+    if (timer)
+      clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void fire();
+    }, debounceMs);
+  }
+  function dispose() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  return { trigger, dispose };
+}
+function generatedArtifactSet(outRel, cwd = process.cwd()) {
+  return /* @__PURE__ */ new Set([
+    resolve5(cwd, outRel),
+    resolve5(cwd, sidecarPathFor(outRel)),
+    resolve5(cwd, graphPathFor(outRel))
+  ]);
+}
+function makeWatchExcludeFilter(excludes, configRel = CONFIG_REL_PATH) {
+  if (excludes.length === 0)
+    return () => false;
+  const match = picomatch2(excludes, { dot: true });
+  return (rel) => rel !== configRel && (match(rel) || match(`${rel}/**`));
+}
+async function codeMapWatch(opts) {
+  const debounceMs = opts.debounceMs ?? 500;
+  const pollMs = opts.pollMs ?? 2e3;
+  const scanPath = opts.surface ?? opts.path;
+  const root = resolve5(process.cwd(), scanPath);
+  const outRel = opts.out ?? (opts.surface ? `.cdd/code-map.${slugifySurface(opts.surface)}.yml` : ".cdd/code-map.yml");
+  const generatedAbs = generatedArtifactSet(outRel);
+  let isExcluded = () => false;
+  try {
+    const cfg = loadCodeMapConfig(root);
+    isExcluded = makeWatchExcludeFilter([...cfg.exclude, ...opts.exclude ?? []]);
+  } catch {
+  }
+  const rebuild = async () => {
+    const exit = await codeMap({ ...opts, check: false, silent: true });
+    if (exit === 0) {
+      log.ok(`code-map refreshed (${(/* @__PURE__ */ new Date()).toLocaleTimeString()})`);
+    } else {
+      log.warn("code-map refresh reported a problem; map left unchanged where possible.");
+    }
+    return exit;
+  };
+  log.info(`code-map --watch: building initial map for ${scanPath}\u2026`);
+  const initialExit = await rebuild();
+  if (initialExit !== 0) {
+    log.error("code-map --watch: initial build failed; not starting the watcher.");
+    return initialExit;
+  }
+  const { trigger, dispose } = createDebouncedRunner(() => rebuild().then(() => void 0), debounceMs);
+  let watcher = null;
+  let pollTimer = null;
+  let driftChecking = false;
+  const triggerIfDrift = () => {
+    if (driftChecking)
+      return;
+    driftChecking = true;
+    void codeMap({ ...opts, check: true, silent: true }).then((drift) => {
+      if (drift !== 0)
+        trigger();
+    }).finally(() => {
+      driftChecking = false;
+    });
+  };
+  const startPolling = (reason) => {
+    if (pollTimer)
+      return;
+    if (reason)
+      log.warn(reason);
+    pollTimer = setInterval(triggerIfDrift, pollMs);
+    log.ok(`polling ${scanPath} every ${pollMs}ms. Ctrl-C to stop.`);
+  };
+  const isSelfWrite = (filename) => {
+    return generatedAbs.has(resolve5(root, filename));
+  };
+  try {
+    watcher = watch(root, { recursive: true }, (_event, filename) => {
+      if (filename) {
+        const rel = filename.toString();
+        if (isSelfWrite(rel))
+          return;
+        if (isExcluded(rel.replace(/\\/g, "/")))
+          return;
+        trigger();
+      } else {
+        triggerIfDrift();
+      }
+    });
+    watcher.on("error", (err) => {
+      log.warn(`watch error (${err.message}); closing watcher and falling back to polling.`);
+      try {
+        watcher?.close();
+      } catch {
+      }
+      watcher = null;
+      startPolling();
+    });
+    log.ok(`watching ${scanPath} (recursive, debounce ${debounceMs}ms). Ctrl-C to stop.`);
+  } catch {
+    startPolling("recursive fs.watch unavailable on this platform; falling back to freshness polling.");
+  }
+  return await new Promise((resolvePromise) => {
+    const stop = () => {
+      dispose();
+      if (watcher)
+        watcher.close();
+      if (pollTimer)
+        clearInterval(pollTimer);
+      log.info("code-map --watch stopped.");
+      resolvePromise(0);
+    };
+    const signal = opts.signal;
+    if (signal) {
+      if (signal.aborted) {
+        stop();
+        return;
+      }
+      signal.addEventListener("abort", stop, { once: true });
+    }
+  });
+}
+var init_code_map_watch = __esm({
+  "src/commands/code-map-watch.ts"() {
+    "use strict";
+    init_logger();
+    init_code_map();
+    init_config();
+    init_index_reader();
+    init_reader();
+  }
+});
+
+// src/commands/code-map-scan-worker.ts
+var code_map_scan_worker_exports = {};
+__export(code_map_scan_worker_exports, {
+  runScanWorker: () => runScanWorker
+});
+import { readFileSync as readFileSync31 } from "fs";
 async function runScanWorker(opts) {
   let scanner;
   switch (opts.lang) {
@@ -10912,7 +11703,7 @@ async function runScanWorker(opts) {
   }
   let files;
   try {
-    files = readFileSync26(opts.batchFile, "utf8").split("\n").map((s) => s.trim()).filter(Boolean);
+    files = readFileSync31(opts.batchFile, "utf8").split("\n").map((s) => s.trim()).filter(Boolean);
   } catch (err) {
     process.stderr.write(`__code-map-scan: cannot read --batch-file: ${err.message}
 `);
@@ -10932,10 +11723,16 @@ var init_code_map_scan_worker = __esm({
 // src/commands/index-query.ts
 var index_query_exports = {};
 __export(index_query_exports, {
+  DEFAULT_SOURCE_BUDGET: () => DEFAULT_SOURCE_BUDGET,
   indexQuery: () => indexQuery,
-  queryEntries: () => queryEntries
+  queryEntries: () => queryEntries,
+  resolveSourceBudget: () => resolveSourceBudget,
+  surfaceRootFor: () => surfaceRootFor
 });
-import { existsSync as existsSync22 } from "fs";
+import { existsSync as existsSync27, readFileSync as readFileSync32 } from "fs";
+function resolveSourceBudget(budget) {
+  return Number.isFinite(budget) && budget > 0 ? Math.floor(budget) : DEFAULT_SOURCE_BUDGET;
+}
 async function indexQuery(term, opts) {
   const mapPath = opts.map || ".cdd/code-map.yml";
   const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 10;
@@ -10945,7 +11742,7 @@ async function indexQuery(term, opts) {
     return printFailure(freshness.error, opts.json);
   }
   refreshed = freshness.refreshed;
-  if (!existsSync22(mapPath)) {
+  if (!existsSync27(mapPath)) {
     return printFailure(`${mapPath} is missing; run \`cdd-kit code-map\` first.`, opts.json);
   }
   let entries;
@@ -10955,6 +11752,9 @@ async function indexQuery(term, opts) {
     return printFailure(`${mapPath} is not readable YAML: ${err.message}`, opts.json);
   }
   const results = queryEntries(entries, term).slice(0, limit);
+  if (opts.withSource) {
+    attachSource(results, resolveSourceBudget(opts.sourceBudget), surfaceRootFor(mapPath));
+  }
   const payload = {
     index: mapPath,
     query: term,
@@ -11073,6 +11873,68 @@ function firstLine(lines) {
   const m = lines?.match(/^\d+/);
   return m ? Number(m[0]) : Number.MAX_SAFE_INTEGER;
 }
+function surfaceRootFor(mapPath) {
+  try {
+    if (!existsSync27(mapPath))
+      return void 0;
+    const head = readFileSync32(mapPath, "utf8").slice(0, 4096);
+    const m = head.match(/^# surface-root:\s*(.+)$/m);
+    return m ? m[1].trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function attachSource(results, budget, baseDir) {
+  const fileCache = /* @__PURE__ */ new Map();
+  let used = 0;
+  const readLines = (path) => {
+    if (fileCache.has(path))
+      return fileCache.get(path) ?? null;
+    let lines = null;
+    try {
+      const resolved = baseDir && baseDir !== "." ? `${baseDir.replace(/\/+$/, "")}/${path}` : path;
+      lines = existsSync27(resolved) ? readFileSync32(resolved, "utf8").split(/\r?\n/) : null;
+    } catch {
+      lines = null;
+    }
+    fileCache.set(path, lines);
+    return lines;
+  };
+  for (const result of results) {
+    const fileLines = readLines(result.path);
+    if (!fileLines)
+      continue;
+    for (const match of result.matches) {
+      const range = resolveRange(match);
+      if (!range)
+        continue;
+      const [start, end] = range;
+      if (used >= budget) {
+        match.source_truncated = true;
+        continue;
+      }
+      const allowedEnd = Math.min(end, start + (budget - used) - 1);
+      const slice = fileLines.slice(start - 1, allowedEnd);
+      match.source = slice.join("\n");
+      used += slice.length;
+      if (allowedEnd < end)
+        match.source_truncated = true;
+    }
+  }
+}
+function resolveRange(match) {
+  if (match.lines) {
+    const m = match.lines.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (m)
+      return [Number(m[1]), Number(m[2])];
+    const single = match.lines.match(/^(\d+)$/);
+    if (single)
+      return [Number(single[1]), Number(single[1])];
+  }
+  if (typeof match.line === "number")
+    return [match.line, match.line];
+  return null;
+}
 function printText(payload) {
   if (payload.results.length === 0) {
     console.log(`No matches for "${payload.query}" in ${payload.index}.`);
@@ -11088,9 +11950,18 @@ function printText(payload) {
       const loc = match.lines ? ` lines ${match.lines}` : match.line ? ` line ${match.line}` : "";
       const detail = match.detail && match.detail !== match.name ? ` - ${match.detail}` : "";
       console.log(`  - ${match.kind}: ${match.name}${loc}${detail}`);
+      if (match.source !== void 0) {
+        for (const srcLine of match.source.split("\n")) {
+          console.log(`      | ${srcLine}`);
+        }
+        if (match.source_truncated)
+          console.log("      | \u2026 (source budget reached; Read the rest directly)");
+      } else if (match.source_truncated) {
+        console.log("      (source budget reached; Read this range directly)");
+      }
     }
   }
-  console.log("Next: read only the listed file/ranges first.");
+  console.log(payload.results.some((r) => r.matches.some((m) => m.source !== void 0)) ? "Source included above \u2014 no separate Read needed for these ranges." : "Next: read only the listed file/ranges first.");
 }
 function printFailure(message, json) {
   if (json) {
@@ -11101,10 +11972,12 @@ function printFailure(message, json) {
   }
   return 1;
 }
+var DEFAULT_SOURCE_BUDGET;
 var init_index_query = __esm({
   "src/commands/index-query.ts"() {
     "use strict";
     init_index_reader();
+    DEFAULT_SOURCE_BUDGET = 400;
   }
 });
 
@@ -11113,7 +11986,7 @@ var index_impact_exports = {};
 __export(index_impact_exports, {
   indexImpact: () => indexImpact
 });
-import { existsSync as existsSync23 } from "fs";
+import { existsSync as existsSync28 } from "fs";
 import { posix as posix2 } from "path";
 async function indexImpact(term, opts) {
   const mapPath = opts.map || ".cdd/code-map.yml";
@@ -11122,7 +11995,7 @@ async function indexImpact(term, opts) {
   if (freshness.error) {
     return printFailure2(freshness.error, opts.json);
   }
-  if (!existsSync23(mapPath)) {
+  if (!existsSync28(mapPath)) {
     return printFailure2(`${mapPath} is missing; run \`cdd-kit code-map\` first.`, opts.json);
   }
   let entries;
@@ -11476,22 +12349,22 @@ __export(graph_exports, {
   graphStatus: () => graphStatus,
   graphSync: () => graphSync
 });
-import { existsSync as existsSync24 } from "fs";
-import { join as join25 } from "path";
-import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync29, readFileSync as readFileSync33 } from "fs";
+import { join as join29 } from "path";
+import { spawnSync as spawnSync7 } from "child_process";
 function codeGraphCommand() {
   return process.env.CDD_CODEGRAPH_BIN || "codegraph";
 }
 function runCodeGraph(args, cwd = process.cwd()) {
   const command = codeGraphCommand();
   if (command.toLowerCase().endsWith(".js")) {
-    return spawnSync3(process.execPath, [command, ...args], { cwd, encoding: "buffer" });
+    return spawnSync7(process.execPath, [command, ...args], { cwd, encoding: "buffer" });
   }
-  return spawnSync3(command, args, { cwd, encoding: "buffer" });
+  return spawnSync7(command, args, { cwd, encoding: "buffer" });
 }
 function probeCodeGraph(cwd = process.cwd()) {
   const command = codeGraphCommand();
-  const initialized = existsSync24(join25(cwd, ".codegraph"));
+  const initialized = existsSync29(join29(cwd, ".codegraph"));
   const version = runCodeGraph(["--version"], cwd);
   if (version.error) {
     return {
@@ -11561,7 +12434,7 @@ async function ensureNativeGraph(mapPath, refresh2) {
   if (freshness.error)
     return { graphPath: graphPathFor(mapPath), refreshed: freshness.refreshed, error: freshness.error };
   const graphPath = graphPathFor(mapPath);
-  if (!existsSync24(graphPath) && refresh2) {
+  if (!existsSync29(graphPath) && refresh2) {
     const { codeMap: codeMap2 } = await Promise.resolve().then(() => (init_code_map(), code_map_exports));
     const exit = await codeMap2({
       path: ".",
@@ -11594,7 +12467,7 @@ async function graphStatus(opts = {}) {
   const graphPath = graphPathFor(mapPath);
   const freshness = checkCodeMapFreshness(cwd, mapPath);
   let graphStats;
-  if (existsSync24(graphPath)) {
+  if (existsSync29(graphPath)) {
     try {
       const graph2 = loadCodeGraph(graphPath);
       graphStats = { graph: graphPath, nodes: graph2.nodes.length, edges: graph2.edges.length, unresolved: graph2.unresolved.length };
@@ -11663,8 +12536,10 @@ async function graphQuery(term, opts) {
     try {
       const graph2 = loadCodeGraph(ensured.graphPath);
       const results = searchGraph(graph2, term, opts.limit);
+      const sources = opts.withSource ? collectNodeSources(results.map((r) => r.node), resolveSourceBudget(opts.sourceBudget), surfaceRootFor(mapPath)) : /* @__PURE__ */ new Map();
       if (opts.json) {
-        writeJson({ engine: "native", graph: ensured.graphPath, query: term, refreshed: ensured.refreshed, results });
+        const withSrc = opts.withSource ? results.map((r) => ({ ...r, source: sources.get(r.node.id)?.source, source_truncated: sources.get(r.node.id)?.truncated })) : results;
+        writeJson({ engine: "native", graph: ensured.graphPath, query: term, refreshed: ensured.refreshed, results: withSrc });
       } else {
         console.log(`graph: ${ensured.graphPath}${ensured.refreshed ? " (refreshed)" : ""}`);
         console.log(`query: ${term}`);
@@ -11673,8 +12548,15 @@ async function graphQuery(term, opts) {
           const n = result.node;
           console.log(`- ${n.kind}: ${n.qualified_name} lines ${n.start_line}-${n.end_line}`);
           console.log(`  edges: ${result.edges.incoming} incoming, ${result.edges.outgoing} outgoing`);
+          const src = sources.get(n.id);
+          if (src) {
+            for (const srcLine of src.source.split("\n"))
+              console.log(`    | ${srcLine}`);
+            if (src.truncated)
+              console.log("    | \u2026 (source budget reached; Read the rest directly)");
+          }
         }
-        console.log("Next: run cdd-kit graph impact <node/file/symbol> before editing.");
+        console.log(opts.withSource ? "Source included above \u2014 no separate Read needed for these ranges." : "Next: run cdd-kit graph impact <node/file/symbol> before editing.");
       }
       return results.length === 0 ? 1 : 0;
     } catch (err) {
@@ -11685,9 +12567,44 @@ async function graphQuery(term, opts) {
     map: opts.map || ".cdd/code-map.yml",
     limit: opts.limit,
     json: opts.json === true,
-    refresh: opts.refresh !== false
+    refresh: opts.refresh !== false,
+    withSource: opts.withSource === true,
+    sourceBudget: resolveSourceBudget(opts.sourceBudget)
   });
 }
+function collectNodeSources(nodes, budget, baseDir) {
+  const out = /* @__PURE__ */ new Map();
+  const fileCache = /* @__PURE__ */ new Map();
+  let used = 0;
+  const readLines = (path) => {
+    if (fileCache.has(path))
+      return fileCache.get(path) ?? null;
+    let lines = null;
+    try {
+      const resolved = baseDir && baseDir !== "." ? `${baseDir.replace(/\/+$/, "")}/${path}` : path;
+      lines = existsSync29(resolved) ? readFileSync33(resolved, "utf8").split(/\r?\n/) : null;
+    } catch {
+      lines = null;
+    }
+    fileCache.set(path, lines);
+    return lines;
+  };
+  for (const node of nodes) {
+    const fileLines = readLines(node.file_path);
+    if (!fileLines || !node.start_line)
+      continue;
+    if (used >= budget) {
+      out.set(node.id, { source: "", truncated: true });
+      continue;
+    }
+    const end = node.end_line && node.end_line >= node.start_line ? node.end_line : node.start_line;
+    const allowedEnd = Math.min(end, node.start_line + (budget - used) - 1);
+    const slice = fileLines.slice(node.start_line - 1, allowedEnd);
+    out.set(node.id, { source: slice.join("\n"), truncated: allowedEnd < end });
+    used += slice.length;
+  }
+  return out;
+}
 async function graphImpact2(term, opts) {
   const selected = selectEngine(opts);
   if ("error" in selected)
@@ -11783,7 +12700,7 @@ async function graphContext2(task, opts) {
   const freshness = await ensureCodeMapFresh(mapPath, opts.refresh !== false);
   if (freshness.error)
     return printEngineError(freshness.error, opts.json, selected.probe);
-  if (!existsSync24(mapPath))
+  if (!existsSync29(mapPath))
     return printEngineError(`${mapPath} is missing; run \`cdd-kit code-map\` first.`, opts.json, selected.probe);
   let entries;
   try {
@@ -11834,12 +12751,70 @@ var init_graph = __esm({
   }
 });
 
+// src/commands/classify-check.ts
+var classify_check_exports = {};
+__export(classify_check_exports, {
+  classifyCheck: () => classifyCheck
+});
+import { existsSync as existsSync30, readFileSync as readFileSync34 } from "fs";
+import { join as join30 } from "path";
+async function classifyCheck(changeId, opts = {}) {
+  const cwd = process.cwd();
+  const policy = loadTierPolicy(cwd);
+  let intent = opts.text ?? "";
+  let source = "inline --text";
+  let paths = [];
+  if (!intent && changeId) {
+    const requestPath = join30(cwd, "specs", "changes", changeId, "change-request.md");
+    if (existsSync30(requestPath))
+      intent = readFileSync34(requestPath, "utf8");
+    paths = getTouchedPaths(cwd);
+    source = `specs/changes/${changeId}/change-request.md + touched paths`;
+  }
+  const floor = computeTierFloor(intent, policy, { paths });
+  if (opts.json) {
+    console.log(JSON.stringify({
+      enabled: policy.enabled,
+      source,
+      floorTier: floor.floorTier,
+      label: floor.label,
+      matched: floor.matched
+    }, null, 2));
+    return 0;
+  }
+  if (!policy.enabled) {
+    log.info("tier-floor policy is disabled (.cdd/tier-policy.json enabled:false) \u2014 no floor enforced.");
+    return 0;
+  }
+  if (!intent && paths.length === 0) {
+    log.warn('no intent text or touched paths found to scan (pass --text "<description>" or a change-id with change-request.md).');
+    return 0;
+  }
+  if (floor.floorTier === null) {
+    log.ok("no sensitive surface matched \u2014 classifier may assign any tier on merit.");
+    return 0;
+  }
+  log.warn(`mechanical tier floor: ${floor.floorTier} (or stricter)`);
+  log.info(`  reason: ${floor.label}`);
+  log.info(`  matched: ${floor.matched.join(", ")}`);
+  log.info(`  \u2192 change-classification.md must declare tier ${floor.floorTier} or stricter; the gate enforces this.`);
+  return 0;
+}
+var init_classify_check = __esm({
+  "src/commands/classify-check.ts"() {
+    "use strict";
+    init_logger();
+    init_tier_floor();
+    init_git_paths();
+  }
+});
+
 // src/mcp/server.ts
 var server_exports = {};
 __export(server_exports, {
   runMcpServer: () => runMcpServer
 });
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync8 } from "child_process";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { createInterface } from "readline";
 async function runMcpServer(opts) {
@@ -11930,6 +12905,7 @@ function callTool(name, args) {
         "--limit",
         String(optionalInt(args.limit, 10)),
         "--json",
+        ...sourceArgs(args),
         ...refreshArgs(args)
       ]);
     case "cdd_graph_context":
@@ -11972,6 +12948,7 @@ function callTool(name, args) {
         "--limit",
         String(optionalInt(args.limit, 10)),
         "--json",
+        ...sourceArgs(args),
         ...refreshArgs(args)
       ]);
     case "cdd_index_impact":
@@ -11995,7 +12972,7 @@ function callTool(name, args) {
 }
 function runCddJson(args) {
   const cliPath = process.argv[1] || fileURLToPath3(import.meta.url);
-  const result = spawnSync4(process.execPath, [cliPath, ...args], {
+  const result = spawnSync8(process.execPath, [cliPath, ...args], {
     cwd: process.cwd(),
     env: process.env,
     encoding: "utf8"
@@ -12017,6 +12994,11 @@ function runCddJson(args) {
 function refreshArgs(args) {
   return args.refresh === false ? ["--no-refresh"] : [];
 }
+function sourceArgs(args) {
+  if (args.withSource !== true)
+    return [];
+  return ["--with-source", "--source-budget", String(optionalInt(args.sourceBudget, 400))];
+}
 function asObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -12062,7 +13044,7 @@ var init_server = __esm({
       },
       {
         name: "cdd_graph_query",
-        description: "Search native graph symbols/files and return candidate nodes with line ranges.",
+        description: "Search native graph symbols/files and return candidate nodes with line ranges. Set withSource:true to also return the source slices inline so no separate file read is needed.",
         inputSchema: {
           type: "object",
           properties: {
@@ -12070,6 +13052,8 @@ var init_server = __esm({
             limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
             map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
             engine: { type: "string", enum: ["auto", "native", "codegraph", "codemap"], default: "auto" },
+            withSource: { type: "boolean", description: "Include matched source slices inline (replaces a follow-up read).", default: false },
+            sourceBudget: { type: "integer", minimum: 1, maximum: 5e3, default: 400, description: "Max total source lines to return when withSource is true." },
             refresh: { type: "boolean", default: true }
           },
           required: ["query"],
@@ -12111,13 +13095,15 @@ var init_server = __esm({
       },
       {
         name: "cdd_index_query",
-        description: "Fallback code-map query for files, symbols, imports, and line ranges.",
+        description: "Fallback code-map query for files, symbols, imports, and line ranges. Set withSource:true to also return the source slices inline so no separate file read is needed.",
         inputSchema: {
           type: "object",
           properties: {
             query: { type: "string", description: "Symbol, file path, import module, enum member, or substring." },
             limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
             map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            withSource: { type: "boolean", description: "Include matched source slices inline (replaces a follow-up read).", default: false },
+            sourceBudget: { type: "integer", minimum: 1, maximum: 5e3, default: 400, description: "Max total source lines to return when withSource is true." },
             refresh: { type: "boolean", default: true }
           },
           required: ["query"],
@@ -12148,28 +13134,28 @@ var archive_exports = {};
 __export(archive_exports, {
   archive: () => archive
 });
-import { join as join26 } from "path";
-import { existsSync as existsSync25, mkdirSync as mkdirSync10, renameSync as renameSync2, readFileSync as readFileSync27, writeFileSync as writeFileSync13, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
+import { join as join31 } from "path";
+import { existsSync as existsSync31, mkdirSync as mkdirSync12, renameSync as renameSync2, readFileSync as readFileSync35, writeFileSync as writeFileSync16, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
 import yaml4 from "js-yaml";
 async function archive(changeId) {
   const cwd = process.cwd();
-  const changeDir = join26(cwd, "specs", "changes", changeId);
+  const changeDir = join31(cwd, "specs", "changes", changeId);
   const archiveYear = (/* @__PURE__ */ new Date()).getFullYear().toString();
-  const archiveBase = join26(cwd, "specs", "archive", archiveYear);
-  const archiveDir = join26(archiveBase, changeId);
-  const indexPath = join26(cwd, "specs", "archive", "INDEX.md");
-  if (!existsSync25(changeDir)) {
+  const archiveBase = join31(cwd, "specs", "archive", archiveYear);
+  const archiveDir = join31(archiveBase, changeId);
+  const indexPath = join31(cwd, "specs", "archive", "INDEX.md");
+  if (!existsSync31(changeDir)) {
     log.error(`Change not found: specs/changes/${changeId}`);
     process.exit(1);
   }
-  if (existsSync25(archiveDir)) {
+  if (existsSync31(archiveDir)) {
     log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
     process.exit(1);
   }
-  const tasksPath = join26(changeDir, "tasks.yml");
-  if (existsSync25(tasksPath)) {
+  const tasksPath = join31(changeDir, "tasks.yml");
+  if (existsSync31(tasksPath)) {
     try {
-      const raw = readFileSync27(tasksPath, "utf8");
+      const raw = readFileSync35(tasksPath, "utf8");
       const data = yaml4.load(raw);
       if (data?.status === "gate-blocked") {
         log.warn("tasks.yml has status: gate-blocked \u2014 archiving anyway (change was paused).");
@@ -12182,8 +13168,8 @@ async function archive(changeId) {
       log.warn("tasks.yml could not be parsed \u2014 archiving anyway.");
     }
   }
-  if (!existsSync25(archiveBase)) {
-    mkdirSync10(archiveBase, { recursive: true });
+  if (!existsSync31(archiveBase)) {
+    mkdirSync12(archiveBase, { recursive: true });
   }
   try {
     renameSync2(changeDir, archiveDir);
@@ -12199,8 +13185,8 @@ async function archive(changeId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const indexLine = `| ${changeId} | ${archiveYear} | ${today} | specs/archive/${archiveYear}/${changeId}/ |
 `;
-  if (!existsSync25(indexPath)) {
-    writeFileSync13(indexPath, `# Archive Index
+  if (!existsSync31(indexPath)) {
+    writeFileSync16(indexPath, `# Archive Index
 
 | change-id | year | archived-date | path |
 |---|---|---|---|
@@ -12224,37 +13210,37 @@ var abandon_exports = {};
 __export(abandon_exports, {
   abandon: () => abandon
 });
-import { join as join27 } from "path";
-import { existsSync as existsSync26, readFileSync as readFileSync28, writeFileSync as writeFileSync14, appendFileSync as appendFileSync2, mkdirSync as mkdirSync11 } from "fs";
+import { join as join32 } from "path";
+import { existsSync as existsSync32, readFileSync as readFileSync36, writeFileSync as writeFileSync17, appendFileSync as appendFileSync2, mkdirSync as mkdirSync13 } from "fs";
 import yaml5 from "js-yaml";
 async function abandon(changeId, opts) {
   const cwd = process.cwd();
-  const changeDir = join27(cwd, "specs", "changes", changeId);
-  const tasksPath = join27(changeDir, "tasks.yml");
-  if (!existsSync26(changeDir)) {
+  const changeDir = join32(cwd, "specs", "changes", changeId);
+  const tasksPath = join32(changeDir, "tasks.yml");
+  if (!existsSync32(changeDir)) {
     log.error(`Change not found: specs/changes/${changeId}`);
     process.exit(1);
   }
-  if (existsSync26(tasksPath)) {
-    const raw = readFileSync28(tasksPath, "utf8");
+  if (existsSync32(tasksPath)) {
+    const raw = readFileSync36(tasksPath, "utf8");
     const data = yaml5.load(raw) ?? {};
     data["status"] = "abandoned";
     if (!data["change-id"]) {
       data["change-id"] = changeId;
     }
-    writeFileSync14(tasksPath, yaml5.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
+    writeFileSync17(tasksPath, yaml5.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const archiveDir = join27(cwd, "specs", "archive");
-  const indexPath = join27(archiveDir, "INDEX.md");
+  const archiveDir = join32(cwd, "specs", "archive");
+  const indexPath = join32(archiveDir, "INDEX.md");
   const reason = opts.reason ?? "no reason given";
   const indexLine = `| ${changeId} | abandoned | ${today} | ${reason} |
 `;
-  if (!existsSync26(archiveDir)) {
-    mkdirSync11(archiveDir, { recursive: true });
+  if (!existsSync32(archiveDir)) {
+    mkdirSync13(archiveDir, { recursive: true });
   }
-  if (!existsSync26(indexPath)) {
-    writeFileSync14(indexPath, `# Archive Index
+  if (!existsSync32(indexPath)) {
+    writeFileSync17(indexPath, `# Archive Index
 
 | change-id | status | date | notes |
 |---|---|---|---|
@@ -12278,28 +13264,28 @@ var list_changes_exports = {};
 __export(list_changes_exports, {
   listChanges: () => listChanges
 });
-import { join as join28 } from "path";
-import { existsSync as existsSync27, readdirSync as readdirSync13, readFileSync as readFileSync29 } from "fs";
+import { join as join33 } from "path";
+import { existsSync as existsSync33, readdirSync as readdirSync14, readFileSync as readFileSync37 } from "fs";
 import yaml6 from "js-yaml";
 async function listChanges() {
   const cwd = process.cwd();
-  const changesDir = join28(cwd, "specs", "changes");
+  const changesDir = join33(cwd, "specs", "changes");
   log.blank();
   const active = [];
-  if (existsSync27(changesDir)) {
-    active.push(...readdirSync13(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name));
+  if (existsSync33(changesDir)) {
+    active.push(...readdirSync14(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name));
   }
   if (active.length === 0) {
     log.info("No active changes in specs/changes/");
   } else {
     log.info("Active changes:");
     for (const id of active) {
-      const tasksPath = join28(changesDir, id, "tasks.yml");
+      const tasksPath = join33(changesDir, id, "tasks.yml");
       let status = "in-progress";
       let pending = 0;
-      if (existsSync27(tasksPath)) {
+      if (existsSync33(tasksPath)) {
         try {
-          const raw = readFileSync29(tasksPath, "utf8");
+          const raw = readFileSync37(tasksPath, "utf8");
           const data = yaml6.load(raw);
           if (data?.status)
             status = data.status;
@@ -12331,9 +13317,9 @@ __export(context_exports, {
   rejectContextExpansion: () => rejectContextExpansion,
   requestContextExpansion: () => requestContextExpansion
 });
-import { existsSync as existsSync28, readFileSync as readFileSync30, writeFileSync as writeFileSync15 } from "fs";
-import { join as join29 } from "path";
-import picomatch2 from "picomatch";
+import { existsSync as existsSync34, readFileSync as readFileSync38, writeFileSync as writeFileSync18 } from "fs";
+import { join as join34 } from "path";
+import picomatch3 from "picomatch";
 function normalizePath(path) {
   return path.replace(/\\/g, "/").replace(/^\.\//, "").trim();
 }
@@ -12347,18 +13333,18 @@ function validateRepoRelativePath(path) {
   return null;
 }
 function manifestPathFor(changeId) {
-  return join29(process.cwd(), "specs", "changes", changeId, "context-manifest.md");
+  return join34(process.cwd(), "specs", "changes", changeId, "context-manifest.md");
 }
 function readManifest(changeId) {
   const manifestPath = manifestPathFor(changeId);
-  if (!existsSync28(manifestPath)) {
+  if (!existsSync34(manifestPath)) {
     log.error(`context manifest not found: specs/changes/${changeId}/context-manifest.md`);
     process.exit(1);
   }
-  return readFileSync30(manifestPath, "utf8");
+  return readFileSync38(manifestPath, "utf8");
 }
 function writeManifest(changeId, content) {
-  writeFileSync15(manifestPathFor(changeId), content.endsWith("\n") ? content : `${content}
+  writeFileSync18(manifestPathFor(changeId), content.endsWith("\n") ? content : `${content}
 `, "utf8");
 }
 function sectionBody(content, heading) {
@@ -12384,7 +13370,7 @@ function pathMatches(relPath, patterns, currentChangeId) {
       return normalized.startsWith("specs/changes/");
     }
     if (/[*?[{]/.test(pattern)) {
-      if (picomatch2.isMatch(normalized, pattern, { dot: true, nocase: false }))
+      if (picomatch3.isMatch(normalized, pattern, { dot: true, nocase: false }))
         return true;
       if (pattern.endsWith("/**")) {
         const base = pattern.slice(0, -3);
@@ -12397,11 +13383,11 @@ function pathMatches(relPath, patterns, currentChangeId) {
   });
 }
 function loadContextPolicy() {
-  const policyPath = join29(process.cwd(), ".cdd", "context-policy.json");
-  if (!existsSync28(policyPath))
+  const policyPath = join34(process.cwd(), ".cdd", "context-policy.json");
+  if (!existsSync34(policyPath))
     return { forbiddenPaths: DEFAULT_FORBIDDEN_PATHS };
   try {
-    const custom = JSON.parse(readFileSync30(policyPath, "utf8"));
+    const custom = JSON.parse(readFileSync38(policyPath, "utf8"));
     return {
       forbiddenPaths: Array.from(/* @__PURE__ */ new Set([
         ...DEFAULT_FORBIDDEN_PATHS,
@@ -12683,16 +13669,16 @@ var init_context = __esm({
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync31 } from "fs";
+import { readFileSync as readFileSync39 } from "fs";
 import os from "os";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { dirname as dirname7, join as join30 } from "path";
+import { dirname as dirname8, join as join35 } from "path";
 import { Command } from "commander";
 
 // src/commands/init.ts
 init_paths();
-import { join as join5 } from "path";
-import { rmSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync4, readdirSync as readdirSync2 } from "fs";
+import { join as join8 } from "path";
+import { rmSync, readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync7, readdirSync as readdirSync2 } from "fs";
 
 // src/utils/copy.ts
 init_logger();
@@ -12860,14 +13846,57 @@ function detectStack(repoRoot) {
   };
 }
 
+// src/commands/suggest-codegen.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join4 } from "path";
+var ARTIFACT_PATH = "contracts/api/openapi.json";
+var CLIENT_OUT = "src/api/types.ts";
+var SCRIPT_GENERATE = "contract:client";
+var SCRIPT_CHECK = "contract:client:check";
+var GENERATE_CMD = `cdd-kit openapi export --out ${ARTIFACT_PATH} && npx --yes openapi-typescript ${ARTIFACT_PATH} -o ${CLIENT_OUT}`;
+var CHECK_CMD = `cdd-kit openapi export --check --out ${ARTIFACT_PATH}`;
+function suggestCodegenScript(cwd) {
+  const pkgPath = join4(cwd, "package.json");
+  if (!existsSync3(pkgPath)) {
+    return { added: [], skipped: "no package.json (client codegen is consumer-specific; see docs/openapi-export.md)" };
+  }
+  let pkg2;
+  let raw;
+  try {
+    raw = readFileSync2(pkgPath, "utf8");
+    pkg2 = JSON.parse(raw);
+  } catch {
+    return { added: [], skipped: "package.json is not valid JSON; left untouched" };
+  }
+  if (typeof pkg2 !== "object" || pkg2 === null || Array.isArray(pkg2)) {
+    return { added: [], skipped: "package.json is not a JSON object; left untouched" };
+  }
+  const scripts = typeof pkg2.scripts === "object" && pkg2.scripts !== null && !Array.isArray(pkg2.scripts) ? pkg2.scripts : {};
+  const hasGenerate = SCRIPT_GENERATE in scripts;
+  const hasCheck = SCRIPT_CHECK in scripts;
+  if (hasGenerate || hasCheck) {
+    const present = [hasGenerate ? SCRIPT_GENERATE : "", hasCheck ? SCRIPT_CHECK : ""].filter(Boolean).join(" + ");
+    return { added: [], skipped: `${present} already present in package.json; leaving codegen wiring to you` };
+  }
+  scripts[SCRIPT_GENERATE] = GENERATE_CMD;
+  scripts[SCRIPT_CHECK] = CHECK_CMD;
+  pkg2.scripts = scripts;
+  const trailing = raw.endsWith("\n") ? "\n" : "";
+  writeFileSync(pkgPath, JSON.stringify(pkg2, null, 2) + trailing, "utf8");
+  return {
+    added: [SCRIPT_GENERATE, SCRIPT_CHECK],
+    note: `requires openapi-typescript (\`npm i -D openapi-typescript\`); edit the output path (${CLIENT_OUT}) to fit your project, then wire \`npm run ${SCRIPT_CHECK}\` into CI`
+  };
+}
+
 // src/commands/init.ts
 init_mcp_hint();
 function readCondaEnvName(cwd) {
-  const envYml = join5(cwd, "environment.yml");
-  if (!existsSync4(envYml))
+  const envYml = join8(cwd, "environment.yml");
+  if (!existsSync7(envYml))
     return "base";
   try {
-    const content = readFileSync3(envYml, "utf8");
+    const content = readFileSync6(envYml, "utf8");
     const match = content.match(/^name:\s*(.+)$/m);
     return match ? match[1].trim() : "base";
   } catch {
@@ -12875,11 +13904,11 @@ function readCondaEnvName(cwd) {
   }
 }
 function loadCiTemplate(stack) {
-  const templatePath = join5(ASSETS_DIR, "ci-templates", `${stack}.yml`);
-  if (!existsSync4(templatePath))
+  const templatePath = join8(ASSETS_DIR, "ci-templates", `${stack}.yml`);
+  if (!existsSync7(templatePath))
     return null;
   try {
-    return readFileSync3(templatePath, "utf8");
+    return readFileSync6(templatePath, "utf8");
   } catch {
     return null;
   }
@@ -12915,6 +13944,7 @@ async function init(opts) {
   }
   const cwd = process.cwd();
   const createdPaths = [];
+  const restoreActions = [];
   const installClaude = opts.provider === "claude" || opts.provider === "both";
   const installCodex = opts.provider === "codex" || opts.provider === "both";
   function track(paths) {
@@ -12930,6 +13960,13 @@ async function init(opts) {
         log.warn(`could not remove: ${p}`);
       }
     }
+    for (const restore of [...restoreActions].reverse()) {
+      try {
+        restore();
+      } catch {
+        log.warn("could not restore an in-place file edit");
+      }
+    }
   }
   log.blank();
   log.info("Initialising contract-driven-delivery kit\u2026");
@@ -12943,9 +13980,9 @@ async function init(opts) {
       const skillDirs = readdirSync2(ASSET.skills, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
       let totalSkillFiles = 0;
       for (const skillName of skillDirs) {
-        const skillDest = join5(SKILLS_HOME, skillName);
+        const skillDest = join8(SKILLS_HOME, skillName);
         log.info(`Installing skill  \u2192 ${skillDest}`);
-        const { count, created } = copyDirTracked(join5(ASSET.skills, skillName), skillDest, { overwrite: true });
+        const { count, created } = copyDirTracked(join8(ASSET.skills, skillName), skillDest, { overwrite: true });
         track(created);
         totalSkillFiles += count;
       }
@@ -12959,44 +13996,44 @@ async function init(opts) {
       log.info(`Scaffolding project files in ${cwd}`);
       const { count: contractsCount, created: contractsCreated } = copyDirTracked(
         ASSET.contracts,
-        join5(cwd, "contracts"),
+        join8(cwd, "contracts"),
         { overwrite: opts.force, label: "contracts" }
       );
       track(contractsCreated);
       log.ok(`contracts/ \u2014 ${contractsCount} file(s) written.`);
       const { count: specsCount, created: specsCreated } = copyDirTracked(
         ASSET.specsTemplates,
-        join5(cwd, "specs", "templates"),
+        join8(cwd, "specs", "templates"),
         { overwrite: opts.force, label: "specs/templates" }
       );
       track(specsCreated);
       log.ok(`specs/templates/ \u2014 ${specsCount} file(s) written.`);
       const { count: testsCount, created: testsCreated } = copyDirTracked(
         ASSET.testsTemplates,
-        join5(cwd, "tests", "templates"),
+        join8(cwd, "tests", "templates"),
         { overwrite: opts.force, label: "tests/templates" }
       );
       track(testsCreated);
       log.ok(`tests/templates/ \u2014 ${testsCount} file(s) written.`);
       const { count: ciCount, created: ciCreated } = copyDirTracked(
         ASSET.ci,
-        join5(cwd, "ci"),
+        join8(cwd, "ci"),
         { overwrite: opts.force, label: "ci" }
       );
       track(ciCreated);
       log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
       const { count: cddConfigCount, created: cddConfigCreated } = copyDirTracked(
         ASSET.cddConfig,
-        join5(cwd, ".cdd"),
+        join8(cwd, ".cdd"),
         { overwrite: opts.force, label: ".cdd" }
       );
       track(cddConfigCreated);
       log.ok(`.cdd/ - ${cddConfigCount} file(s) written.`);
-      const modelPolicyPath = join5(cwd, ".cdd", "model-policy.json");
-      if (existsSync4(modelPolicyPath)) {
+      const modelPolicyPath = join8(cwd, ".cdd", "model-policy.json");
+      if (existsSync7(modelPolicyPath)) {
         let existing = {};
         try {
-          existing = JSON.parse(readFileSync3(modelPolicyPath, "utf8"));
+          existing = JSON.parse(readFileSync6(modelPolicyPath, "utf8"));
         } catch {
         }
         const merged = {
@@ -13005,11 +14042,11 @@ async function init(opts) {
           generated_at: (/* @__PURE__ */ new Date()).toISOString(),
           roles: existing.roles && typeof existing.roles === "object" && Object.keys(existing.roles).length > 0 ? existing.roles : {}
         };
-        writeFileSync2(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        writeFileSync5(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
       }
       const { count: wfCount, created: wfCreated } = copyDirTracked(
         ASSET.githubWorkflows,
-        join5(cwd, ".github", "workflows"),
+        join8(cwd, ".github", "workflows"),
         { overwrite: opts.force, label: ".github/workflows" }
       );
       track(wfCreated);
@@ -13033,11 +14070,11 @@ async function init(opts) {
       } else {
         log.warn("Could not detect stack \u2014 CI placeholder left in place.");
       }
-      const ciYmlDest = join5(cwd, ".github", "workflows", "contract-driven-gates.yml");
-      if (existsSync4(ciYmlDest)) {
+      const ciYmlDest = join8(cwd, ".github", "workflows", "contract-driven-gates.yml");
+      if (existsSync7(ciYmlDest)) {
         const template = loadCiTemplate(detection.primary);
         if (template) {
-          const original = readFileSync3(ciYmlDest, "utf8");
+          const original = readFileSync6(ciYmlDest, "utf8");
           let patched = patchFastGateYml(original, template, detection.primary);
           if (detection.primary === "conda" && patched.includes("{{conda-env-name}}")) {
             const envName = readCondaEnvName(cwd);
@@ -13045,39 +14082,52 @@ async function init(opts) {
             log.ok(`Conda environment name set to: ${envName}`);
           }
           if (patched !== original) {
-            writeFileSync2(ciYmlDest, patched, "utf8");
+            writeFileSync5(ciYmlDest, patched, "utf8");
             log.ok(`CI fast-gate patched for stack: ${detection.primary}`);
           }
         }
       }
+      const pkgJsonPath = join8(cwd, "package.json");
+      const pkgJsonBefore = existsSync7(pkgJsonPath) ? readFileSync6(pkgJsonPath, "utf8") : null;
+      const codegen = suggestCodegenScript(cwd);
+      if (codegen.added.length > 0) {
+        if (pkgJsonBefore !== null) {
+          restoreActions.push(() => writeFileSync5(pkgJsonPath, pkgJsonBefore, "utf8"));
+        }
+        log.ok(`package.json: added ${codegen.added.join(" + ")} script(s) for contract\u2192client codegen`);
+        if (codegen.note)
+          log.info(codegen.note);
+      } else if (codegen.skipped && existsSync7(pkgJsonPath)) {
+        log.info(`contract\u2192client codegen: ${codegen.skipped}`);
+      }
       if (installClaude) {
         const { written: claudeWritten, created: claudeCreated } = copyFileTracked(
           ASSET.claudeTemplate,
-          join5(cwd, "CLAUDE.md"),
+          join8(cwd, "CLAUDE.md"),
           { overwrite: false, label: "CLAUDE.md" }
         );
         if (claudeCreated)
-          track([join5(cwd, "CLAUDE.md")]);
+          track([join8(cwd, "CLAUDE.md")]);
         if (claudeWritten)
           log.ok("CLAUDE.md created.");
         const { written: agentsWritten, created: agentsCreated } = copyFileTracked(
           ASSET.agentsTemplate,
-          join5(cwd, "AGENTS.md"),
+          join8(cwd, "AGENTS.md"),
           { overwrite: false, label: "AGENTS.md" }
         );
         if (agentsCreated)
-          track([join5(cwd, "AGENTS.md")]);
+          track([join8(cwd, "AGENTS.md")]);
         if (agentsWritten)
           log.ok("AGENTS.md created.");
       }
       if (installCodex) {
         const { written: codexWritten, created: codexCreated } = copyFileTracked(
           ASSET.codexTemplate,
-          join5(cwd, "CODEX.md"),
+          join8(cwd, "CODEX.md"),
           { overwrite: false, label: "CODEX.md" }
         );
         if (codexCreated)
-          track([join5(cwd, "CODEX.md")]);
+          track([join8(cwd, "CODEX.md")]);
         if (codexWritten)
           log.ok("CODEX.md created.");
       }
@@ -13085,6 +14135,16 @@ async function init(opts) {
         const { installCodeMapHook: installCodeMapHook2 } = await Promise.resolve().then(() => (init_code_map_hook(), code_map_hook_exports));
         await installCodeMapHook2(cwd);
       }
+      if (!opts.globalOnly && opts.arm !== false) {
+        log.info("Arming enforcement chokepoints\u2026");
+        if (installClaude) {
+          const { installAgentHooks: installAgentHooks2 } = await Promise.resolve().then(() => (init_install_agent_hooks(), install_agent_hooks_exports));
+          await installAgentHooks2({ graphFirst: "advisory", fromInit: true });
+        }
+        const { installHooks: installHooks2 } = await Promise.resolve().then(() => (init_install_hooks(), install_hooks_exports));
+        await installHooks2({ fromInit: true });
+        log.info("Chokepoints armed. Run `cdd-kit doctor` to see live/dormant status; use `--no-arm` next time to skip.");
+      }
       log.blank();
     }
   } catch (err) {
@@ -13108,9 +14168,9 @@ init_update();
 
 // src/commands/new-change.ts
 init_paths();
-import { join as join9, relative as relative3 } from "path";
+import { join as join12, relative as relative3 } from "path";
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync8, readFileSync as readFileSync8, readdirSync as readdirSync5, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync11, readdirSync as readdirSync5, writeFileSync as writeFileSync7 } from "fs";
 init_logger();
 init_context_scan();
 init_digest();
@@ -13122,10 +14182,10 @@ function inputsDigest2(paths, cwd) {
   return createHash4("sha256").update(combined).digest("hex");
 }
 function findContractFiles2(dir, found = []) {
-  if (!existsSync8(dir))
+  if (!existsSync11(dir))
     return found;
   for (const entry of readdirSync5(dir, { withFileTypes: true })) {
-    const fullPath = join9(dir, entry.name);
+    const fullPath = join12(dir, entry.name);
     if (entry.isDirectory())
       findContractFiles2(fullPath, found);
     else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "INDEX.md" && entry.name !== "CHANGELOG.md") {
@@ -13135,22 +14195,22 @@ function findContractFiles2(dir, found = []) {
   return found;
 }
 function readIndexDigest(filePath) {
-  if (!existsSync8(filePath))
+  if (!existsSync11(filePath))
     return null;
-  const m = readFileSync8(filePath, "utf8").match(/^inputs-digest:\s*([a-f0-9]+)/m);
+  const m = readFileSync11(filePath, "utf8").match(/^inputs-digest:\s*([a-f0-9]+)/m);
   return m ? m[1] : null;
 }
 async function ensureFreshContextIndexes(cwd) {
-  const projectMap = join9(cwd, "specs", "context", "project-map.md");
-  const contractsIndex = join9(cwd, "specs", "context", "contracts-index.md");
-  const policyPath = join9(cwd, ".cdd", "context-policy.json");
-  const policyInputs = [policyPath].filter(existsSync8);
-  const contractFiles = findContractFiles2(join9(cwd, "contracts"));
+  const projectMap = join12(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join12(cwd, "specs", "context", "contracts-index.md");
+  const policyPath = join12(cwd, ".cdd", "context-policy.json");
+  const policyInputs = [policyPath].filter(existsSync11);
+  const contractFiles = findContractFiles2(join12(cwd, "contracts"));
   const wantProjectDigest = inputsDigest2(policyInputs, cwd);
   const wantContractsDigest = inputsDigest2(contractFiles, cwd);
   const haveProjectDigest = readIndexDigest(projectMap);
   const haveContractsDigest = readIndexDigest(contractsIndex);
-  const needsScan = !existsSync8(projectMap) || !existsSync8(contractsIndex) || haveProjectDigest !== wantProjectDigest || haveContractsDigest !== wantContractsDigest;
+  const needsScan = !existsSync11(projectMap) || !existsSync11(contractsIndex) || haveProjectDigest !== wantProjectDigest || haveContractsDigest !== wantContractsDigest;
   if (!needsScan)
     return;
   log.info("context indexes missing or stale \u2014 running cdd-kit context-scan\u2026");
@@ -13181,9 +14241,9 @@ function parseDependsOn(raw) {
   return raw.split(",").map((item) => item.trim()).filter(Boolean);
 }
 function applyScaffoldMetadata(tasksPath, changeId, dependencies) {
-  if (!existsSync8(tasksPath))
+  if (!existsSync11(tasksPath))
     return;
-  let raw = readFileSync8(tasksPath, "utf8");
+  let raw = readFileSync11(tasksPath, "utf8");
   raw = raw.replace(/^change-id:\s*<change-id>\s*$/m, `change-id: ${changeId}`);
   if (dependencies.length > 0) {
     const dependsOn = [
@@ -13192,7 +14252,7 @@ function applyScaffoldMetadata(tasksPath, changeId, dependencies) {
     ].join("\n");
     raw = raw.replace(/^depends-on:\s*\[\]\s*$/m, dependsOn);
   }
-  writeFileSync4(tasksPath, raw, "utf8");
+  writeFileSync7(tasksPath, raw, "utf8");
 }
 async function newChange(name, opts) {
   if (!SAFE_NAME.test(name)) {
@@ -13207,8 +14267,8 @@ async function newChange(name, opts) {
     }
   }
   const cwd = process.cwd();
-  const changeDir = join9(cwd, "specs", "changes", name);
-  if (existsSync8(changeDir)) {
+  const changeDir = join12(cwd, "specs", "changes", name);
+  if (existsSync11(changeDir)) {
     if (opts.force) {
       log.warn(`Forcing re-scaffold of existing change directory: ${changeDir}`);
       log.warn("Existing files will NOT be deleted; only template files will be overwritten.");
@@ -13231,9 +14291,9 @@ async function newChange(name, opts) {
   const templates = opts.all ? [...REQUIRED_TEMPLATES, ...listOptional()] : [...REQUIRED_TEMPLATES];
   let written = 0;
   for (const tmpl of templates) {
-    const src = join9(ASSET.specsTemplates, tmpl);
-    const dest = join9(changeDir, tmpl);
-    if (!existsSync8(src)) {
+    const src = join12(ASSET.specsTemplates, tmpl);
+    const dest = join12(changeDir, tmpl);
+    if (!existsSync11(src)) {
       log.warn(`Template not found, skipping: ${tmpl}`);
       continue;
     }
@@ -13241,7 +14301,7 @@ async function newChange(name, opts) {
     log.dim(tmpl);
     written += 1;
   }
-  const tasksPath = join9(changeDir, "tasks.yml");
+  const tasksPath = join12(changeDir, "tasks.yml");
   applyScaffoldMetadata(tasksPath, name, dependencies);
   if (dependencies.length > 0) {
     log.dim(`depends-on: ${dependencies.join(", ")}`);
@@ -13254,9 +14314,9 @@ async function newChange(name, opts) {
 // src/commands/validate.ts
 init_paths();
 init_logger();
-import { join as join10 } from "path";
-import { existsSync as existsSync9 } from "fs";
-import { spawnSync } from "child_process";
+import { join as join13 } from "path";
+import { existsSync as existsSync12 } from "fs";
+import { spawnSync as spawnSync2 } from "child_process";
 var VALIDATORS = [
   {
     flag: "contracts",
@@ -13264,6 +14324,7 @@ var VALIDATORS = [
     label: "contracts",
     chain: [
       { script: "validate_api_semantic.py", label: "API semantic" },
+      { script: "validate_api_conformance.py", label: "API conformance" },
       { script: "validate_env_semantic.py", label: "Env semantic" }
     ]
   },
@@ -13274,7 +14335,7 @@ var VALIDATORS = [
 ];
 function resolvePython() {
   for (const cmd of ["python3", "python"]) {
-    const r = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+    const r = spawnSync2(cmd, ["--version"], { stdio: "ignore" });
     if (r.status === 0)
       return cmd;
   }
@@ -13288,21 +14349,22 @@ async function validate(opts) {
     log.error(e instanceof Error ? e.message : String(e));
     process.exit(1);
   }
-  const scriptsDir = join10(ASSET.skill, "scripts");
+  const scriptsDir = join13(ASSET.skill, "scripts");
   const runAll = !opts.contracts && !opts.env && !opts.ci && !opts.spec && !opts.versions;
+  const pyEnv = { ...process.env, PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" };
   log.blank();
   let failed = false;
   for (const v of VALIDATORS) {
     if (!runAll && !opts[v.flag])
       continue;
-    const scriptPath = join10(scriptsDir, v.script);
-    if (!existsSync9(scriptPath)) {
+    const scriptPath = join13(scriptsDir, v.script);
+    if (!existsSync12(scriptPath)) {
       log.warn(`${v.label}: script not found, skipping (${v.script})`);
       log.blank();
       continue;
     }
     log.info(`Validating ${v.label}\u2026`);
-    const r = spawnSync(py, [scriptPath, ...v.args ?? []], { stdio: "inherit", cwd: process.cwd() });
+    const r = spawnSync2(py, [scriptPath, ...v.args ?? []], { stdio: "inherit", cwd: process.cwd(), env: pyEnv });
     if (r.status !== 0) {
       log.error(`${v.label} validation failed.`);
       failed = true;
@@ -13312,14 +14374,14 @@ async function validate(opts) {
     log.blank();
     if (v.chain) {
       for (const chained of v.chain) {
-        const chainedPath = join10(scriptsDir, chained.script);
-        if (!existsSync9(chainedPath)) {
+        const chainedPath = join13(scriptsDir, chained.script);
+        if (!existsSync12(chainedPath)) {
           log.warn(`${chained.label}: script not found, skipping (${chained.script})`);
           log.blank();
           continue;
         }
         log.info(`Validating ${chained.label}\u2026`);
-        const cr = spawnSync(py, [chainedPath], { stdio: "inherit", cwd: process.cwd() });
+        const cr = spawnSync2(py, [chainedPath], { stdio: "inherit", cwd: process.cwd(), env: pyEnv });
         if (cr.status !== 0) {
           log.error(`${chained.label} validation failed.`);
           failed = true;
@@ -13343,8 +14405,8 @@ async function validate(opts) {
 var import_ajv = __toESM(require_ajv(), 1);
 var import_ajv_formats = __toESM(require_dist(), 1);
 init_logger();
-import { existsSync as existsSync10, readFileSync as readFileSync9, readdirSync as readdirSync6 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync13, readdirSync as readdirSync6 } from "fs";
+import { join as join15 } from "path";
 import yaml from "js-yaml";
 
 // src/schemas/tasks.schema.ts
@@ -13373,6 +14435,7 @@ var tasksSchema = {
       items: { type: "string", pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$" },
       default: []
     },
+    "tier-floor-override": { type: "string", minLength: 1 },
     "token-budget": { type: ["string", "number"] },
     created: { type: "string" },
     completed: { type: "string" },
@@ -13395,6 +14458,8 @@ var tasksSchema = {
 };
 
 // src/commands/gate.ts
+init_tier_floor();
+init_git_paths();
 var ajv = new import_ajv.default({ allErrors: true, allowUnionTypes: true });
 (0, import_ajv_formats.default)(ajv);
 var validateTasks = ajv.compile(tasksSchema);
@@ -13432,6 +14497,15 @@ function meaningfulChars(text) {
 function stripHtmlComments(text) {
   return text.replace(/<!--[\s\S]*?-->/g, "");
 }
+var PLACEHOLDER_LITERALS = ["<id>", "<date>", "<change-id>"];
+var RE_META = /[.*+?^${}()|[\]\\]/g;
+function findPlaceholders(text) {
+  const clean = stripHtmlComments(text);
+  return PLACEHOLDER_LITERALS.filter((token) => {
+    const re = new RegExp(`:[ \\t]*${token.replace(RE_META, "\\$&")}[ \\t]*\\r?$`, "m");
+    return re.test(clean);
+  }).sort();
+}
 function countPendingExpansions(sectionBody2) {
   if (!sectionBody2.trim())
     return 0;
@@ -13453,7 +14527,7 @@ function countPendingContextRequests(content) {
 }
 function loadYamlFile(path) {
   try {
-    const raw = readFileSync9(path, "utf8");
+    const raw = readFileSync13(path, "utf8");
     return { data: yaml.load(raw, { schema: yaml.JSON_SCHEMA }), parseError: null };
   } catch (err) {
     return { data: null, parseError: err.message };
@@ -13484,8 +14558,8 @@ function ajvErrorsToMessages(errors, prefix, knownKeys) {
   return out;
 }
 function isContextGovernedChange(changeDir) {
-  const tasksPath = join11(changeDir, "tasks.yml");
-  if (!existsSync10(tasksPath))
+  const tasksPath = join15(changeDir, "tasks.yml");
+  if (!existsSync14(tasksPath))
     return false;
   const { data } = loadYamlFile(tasksPath);
   return data?.["context-governance"] === "v1";
@@ -13513,12 +14587,12 @@ function lintTasksFile(tasksPath, errors, warnings) {
   return data;
 }
 function resolveTier(changeDir) {
-  const classifPath = join11(changeDir, "change-classification.md");
-  const classificationPresent = existsSync10(classifPath);
-  const classificationText = classificationPresent ? readFileSync9(classifPath, "utf8") : "";
+  const classifPath = join15(changeDir, "change-classification.md");
+  const classificationPresent = existsSync14(classifPath);
+  const classificationText = classificationPresent ? readFileSync13(classifPath, "utf8") : "";
   const classificationHasLooseMarker = classificationPresent && TIER_PATTERN.test(classificationText);
-  const tasksPath = join11(changeDir, "tasks.yml");
-  if (existsSync10(tasksPath)) {
+  const tasksPath = join15(changeDir, "tasks.yml");
+  if (existsSync14(tasksPath)) {
     const { data } = loadYamlFile(tasksPath);
     const t = data?.tier;
     if (typeof t === "number" && t >= 0 && t <= 5) {
@@ -13564,7 +14638,7 @@ function enforceTierConsistency(changeDir, errors, warnings) {
     return;
   }
   if (resolution.source === "tasks-frontmatter" && resolution.classificationPresent) {
-    const text = readFileSync9(join11(changeDir, "change-classification.md"), "utf8");
+    const text = readFileSync13(join15(changeDir, "change-classification.md"), "utf8");
     const structured = text.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
     const bold = text.match(/\*\*Tier:\*\*\s*Tier\s*(\d)\b/i);
     const classifTier = structured ? parseInt(structured[1], 10) : bold ? parseInt(bold[1], 10) : NaN;
@@ -13575,12 +14649,50 @@ function enforceTierConsistency(changeDir, errors, warnings) {
     }
   }
 }
+function enforceTierFloor(changeDir, errors, warnings) {
+  const cwd = process.cwd();
+  const policy = loadTierPolicy(cwd);
+  if (!policy.enabled)
+    return;
+  const requestPath = join15(changeDir, "change-request.md");
+  const requestText = existsSync14(requestPath) ? readFileSync13(requestPath, "utf8") : "";
+  const staged = getStagedPaths(cwd);
+  const stagedChangeIds = new Set(
+    staged.map((p) => /^specs\/changes\/([^/]+)\//.exec(p)?.[1]).filter((id) => id !== void 0)
+  );
+  const touched = stagedChangeIds.size > 1 ? [] : staged;
+  const floor = computeTierFloor(requestText, policy, { paths: touched });
+  if (floor.floorTier === null)
+    return;
+  const declared = resolveTier(changeDir).tier;
+  if (declared === null) {
+    warnings.push(
+      `tier floor: ${floor.label} detected (matched: ${floor.matched.join(", ")}); classification must declare tier ${floor.floorTier} or stricter.`
+    );
+    return;
+  }
+  if (declared <= floor.floorTier)
+    return;
+  const overrideRaw = (() => {
+    const { data } = loadYamlFile(join15(changeDir, "tasks.yml"));
+    const o = data?.["tier-floor-override"];
+    return typeof o === "string" ? o.trim() : "";
+  })();
+  const detail = `${floor.label} detected (matched: ${floor.matched.join(", ")}) requires tier ${floor.floorTier} or stricter, but classification declared tier ${declared}.`;
+  if (overrideRaw) {
+    warnings.push(`tier floor override: ${detail} Bypassed by tier-floor-override: "${overrideRaw}".`);
+  } else {
+    errors.push(
+      `tier floor violation: ${detail} Re-classify to tier ${floor.floorTier} (or stricter), or record \`tier-floor-override: "<reason>"\` in tasks.yml frontmatter to bypass with an audit trail. Disable entirely in .cdd/tier-policy.json.`
+    );
+  }
+}
 function isArchivedChange(cwd, changeId) {
-  const archiveRoot = join11(cwd, "specs", "archive");
-  if (!existsSync10(archiveRoot))
+  const archiveRoot = join15(cwd, "specs", "archive");
+  if (!existsSync14(archiveRoot))
     return false;
   const years = readdirSync6(archiveRoot, { withFileTypes: true }).filter((d) => d.isDirectory());
-  return years.some((year) => existsSync10(join11(archiveRoot, year.name, changeId)));
+  return years.some((year) => existsSync14(join15(archiveRoot, year.name, changeId)));
 }
 function detectDependencyCycle(cwd, startChangeId) {
   const visited = /* @__PURE__ */ new Set();
@@ -13593,8 +14705,8 @@ function detectDependencyCycle(cwd, startChangeId) {
       return null;
     visited.add(id);
     stack.push(id);
-    const tasksPath = join11(cwd, "specs", "changes", id, "tasks.yml");
-    if (existsSync10(tasksPath)) {
+    const tasksPath = join15(cwd, "specs", "changes", id, "tasks.yml");
+    if (existsSync14(tasksPath)) {
       const { data } = loadYamlFile(tasksPath);
       const deps = data?.["depends-on"] ?? [];
       for (const dep of deps) {
@@ -13609,8 +14721,8 @@ function detectDependencyCycle(cwd, startChangeId) {
   return visit(startChangeId);
 }
 function validateDependencies(cwd, changeId, changeDir) {
-  const tasksPath = join11(changeDir, "tasks.yml");
-  if (!existsSync10(tasksPath))
+  const tasksPath = join15(changeDir, "tasks.yml");
+  if (!existsSync14(tasksPath))
     return [];
   const { data } = loadYamlFile(tasksPath);
   const dependencies = data?.["depends-on"] ?? [];
@@ -13624,10 +14736,10 @@ function validateDependencies(cwd, changeId, changeDir) {
       errors.push(`tasks.yml: change cannot depend on itself (${dep})`);
       continue;
     }
-    const upstreamDir = join11(cwd, "specs", "changes", dep);
-    if (existsSync10(upstreamDir)) {
-      const upstreamTasks = join11(upstreamDir, "tasks.yml");
-      if (!existsSync10(upstreamTasks)) {
+    const upstreamDir = join15(cwd, "specs", "changes", dep);
+    if (existsSync14(upstreamDir)) {
+      const upstreamTasks = join15(upstreamDir, "tasks.yml");
+      if (!existsSync14(upstreamTasks)) {
         errors.push(`dependency ${dep}: missing tasks.yml`);
         continue;
       }
@@ -13647,19 +14759,19 @@ function validateDependencies(cwd, changeId, changeDir) {
 async function gate(changeId, opts = {}) {
   const strict = opts.strict ?? false;
   const cwd = process.cwd();
-  const changeDir = join11(cwd, "specs", "changes", changeId);
-  if (!existsSync10(changeDir)) {
+  const changeDir = join15(cwd, "specs", "changes", changeId);
+  if (!existsSync14(changeDir)) {
     log.error(`change not found: ${changeId} (looked in ${changeDir})`);
     process.exit(1);
   }
   const errors = [];
   const warnings = [];
   const isNewChange = isContextGovernedChange(changeDir);
-  const manifestPath = join11(changeDir, "context-manifest.md");
-  const hasManifest = existsSync10(manifestPath);
+  const manifestPath = join15(changeDir, "context-manifest.md");
+  const hasManifest = existsSync14(manifestPath);
   errors.push(...validateDependencies(cwd, changeId, changeDir));
   if (hasManifest) {
-    const pending = countPendingContextRequests(readFileSync9(manifestPath, "utf8"));
+    const pending = countPendingContextRequests(readFileSync13(manifestPath, "utf8"));
     if (pending > 0) {
       warnings.push(`context-manifest.md: has ${pending} pending context expansion request(s)`);
     }
@@ -13675,7 +14787,7 @@ async function gate(changeId, opts = {}) {
       }
       continue;
     }
-    if (!existsSync10(join11(changeDir, f))) {
+    if (!existsSync14(join15(changeDir, f))) {
       errors.push(`missing required artifact: ${f}`);
     }
   }
@@ -13685,21 +14797,30 @@ async function gate(changeId, opts = {}) {
         continue;
       if (f === "tasks.yml")
         continue;
-      const content = readFileSync9(join11(changeDir, f), "utf8");
+      const content = readFileSync13(join15(changeDir, f), "utf8");
       const minChars = MIN_CHARS[f] ?? 100;
       if (meaningfulChars(content) < minChars) {
         errors.push(`${f}: appears to be a stub (< ${minChars} meaningful chars)`);
+        continue;
+      }
+      if (f !== "context-manifest.md") {
+        const placeholders = findPlaceholders(content);
+        if (placeholders.length > 0) {
+          errors.push(
+            `${f}: still contains unfilled template placeholder(s) ${placeholders.join(", ")} \u2014 replace them with the change's real values before the gate can pass`
+          );
+        }
       }
     }
-    const classifPath = join11(changeDir, "change-classification.md");
+    const classifPath = join15(changeDir, "change-classification.md");
     const tierResolution = resolveTier(changeDir);
-    if (tierResolution.tier === null && existsSync10(classifPath) && !tierResolution.classificationHasLooseMarker) {
+    if (tierResolution.tier === null && existsSync14(classifPath) && !tierResolution.classificationHasLooseMarker) {
       errors.push("change-classification.md: missing tier/risk marker (set tier in tasks.yml frontmatter, or include Tier 0-5 / low|medium|high|critical in change-classification.md)");
     }
   }
-  const tasksPath = join11(changeDir, "tasks.yml");
+  const tasksPath = join15(changeDir, "tasks.yml");
   let tasksData = null;
-  if (existsSync10(tasksPath)) {
+  if (existsSync14(tasksPath)) {
     tasksData = lintTasksFile(tasksPath, errors, warnings);
   }
   if (tasksData) {
@@ -13714,6 +14835,7 @@ async function gate(changeId, opts = {}) {
     }
   }
   enforceTierConsistency(changeDir, errors, warnings);
+  enforceTierFloor(changeDir, errors, warnings);
   for (const w of warnings) {
     log.warn(`  ${w}`);
   }
@@ -13737,75 +14859,540 @@ async function gate(changeId, opts = {}) {
   log.ok(`gate passed for change: ${changeId}`);
 }
 
-// src/commands/install-hooks.ts
-init_paths();
+// src/cli/index.ts
+init_install_hooks();
+init_install_agent_hooks();
+
+// src/commands/openapi-export.ts
 init_logger();
-import { existsSync as existsSync11, readFileSync as readFileSync10, writeFileSync as writeFileSync5, chmodSync as chmodSync2, mkdirSync as mkdirSync5 } from "fs";
-import { join as join12 } from "path";
-var START_MARKER2 = "# cdd-kit-managed-block-start";
-var END_MARKER2 = "# cdd-kit-managed-block-end";
-async function installHooks() {
-  const cwd = process.cwd();
-  const gitDir = join12(cwd, ".git");
-  if (!existsSync11(gitDir)) {
-    log.error("not a git repository (no .git/ found in cwd)");
-    process.exit(1);
+import { existsSync as existsSync15, readFileSync as readFileSync14, writeFileSync as writeFileSync8, mkdirSync as mkdirSync7 } from "fs";
+import { dirname as dirname4, resolve as resolve2 } from "path";
+var DEFAULT_CONTRACT = "contracts/api/api-contract.md";
+var VALID_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "delete", "patch", "head", "options"]);
+function stripFrontmatter(text) {
+  const fm = {};
+  if (text.startsWith("---")) {
+    const end = text.indexOf("\n---", 3);
+    if (end !== -1) {
+      const block = text.slice(3, end);
+      for (const line of block.split("\n")) {
+        const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (m)
+          fm[m[1].trim()] = m[2].trim();
+      }
+      return { body: text.slice(end + 4).replace(/^\n+/, ""), frontmatter: fm };
+    }
   }
-  const hooksDir = join12(gitDir, "hooks");
-  mkdirSync5(hooksDir, { recursive: true });
-  const dest = join12(hooksDir, "pre-commit");
-  const ourHook = readFileSync10(join12(ASSET.hooks, "pre-commit"), "utf8");
-  let final;
-  if (!existsSync11(dest)) {
-    final = ourHook;
-  } else {
-    const existing = readFileSync10(dest, "utf8");
-    const startIdx = existing.indexOf(START_MARKER2);
-    const endIdx = existing.indexOf(END_MARKER2);
-    if (startIdx >= 0 && endIdx > startIdx) {
-      const before = existing.slice(0, startIdx);
-      const after = existing.slice(endIdx + END_MARKER2.length);
-      const ourStart = ourHook.indexOf(START_MARKER2);
-      const ourEnd = ourHook.indexOf(END_MARKER2) + END_MARKER2.length;
-      const ourBlock = ourHook.slice(ourStart, ourEnd);
-      final = before + ourBlock + after;
-    } else {
-      const ourStart = ourHook.indexOf(START_MARKER2);
-      const ourEnd = ourHook.indexOf(END_MARKER2) + END_MARKER2.length;
-      const ourBlock = ourHook.slice(ourStart, ourEnd);
-      if (existing.startsWith("#!")) {
-        const firstNewline = existing.indexOf("\n");
-        const shebang = existing.slice(0, firstNewline + 1);
-        const rest = existing.slice(firstNewline + 1);
-        final = shebang + "\n" + ourBlock + "\n" + rest;
+  return { body: text, frontmatter: fm };
+}
+function parseRow(line) {
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+}
+function isSeparator(cells) {
+  return cells.every((c) => c === "" || /^:?-+:?$/.test(c));
+}
+function parseEndpoints(body) {
+  const rows = [];
+  let inTable = false;
+  let sepSeen = false;
+  for (const raw of body.split("\n")) {
+    const line = raw.trim();
+    if (!line || !line.startsWith("|"))
+      continue;
+    const cells = parseRow(line);
+    if (cells[0]?.toLowerCase() === "method") {
+      inTable = true;
+      sepSeen = false;
+      continue;
+    }
+    if (!inTable)
+      continue;
+    if (!sepSeen && isSeparator(cells)) {
+      sepSeen = true;
+      continue;
+    }
+    if (cells.length < 2 || !cells.some(Boolean))
+      continue;
+    const method = (cells[0] ?? "").toLowerCase();
+    const path = cells[1] ?? "";
+    if (!VALID_METHODS.has(method) || !path.startsWith("/"))
+      continue;
+    rows.push({
+      method,
+      path,
+      auth: (cells[2] ?? "").toLowerCase(),
+      request: cells[3] ?? "",
+      response: cells[4] ?? "",
+      errors: cells[5] ?? ""
+    });
+  }
+  return rows;
+}
+var SCHEMA_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
+var PRIMITIVE_TYPES = /* @__PURE__ */ new Set(["string", "integer", "number", "boolean"]);
+function extractSchemasSection(body) {
+  const lines = body.split("\n");
+  const start = lines.findIndex((line) => /^##\s+Schemas\s*$/i.test(line.trim()));
+  if (start === -1)
+    return "";
+  const out = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i].trim()))
+      break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+function parseSchemaSections(body) {
+  const schemasBlock = extractSchemasSection(body).replace(/<!--[\s\S]*?-->/g, "");
+  if (!schemasBlock.trim())
+    return { sections: [], errors: [] };
+  const sections = [];
+  const errors = [];
+  const seen = /* @__PURE__ */ new Set();
+  const headingRe = /^###\s+(.+?)\s*$/gm;
+  const headings = Array.from(schemasBlock.matchAll(headingRe));
+  for (let i = 0; i < headings.length; i += 1) {
+    const heading = headings[i];
+    const name = (heading[1] ?? "").trim();
+    const contentStart = (heading.index ?? 0) + heading[0].length;
+    const contentEnd = i + 1 < headings.length ? headings[i + 1].index ?? schemasBlock.length : schemasBlock.length;
+    if (!SCHEMA_NAME_RE.test(name))
+      continue;
+    if (seen.has(name)) {
+      errors.push(`Duplicate schema section: ${name}`);
+      continue;
+    }
+    seen.add(name);
+    sections.push({ name, content: schemasBlock.slice(contentStart, contentEnd) });
+  }
+  return { sections, errors };
+}
+function parseJsonSchemaBlocks(section) {
+  const blocks = [];
+  const errors = [];
+  const blockRe = /```json-schema\s*\n([\s\S]*?)```/g;
+  for (const match of section.content.matchAll(blockRe)) {
+    try {
+      const parsed = JSON.parse(match[1] ?? "");
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        errors.push(`Schema ${section.name}: json-schema block must be a JSON object`);
       } else {
-        final = "#!/bin/sh\n" + ourBlock + "\n" + existing;
+        blocks.push(parsed);
       }
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      errors.push(`Schema ${section.name}: invalid json-schema block (${detail})`);
     }
   }
-  writeFileSync5(dest, final, "utf8");
-  try {
-    chmodSync2(dest, 493);
-  } catch {
+  return { blocks, errors };
+}
+function findForeignFenceTag(section) {
+  const fenceRe = /```([^\n]*)(?:\n|$)[\s\S]*?```/g;
+  for (const match of section.content.matchAll(fenceRe)) {
+    const info = (match[1] ?? "").trim();
+    if (info !== "json-schema")
+      return info;
   }
-  log.ok(`pre-commit hook installed at ${dest}`);
-  log.info("cdd-kit gate will now run automatically before each commit affecting specs/changes/");
+  return null;
+}
+function parseFieldTable(section) {
+  const lines = section.content.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line.startsWith("|"))
+      continue;
+    const header = parseRow(line).map((c) => c.toLowerCase());
+    const fieldIdx = header.indexOf("field");
+    const typeIdx = header.indexOf("type");
+    const requiredIdx = header.indexOf("required");
+    if (fieldIdx === -1 || typeIdx === -1 || requiredIdx === -1)
+      continue;
+    const separator = lines[i + 1]?.trim();
+    if (!separator?.startsWith("|") || !isSeparator(parseRow(separator)))
+      continue;
+    const notesIdx = header.indexOf("notes");
+    const formatIdx = header.indexOf("format");
+    const rows = [];
+    for (let j = i + 2; j < lines.length; j += 1) {
+      const rowLine = lines[j].trim();
+      if (!rowLine || !rowLine.startsWith("|"))
+        break;
+      const cells = parseRow(rowLine);
+      if (isSeparator(cells) || cells.length < 2 || !cells.some(Boolean))
+        continue;
+      rows.push({
+        field: cells[fieldIdx] ?? "",
+        type: cells[typeIdx] ?? "",
+        required: cells[requiredIdx] ?? "",
+        notes: notesIdx === -1 ? "" : cells[notesIdx] ?? "",
+        format: formatIdx === -1 ? "" : cells[formatIdx] ?? ""
+      });
+    }
+    return { rows, found: true };
+  }
+  return { rows: [], found: false };
+}
+function compileType(typeValue, schemaNames, resolvableNames, context2) {
+  const type = typeValue.trim();
+  if (!type)
+    throw new Error(`${context2}: empty type`);
+  if (type.endsWith("[]")) {
+    const inner = type.slice(0, -2).trim();
+    if (!inner || inner.endsWith("[]"))
+      throw new Error(`${context2}: unsupported array type "${type}"`);
+    return { type: "array", items: compileType(inner, schemaNames, resolvableNames, context2) };
+  }
+  if (PRIMITIVE_TYPES.has(type))
+    return { type };
+  const enumMatch = type.match(/^enum\((.*)\)$/);
+  if (enumMatch) {
+    const values = (enumMatch[1] ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+    if (values.length === 0)
+      throw new Error(`${context2}: enum must list at least one value`);
+    return { type: "string", enum: values };
+  }
+  if (SCHEMA_NAME_RE.test(type) && schemaNames.has(type)) {
+    if (!resolvableNames.has(type)) {
+      throw new Error(`${context2}: referenced schema "${type}" has no field table or json-schema block`);
+    }
+    return { $ref: `#/components/schemas/${type}` };
+  }
+  throw new Error(`${context2}: unknown type "${type}"`);
+}
+function compileFieldTable(section, rows, schemaNames, resolvableNames) {
+  const properties = {};
+  const required = [];
+  for (const row of rows) {
+    const field = row.field.trim();
+    if (!field)
+      throw new Error(`Schema ${section.name}: field name is required`);
+    const schema = compileType(row.type, schemaNames, resolvableNames, `Schema ${section.name}, field ${field}`);
+    if (row.notes.trim())
+      schema.description = row.notes.trim();
+    if (row.format.trim())
+      schema.format = row.format.trim();
+    properties[field] = schema;
+    if (row.required.trim().toLowerCase() === "yes")
+      required.push(field);
+  }
+  const compiled = { type: "object", properties };
+  if (required.length > 0)
+    compiled.required = required;
+  return compiled;
+}
+function parseContractSchemas(body) {
+  const { sections, errors } = parseSchemaSections(body);
+  if (sections.length === 0)
+    return { schemas: {}, errors };
+  const schemaNames = new Set(sections.map((s) => s.name));
+  const metadata = /* @__PURE__ */ new Map();
+  const resolvableNames = /* @__PURE__ */ new Set();
+  for (const section of sections) {
+    const raw = parseJsonSchemaBlocks(section);
+    errors.push(...raw.errors);
+    if (raw.blocks.length > 1)
+      errors.push(`Schema ${section.name}: expected at most one json-schema block`);
+    const fields = parseFieldTable(section);
+    if (raw.blocks.length > 0 && fields.found) {
+      errors.push(`Schema ${section.name}: choose either a field table or a json-schema block, not both`);
+    }
+    const foreign = findForeignFenceTag(section);
+    if (foreign !== null) {
+      const desc = foreign ? `a \`\`\`${foreign} code block` : "an untagged code block";
+      errors.push(
+        `Schema ${section.name}: found ${desc}, but a machine-typed schema body must use a \`\`\`json-schema fence. Change the fence to \`\`\`json-schema, use a "| field | type | required | ... |" table, or remove the fence to keep it a free-form (Tier C) prose contract.`
+      );
+    }
+    if (raw.blocks.length === 1 || fields.found)
+      resolvableNames.add(section.name);
+    metadata.set(section.name, {
+      section,
+      rawBlocks: raw.blocks,
+      fieldRows: fields.rows,
+      hasFieldTable: fields.found
+    });
+  }
+  const schemas = {};
+  for (const [name, item] of metadata) {
+    if (item.rawBlocks.length === 1 && !item.hasFieldTable) {
+      schemas[name] = item.rawBlocks[0];
+      continue;
+    }
+    if (!item.hasFieldTable)
+      continue;
+    try {
+      schemas[name] = compileFieldTable(item.section, item.fieldRows, schemaNames, resolvableNames);
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  return { schemas, errors };
+}
+function resolveSchemaCell(cell, schemas) {
+  const raw = cell.trim();
+  if (!raw || raw === "-")
+    return void 0;
+  const isArray = raw.endsWith("[]");
+  const name = isArray ? raw.slice(0, -2).trim() : raw;
+  if (!SCHEMA_NAME_RE.test(name) || !schemas[name])
+    return void 0;
+  const ref = { $ref: `#/components/schemas/${name}` };
+  return isArray ? { type: "array", items: ref } : ref;
+}
+function toOpenApiPath(path) {
+  const params = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addParam = (name) => {
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      params.push({ name, in: "path", required: true, schema: { type: "string" } });
+    }
+  };
+  let oapi = path.replace(/:([A-Za-z_][\w]*)/g, (_m, n) => {
+    addParam(n);
+    return `{${n}}`;
+  }).replace(/\{([^}/]+)\}/g, (_m, n) => {
+    addParam(n.trim());
+    return `{${n.trim()}}`;
+  });
+  oapi = oapi.split("?", 1)[0];
+  return { path: oapi, params };
+}
+function authToSecurity(auth) {
+  switch (auth) {
+    case "required":
+    case "admin":
+      return { security: [{ bearerAuth: [] }], scheme: "bearerAuth" };
+    case "optional":
+      return { security: [{ bearerAuth: [] }, {}], scheme: "bearerAuth" };
+    case "none":
+    case "public":
+    case "":
+      return {};
+    default:
+      return { security: [{ bearerAuth: [] }], scheme: "bearerAuth" };
+  }
+}
+function statusFromErrors(errors) {
+  const codes = (errors.match(/\b[1-5]\d\d\b/g) ?? []).filter((v, i, a) => a.indexOf(v) === i);
+  return codes;
+}
+function buildDoc(endpoints, frontmatter, styleBlock, schemas) {
+  const paths = {};
+  let anySecurity = false;
+  for (const ep of endpoints) {
+    const { path, params } = toOpenApiPath(ep.path);
+    const successCode = ep.method === "post" ? "201" : "200";
+    const responseSchema = resolveSchemaCell(ep.response, schemas);
+    const responses = {
+      [successCode]: { description: ep.response ? `Contract response: ${ep.response}` : "Success" }
+    };
+    if (responseSchema) {
+      responses[successCode].content = {
+        "application/json": { schema: responseSchema }
+      };
+    }
+    for (const code of statusFromErrors(ep.errors)) {
+      if (!responses[code])
+        responses[code] = { description: "Error response (see contract error format)" };
+    }
+    const op = {
+      summary: `${ep.method.toUpperCase()} ${ep.path}`,
+      responses
+    };
+    if (params.length > 0)
+      op.parameters = params;
+    const { security, scheme } = authToSecurity(ep.auth);
+    if (security) {
+      op.security = security;
+      if (scheme)
+        anySecurity = true;
+    }
+    if (ep.request && ep.request !== "-" && ep.method !== "get") {
+      const requestSchema = resolveSchemaCell(ep.request, schemas);
+      if (requestSchema) {
+        op.requestBody = {
+          description: `Contract request: ${ep.request}`,
+          content: {
+            "application/json": { schema: requestSchema }
+          }
+        };
+      } else {
+        op.requestBody = {
+          description: `Contract request: ${ep.request} (schema not machine-resolved; see contract)`,
+          content: {},
+          "x-cdd-unresolved": true
+        };
+      }
+    }
+    if (ep.response && !responseSchema)
+      op["x-cdd-response-contract"] = ep.response;
+    if (ep.errors)
+      op["x-cdd-errors"] = ep.errors;
+    paths[path] = paths[path] ?? {};
+    paths[path][ep.method] = op;
+  }
+  const doc = {
+    openapi: "3.1.0",
+    info: {
+      title: frontmatter.summary || frontmatter.surface || "API",
+      version: frontmatter["schema-version"] || "0.0.0"
+    },
+    paths,
+    "x-cdd-generated-from": DEFAULT_CONTRACT,
+    "x-cdd-note": "Generated by `cdd-kit openapi export` from the markdown API contract (the source of truth). Partial by design: request/response bodies are free-form prose in the contract and are marked unresolved. Do not hand-edit; regenerate from the contract."
+  };
+  const styleText = styleBlock.trim();
+  if (styleText)
+    doc.info.description = styleText;
+  if (anySecurity) {
+    doc.components = doc.components ?? {};
+    doc.components.securitySchemes = {
+      bearerAuth: { type: "http", scheme: "bearer" }
+    };
+  }
+  if (Object.keys(schemas).length > 0) {
+    doc.components = doc.components ?? {};
+    doc.components.schemas = schemas;
+  }
+  return doc;
+}
+function extractStyleBlock(body) {
+  const m = body.match(/^##\s+API Style\s*\n([\s\S]*?)(?:\n##\s|\n#\s|$)/m);
+  if (!m)
+    return "";
+  return m[1].split("\n").map((l) => l.trim()).filter((l) => l.startsWith("-")).join("\n");
+}
+function isNonEmptyComposite(v) {
+  if (typeof v !== "object" || v === null)
+    return false;
+  return Array.isArray(v) ? v.length > 0 : Object.keys(v).length > 0;
+}
+function yamlScalar(value) {
+  if (value === null || value === void 0)
+    return "null";
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  const s = String(value);
+  if (s === "" || /[:#?{}\[\],&*!|>'"%@`]/.test(s) || /^[\s-]/.test(s) || /\s$/.test(s) || /^\d/.test(s)) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+function toYaml(value, indent = 0) {
+  const pad = "  ".repeat(indent);
+  if (!isNonEmptyComposite(value)) {
+    if (Array.isArray(value))
+      return "[]";
+    if (typeof value === "object" && value !== null)
+      return "{}";
+    return yamlScalar(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (isNonEmptyComposite(item)) {
+        return `${pad}-
+${toYaml(item, indent + 1)}`;
+      }
+      return `${pad}- ${toYaml(item, indent)}`;
+    }).join("\n");
+  }
+  return Object.entries(value).map(([k, v]) => {
+    const key = /[:#\s]/.test(k) ? JSON.stringify(k) : k;
+    if (isNonEmptyComposite(v)) {
+      return `${pad}${key}:
+${toYaml(v, indent + 1)}`;
+    }
+    return `${pad}${key}: ${toYaml(v, indent)}`;
+  }).join("\n");
+}
+async function openapiExport(opts = {}) {
+  const contractPath = opts.contract || DEFAULT_CONTRACT;
+  const format = opts.format || "json";
+  if (!existsSync15(contractPath)) {
+    log.error(`API contract not found: ${contractPath}`);
+    return 1;
+  }
+  const raw = readFileSync14(contractPath, "utf8");
+  const { body, frontmatter } = stripFrontmatter(raw);
+  const endpoints = parseEndpoints(body);
+  const contractSchemas = parseContractSchemas(body);
+  if (contractSchemas.errors.length > 0) {
+    for (const err of contractSchemas.errors)
+      log.error(err);
+    return 1;
+  }
+  if (endpoints.length === 0) {
+    log.error(`No endpoint table rows found in ${contractPath}. Add rows to the "| method | path | ... |" table first.`);
+    return 1;
+  }
+  const styleBlock = extractStyleBlock(body);
+  const doc = buildDoc(endpoints, frontmatter, styleBlock, contractSchemas.schemas);
+  const serialized = format === "yaml" ? `${toYaml(doc)}
+` : `${JSON.stringify(doc, null, 2)}
+`;
+  if (opts.check) {
+    if (!opts.out) {
+      log.error("openapi export --check requires --out <path> (the committed artifact to verify against the contract)");
+      return 1;
+    }
+    const contractFlag = contractPath === DEFAULT_CONTRACT ? "" : ` --contract ${contractPath}`;
+    const yamlFlag = format === "yaml" ? " --yaml" : "";
+    const regen = `cdd-kit openapi export${contractFlag} --out ${opts.out}${yamlFlag}`;
+    if (!existsSync15(opts.out)) {
+      log.error(`openapi export --check: ${opts.out} does not exist. Run \`${regen}\` and commit it.`);
+      return 1;
+    }
+    const committed = readFileSync14(opts.out, "utf8");
+    if (committed === serialized) {
+      log.ok(`OpenAPI artifact ${opts.out} is in sync with ${contractPath} (${endpoints.length} endpoint(s))`);
+      return 0;
+    }
+    log.error(`OpenAPI artifact ${opts.out} is OUT OF SYNC with ${contractPath}. The contract changed but the export was not regenerated.`);
+    log.error(`Fix: \`${regen}\` and commit the result.`);
+    return 1;
+  }
+  if (opts.out) {
+    const outPath = resolve2(opts.out);
+    mkdirSync7(dirname4(outPath), { recursive: true });
+    writeFileSync8(outPath, serialized, "utf8");
+    log.ok(`OpenAPI ${format.toUpperCase()} written to ${outPath} (${endpoints.length} endpoint(s))`);
+    const unresolved = countUnresolved(doc);
+    if (unresolved > 0) {
+      log.info(`${unresolved} request body schema(s) left unresolved (free-form prose in the contract). Fill them in the consumer generator or enrich the contract.`);
+    }
+  } else {
+    process.stdout.write(serialized);
+  }
+  return 0;
+}
+function countUnresolved(doc) {
+  let n = 0;
+  for (const methods of Object.values(doc.paths)) {
+    for (const op of Object.values(methods)) {
+      if (op.requestBody?.["x-cdd-unresolved"])
+        n += 1;
+    }
+  }
+  return n;
 }
 
 // src/cli/index.ts
-var __dirname2 = dirname7(fileURLToPath4(import.meta.url));
-var pkg = JSON.parse(readFileSync31(join30(__dirname2, "..", "..", "package.json"), "utf8"));
+var __dirname2 = dirname8(fileURLToPath4(import.meta.url));
+var pkg = JSON.parse(readFileSync39(join35(__dirname2, "..", "..", "package.json"), "utf8"));
 var program = new Command();
 program.name("cdd-kit").description("Contract-Driven Delivery Kit CLI").version(pkg.version);
 program.command("init").description(
   "Install agents/skill into ~/.claude and scaffold project files in cwd"
-).option("--global-only", "Only install into ~/.claude, skip project files", false).option("--local-only", "Only scaffold project files, skip ~/.claude", false).option("--force", "Overwrite existing project files", false).option("--provider <provider>", "Provider adapter to scaffold: claude, codex, or both", "claude").option("--hooks", "Install a pre-commit hook that auto-regenerates .cdd/code-map.yml", false).action(
+).option("--global-only", "Only install into ~/.claude, skip project files", false).option("--local-only", "Only scaffold project files, skip ~/.claude", false).option("--force", "Overwrite existing project files", false).option("--provider <provider>", "Provider adapter to scaffold: claude, codex, or both", "claude").option("--hooks", "Also install the pre-commit hook that auto-regenerates .cdd/code-map.yml", false).option("--no-arm", "Skip arming enforcement chokepoints (graph-first hook + pre-commit gate)").action(
   (opts) => init({
     globalOnly: opts.globalOnly,
     localOnly: opts.localOnly,
     force: opts.force,
     provider: opts.provider,
-    hooks: opts.hooks
+    hooks: opts.hooks,
+    arm: opts.arm !== false
   })
 );
 program.command("update").description("Update provider assets for the current project (does not overwrite project guidance files)").option("--yes", "Apply changes (default is dry-run)", false).option("--provider <provider>", "Provider adapter to update: auto, claude, codex, or both", "auto").option("--postinstall", "Internal: invoked by npm postinstall; no-op if cdd has not been init-ed", false).action((opts) => update({ yes: opts.yes, provider: opts.provider, postinstall: opts.postinstall }));
@@ -13866,7 +15453,26 @@ function resolveWorkers(value) {
     return 1;
   return Math.min(n, 16);
 }
-program.command("code-map [path]").description("Scan source files and emit a structural index at .cdd/code-map.yml").option("--out <path>", "Output YAML path (default .cdd/code-map.yml; with --surface, .cdd/code-map.<surface>.yml)").option("--surface <subpath>", "Scope the scan to a monorepo subtree and name the map after it").option("--workers [n]", "Parallelize JS/TS/Vue scanning across N child processes (default: CPU count - 1)").option("--include <glob>", "Additional include glob (repeatable)", collectRepeatable, []).option("--exclude <glob>", "Additional exclude glob (repeatable)", collectRepeatable, []).option("--check", "Exit 1 if regenerating would change the file (no write)", false).option("--max-lines <n>", "Warn for files exceeding this line count (default 100000)", "100000").action(async (path, opts) => {
+program.command("code-map [path]").description("Scan source files and emit a structural index at .cdd/code-map.yml").option("--out <path>", "Output YAML path (default .cdd/code-map.yml; with --surface, .cdd/code-map.<surface>.yml)").option("--surface <subpath>", "Scope the scan to a monorepo subtree and name the map after it").option("--workers [n]", "Parallelize JS/TS/Vue scanning across N child processes (default: CPU count - 1)").option("--include <glob>", "Additional include glob (repeatable)", collectRepeatable, []).option("--exclude <glob>", "Additional exclude glob (repeatable)", collectRepeatable, []).option("--check", "Exit 1 if regenerating would change the file (no write)", false).option("--watch", "Keep the map fresh in the background, rebuilding on file changes (debounced)", false).option("--debounce <ms>", "With --watch: coalesce change bursts within this window (default 500)", "500").option("--max-lines <n>", "Warn for files exceeding this line count (default 100000)", "100000").action(async (path, opts) => {
+  if (opts.watch) {
+    const { codeMapWatch: codeMapWatch2 } = await Promise.resolve().then(() => (init_code_map_watch(), code_map_watch_exports));
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    const exit2 = await codeMapWatch2({
+      path: path ?? ".",
+      out: opts.out,
+      surface: opts.surface,
+      workers: resolveWorkers(opts.workers),
+      include: opts.include,
+      exclude: opts.exclude,
+      maxLines: parseInt(opts.maxLines, 10),
+      debounceMs: parseInt(opts.debounce ?? "500", 10),
+      signal: controller.signal
+    });
+    process.exit(exit2);
+  }
   const { codeMap: codeMap2 } = await Promise.resolve().then(() => (init_code_map(), code_map_exports));
   const exit = await codeMap2({
     path: path ?? ".",
@@ -13886,13 +15492,15 @@ program.command("__code-map-scan", { hidden: true }).requiredOption("--lang <lan
   process.exit(exit);
 });
 var index = program.command("index").description("Query machine-readable project indexes before opening source files");
-index.command("query <term>").description("Search .cdd/code-map.yml for files, symbols, imports, and line ranges").option("--map <path>", "Code-map YAML path", ".cdd/code-map.yml").option("--limit <n>", "Maximum result files to print", "10").option("--json", "Print machine-readable JSON", false).option("--no-refresh", "Do not auto-regenerate stale or missing code-map before querying").action(async (term, opts) => {
+index.command("query <term>").description("Search .cdd/code-map.yml for files, symbols, imports, and line ranges").option("--map <path>", "Code-map YAML path", ".cdd/code-map.yml").option("--limit <n>", "Maximum result files to print", "10").option("--json", "Print machine-readable JSON", false).option("--with-source", "Include the matched source slices inline so no separate Read is needed", false).option("--source-budget <n>", "Max total source lines to emit with --with-source", "400").option("--no-refresh", "Do not auto-regenerate stale or missing code-map before querying").action(async (term, opts) => {
   const { indexQuery: indexQuery2 } = await Promise.resolve().then(() => (init_index_query(), index_query_exports));
   const exit = await indexQuery2(term, {
     map: opts.map,
     limit: parseInt(opts.limit, 10),
     json: opts.json === true,
-    refresh: opts.refresh !== false
+    refresh: opts.refresh !== false,
+    withSource: opts.withSource === true,
+    sourceBudget: parseInt(opts.sourceBudget ?? "400", 10)
   });
   process.exit(exit);
 });
@@ -13917,14 +15525,16 @@ graph.command("sync [path]").description("Run CodeGraph incremental sync (requir
   const exit = await graphSync2({ path, engine: opts.engine, json: opts.json === true });
   process.exit(exit);
 });
-graph.command("query <term>").description("Search native graph symbols, optionally delegating to CodeGraph or code-map").option("--engine <engine>", "Graph engine: auto, native, codegraph, or codemap", "auto").option("--map <path>", "Code-map YAML path for fallback", ".cdd/code-map.yml").option("--limit <n>", "Maximum results to print", "10").option("--json", "Print machine-readable JSON", false).option("--no-refresh", "Do not auto-regenerate stale or missing fallback code-map").action(async (term, opts) => {
+graph.command("query <term>").description("Search native graph symbols, optionally delegating to CodeGraph or code-map").option("--engine <engine>", "Graph engine: auto, native, codegraph, or codemap", "auto").option("--map <path>", "Code-map YAML path for fallback", ".cdd/code-map.yml").option("--limit <n>", "Maximum results to print", "10").option("--json", "Print machine-readable JSON", false).option("--with-source", "Include matched source slices inline so no separate Read is needed (native/codemap engines)", false).option("--source-budget <n>", "Max total source lines to emit with --with-source", "400").option("--no-refresh", "Do not auto-regenerate stale or missing fallback code-map").action(async (term, opts) => {
   const { graphQuery: graphQuery2 } = await Promise.resolve().then(() => (init_graph(), graph_exports));
   const exit = await graphQuery2(term, {
     engine: opts.engine,
     map: opts.map,
     limit: parseInt(opts.limit, 10),
     json: opts.json === true,
-    refresh: opts.refresh !== false
+    refresh: opts.refresh !== false,
+    withSource: opts.withSource === true,
+    sourceBudget: parseInt(opts.sourceBudget ?? "400", 10)
   });
   process.exit(exit);
 });
@@ -13951,6 +15561,11 @@ graph.command("context <task>").description("Build task context with native grap
   });
   process.exit(exit);
 });
+program.command("classify-check [change-id]").description("Show the mechanical risk-tier floor for a change before classification (advisory; gate enforces it)").option("--text <text>", "Scan this inline intent text instead of a change directory").option("--json", "Print machine-readable JSON", false).action(async (changeId, opts) => {
+  const { classifyCheck: classifyCheck2 } = await Promise.resolve().then(() => (init_classify_check(), classify_check_exports));
+  const exit = await classifyCheck2(changeId, { text: opts.text, json: opts.json });
+  process.exit(exit);
+});
 program.command("mcp").description("Run the cdd-kit MCP stdio server exposing graph and code-map tools").action(async () => {
   const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
   await runMcpServer2({ version: pkg.version });
@@ -13982,6 +15597,19 @@ program.command("list").description("List active changes in specs/changes/").act
 program.command("install-hooks").description("Install pre-commit hook that runs cdd-kit gate on staged changes").action(async () => {
   await installHooks();
 });
+program.command("install-agent-hooks").description("Install Claude Code agent hooks into .claude/settings.json (graph-first exploration)").option("--graph-first <mode>", "Install the graph-first PreToolUse hook: 'advisory' (default) or 'strict'", "advisory").action(async (opts) => {
+  await installAgentHooks({ graphFirst: opts.graphFirst });
+});
+var openapi = program.command("openapi").description("Project the API contract into tooling artifacts (see docs/adr/0001-contract-to-openapi-export.md)");
+openapi.command("export").description("Export contracts/api/api-contract.md as a minimal OpenAPI 3.1 skeleton").option("--contract <path>", "API contract markdown path", "contracts/api/api-contract.md").option("--out <path>", "Write to a file instead of stdout").option("--yaml", "Emit YAML instead of JSON", false).option("--check", "Verify the artifact at --out is in sync with the contract (exits 1 on drift); does not write", false).action(async (opts) => {
+  const exit = await openapiExport({
+    contract: opts.contract,
+    out: opts.out,
+    format: opts.yaml ? "yaml" : "json",
+    check: opts.check
+  });
+  process.exit(exit);
+});
 program.command("detect-stack").description("Detect the project tech stack and print the result").action(() => {
   const cwd = process.cwd();
   const result = detectStack(cwd);