contract-driven-delivery 2.0.7 → 2.0.9

package/dist/cli/index.js

@@ -139,6 +139,13 @@ ${CODE_MAP_BLOCK}
     chmodSync(dest, 493);
   } catch {
   }
+  try {
+    const cddDir = join4(cwd, ".cdd");
+    mkdirSync2(cddDir, { recursive: true });
+    writeFileSync(join4(cddDir, ".hooks-installed"), `installed: ${(/* @__PURE__ */ new Date()).toISOString()}
+`, "utf8");
+  } catch {
+  }
   log.ok(`code-map pre-commit hook installed at ${dest}`);
 }
 var START_MARKER, END_MARKER, CODE_MAP_BLOCK;
@@ -151,7 +158,8 @@ var init_code_map_hook = __esm({
     CODE_MAP_BLOCK = `${START_MARKER}
 # Auto-regenerates .cdd/code-map.yml when source files are staged.
 # Generated by: cdd-kit init --hooks (re-run to update).
-staged_src=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(py|js|vue)$' || true)
+# Extension list mirrors src/code-map/config.ts BUILTIN_INCLUDE.
+staged_src=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(py|js|jsx|mjs|cjs|ts|tsx|vue)$' || true)
 if [ -n "$staged_src" ]; then
   if cdd-kit code-map --check >/dev/null 2>&1; then
     : # already up to date
@@ -201,6 +209,173 @@ 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 { createHash } from "crypto";
+import { homedir as homedir2 } from "os";
+function fileHash(filePath) {
+  const buf = readFileSync5(filePath);
+  return createHash("sha256").update(buf).digest("hex");
+}
+function diffDir(src, dest) {
+  const entries = [];
+  if (!existsSync6(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);
+      if (item.isDirectory()) {
+        walk(srcPath, destPath);
+      } else {
+        if (!existsSync6(destPath)) {
+          entries.push({ src: srcPath, dest: destPath, action: "add" });
+        } else if (fileHash(srcPath) !== fileHash(destPath)) {
+          entries.push({ src: srcPath, dest: destPath, action: "overwrite" });
+        } else {
+          entries.push({ src: srcPath, dest: destPath, action: "skip" });
+        }
+      }
+    }
+  }
+  walk(src, dest);
+  return entries;
+}
+function applyDir(entries) {
+  let count = 0;
+  for (const e of entries) {
+    if (e.action === "skip")
+      continue;
+    mkdirSync3(join7(e.dest, ".."), { recursive: true });
+    copyFileSync2(e.src, e.dest);
+    count += 1;
+  }
+  return count;
+}
+function backupDir(dir, backupDest) {
+  if (!existsSync6(dir))
+    return;
+  mkdirSync3(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);
+      if (item.isDirectory()) {
+        mkdirSync3(d, { recursive: true });
+        walk(s, d);
+      } else
+        copyFileSync2(s, d);
+    }
+  }
+  walk(dir, backupDest);
+}
+async function update(opts) {
+  if (opts.postinstall) {
+    if (!existsSync6(join7(SKILLS_HOME, "contract-driven-delivery"))) {
+      return;
+    }
+    opts.yes = true;
+    opts.provider = "claude";
+  }
+  const quiet = !!opts.postinstall;
+  if (!quiet)
+    log.blank();
+  const cwd = process.cwd();
+  const requestedProvider = opts.provider ?? "auto";
+  if (!validateProviderOption(requestedProvider)) {
+    log.error(`Invalid provider: ${requestedProvider}. Use auto, claude, codex, or both.`);
+    process.exit(1);
+  }
+  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 toWrite = [...agentDiff, ...skillDiff].filter((e) => e.action !== "skip");
+  const toAdd = toWrite.filter((e) => e.action === "add");
+  const toOver = toWrite.filter((e) => e.action === "overwrite");
+  const toSkip = [...agentDiff, ...skillDiff].filter((e) => e.action === "skip");
+  if (!quiet) {
+    log.info(`Provider: ${provider}`);
+    if (updateClaudeAssets) {
+      log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
+      log.info(`Dry-run diff \u2014 skills: ${SKILLS_HOME}`);
+    } else {
+      log.info("Codex provider has no global cdd-kit assets to update.");
+      log.info("Project files are preserved; run cdd-kit init --local-only --provider codex to add missing local guidance.");
+    }
+    log.blank();
+    if (toAdd.length)
+      log.info(`  + ${toAdd.length} file(s) would be added`);
+    if (toOver.length)
+      log.warn(`  ~ ${toOver.length} file(s) would be overwritten (user edits lost without backup)`);
+    if (toSkip.length)
+      log.dim(`    ${toSkip.length} file(s) unchanged (skipped)`);
+  }
+  if (toWrite.length === 0) {
+    if (!quiet) {
+      log.blank();
+      log.ok("Already up to date \u2014 nothing to write.");
+      log.blank();
+    }
+    return;
+  }
+  if (!quiet && !opts.yes) {
+    log.blank();
+    log.info("Run with --yes to apply changes. Example:");
+    log.dim("  cdd-kit update --yes");
+    log.blank();
+    return;
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupRoot = join7(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"));
+  if (!quiet)
+    log.ok(`Backup complete: ${backupRoot}`);
+  if (!quiet)
+    log.blank();
+  let totalSynced = 0;
+  if (updateClaudeAssets) {
+    if (!quiet)
+      log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
+    const agentCount = applyDir(agentDiff);
+    if (!quiet)
+      log.ok(`${agentCount} agent file(s) updated.`);
+    totalSynced += agentCount;
+    if (!quiet)
+      log.info(`Updating skills \u2192 ${SKILLS_HOME}`);
+    const skillCount = applyDir(skillDiff);
+    if (!quiet)
+      log.ok(`${skillCount} skill file(s) updated.`);
+    totalSynced += skillCount;
+  }
+  if (quiet) {
+    if (totalSynced > 0)
+      log.ok(`cdd-kit: synced ${totalSynced} file(s) to ~/.claude/`);
+  } else {
+    log.blank();
+    log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
+    log.ok("Update complete.");
+    log.info(`Backup saved to: ${backupRoot}`);
+    log.blank();
+  }
+}
+var init_update = __esm({
+  "src/commands/update.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    init_provider();
+  }
+});
+
 // src/commands/context-scan.ts
 var context_scan_exports = {};
 __export(context_scan_exports, {
@@ -240,7 +415,14 @@ function getForbiddenPaths(cwd) {
 }
 function isForbidden(relPath, forbidden) {
   const normalized = relPath.replace(/\\/g, "/");
-  return forbidden.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`));
+  if (forbidden.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`))) {
+    return true;
+  }
+  for (const segment of normalized.split("/")) {
+    if (FORBIDDEN_DIRECTORY_NAMES.has(segment))
+      return true;
+  }
+  return false;
 }
 function buildTree(dir, cwd, forbidden, stats, prefix = "", depth = 0) {
   const entries = readdirSync4(dir, { withFileTypes: true }).sort((a, b) => {
@@ -457,7 +639,7 @@ async function contextScan(opts = {}) {
     log.ok("Created specs/context/contracts-index.md");
   }
 }
-var DEFAULT_FORBIDDEN, PER_DIR_ENTRY_CAP;
+var DEFAULT_FORBIDDEN, FORBIDDEN_DIRECTORY_NAMES, PER_DIR_ENTRY_CAP;
 var init_context_scan = __esm({
   "src/commands/context-scan.ts"() {
     "use strict";
@@ -470,8 +652,43 @@ var init_context_scan = __esm({
       "build",
       "assets",
       "specs/archive",
-      "specs/changes"
+      "specs/changes",
+      // cdd-kit runtime artifacts. Without these the user's local backups land
+      // in `specs/context/project-map.md`, polluting it and breaking the
+      // inputs-digest match for any fresh clone.
+      ".cdd/.refresh-backup",
+      ".cdd/migrate-backup",
+      ".cdd/runtime"
     ];
+    FORBIDDEN_DIRECTORY_NAMES = /* @__PURE__ */ new Set([
+      // Node — also caught by top-level prefix, but a nested
+      // `frontend/node_modules` requires basename matching
+      "node_modules",
+      // Python
+      "__pycache__",
+      ".pytest_cache",
+      ".mypy_cache",
+      ".ruff_cache",
+      ".tox",
+      // JS/TS frameworks
+      ".next",
+      ".nuxt",
+      ".svelte-kit",
+      ".parcel-cache",
+      ".turbo",
+      ".nyc_output",
+      // Generic build / coverage caches
+      "coverage",
+      "htmlcov",
+      ".cache",
+      // Virtualenvs
+      "venv",
+      ".venv",
+      // IDE / OS noise
+      ".idea",
+      ".vscode",
+      ".DS_Store"
+    ]);
     PER_DIR_ENTRY_CAP = 50;
   }
 });
@@ -4046,49 +4263,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative5, options, skipNormalization) {
+    function resolveComponent(base, relative6, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative5 = parse3(serialize(relative5, options), options);
+        relative6 = parse3(serialize(relative6, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative5.scheme) {
-        target.scheme = relative5.scheme;
-        target.userinfo = relative5.userinfo;
-        target.host = relative5.host;
-        target.port = relative5.port;
-        target.path = removeDotSegments(relative5.path || "");
-        target.query = relative5.query;
+      if (!options.tolerant && relative6.scheme) {
+        target.scheme = relative6.scheme;
+        target.userinfo = relative6.userinfo;
+        target.host = relative6.host;
+        target.port = relative6.port;
+        target.path = removeDotSegments(relative6.path || "");
+        target.query = relative6.query;
       } else {
-        if (relative5.userinfo !== void 0 || relative5.host !== void 0 || relative5.port !== void 0) {
-          target.userinfo = relative5.userinfo;
-          target.host = relative5.host;
-          target.port = relative5.port;
-          target.path = removeDotSegments(relative5.path || "");
-          target.query = relative5.query;
+        if (relative6.userinfo !== void 0 || relative6.host !== void 0 || relative6.port !== void 0) {
+          target.userinfo = relative6.userinfo;
+          target.host = relative6.host;
+          target.port = relative6.port;
+          target.path = removeDotSegments(relative6.path || "");
+          target.query = relative6.query;
         } else {
-          if (!relative5.path) {
+          if (!relative6.path) {
             target.path = base.path;
-            if (relative5.query !== void 0) {
-              target.query = relative5.query;
+            if (relative6.query !== void 0) {
+              target.query = relative6.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative5.path[0] === "/") {
-              target.path = removeDotSegments(relative5.path);
+            if (relative6.path[0] === "/") {
+              target.path = removeDotSegments(relative6.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative5.path;
+                target.path = "/" + relative6.path;
               } else if (!base.path) {
-                target.path = relative5.path;
+                target.path = relative6.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative5.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative6.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative5.query;
+            target.query = relative6.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -4096,7 +4313,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative5.fragment;
+      target.fragment = relative6.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -7468,1877 +7685,2232 @@ var init_freshness = __esm({
   }
 });
 
-// src/code-map/yaml-writer.ts
-function quoteScalar(s) {
-  if (s.startsWith(".") || YAML_RESERVED.test(s) || s.includes(" ") || s === "" || s === "null" || s === "true" || s === "false") {
-    return `'${s.replace(/'/g, "''")}'`;
-  }
-  return s;
-}
-function quotePath(p) {
-  if (YAML_RESERVED.test(p) || p.includes(" ")) {
-    return `'${p.replace(/'/g, "''")}'`;
-  }
-  return p;
-}
-function renderItems(items) {
-  if (items.length === 0)
-    return "[]";
-  return `[${items.map(quoteScalar).join(", ")}]`;
-}
-function truncateDecorator(d, max = 80) {
-  const cleaned = d.replace(/\r?\n/g, " ");
-  return cleaned.length <= max ? cleaned : cleaned.slice(0, max) + "...";
-}
-function renderClass(c) {
-  const lines = [];
-  lines.push(`    - name: ${c.name}`);
-  lines.push(`      lines: ${c.lines[0]}-${c.lines[1]}`);
-  if (c.methods.length > 0) {
-    lines.push("      methods:");
-    for (const m of c.methods) {
-      const asyncPrefix = m.async ? "async " : "";
-      lines.push(`        - { name: ${asyncPrefix}${m.name}, lines: ${m.lines[0]}-${m.lines[1]} }`);
-    }
+// src/commands/migrate.ts
+var migrate_exports = {};
+__export(migrate_exports, {
+  migrate: () => migrate
+});
+import { join as join16 } from "path";
+import { cpSync as cpSync2, existsSync as existsSync14, mkdirSync as mkdirSync6, readdirSync as readdirSync8, readFileSync as readFileSync11, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
+import yaml3 from "js-yaml";
+function backupChangeDir(cwd, changeId, sessionStamp) {
+  const backupRoot = join16(cwd, ".cdd", "migrate-backup", sessionStamp);
+  const backupDir2 = join16(backupRoot, changeId);
+  mkdirSync6(backupRoot, { recursive: true });
+  const sourceDir = join16(cwd, "specs", "changes", changeId);
+  if (existsSync14(sourceDir)) {
+    cpSync2(sourceDir, backupDir2, { recursive: true });
   }
-  return lines;
+  return backupDir2;
 }
-function renderFunction(f) {
-  const asyncPrefix = f.async ? "async " : "";
-  let comment = "";
-  if (f.decorators.length > 0) {
-    const truncated = truncateDecorator(f.decorators[0]);
-    comment = `  # @${truncated}`;
-  }
-  return `    - { name: ${asyncPrefix}${f.name}, lines: ${f.lines[0]}-${f.lines[1]} }${comment}`;
+function buildLegacyContextManifest(changeId) {
+  return [
+    "# Context Manifest",
+    "",
+    "Generated by `cdd-kit migrate` for an existing change.",
+    "Legacy manifest. Forbidden paths come from `.cdd/context-policy.json`.",
+    "",
+    "## Affected Surfaces",
+    "- legacy-unknown",
+    "",
+    "## Allowed Paths",
+    `- specs/changes/${changeId}/`,
+    "",
+    "## Required Contracts",
+    "- legacy-unknown",
+    "",
+    "## Required Tests",
+    "- legacy-unknown",
+    "",
+    "## Agent Work Packets",
+    "",
+    "## Context Expansion Requests",
+    "-",
+    "",
+    "## Approved Expansions",
+    "-",
+    ""
+  ].join("\n");
 }
-function renderTypeDef(t) {
-  const exportedSuffix = t.exported ? "" : "  # local";
-  return `    - { name: ${t.name}, lines: ${t.lines[0]}-${t.lines[1]} }${exportedSuffix}`;
+function buildContextGovernedManifest(changeId) {
+  return [
+    "# Context Manifest",
+    "",
+    "Generated by `cdd-kit migrate --enable-context-governance` for an existing change.",
+    "Review and narrow the allowed paths before assigning implementation work.",
+    "Forbidden paths come from `.cdd/context-policy.json`.",
+    "",
+    "## Affected Surfaces",
+    "- legacy-unknown",
+    "",
+    "## Allowed Paths",
+    `- specs/changes/${changeId}/`,
+    "- specs/context/project-map.md",
+    "- specs/context/contracts-index.md",
+    "",
+    "## Required Contracts",
+    "- legacy-unknown",
+    "",
+    "## Required Tests",
+    "- legacy-unknown",
+    "",
+    "## Agent Work Packets",
+    "",
+    "### change-classifier",
+    "- allowed:",
+    `  - specs/changes/${changeId}/`,
+    "  - specs/context/project-map.md",
+    "  - specs/context/contracts-index.md",
+    "",
+    "## Context Expansion Requests",
+    "",
+    "<!--",
+    "Agents must request context expansion instead of reading outside their work packet.",
+    "Use this format only for real requests:",
+    "",
+    "- request-id: CER-001",
+    "  requested_paths:",
+    "    - src/example.ts",
+    "  reason: why this file is required",
+    "  status: pending",
+    "-->",
+    "",
+    "## Approved Expansions",
+    "-",
+    ""
+  ].join("\n");
 }
-function renderEnum(e) {
-  const lines = [];
-  const exportedSuffix = e.exported ? "" : "  # local";
-  lines.push(`    - name: ${e.name}`);
-  lines.push(`      lines: ${e.lines[0]}-${e.lines[1]}${exportedSuffix}`);
-  if (e.members.length > 0) {
-    lines.push(`      members: [${e.members.join(", ")}]`);
+function parseLegacyFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m)
+    return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const colon = line.indexOf(":");
+    if (colon === -1)
+      continue;
+    const key = line.slice(0, colon).trim();
+    if (!key)
+      continue;
+    out[key] = line.slice(colon + 1).trim();
   }
-  return lines;
+  return out;
 }
-function renderYaml(entries, opts) {
-  const now = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
-  const totalSrc = entries.reduce((s, e) => s + e.total_lines, 0);
-  const bodyLines = [];
-  for (let i = 0; i < entries.length; i++) {
-    const e = entries[i];
-    if (i > 0)
-      bodyLines.push("");
-    const pathKey = quotePath(e.path);
-    bodyLines.push(`${pathKey}:  # ${e.total_lines} lines`);
-    if (e.imports.length > 0) {
-      bodyLines.push("  imports:");
-      for (const imp of e.imports) {
-        const mod = quoteScalar(imp.module);
-        bodyLines.push(`    - { module: ${mod}, items: ${renderItems(imp.items)}, line: ${imp.line} }`);
-      }
-    }
-    if (e.constants.length > 0) {
-      bodyLines.push("  constants:");
-      for (const c of e.constants) {
-        bodyLines.push(`    - { name: ${c.name}, line: ${c.line} }`);
-      }
-    }
-    if (e.classes.length > 0) {
-      bodyLines.push("  classes:");
-      for (const c of e.classes) {
-        bodyLines.push(...renderClass(c));
-      }
-    }
-    if (e.functions.length > 0) {
-      bodyLines.push("  functions:");
-      for (const f of e.functions) {
-        bodyLines.push(renderFunction(f));
-      }
-    }
-    if (e.interfaces && e.interfaces.length > 0) {
-      bodyLines.push("  interfaces:");
-      for (const t of e.interfaces) {
-        bodyLines.push(renderTypeDef(t));
-      }
-    }
-    if (e.types && e.types.length > 0) {
-      bodyLines.push("  types:");
-      for (const t of e.types) {
-        bodyLines.push(renderTypeDef(t));
-      }
-    }
-    if (e.enums && e.enums.length > 0) {
-      bodyLines.push("  enums:");
-      for (const en of e.enums) {
-        bodyLines.push(...renderEnum(en));
-      }
-    }
-  }
-  const mapLines = bodyLines.length + 2;
-  const compression = totalSrc === 0 ? 0 : totalSrc / mapLines;
-  const fileCount = entries.length;
-  const header = [
-    `# generated: ${now} by ${opts.generator}`,
-    `# files: ${fileCount}, src-lines: ${totalSrc}, map-lines: ${mapLines}, compression: ${compression.toFixed(1)}x`
-  ];
-  return [...header, ...bodyLines].join("\n") + "\n";
+function parseListField(raw) {
+  if (!raw)
+    return [];
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed === "[]")
+    return [];
+  const inner = trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+  return inner.split(",").map((item) => item.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
 }
-var YAML_RESERVED;
-var init_yaml_writer = __esm({
-  "src/code-map/yaml-writer.ts"() {
-    "use strict";
-    YAML_RESERVED = /[:[\]{},&*!|>'"%@`#]/;
-  }
-});
-
-// src/code-map/orchestrator.ts
-async function scanInProcess(scanner, absolutePaths, repoRoot) {
-  const entries = [];
-  const warnings = [];
-  for (const absPath of absolutePaths) {
-    try {
-      const entry = await scanner.scan(absPath, repoRoot);
-      if (entry === null) {
-        const rel = absPath.replace(/\\/g, "/").replace(repoRoot.replace(/\\/g, "/") + "/", "");
-        warnings.push({ path: rel, message: "parse error (scanner returned null)" });
-      } else {
-        entries.push(entry);
-      }
-    } catch (err) {
-      const rel = absPath.replace(/\\/g, "/").replace(repoRoot.replace(/\\/g, "/") + "/", "");
-      warnings.push({ path: rel, message: `IO error: ${err.message}` });
+function parseLegacyTaskList(body) {
+  const lines = body.split(/\r?\n/);
+  const rows = [];
+  let currentSection;
+  for (const raw of lines) {
+    const headerMatch = raw.match(/^##\s+\d+\.\s+(.*)\s*$/);
+    if (headerMatch) {
+      currentSection = headerMatch[1].trim();
+      continue;
     }
+    const itemMatch = raw.match(/^\s*-\s*\[([ xX\-])\]\s+(\d+(?:\.\d+)*)\s+(.*)\s*$/);
+    if (!itemMatch)
+      continue;
+    const mark = itemMatch[1];
+    const id = itemMatch[2];
+    const title = itemMatch[3].trim();
+    let status = "pending";
+    if (mark === "x" || mark === "X")
+      status = "done";
+    else if (mark === "-")
+      status = "skipped";
+    rows.push({ id, title, status, section: currentSection });
   }
-  return { entries, warnings };
+  return rows;
 }
-function bucketByExtension(files) {
-  const out = {};
-  for (const f of files) {
-    const dot = f.lastIndexOf(".");
-    const ext = dot >= 0 ? f.slice(dot).toLowerCase() : "";
-    if (!out[ext])
-      out[ext] = [];
-    out[ext].push(f);
+function migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pendingWrites, pendingDeletes) {
+  const newPath = join16(changeDir, "tasks.yml");
+  const legacyPath = join16(changeDir, "tasks.md");
+  if (existsSync14(newPath)) {
+    return;
   }
-  return out;
-}
-var init_orchestrator = __esm({
-  "src/code-map/orchestrator.ts"() {
-    "use strict";
-    init_include_exclude();
+  if (!existsSync14(legacyPath)) {
+    warnings.push("tasks.md not found and tasks.yml missing \u2014 skipping tasks migration");
+    return;
   }
-});
-
-// src/code-map/scanners/common.ts
-import { relative as relative3 } from "path";
-function canonicalRelPath(absolutePath, repoRoot) {
-  const rel = relative3(repoRoot, absolutePath);
-  return rel.replace(/\\/g, "/").normalize("NFC");
-}
-function isAllCapsConst(name) {
-  return name.length >= 2 && /^[A-Z][A-Z0-9_]*$/.test(name);
-}
-function isBinary(content) {
-  const head = content.slice(0, 4096);
-  return head.includes("\0");
-}
-var init_common = __esm({
-  "src/code-map/scanners/common.ts"() {
-    "use strict";
+  const raw = readFileSync11(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;
+  const tasksRows = parseLegacyTaskList(body);
+  const data = {};
+  data["change-id"] = fm["change-id"] || changeId;
+  data["status"] = fm["status"] || "in-progress";
+  if (fm["tier"] && /^\d+$/.test(fm["tier"])) {
+    data["tier"] = parseInt(fm["tier"], 10);
+  } else if (detectedTier) {
+    data["tier"] = parseInt(detectedTier, 10);
+  } else {
+    data["tier"] = null;
   }
-});
-
-// src/code-map/scanners/python.ts
-var python_exports = {};
-__export(python_exports, {
-  pythonScanner: () => pythonScanner
-});
-import { spawnSync as spawnSync2 } from "child_process";
-import { writeFileSync as writeFileSync6, unlinkSync } from "fs";
-import { join as join16 } from "path";
-import { tmpdir } from "os";
-function detectPython2() {
-  for (const candidate of ["python3", "python"]) {
-    try {
-      const result = spawnSync2(candidate, ["--version"], {
-        encoding: "utf8",
-        timeout: 5e3
-      });
-      if (result.status === 0)
-        return candidate;
-    } catch {
-    }
+  if (enableContextGovernance || fm["context-governance"] === "v1") {
+    data["context-governance"] = "v1";
   }
-  return null;
+  const archive2 = parseListField(fm["archive-tasks"]);
+  data["archive-tasks"] = archive2.length > 0 ? archive2 : ["7.1", "7.2"];
+  const deps = parseListField(fm["depends-on"]);
+  data["depends-on"] = deps;
+  data["tasks"] = tasksRows.map((r) => {
+    const out = { id: r.id, title: r.title, status: r.status };
+    if (r.section)
+      out["section"] = r.section;
+    return out;
+  });
+  const yamlOut = yaml3.dump(data, { lineWidth: -1, noRefs: true });
+  pendingWrites.push({ path: newPath, content: yamlOut });
+  pendingDeletes.push({ path: legacyPath });
+  changed.push(`tasks.md -> tasks.yml (${tasksRows.length} task(s) migrated)`);
 }
-var TIMEOUT_MS, PythonScanner, pythonScanner;
-var init_python = __esm({
-  "src/code-map/scanners/python.ts"() {
-    "use strict";
-    init_paths();
-    init_common();
-    TIMEOUT_MS = parseInt(process.env["CDD_CODE_MAP_TIMEOUT_MS"] ?? "30000", 10);
-    PythonScanner = class {
-      extensions = [".py"];
-      _interpreter = void 0;
-      getInterpreter() {
-        if (this._interpreter === void 0) {
-          this._interpreter = detectPython2();
+function parseLegacyAgentLog(content) {
+  const lines = content.split(/\r?\n/);
+  const data = {};
+  let i = 0;
+  const topFieldRe = /^[ ]{0,1}-\s*([\w-]+):\s*(.*)$/;
+  while (i < lines.length) {
+    const line = lines[i];
+    const fieldMatch = line.match(topFieldRe);
+    if (!fieldMatch) {
+      i++;
+      continue;
+    }
+    const key = fieldMatch[1];
+    const inline = fieldMatch[2].trim();
+    if (key === "files-read" || key === "artifacts") {
+      const items = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const sub = lines[j];
+        if (topFieldRe.test(sub))
+          break;
+        if (/^#/.test(sub))
+          break;
+        const itemMatch = sub.match(/^\s{2,}-\s+(.+?)\s*$/);
+        if (itemMatch) {
+          items.push(itemMatch[1].trim());
         }
-        return this._interpreter;
-      }
-      async scan(absolutePath, repoRoot) {
-        const result = await this.scanBatch([absolutePath], repoRoot);
-        return result.entries[0] ?? null;
+        j++;
       }
-      async scanBatch(absolutePaths, repoRoot) {
-        const interpreter = this.getInterpreter();
-        const entries = [];
-        const warnings = [];
-        if (!interpreter) {
-          const count = absolutePaths.length;
-          warnings.push({
-            path: "",
-            message: `python interpreter not found on PATH; skipping ${count} .py file${count === 1 ? "" : "s"}`
-          });
-          return { entries, warnings };
-        }
-        const scriptPath = ASSET.codeMapPython;
-        const rand = Math.random().toString(36).slice(2);
-        const listFile = join16(tmpdir(), `cdd-codemap-${process.pid}-${rand}.txt`);
-        writeFileSync6(listFile, absolutePaths.join("\n") + "\n", "utf8");
-        let stdout = "";
-        let stderr = "";
-        let exitCode = 0;
-        try {
-          const result = spawnSync2(
-            interpreter,
-            [scriptPath, "--batch-file", listFile, "--repo-root", repoRoot],
-            {
-              encoding: "utf8",
-              timeout: TIMEOUT_MS,
-              maxBuffer: 50 * 1024 * 1024
-              // 50MB
-            }
-          );
-          stdout = result.stdout ?? "";
-          stderr = result.stderr ?? "";
-          exitCode = result.status ?? -1;
-          if (result.error) {
-            const errMsg = result.error.message ?? String(result.error);
-            if (errMsg.includes("ENOENT")) {
-              warnings.push({
-                path: "",
-                message: `python interpreter not found (ENOENT); skipping ${absolutePaths.length} .py file(s)`
-              });
-              return { entries, warnings };
-            }
-            if (errMsg.includes("ETIMEDOUT") || errMsg.includes("timeout")) {
-              warnings.push({
-                path: "",
-                message: `python scanner timed out after ${TIMEOUT_MS}ms; skipping .py files`
-              });
-              return { entries, warnings };
-            }
-            warnings.push({
-              path: "",
-              message: `python scanner error: ${errMsg}; skipping .py files`
-            });
-            return { entries, warnings };
-          }
-        } finally {
-          try {
-            unlinkSync(listFile);
-          } catch {
-          }
-        }
-        if (exitCode === 3) {
-          warnings.push({
-            path: "",
-            message: "python interpreter is < 3.9 (need ast.unparse); skipping .py files"
-          });
-          return { entries, warnings };
-        }
-        for (const line of stdout.split("\n")) {
-          const trimmed = line.trim();
-          if (!trimmed)
-            continue;
-          let parsed;
-          try {
-            parsed = JSON.parse(trimmed);
-          } catch {
-            continue;
-          }
-          if (!parsed.ok) {
-            warnings.push({ path: parsed.path, message: parsed.error });
-            continue;
+      if (key === "files-read") {
+        data["files-read"] = items;
+      } else {
+        data["artifacts"] = items.map((s) => {
+          const idx = s.indexOf(":");
+          if (idx === -1) {
+            return { type: "note", pointer: s };
           }
-          const r = parsed;
-          entries.push({
-            path: canonicalRelPath(join16(repoRoot, r.path), repoRoot),
-            total_lines: r.total_lines,
-            imports: r.imports ?? [],
-            constants: r.constants ?? [],
-            classes: (r.classes ?? []).map((c) => ({
-              name: c.name,
-              lines: [c.lines[0], c.lines[1]],
-              methods: (c.methods ?? []).map((m) => ({
-                name: m.name,
-                lines: [m.lines[0], m.lines[1]],
-                async: m.async
-              }))
-            })),
-            functions: (r.functions ?? []).map((f) => ({
-              name: f.name,
-              lines: [f.lines[0], f.lines[1]],
-              decorators: f.decorators ?? [],
-              async: f.async
-            }))
-          });
-        }
-        if (exitCode === 2) {
-          warnings.push({
-            path: "",
-            message: `python scanner exited with code 2 (fatal); partial results only. stderr: ${stderr.slice(0, 200)}`
-          });
-        }
-        return { entries, warnings };
+          const type = s.slice(0, idx).trim();
+          const pointer = s.slice(idx + 1).trim();
+          return { type, pointer };
+        });
       }
-    };
-    pythonScanner = new PythonScanner();
-  }
-});
-
-// src/code-map/scanners/javascript.ts
-var javascript_exports = {};
-__export(javascript_exports, {
-  COMMON_PLUGINS: () => COMMON_PLUGINS,
-  countSourceLines: () => countSourceLines,
-  jsScanner: () => jsScanner,
-  parseAndExtract: () => parseAndExtract,
-  parseJsSource: () => parseJsSource,
-  parseSourceWithPlugins: () => parseSourceWithPlugins
-});
-import { readFileSync as readFileSync12 } from "fs";
-import { parse } from "@babel/parser";
-function parseSourceWithPlugins(source, plugins) {
-  return parse(source, {
-    sourceType: "unambiguous",
-    allowReturnOutsideFunction: true,
-    allowAwaitOutsideFunction: true,
-    errorRecovery: true,
-    plugins
-  });
-}
-function isCallExpression(node, callee) {
-  if (!node || node.type !== "CallExpression")
-    return false;
-  const c = node.callee;
-  return c.type === "Identifier" && c.name === callee;
-}
-function extractRequireModule(node) {
-  if (!node || node.type !== "CallExpression")
-    return null;
-  const c = node.callee;
-  if (c.type !== "Identifier" || c.name !== "require")
-    return null;
-  const arg = node.arguments[0];
-  if (!arg || arg.type !== "StringLiteral")
-    return null;
-  return arg.value;
-}
-function getLineRange(node) {
-  const start = node.loc?.start.line ?? 1;
-  const end = node.loc?.end.line ?? start;
-  return [start, end];
-}
-function processImportDeclaration(node) {
-  const items = [];
-  for (const spec of node.specifiers) {
-    if (spec.type === "ImportDefaultSpecifier") {
-      items.push(`default:${spec.local.name}`);
-    } else if (spec.type === "ImportNamespaceSpecifier") {
-      items.push(`*:${spec.local.name}`);
-    } else if (spec.type === "ImportSpecifier") {
-      const imported = spec.imported;
-      items.push(imported.type === "Identifier" ? imported.name : spec.local.name);
+      i = j;
+      continue;
     }
+    data[key] = inline;
+    i++;
   }
-  return {
-    module: node.source.value,
-    items,
-    line: node.loc?.start.line ?? 1
-  };
+  return data;
 }
-function processFunctionDeclaration(node, nameOverride) {
-  const name = nameOverride ?? node.id?.name;
-  if (!name)
-    return null;
-  return {
-    name,
-    lines: getLineRange(node),
-    decorators: [],
-    async: node.async
-  };
+function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
+  const agentLogDir = join16(changeDir, "agent-log");
+  if (!existsSync14(agentLogDir))
+    return;
+  const mdLogs = readdirSync8(agentLogDir).filter((f) => f.endsWith(".md"));
+  for (const f of mdLogs) {
+    const fullPath = join16(agentLogDir, f);
+    const yamlName = f.replace(/\.md$/, ".yml");
+    const yamlFull = join16(agentLogDir, yamlName);
+    if (existsSync14(yamlFull))
+      continue;
+    const raw = readFileSync11(fullPath, "utf8");
+    const parsed = parseLegacyAgentLog(raw);
+    const yamlOut = yaml3.dump(parsed, { lineWidth: -1, noRefs: true });
+    pendingWrites.push({ path: yamlFull, content: yamlOut });
+    pendingDeletes.push({ path: fullPath });
+    changed.push(`agent-log/${f} -> agent-log/${yamlName}`);
+  }
 }
-function processClassDeclaration(node, nameOverride) {
-  const name = nameOverride ?? node.id?.name;
-  if (!name)
-    return null;
-  const methods = [];
-  for (const member of node.body.body) {
-    if (member.type === "ClassMethod" || member.type === "ClassPrivateMethod") {
-      const m = member;
-      let methodName;
-      if (m.key.type === "Identifier") {
-        methodName = m.key.name;
-      } else if (m.key.type === "PrivateName") {
-        methodName = `#${m.key.id.name}`;
+function migrateOne(changeId, changeDir, enableContextGovernance) {
+  const changed = [];
+  const warnings = [];
+  const pending = [];
+  const deletes = [];
+  let detectedTier = null;
+  const classifPath = join16(changeDir, "change-classification.md");
+  if (existsSync14(classifPath)) {
+    const content = readFileSync11(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)
+      detectedTier = oldMatch[1];
+    if (!hasNewTierFormat) {
+      if (detectedTier) {
+        const addition = `
+## Tier
+- ${detectedTier}
+`;
+        if (!content.includes("\n## Tier\n")) {
+          changed.push(
+            `change-classification.md: appended "## Tier\\n- ${detectedTier}" (converted from old format)`
+          );
+          pending.push({ path: classifPath, content: content + addition });
+        }
       } else {
-        methodName = "<computed>";
+        warnings.push(
+          "change-classification.md: could not detect tier (no **Tier:** N or ## Tier N found). Set `tier: <0-5>` in tasks.yml frontmatter to enable tier-based gate checks."
+        );
       }
-      methods.push({
-        name: methodName,
-        lines: getLineRange(m),
-        async: m.async
-      });
+    } else {
+      const structured = content.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
+      if (structured)
+        detectedTier = structured[1];
     }
   }
-  return {
-    name,
-    lines: getLineRange(node),
-    methods
-  };
+  migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pending, deletes);
+  migrateAgentLogs(changeDir, changed, pending, deletes);
+  const manifestPath = join16(changeDir, "context-manifest.md");
+  if (!existsSync14(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,
+      content: enableContextGovernance ? buildContextGovernedManifest(changeId) : buildLegacyContextManifest(changeId)
+    });
+  } else if (enableContextGovernance) {
+    warnings.push("context-manifest.md already exists \u2014 review allowed paths before relying on context-governance: v1");
+  }
+  return { result: { changed, warnings }, pending, deletes };
 }
-function processVariableDeclaration(node, imports, constants, functions) {
-  for (const decl of node.declarations) {
-    if (!decl.id || decl.id.type !== "Identifier")
-      continue;
-    const varName = decl.id.name;
-    const init2 = decl.init;
-    if (init2 && isCallExpression(init2, "require")) {
-      const mod = extractRequireModule(init2);
-      if (mod) {
-        imports.push({ module: mod, items: [`default:${varName}`], line: node.loc?.start.line ?? 1 });
+function commitWritesAtomically(pending, deletes) {
+  const renames = [];
+  try {
+    for (const write of pending) {
+      const tmp = `${write.path}.cdd-migrate.tmp`;
+      writeFileSync6(tmp, write.content, "utf8");
+      renames.push({ tmp, final: write.path });
+    }
+  } catch (err) {
+    for (const r of renames) {
+      try {
+        rmSync2(r.tmp, { force: true });
+      } catch {
       }
+    }
+    throw err;
+  }
+  for (const r of renames) {
+    renameSync(r.tmp, r.final);
+  }
+  for (const d of deletes) {
+    try {
+      rmSync2(d.path, { force: true });
+    } catch {
+    }
+  }
+}
+async function migrate(changeId, opts = {}) {
+  const cwd = process.cwd();
+  const dryRun = opts.dryRun ?? false;
+  const enableContextGovernance = opts.enableContextGovernance ?? false;
+  const noBackup = opts.noBackup ?? false;
+  const idsToMigrate = [];
+  if (opts.all) {
+    const changesDir = join16(cwd, "specs", "changes");
+    if (!existsSync14(changesDir)) {
+      log.info("No specs/changes/ directory found \u2014 nothing to migrate.");
+      return;
+    }
+    idsToMigrate.push(
+      ...readdirSync8(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+    );
+  } else if (changeId) {
+    const specificDir = join16(cwd, "specs", "changes", changeId);
+    if (!existsSync14(specificDir)) {
+      log.error(`Change not found: specs/changes/${changeId}`);
+      process.exit(1);
+    }
+    idsToMigrate.push(changeId);
+  } else {
+    log.error("Usage: cdd-kit migrate <change-id>  |  cdd-kit migrate --all  [--dry-run] [--no-backup]");
+    process.exit(1);
+  }
+  if (idsToMigrate.length === 0) {
+    log.info("No changes found to migrate.");
+    return;
+  }
+  if (dryRun) {
+    log.info("Dry run \u2014 no files will be written.");
+    log.blank();
+  }
+  const sessionStamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  let migratedCount = 0;
+  let upToDateCount = 0;
+  const backupRoot = join16(cwd, ".cdd", "migrate-backup", sessionStamp);
+  for (const id of idsToMigrate) {
+    const changeDir = join16(cwd, "specs", "changes", id);
+    if (!existsSync14(changeDir)) {
+      log.warn(`  ${id}: directory not found \u2014 skipping`);
       continue;
     }
-    if (isAllCapsConst(varName) && init2 !== null && init2 !== void 0) {
-      constants.push({ name: varName, line: node.loc?.start.line ?? 1 });
+    const { result, pending, deletes } = migrateOne(id, changeDir, enableContextGovernance);
+    const { changed, warnings } = result;
+    if (changed.length === 0) {
+      log.info(`  ${id}: already up to date`);
+      upToDateCount++;
+      for (const w of warnings)
+        log.warn(`  ${id}: ${w}`);
       continue;
     }
-    if (init2 && (init2.type === "ArrowFunctionExpression" || init2.type === "FunctionExpression")) {
-      functions.push({
-        name: varName,
-        lines: getLineRange(node),
-        decorators: [],
-        async: init2.async
-      });
-    } else if (init2 && init2.type === "CallExpression" && /^[A-Z]/.test(varName)) {
-      functions.push({
-        name: varName,
-        lines: getLineRange(node),
-        decorators: [],
-        async: false
-      });
+    if (!dryRun) {
+      try {
+        if (!noBackup)
+          backupChangeDir(cwd, id, sessionStamp);
+        commitWritesAtomically(pending, deletes);
+      } catch (err) {
+        log.error(`  ${id}: migration failed \u2014 ${err.message}`);
+        if (!noBackup) {
+          log.error(`  ${id}: restore from .cdd/migrate-backup/${sessionStamp}/${id}/`);
+        }
+        process.exit(1);
+      }
+    }
+    log.ok(`  ${id}: migrated`);
+    for (const c of changed)
+      log.info(`    + ${c}`);
+    migratedCount++;
+    for (const w of warnings)
+      log.warn(`  ${id}: ${w}`);
+  }
+  log.blank();
+  if (dryRun) {
+    log.info(`Dry run complete: ${migratedCount} change(s) would be updated, ${upToDateCount} already up to date.`);
+  } else {
+    log.ok(`Migration complete: ${migratedCount} updated, ${upToDateCount} already up to date.`);
+    if (migratedCount > 0 && !noBackup) {
+      log.info(`Backup: ${backupRoot}`);
+      if (ensureGitignoreEntry(cwd, ".cdd/migrate-backup/")) {
+        log.info("Added `.cdd/migrate-backup/` to .gitignore");
+      }
+      log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to YAML format"');
+      log.info("When stable, remove backup: rm -rf .cdd/migrate-backup/");
     }
   }
 }
-function processTsInterfaceDeclaration(node, exported) {
-  if (!node || node.type !== "TSInterfaceDeclaration")
-    return null;
-  if (!node.id || node.id.type !== "Identifier")
-    return null;
-  return {
-    name: node.id.name,
-    lines: getLineRange(node),
-    exported
-  };
-}
-function processTsTypeAliasDeclaration(node, exported) {
-  if (!node || node.type !== "TSTypeAliasDeclaration")
-    return null;
-  if (!node.id || node.id.type !== "Identifier")
-    return null;
-  return {
-    name: node.id.name,
-    lines: getLineRange(node),
-    exported
-  };
+function ensureGitignoreEntry(cwd, entry) {
+  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 (existsSync14(path))
+    existing = readFileSync11(path, "utf8");
+  if (re.test(existing))
+    return false;
+  const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const block = existing.length === 0 ? `# cdd-kit generated backups (do not commit)
+${trimmed}
+` : `${sep}
+# cdd-kit generated backups (do not commit)
+${trimmed}
+`;
+  writeFileSync6(path, existing + block, "utf8");
+  return true;
 }
-function processTsEnumDeclaration(node, exported) {
-  if (!node || node.type !== "TSEnumDeclaration")
-    return null;
-  if (!node.id || node.id.type !== "Identifier")
-    return null;
-  const members = [];
-  for (const m of node.members ?? []) {
-    if (!m || !m.id)
+var init_migrate = __esm({
+  "src/commands/migrate.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
+// src/commands/upgrade.ts
+var upgrade_exports = {};
+__export(upgrade_exports, {
+  upgrade: () => upgrade
+});
+import { existsSync as existsSync15, mkdirSync as mkdirSync7, readdirSync as readdirSync9, copyFileSync as copyFileSync3, readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname4, join as join17, relative as relative3 } from "path";
+function planMissingFiles(srcDir, destDir, label, planned) {
+  if (!existsSync15(srcDir))
+    return;
+  for (const entry of readdirSync9(srcDir, { withFileTypes: true })) {
+    const src = join17(srcDir, entry.name);
+    const dest = join17(destDir, entry.name);
+    if (entry.isDirectory()) {
+      planMissingFiles(src, dest, join17(label, entry.name), planned);
       continue;
-    if (m.id.type === "Identifier")
-      members.push(m.id.name);
-    else if (m.id.type === "StringLiteral")
-      members.push(m.id.value);
+    }
+    if (!existsSync15(dest)) {
+      planned.push({ src, dest, rel: join17(label, relative3(srcDir, src)) });
+    }
   }
-  return {
-    name: node.id.name,
-    lines: getLineRange(node),
-    exported,
-    members
-  };
 }
-function processStatement(stmt, buckets, extractTsTypes, exportedFromWrapper = false) {
-  if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) {
-    processStatement(stmt.declaration, buckets, extractTsTypes, true);
-    return;
+function planProviderGuidance(cwd, provider, planned) {
+  if (provider === "claude" || provider === "both") {
+    if (!existsSync15(join17(cwd, "CLAUDE.md"))) {
+      planned.push({ src: ASSET.claudeTemplate, dest: join17(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
+    }
+    if (!existsSync15(join17(cwd, "AGENTS.md"))) {
+      planned.push({ src: ASSET.agentsTemplate, dest: join17(cwd, "AGENTS.md"), rel: "AGENTS.md" });
+    }
   }
-  if (stmt.type === "ExportDefaultDeclaration") {
-    const decl = stmt.declaration;
-    if (decl.type === "FunctionDeclaration") {
-      const fe = processFunctionDeclaration(decl, decl.id?.name ?? "default");
-      if (fe)
-        buckets.functions.push(fe);
-    } else if (decl.type === "ClassDeclaration") {
-      const ce = processClassDeclaration(decl, decl.id?.name ?? "default");
-      if (ce)
-        buckets.classes.push(ce);
+  if ((provider === "codex" || provider === "both") && !existsSync15(join17(cwd, "CODEX.md"))) {
+    planned.push({ src: ASSET.codexTemplate, dest: join17(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);
+  }
+}
+async function upgrade(opts = {}) {
+  const cwd = process.cwd();
+  const requestedProvider = opts.provider ?? "auto";
+  if (!validateProviderOption(requestedProvider)) {
+    log.error(`Invalid provider: ${requestedProvider}. Use auto, claude, codex, or both.`);
+    process.exit(1);
+  }
+  const provider = inferProvider(cwd, requestedProvider);
+  const plan = [];
+  planMissingFiles(ASSET.contracts, join17(cwd, "contracts"), "contracts", plan);
+  planMissingFiles(ASSET.specsTemplates, join17(cwd, "specs", "templates"), "specs/templates", plan);
+  planMissingFiles(ASSET.testsTemplates, join17(cwd, "tests", "templates"), "tests/templates", plan);
+  planMissingFiles(ASSET.ci, join17(cwd, "ci"), "ci", plan);
+  planMissingFiles(ASSET.githubWorkflows, join17(cwd, ".github", "workflows"), ".github/workflows", plan);
+  planMissingFiles(ASSET.cddConfig, join17(cwd, ".cdd"), ".cdd", plan);
+  planProviderGuidance(cwd, provider, plan);
+  log.blank();
+  log.info(`Upgrade provider: ${provider}`);
+  if (plan.length === 0) {
+    log.ok("No missing cdd-kit project files found.");
+    if (opts.migrateChanges) {
+      log.blank();
+      log.info("Running change migration flow...");
+      await migrate(void 0, {
+        all: true,
+        dryRun: !opts.yes,
+        enableContextGovernance: opts.enableContextGovernance
+      });
     }
+    log.blank();
     return;
   }
-  if (stmt.type === "ImportDeclaration") {
-    buckets.imports.push(processImportDeclaration(stmt));
+  log.info(`${plan.length} missing file(s) detected:`);
+  for (const item of plan)
+    log.dim(`  + ${item.rel.replace(/\\/g, "/")}`);
+  if (!opts.yes) {
+    log.blank();
+    log.info("Dry run only. Re-run with --yes to write missing files.");
+    if (opts.migrateChanges) {
+      log.blank();
+      log.info("Previewing existing change migration because --migrate-changes was requested.");
+      await migrate(void 0, {
+        all: true,
+        dryRun: true,
+        enableContextGovernance: opts.enableContextGovernance
+      });
+    }
+    log.blank();
     return;
   }
-  if (stmt.type === "FunctionDeclaration") {
-    const fe = processFunctionDeclaration(stmt);
-    if (fe)
-      buckets.functions.push(fe);
-    return;
+  applyCopy(plan);
+  const modelPolicyPath = join17(cwd, ".cdd", "model-policy.json");
+  if (existsSync15(modelPolicyPath)) {
+    let existing = {};
+    try {
+      existing = JSON.parse(readFileSync12(modelPolicyPath, "utf8"));
+    } catch {
+    }
+    const merged = {
+      ...existing,
+      provider,
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      roles: existing.roles && typeof existing.roles === "object" ? existing.roles : {}
+    };
+    writeFileSync7(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
   }
-  if (stmt.type === "ClassDeclaration") {
-    const ce = processClassDeclaration(stmt);
-    if (ce)
-      buckets.classes.push(ce);
-    return;
+  log.blank();
+  log.ok(`Upgrade complete: ${plan.length} missing file(s) added.`);
+  log.info("Existing project guidance and contracts were preserved.");
+  if (opts.migrateChanges) {
+    log.blank();
+    log.info("Running change migration flow...");
+    await migrate(void 0, {
+      all: true,
+      dryRun: false,
+      enableContextGovernance: opts.enableContextGovernance
+    });
   }
-  if (stmt.type === "VariableDeclaration") {
-    processVariableDeclaration(stmt, buckets.imports, buckets.constants, buckets.functions);
-    return;
+  log.blank();
+}
+var init_upgrade = __esm({
+  "src/commands/upgrade.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    init_provider();
+    init_migrate();
   }
-  if (extractTsTypes) {
-    const anyStmt = stmt;
-    if (anyStmt.type === "TSInterfaceDeclaration") {
-      const e = processTsInterfaceDeclaration(anyStmt, exportedFromWrapper);
-      if (e)
-        buckets.interfaces.push(e);
-      return;
+});
+
+// src/code-map/yaml-writer.ts
+function quoteScalar(s) {
+  if (s.startsWith(".") || YAML_RESERVED.test(s) || s.includes(" ") || s === "" || s === "null" || s === "true" || s === "false") {
+    return `'${s.replace(/'/g, "''")}'`;
+  }
+  return s;
+}
+function quotePath(p) {
+  if (YAML_RESERVED.test(p) || p.includes(" ")) {
+    return `'${p.replace(/'/g, "''")}'`;
+  }
+  return p;
+}
+function renderItems(items) {
+  if (items.length === 0)
+    return "[]";
+  return `[${items.map(quoteScalar).join(", ")}]`;
+}
+function truncateDecorator(d, max = 80) {
+  const cleaned = d.replace(/\r?\n/g, " ");
+  return cleaned.length <= max ? cleaned : cleaned.slice(0, max) + "...";
+}
+function renderClass(c) {
+  const lines = [];
+  lines.push(`    - name: ${c.name}`);
+  lines.push(`      lines: ${c.lines[0]}-${c.lines[1]}`);
+  if (c.methods.length > 0) {
+    lines.push("      methods:");
+    for (const m of c.methods) {
+      const asyncPrefix = m.async ? "async " : "";
+      lines.push(`        - { name: ${asyncPrefix}${m.name}, lines: ${m.lines[0]}-${m.lines[1]} }`);
     }
-    if (anyStmt.type === "TSTypeAliasDeclaration") {
-      const e = processTsTypeAliasDeclaration(anyStmt, exportedFromWrapper);
-      if (e)
-        buckets.types.push(e);
-      return;
+  }
+  return lines;
+}
+function renderFunction(f) {
+  const asyncPrefix = f.async ? "async " : "";
+  let comment = "";
+  if (f.decorators.length > 0) {
+    const truncated = truncateDecorator(f.decorators[0]);
+    comment = `  # @${truncated}`;
+  }
+  return `    - { name: ${asyncPrefix}${f.name}, lines: ${f.lines[0]}-${f.lines[1]} }${comment}`;
+}
+function renderTypeDef(t) {
+  const exportedSuffix = t.exported ? "" : "  # local";
+  return `    - { name: ${t.name}, lines: ${t.lines[0]}-${t.lines[1]} }${exportedSuffix}`;
+}
+function renderEnum(e) {
+  const lines = [];
+  const exportedSuffix = e.exported ? "" : "  # local";
+  lines.push(`    - name: ${e.name}`);
+  lines.push(`      lines: ${e.lines[0]}-${e.lines[1]}${exportedSuffix}`);
+  if (e.members.length > 0) {
+    lines.push(`      members: [${e.members.join(", ")}]`);
+  }
+  return lines;
+}
+function renderYaml(entries, opts) {
+  const now = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  const totalSrc = entries.reduce((s, e) => s + e.total_lines, 0);
+  const bodyLines = [];
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (i > 0)
+      bodyLines.push("");
+    const pathKey = quotePath(e.path);
+    bodyLines.push(`${pathKey}:  # ${e.total_lines} lines`);
+    if (e.imports.length > 0) {
+      bodyLines.push("  imports:");
+      for (const imp of e.imports) {
+        const mod = quoteScalar(imp.module);
+        bodyLines.push(`    - { module: ${mod}, items: ${renderItems(imp.items)}, line: ${imp.line} }`);
+      }
     }
-    if (anyStmt.type === "TSEnumDeclaration") {
-      const e = processTsEnumDeclaration(anyStmt, exportedFromWrapper);
-      if (e)
-        buckets.enums.push(e);
-      return;
+    if (e.constants.length > 0) {
+      bodyLines.push("  constants:");
+      for (const c of e.constants) {
+        bodyLines.push(`    - { name: ${c.name}, line: ${c.line} }`);
+      }
+    }
+    if (e.classes.length > 0) {
+      bodyLines.push("  classes:");
+      for (const c of e.classes) {
+        bodyLines.push(...renderClass(c));
+      }
+    }
+    if (e.functions.length > 0) {
+      bodyLines.push("  functions:");
+      for (const f of e.functions) {
+        bodyLines.push(renderFunction(f));
+      }
+    }
+    if (e.interfaces && e.interfaces.length > 0) {
+      bodyLines.push("  interfaces:");
+      for (const t of e.interfaces) {
+        bodyLines.push(renderTypeDef(t));
+      }
+    }
+    if (e.types && e.types.length > 0) {
+      bodyLines.push("  types:");
+      for (const t of e.types) {
+        bodyLines.push(renderTypeDef(t));
+      }
+    }
+    if (e.enums && e.enums.length > 0) {
+      bodyLines.push("  enums:");
+      for (const en of e.enums) {
+        bodyLines.push(...renderEnum(en));
+      }
     }
   }
-  if (stmt.type === "ExpressionStatement") {
-    const expr = stmt.expression;
-    if (isCallExpression(expr, "require")) {
-      const mod = extractRequireModule(expr);
-      if (mod) {
-        buckets.imports.push({ module: mod, items: [], line: stmt.loc?.start.line ?? 1 });
+  const mapLines = bodyLines.length + 2;
+  const compression = totalSrc === 0 ? 0 : totalSrc / mapLines;
+  const fileCount = entries.length;
+  const header = [
+    `# generated: ${now} by ${opts.generator}`,
+    `# files: ${fileCount}, src-lines: ${totalSrc}, map-lines: ${mapLines}, compression: ${compression.toFixed(1)}x`
+  ];
+  return [...header, ...bodyLines].join("\n") + "\n";
+}
+var YAML_RESERVED;
+var init_yaml_writer = __esm({
+  "src/code-map/yaml-writer.ts"() {
+    "use strict";
+    YAML_RESERVED = /[:[\]{},&*!|>'"%@`#]/;
+  }
+});
+
+// src/code-map/orchestrator.ts
+async function scanInProcess(scanner, absolutePaths, repoRoot) {
+  const entries = [];
+  const warnings = [];
+  for (const absPath of absolutePaths) {
+    try {
+      const entry = await scanner.scan(absPath, repoRoot);
+      if (entry === null) {
+        const rel = absPath.replace(/\\/g, "/").replace(repoRoot.replace(/\\/g, "/") + "/", "");
+        warnings.push({ path: rel, message: "parse error (scanner returned null)" });
+      } else {
+        entries.push(entry);
       }
+    } catch (err) {
+      const rel = absPath.replace(/\\/g, "/").replace(repoRoot.replace(/\\/g, "/") + "/", "");
+      warnings.push({ path: rel, message: `IO error: ${err.message}` });
     }
   }
+  return { entries, warnings };
 }
-function parseAndExtract(source, opts) {
-  let ast;
-  try {
-    ast = parseSourceWithPlugins(source, opts.plugins);
-  } catch {
-    return null;
+function bucketByExtension(files) {
+  const out = {};
+  for (const f of files) {
+    const dot = f.lastIndexOf(".");
+    const ext = dot >= 0 ? f.slice(dot).toLowerCase() : "";
+    if (!out[ext])
+      out[ext] = [];
+    out[ext].push(f);
   }
-  const buckets = {
-    imports: [],
-    constants: [],
-    functions: [],
-    classes: [],
-    interfaces: [],
-    types: [],
-    enums: []
-  };
-  for (const stmt of ast.program.body) {
-    processStatement(stmt, buckets, !!opts.extractTsTypes);
+  return out;
+}
+var init_orchestrator = __esm({
+  "src/code-map/orchestrator.ts"() {
+    "use strict";
+    init_include_exclude();
   }
-  return buckets;
+});
+
+// src/code-map/scanners/common.ts
+import { relative as relative4 } from "path";
+function canonicalRelPath(absolutePath, repoRoot) {
+  const rel = relative4(repoRoot, absolutePath);
+  return rel.replace(/\\/g, "/").normalize("NFC");
 }
-function countSourceLines(source) {
-  if (source === "")
-    return 0;
-  return source.split(/\r?\n/).length - (source.endsWith("\n") || source.endsWith("\r\n") ? 1 : 0);
+function isAllCapsConst(name) {
+  return name.length >= 2 && /^[A-Z][A-Z0-9_]*$/.test(name);
 }
-function parseJsSource(source, relPath) {
-  const total_lines = countSourceLines(source);
-  const r = parseAndExtract(source, { plugins: JS_PLUGINS, extractTsTypes: false });
-  if (!r)
-    return null;
-  return {
-    path: relPath,
-    total_lines,
-    imports: r.imports,
-    constants: r.constants,
-    classes: r.classes,
-    functions: r.functions
-  };
+function isBinary(content) {
+  const head = content.slice(0, 4096);
+  return head.includes("\0");
 }
-var COMMON_PLUGINS, JS_PLUGINS, JavaScriptScanner, jsScanner;
-var init_javascript = __esm({
-  "src/code-map/scanners/javascript.ts"() {
+var init_common = __esm({
+  "src/code-map/scanners/common.ts"() {
     "use strict";
-    init_common();
-    COMMON_PLUGINS = [
-      "classProperties",
-      "classPrivateProperties",
-      "classPrivateMethods",
-      "decorators-legacy",
-      "topLevelAwait",
-      "dynamicImport",
-      "optionalChaining",
-      "nullishCoalescingOperator",
-      "objectRestSpread",
-      "asyncGenerators",
-      "numericSeparator",
-      "logicalAssignment"
-    ];
-    JS_PLUGINS = ["jsx", ...COMMON_PLUGINS];
-    JavaScriptScanner = class {
-      extensions = [".js"];
-      async scan(absolutePath, repoRoot) {
-        let source;
-        try {
-          source = readFileSync12(absolutePath, "utf8");
-        } catch (err) {
-          throw err;
-        }
-        if (isBinary(source)) {
-          return null;
-        }
-        const relPath = canonicalRelPath(absolutePath, repoRoot);
-        return parseJsSource(source, relPath);
-      }
-    };
-    jsScanner = new JavaScriptScanner();
   }
 });
 
-// src/code-map/scanners/typescript.ts
-var typescript_exports = {};
-__export(typescript_exports, {
-  tsScanner: () => tsScanner
+// src/code-map/scanners/python.ts
+var python_exports = {};
+__export(python_exports, {
+  pythonScanner: () => pythonScanner
 });
-import { readFileSync as readFileSync13 } from "fs";
-var TypeScriptScanner, tsScanner;
-var init_typescript = __esm({
-  "src/code-map/scanners/typescript.ts"() {
+import { spawnSync as spawnSync2 } from "child_process";
+import { writeFileSync as writeFileSync8, unlinkSync } from "fs";
+import { join as join18 } from "path";
+import { tmpdir } from "os";
+function detectPython2() {
+  for (const candidate of ["python3", "python"]) {
+    try {
+      const result = spawnSync2(candidate, ["--version"], {
+        encoding: "utf8",
+        timeout: 5e3
+      });
+      if (result.status === 0)
+        return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+var TIMEOUT_MS, PythonScanner, pythonScanner;
+var init_python = __esm({
+  "src/code-map/scanners/python.ts"() {
     "use strict";
+    init_paths();
     init_common();
-    init_javascript();
-    TypeScriptScanner = class {
-      extensions = [".ts", ".tsx"];
-      async scan(absolutePath, repoRoot) {
-        let source;
-        try {
-          source = readFileSync13(absolutePath, "utf8");
-        } catch (err) {
-          throw err;
-        }
-        if (isBinary(source)) {
-          return null;
+    TIMEOUT_MS = parseInt(process.env["CDD_CODE_MAP_TIMEOUT_MS"] ?? "30000", 10);
+    PythonScanner = class {
+      extensions = [".py"];
+      _interpreter = void 0;
+      getInterpreter() {
+        if (this._interpreter === void 0) {
+          this._interpreter = detectPython2();
         }
-        const isTsx = absolutePath.toLowerCase().endsWith(".tsx");
-        const plugins = isTsx ? ["typescript", "jsx", ...COMMON_PLUGINS] : ["typescript", ...COMMON_PLUGINS];
-        const r = parseAndExtract(source, { plugins, extractTsTypes: true });
-        if (!r)
-          return null;
-        const relPath = canonicalRelPath(absolutePath, repoRoot);
-        const total_lines = countSourceLines(source);
-        return {
-          path: relPath,
-          total_lines,
-          imports: r.imports,
-          constants: r.constants,
-          classes: r.classes,
-          functions: r.functions,
-          interfaces: r.interfaces,
-          types: r.types,
-          enums: r.enums
-        };
+        return this._interpreter;
       }
-    };
-    tsScanner = new TypeScriptScanner();
-  }
-});
-
-// src/code-map/scanners/vue.ts
-var vue_exports = {};
-__export(vue_exports, {
-  vueScanner: () => vueScanner
-});
-import { readFileSync as readFileSync14 } from "fs";
-import { parse as parse2 } from "@vue/compiler-sfc";
-var VueScanner, vueScanner;
-var init_vue = __esm({
-  "src/code-map/scanners/vue.ts"() {
-    "use strict";
-    init_common();
-    init_javascript();
-    VueScanner = class {
-      extensions = [".vue"];
       async scan(absolutePath, repoRoot) {
-        let source;
-        try {
-          source = readFileSync14(absolutePath, "utf8");
-        } catch (err) {
-          throw err;
-        }
-        if (isBinary(source)) {
-          return null;
-        }
-        const relPath = canonicalRelPath(absolutePath, repoRoot);
-        const total_lines = source.split(/\r?\n/).length - (source.endsWith("\n") || source.endsWith("\r\n") ? 1 : 0);
-        const { descriptor } = parse2(source, { filename: absolutePath });
-        const allImports = [];
-        const allConstants = [];
-        const allFunctions = [];
-        const allClasses = [];
+        const result = await this.scanBatch([absolutePath], repoRoot);
+        return result.entries[0] ?? null;
+      }
+      async scanBatch(absolutePaths, repoRoot) {
+        const interpreter = this.getInterpreter();
+        const entries = [];
         const warnings = [];
-        const scriptBlocks = [descriptor.script, descriptor.scriptSetup].filter(Boolean);
-        if (scriptBlocks.length === 0) {
-          return {
-            path: relPath,
-            total_lines,
-            imports: [],
-            constants: [],
-            classes: [],
-            functions: []
-          };
+        if (!interpreter) {
+          const count = absolutePaths.length;
+          warnings.push({
+            path: "",
+            message: `python interpreter not found on PATH; skipping ${count} .py file${count === 1 ? "" : "s"}`
+          });
+          return { entries, warnings };
         }
-        for (const block of scriptBlocks) {
-          if (!block)
-            continue;
-          if (block.lang === "ts" || block.lang === "tsx") {
+        const scriptPath = ASSET.codeMapPython;
+        const rand = Math.random().toString(36).slice(2);
+        const listFile = join18(tmpdir(), `cdd-codemap-${process.pid}-${rand}.txt`);
+        writeFileSync8(listFile, absolutePaths.join("\n") + "\n", "utf8");
+        let stdout = "";
+        let stderr = "";
+        let exitCode = 0;
+        try {
+          const result = spawnSync2(
+            interpreter,
+            [scriptPath, "--batch-file", listFile, "--repo-root", repoRoot],
+            {
+              encoding: "utf8",
+              timeout: TIMEOUT_MS,
+              maxBuffer: 50 * 1024 * 1024
+              // 50MB
+            }
+          );
+          stdout = result.stdout ?? "";
+          stderr = result.stderr ?? "";
+          exitCode = result.status ?? -1;
+          if (result.error) {
+            const errMsg = result.error.message ?? String(result.error);
+            if (errMsg.includes("ENOENT")) {
+              warnings.push({
+                path: "",
+                message: `python interpreter not found (ENOENT); skipping ${absolutePaths.length} .py file(s)`
+              });
+              return { entries, warnings };
+            }
+            if (errMsg.includes("ETIMEDOUT") || errMsg.includes("timeout")) {
+              warnings.push({
+                path: "",
+                message: `python scanner timed out after ${TIMEOUT_MS}ms; skipping .py files`
+              });
+              return { entries, warnings };
+            }
             warnings.push({
-              path: relPath,
-              message: `skipping <script lang=${block.lang}> block (TypeScript not supported in v1)`
+              path: "",
+              message: `python scanner error: ${errMsg}; skipping .py files`
             });
-            continue;
-          }
-          const blockContent = block.content;
-          const lineOffset = block.loc.start.line;
-          const scriptEntry = parseJsSource(blockContent, relPath);
-          if (!scriptEntry) {
-            warnings.push({ path: relPath, message: "parse error in script block" });
-            continue;
+            return { entries, warnings };
           }
-          const offset = lineOffset - 1;
-          for (const imp of scriptEntry.imports) {
-            allImports.push({ ...imp, line: imp.line + offset });
+        } finally {
+          try {
+            unlinkSync(listFile);
+          } catch {
           }
-          for (const c of scriptEntry.constants) {
-            allConstants.push({ ...c, line: c.line + offset });
+        }
+        if (exitCode === 3) {
+          warnings.push({
+            path: "",
+            message: "python interpreter is < 3.9 (need ast.unparse); skipping .py files"
+          });
+          return { entries, warnings };
+        }
+        for (const line of stdout.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed)
+            continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(trimmed);
+          } catch {
+            continue;
           }
-          for (const fn of scriptEntry.functions) {
-            allFunctions.push({
-              ...fn,
-              lines: [fn.lines[0] + offset, fn.lines[1] + offset]
-            });
+          if (!parsed.ok) {
+            warnings.push({ path: parsed.path, message: parsed.error });
+            continue;
           }
-          for (const cls of scriptEntry.classes) {
-            allClasses.push({
-              ...cls,
-              lines: [cls.lines[0] + offset, cls.lines[1] + offset],
-              methods: cls.methods.map((m) => ({
-                ...m,
-                lines: [m.lines[0] + offset, m.lines[1] + offset]
+          const r = parsed;
+          entries.push({
+            path: canonicalRelPath(join18(repoRoot, r.path), repoRoot),
+            total_lines: r.total_lines,
+            imports: r.imports ?? [],
+            constants: r.constants ?? [],
+            classes: (r.classes ?? []).map((c) => ({
+              name: c.name,
+              lines: [c.lines[0], c.lines[1]],
+              methods: (c.methods ?? []).map((m) => ({
+                name: m.name,
+                lines: [m.lines[0], m.lines[1]],
+                async: m.async
               }))
-            });
-          }
+            })),
+            functions: (r.functions ?? []).map((f) => ({
+              name: f.name,
+              lines: [f.lines[0], f.lines[1]],
+              decorators: f.decorators ?? [],
+              async: f.async
+            }))
+          });
         }
-        return {
-          path: relPath,
-          total_lines,
-          imports: allImports,
-          constants: allConstants,
-          classes: allClasses,
-          functions: allFunctions
-        };
+        if (exitCode === 2) {
+          warnings.push({
+            path: "",
+            message: `python scanner exited with code 2 (fatal); partial results only. stderr: ${stderr.slice(0, 200)}`
+          });
+        }
+        return { entries, warnings };
       }
     };
-    vueScanner = new VueScanner();
-  }
-});
-
-// src/commands/code-map.ts
-var code_map_exports = {};
-__export(code_map_exports, {
-  codeMap: () => codeMap
-});
-import { existsSync as existsSync14, mkdirSync as mkdirSync6, readFileSync as readFileSync15, writeFileSync as writeFileSync7 } from "fs";
-import { resolve, dirname as dirname4 } from "path";
-import { createRequire } from "module";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join17 } from "path";
-async function codeMap(opts) {
-  const root = resolve(process.cwd(), opts.path);
-  const start = Date.now();
-  let cfg;
-  try {
-    cfg = loadCodeMapConfig(root);
-  } catch (err) {
-    log.error(`code-map: ${err.message}`);
-    return 1;
-  }
-  const include = [...cfg.include, ...opts.include];
-  const exclude = [...cfg.exclude, ...opts.exclude];
-  const files = walkRepo(root, { include, exclude });
-  const buckets = bucketByExtension(files);
-  const result = { entries: [], warnings: [] };
-  const tasks = [];
-  if (buckets[".py"]?.length) {
-    const { pythonScanner: pythonScanner2 } = await Promise.resolve().then(() => (init_python(), python_exports));
-    if (pythonScanner2.scanBatch) {
-      tasks.push(pythonScanner2.scanBatch(buckets[".py"], root));
-    }
-  }
-  const jsFiles = [
-    ...buckets[".js"] ?? [],
-    ...buckets[".jsx"] ?? [],
-    ...buckets[".mjs"] ?? [],
-    ...buckets[".cjs"] ?? []
-  ];
-  if (jsFiles.length) {
-    const { jsScanner: jsScanner2 } = await Promise.resolve().then(() => (init_javascript(), javascript_exports));
-    tasks.push(scanInProcess(jsScanner2, jsFiles, root));
-  }
-  const tsFiles = [
-    ...buckets[".ts"] ?? [],
-    ...buckets[".tsx"] ?? []
-  ];
-  if (tsFiles.length) {
-    const { tsScanner: tsScanner2 } = await Promise.resolve().then(() => (init_typescript(), typescript_exports));
-    tasks.push(scanInProcess(tsScanner2, tsFiles, root));
-  }
-  if (buckets[".vue"]?.length) {
-    const { vueScanner: vueScanner2 } = await Promise.resolve().then(() => (init_vue(), vue_exports));
-    tasks.push(scanInProcess(vueScanner2, buckets[".vue"], root));
-  }
-  for (const r of await Promise.all(tasks)) {
-    result.entries.push(...r.entries);
-    result.warnings.push(...r.warnings);
-  }
-  result.entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
-  for (const e of result.entries) {
-    if (e.total_lines > opts.maxLines) {
-      result.warnings.push({
-        path: e.path,
-        message: `file exceeds --max-lines (${e.total_lines} > ${opts.maxLines})`
-      });
-    }
-  }
-  const yamlBody = renderYaml(result.entries, { generator: `cdd-kit ${_pkg.version}` });
-  const totalSrc = result.entries.reduce((s, e) => s + e.total_lines, 0);
-  const mapLines = yamlBody.split("\n").length;
-  const compression = totalSrc === 0 ? 0 : totalSrc / mapLines;
-  const summaryLine = `scanned ${result.entries.length} files, ${totalSrc} src lines -> ${opts.out} (${mapLines} lines, compression ${compression.toFixed(1)}x)`;
-  for (const w of result.warnings) {
-    log.warn(`${w.path}: ${w.message}`);
-  }
-  if (opts.check) {
-    const existing = existsSync14(opts.out) ? readFileSync15(opts.out, "utf8") : "";
-    const normalize = (s) => s.replace(/^# generated: [^\n]+\n/m, "# generated: <normalized>\n");
-    if (normalize(existing) !== normalize(yamlBody)) {
-      log.error(`code-map out of date: ${opts.out} would change. Run \`cdd-kit code-map\` to regenerate.`);
-      return 1;
-    }
-    log.ok(`code-map up to date: ${opts.out}`);
-    return 0;
-  }
-  mkdirSync6(dirname4(opts.out), { recursive: true });
-  writeFileSync7(opts.out, yamlBody, "utf8");
-  log.ok(`${summaryLine} (${Date.now() - start}ms)`);
-  return 0;
-}
-var _require, _pkgPath, _pkg;
-var init_code_map = __esm({
-  "src/commands/code-map.ts"() {
-    "use strict";
-    init_logger();
-    init_yaml_writer();
-    init_orchestrator();
-    init_config();
-    _require = createRequire(import.meta.url);
-    _pkgPath = join17(fileURLToPath2(import.meta.url), "..", "..", "..", "package.json");
-    _pkg = JSON.parse(readFileSync15(_pkgPath, "utf8"));
+    pythonScanner = new PythonScanner();
   }
 });
 
-// src/commands/doctor.ts
-var doctor_exports = {};
-__export(doctor_exports, {
-  doctor: () => doctor
+// src/code-map/scanners/javascript.ts
+var javascript_exports = {};
+__export(javascript_exports, {
+  COMMON_PLUGINS: () => COMMON_PLUGINS,
+  countSourceLines: () => countSourceLines,
+  jsScanner: () => jsScanner,
+  parseAndExtract: () => parseAndExtract,
+  parseJsSource: () => parseJsSource,
+  parseSourceWithPlugins: () => parseSourceWithPlugins
 });
-import { existsSync as existsSync15, readdirSync as readdirSync8, readFileSync as readFileSync16 } from "fs";
-import { createHash as createHash4 } from "crypto";
-import { join as join18 } from "path";
-function fileExists(cwd, relPath) {
-  return existsSync15(join18(cwd, relPath));
-}
-function findFiles(dir, predicate, found = []) {
-  if (!existsSync15(dir))
-    return found;
-  for (const entry of readdirSync8(dir, { withFileTypes: true })) {
-    const fullPath = join18(dir, entry.name);
-    if (entry.isDirectory())
-      findFiles(fullPath, predicate, found);
-    else if (entry.isFile() && predicate(entry.name))
-      found.push(fullPath);
-  }
-  return found;
+import { readFileSync as readFileSync14 } from "fs";
+import { parse } from "@babel/parser";
+function parseSourceWithPlugins(source, plugins) {
+  return parse(source, {
+    sourceType: "unambiguous",
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+    errorRecovery: true,
+    plugins
+  });
 }
-function sha256OfFile3(path) {
-  try {
-    return createHash4("sha256").update(readFileSync16(path)).digest("hex");
-  } catch {
-    return "";
-  }
+function isCallExpression(node, callee) {
+  if (!node || node.type !== "CallExpression")
+    return false;
+  const c = node.callee;
+  return c.type === "Identifier" && c.name === callee;
 }
-function inputDigest(paths) {
-  const combined = paths.slice().sort().map((p) => `${p}:${sha256OfFile3(p)}`).join("\n");
-  return createHash4("sha256").update(combined).digest("hex");
+function extractRequireModule(node) {
+  if (!node || node.type !== "CallExpression")
+    return null;
+  const c = node.callee;
+  if (c.type !== "Identifier" || c.name !== "require")
+    return null;
+  const arg = node.arguments[0];
+  if (!arg || arg.type !== "StringLiteral")
+    return null;
+  return arg.value;
 }
-function readContextIndexMetadata(filePath) {
-  if (!existsSync15(filePath))
-    return {};
-  const text = readFileSync16(filePath, "utf8");
-  const out = {};
-  const digestMatch = text.match(/^inputs-digest:\s*([a-f0-9]+)/m);
-  if (digestMatch)
-    out.inputsDigest = digestMatch[1];
-  const missingMatch = text.match(/^missing-summary-count:\s*(\d+)/m);
-  if (missingMatch)
-    out.missingSummary = Number(missingMatch[1]);
-  return out;
+function getLineRange(node) {
+  const start = node.loc?.start.line ?? 1;
+  const end = node.loc?.end.line ?? start;
+  return [start, end];
 }
-function checkContextFreshness(cwd) {
-  const findings = [];
-  const projectMap = join18(cwd, "specs", "context", "project-map.md");
-  const contractsIndex = join18(cwd, "specs", "context", "contracts-index.md");
-  const contextPolicy = join18(cwd, ".cdd", "context-policy.json");
-  const contractFiles = findFiles(
-    join18(cwd, "contracts"),
-    (name) => name.endsWith(".md") && name !== "INDEX.md" && name !== "CHANGELOG.md"
-  );
-  if (!existsSync15(projectMap) || !existsSync15(contractsIndex)) {
-    findings.push({
-      level: "warning",
-      message: "specs/context indexes are missing; run cdd-kit context-scan before classification"
-    });
-    return findings;
-  }
-  const projectMapMeta = readContextIndexMetadata(projectMap);
-  const contractsIndexMeta = readContextIndexMetadata(contractsIndex);
-  const projectInputDigest = inputDigest([contextPolicy].filter(existsSync15));
-  if (projectMapMeta.inputsDigest === void 0) {
-    findings.push({
-      level: "warning",
-      message: "specs/context/project-map.md was generated by an older cdd-kit (no inputs-digest); re-run cdd-kit context-scan"
-    });
-  } else if (projectInputDigest && projectMapMeta.inputsDigest !== projectInputDigest) {
-    findings.push({
-      level: "warning",
-      message: "specs/context/project-map.md inputs changed (.cdd/context-policy.json); re-run cdd-kit context-scan"
-    });
-  }
-  const contractsInputDigest = inputDigest(contractFiles);
-  if (contractsIndexMeta.inputsDigest === void 0) {
-    findings.push({
-      level: "warning",
-      message: "specs/context/contracts-index.md was generated by an older cdd-kit (no inputs-digest); re-run cdd-kit context-scan"
-    });
-  } else if (contractsInputDigest && contractsIndexMeta.inputsDigest !== contractsInputDigest) {
-    findings.push({
-      level: "warning",
-      message: "specs/context/contracts-index.md inputs changed (contracts/*); re-run cdd-kit context-scan"
-    });
-  }
-  if (contractsIndexMeta.missingSummary !== void 0 && contractsIndexMeta.missingSummary > 0) {
-    findings.push({
-      level: "warning",
-      message: `contracts-index reports ${contractsIndexMeta.missingSummary} contract(s) without deterministic summary metadata`
-    });
-  }
-  if (findings.length === 0) {
-    findings.push({ level: "ok", message: "context indexes are present and fresh" });
+function processImportDeclaration(node) {
+  const items = [];
+  for (const spec of node.specifiers) {
+    if (spec.type === "ImportDefaultSpecifier") {
+      items.push(`default:${spec.local.name}`);
+    } else if (spec.type === "ImportNamespaceSpecifier") {
+      items.push(`*:${spec.local.name}`);
+    } else if (spec.type === "ImportSpecifier") {
+      const imported = spec.imported;
+      items.push(imported.type === "Identifier" ? imported.name : spec.local.name);
+    }
   }
-  return findings;
+  return {
+    module: node.source.value,
+    items,
+    line: node.loc?.start.line ?? 1
+  };
 }
-function readAgentModel(path) {
-  try {
-    const text = readFileSync16(path, "utf8");
-    const m = text.match(/^model:\s*(\S+)/m);
-    return m ? m[1] : null;
-  } catch {
+function processFunctionDeclaration(node, nameOverride) {
+  const name = nameOverride ?? node.id?.name;
+  if (!name)
     return null;
-  }
+  return {
+    name,
+    lines: getLineRange(node),
+    decorators: [],
+    async: node.async
+  };
 }
-function checkModelPolicyDrift(cwd) {
-  const policyPath = join18(cwd, ".cdd", "model-policy.json");
-  if (!existsSync15(policyPath))
-    return [];
-  let policy;
-  try {
-    policy = JSON.parse(readFileSync16(policyPath, "utf8"));
-  } catch {
-    return [{ level: "warning", message: ".cdd/model-policy.json is not valid JSON" }];
-  }
-  const roles = policy.roles ?? {};
-  if (Object.keys(roles).length === 0) {
-    return [{
-      level: "warning",
-      message: ".cdd/model-policy.json has no role bindings; run cdd-kit upgrade to install defaults"
-    }];
-  }
-  const candidateDirs = [
-    join18(cwd, ".claude", "agents"),
-    process.env.HOME ? join18(process.env.HOME, ".claude", "agents") : "",
-    process.env.USERPROFILE ? join18(process.env.USERPROFILE, ".claude", "agents") : ""
-  ].filter((p) => p && existsSync15(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 = join18(dir, `${role}.md`);
-      if (!existsSync15(path))
-        continue;
-      foundAny = true;
-      const actual = readAgentModel(path);
-      if (actual && actual !== expected) {
-        findings.push({
-          level: "warning",
-          message: `model-policy drift: ${role} expected ${expected}, agent prompt uses ${actual} (${path})`
-        });
+function processClassDeclaration(node, nameOverride) {
+  const name = nameOverride ?? node.id?.name;
+  if (!name)
+    return null;
+  const methods = [];
+  for (const member of node.body.body) {
+    if (member.type === "ClassMethod" || member.type === "ClassPrivateMethod") {
+      const m = member;
+      let methodName;
+      if (m.key.type === "Identifier") {
+        methodName = m.key.name;
+      } else if (m.key.type === "PrivateName") {
+        methodName = `#${m.key.id.name}`;
+      } else {
+        methodName = "<computed>";
       }
+      methods.push({
+        name: methodName,
+        lines: getLineRange(m),
+        async: m.async
+      });
     }
-    if (!foundAny) {
-    }
-  }
-  if (findings.length === 0) {
-    findings.push({ level: "ok", message: "model-policy roles match installed agent prompts" });
   }
-  return findings;
+  return {
+    name,
+    lines: getLineRange(node),
+    methods
+  };
 }
-async function checkAgentLint(cwd) {
-  const agentsDir = join18(cwd, ".claude", "agents");
-  if (!existsSync15(agentsDir))
-    return [];
-  try {
-    const { readdirSync: rds, readFileSync: rfs } = await import("fs");
-    const files = rds(agentsDir).filter((f) => f.endsWith(".md"));
-    if (files.length === 0)
-      return [];
-    const findings = [];
-    for (const filename of files) {
-      const content = rfs(join18(agentsDir, filename), "utf8");
-      const artifactsSection = content.match(
-        /### Required artifacts for this agent\s*\n[\s\S]*?(?=\n#{2,3} |\n---|\s*$)/
-      )?.[0];
-      if (!artifactsSection || !/```ya?ml\s*\nartifacts:/.test(artifactsSection)) {
-        findings.push({
-          level: "warning",
-          message: `lint-agents: ${filename}: missing artifacts YAML block in Required artifacts section`
-        });
-      }
-      const readScopeCount = (content.match(/^## Read scope\s*$/gm) ?? []).length;
-      if (readScopeCount > 1) {
-        findings.push({
-          level: "warning",
-          message: `lint-agents: ${filename}: duplicate ## Read scope headings (${readScopeCount})`
-        });
+function processVariableDeclaration(node, imports, constants, functions) {
+  for (const decl of node.declarations) {
+    if (!decl.id || decl.id.type !== "Identifier")
+      continue;
+    const varName = decl.id.name;
+    const init2 = decl.init;
+    if (init2 && isCallExpression(init2, "require")) {
+      const mod = extractRequireModule(init2);
+      if (mod) {
+        imports.push({ module: mod, items: [`default:${varName}`], line: node.loc?.start.line ?? 1 });
       }
+      continue;
     }
-    if (findings.length === 0) {
-      findings.push({ level: "ok", message: "lint-agents: all agent prompts pass shape checks" });
+    if (isAllCapsConst(varName) && init2 !== null && init2 !== void 0) {
+      constants.push({ name: varName, line: node.loc?.start.line ?? 1 });
+      continue;
     }
-    return findings;
-  } catch {
-    return [];
+    if (init2 && (init2.type === "ArrowFunctionExpression" || init2.type === "FunctionExpression")) {
+      functions.push({
+        name: varName,
+        lines: getLineRange(node),
+        decorators: [],
+        async: init2.async
+      });
+    } else if (init2 && init2.type === "CallExpression" && /^[A-Z]/.test(varName)) {
+      functions.push({
+        name: varName,
+        lines: getLineRange(node),
+        decorators: [],
+        async: false
+      });
+    }
+  }
+}
+function processTsInterfaceDeclaration(node, exported) {
+  if (!node || node.type !== "TSInterfaceDeclaration")
+    return null;
+  if (!node.id || node.id.type !== "Identifier")
+    return null;
+  return {
+    name: node.id.name,
+    lines: getLineRange(node),
+    exported
+  };
+}
+function processTsTypeAliasDeclaration(node, exported) {
+  if (!node || node.type !== "TSTypeAliasDeclaration")
+    return null;
+  if (!node.id || node.id.type !== "Identifier")
+    return null;
+  return {
+    name: node.id.name,
+    lines: getLineRange(node),
+    exported
+  };
+}
+function processTsEnumDeclaration(node, exported) {
+  if (!node || node.type !== "TSEnumDeclaration")
+    return null;
+  if (!node.id || node.id.type !== "Identifier")
+    return null;
+  const members = [];
+  for (const m of node.members ?? []) {
+    if (!m || !m.id)
+      continue;
+    if (m.id.type === "Identifier")
+      members.push(m.id.name);
+    else if (m.id.type === "StringLiteral")
+      members.push(m.id.value);
   }
+  return {
+    name: node.id.name,
+    lines: getLineRange(node),
+    exported,
+    members
+  };
 }
-function checkCodeMap(cwd) {
-  const findings = [];
-  const mapPath = join18(cwd, ".cdd", "code-map.yml");
-  if (!existsSync15(mapPath)) {
-    const probe2 = checkCodeMapFreshness(cwd);
-    if (probe2.status === "config-error") {
-      findings.push({ level: "warning", message: `.cdd/code-map-config.yml is invalid: ${probe2.configError}` });
-    } else if (probe2.status === "missing-with-sources") {
-      findings.push({ level: "warning", message: ".cdd/code-map.yml is missing; run `cdd-kit code-map`" });
+function processStatement(stmt, buckets, extractTsTypes, exportedFromWrapper = false) {
+  if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) {
+    processStatement(stmt.declaration, buckets, extractTsTypes, true);
+    return;
+  }
+  if (stmt.type === "ExportDefaultDeclaration") {
+    const decl = stmt.declaration;
+    if (decl.type === "FunctionDeclaration") {
+      const fe = processFunctionDeclaration(decl, decl.id?.name ?? "default");
+      if (fe)
+        buckets.functions.push(fe);
+    } else if (decl.type === "ClassDeclaration") {
+      const ce = processClassDeclaration(decl, decl.id?.name ?? "default");
+      if (ce)
+        buckets.classes.push(ce);
     }
-    return findings;
+    return;
   }
-  const probe = checkCodeMapFreshness(cwd);
-  if (probe.status === "config-error") {
-    findings.push({ level: "warning", message: `.cdd/code-map-config.yml is invalid: ${probe.configError}` });
-    return findings;
+  if (stmt.type === "ImportDeclaration") {
+    buckets.imports.push(processImportDeclaration(stmt));
+    return;
   }
-  if (probe.status === "stale") {
-    const top = probe.staleFiles.slice(0, 3).join(", ");
-    const more = probe.staleCount > 3 ? ` (+${probe.staleCount - 3} more)` : "";
-    findings.push({ level: "warning", message: `code-map stale: ${top}${more}; run \`cdd-kit code-map\`` });
+  if (stmt.type === "FunctionDeclaration") {
+    const fe = processFunctionDeclaration(stmt);
+    if (fe)
+      buckets.functions.push(fe);
+    return;
   }
-  const text = readFileSync16(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` });
-  } else {
-    findings.push({ level: "warning", message: ".cdd/code-map.yml has no metadata header (regenerate with cdd-kit 2.0.5+)" });
+  if (stmt.type === "ClassDeclaration") {
+    const ce = processClassDeclaration(stmt);
+    if (ce)
+      buckets.classes.push(ce);
+    return;
   }
-  return findings;
-}
-async function buildDoctorReport(cwd, opts) {
-  const requestedProvider = opts.provider ?? "auto";
-  if (!validateProviderOption(requestedProvider)) {
-    log.error(`Invalid provider: ${requestedProvider}. Use auto, claude, codex, or both.`);
-    process.exit(1);
+  if (stmt.type === "VariableDeclaration") {
+    processVariableDeclaration(stmt, buckets.imports, buckets.constants, buckets.functions);
+    return;
   }
-  const strict = opts.strict ?? false;
-  const provider = inferProvider(cwd, requestedProvider);
-  const findings = [];
-  for (const relPath of ["contracts", "specs/templates", ".cdd/context-policy.json", ".cdd/model-policy.json"]) {
-    findings.push(fileExists(cwd, relPath) ? { level: "ok", message: `${relPath} exists` } : { level: "warning", message: `${relPath} is missing; run cdd-kit upgrade --yes` });
+  if (extractTsTypes) {
+    const anyStmt = stmt;
+    if (anyStmt.type === "TSInterfaceDeclaration") {
+      const e = processTsInterfaceDeclaration(anyStmt, exportedFromWrapper);
+      if (e)
+        buckets.interfaces.push(e);
+      return;
+    }
+    if (anyStmt.type === "TSTypeAliasDeclaration") {
+      const e = processTsTypeAliasDeclaration(anyStmt, exportedFromWrapper);
+      if (e)
+        buckets.types.push(e);
+      return;
+    }
+    if (anyStmt.type === "TSEnumDeclaration") {
+      const e = processTsEnumDeclaration(anyStmt, exportedFromWrapper);
+      if (e)
+        buckets.enums.push(e);
+      return;
+    }
   }
-  if ((provider === "claude" || provider === "both") && !fileExists(cwd, "CLAUDE.md")) {
-    findings.push({ level: "warning", message: "CLAUDE.md is missing for Claude provider; run cdd-kit upgrade --provider claude --yes" });
+  if (stmt.type === "ExpressionStatement") {
+    const expr = stmt.expression;
+    if (isCallExpression(expr, "require")) {
+      const mod = extractRequireModule(expr);
+      if (mod) {
+        buckets.imports.push({ module: mod, items: [], line: stmt.loc?.start.line ?? 1 });
+      }
+    }
   }
-  if ((provider === "claude" || provider === "both") && !fileExists(cwd, "AGENTS.md")) {
-    findings.push({ level: "warning", message: "AGENTS.md is missing for Claude provider; run cdd-kit upgrade --provider claude --yes" });
+}
+function parseAndExtract(source, opts) {
+  let ast;
+  try {
+    ast = parseSourceWithPlugins(source, opts.plugins);
+  } catch {
+    return null;
   }
-  if ((provider === "codex" || provider === "both") && !fileExists(cwd, "CODEX.md")) {
-    findings.push({ level: "warning", message: "CODEX.md is missing for Codex provider; run cdd-kit upgrade --provider codex --yes" });
+  const buckets = {
+    imports: [],
+    constants: [],
+    functions: [],
+    classes: [],
+    interfaces: [],
+    types: [],
+    enums: []
+  };
+  for (const stmt of ast.program.body) {
+    processStatement(stmt, buckets, !!opts.extractTsTypes);
   }
-  findings.push(...checkContextFreshness(cwd));
-  findings.push(...checkModelPolicyDrift(cwd));
-  findings.push(...await checkAgentLint(cwd));
-  findings.push(...checkCodeMap(cwd));
-  const errors = findings.filter((finding) => finding.level === "error").length;
-  const warnings = findings.filter((finding) => finding.level === "warning").length;
+  return buckets;
+}
+function countSourceLines(source) {
+  if (source === "")
+    return 0;
+  return source.split(/\r?\n/).length - (source.endsWith("\n") || source.endsWith("\r\n") ? 1 : 0);
+}
+function parseJsSource(source, relPath) {
+  const total_lines = countSourceLines(source);
+  const r = parseAndExtract(source, { plugins: JS_PLUGINS, extractTsTypes: false });
+  if (!r)
+    return null;
   return {
-    provider,
-    strict,
-    findings,
-    errors,
-    warnings,
-    ok: errors === 0 && (!strict || warnings === 0)
+    path: relPath,
+    total_lines,
+    imports: r.imports,
+    constants: r.constants,
+    classes: r.classes,
+    functions: r.functions
   };
 }
-async function attemptAutoFixes(cwd, report) {
-  const fixed = [];
-  const remaining = [];
-  for (const finding of report.findings) {
-    if (finding.level !== "warning") {
-      remaining.push(finding);
-      continue;
-    }
-    if (/specs\/context indexes are missing|inputs changed|older cdd-kit|older than/i.test(finding.message)) {
-      try {
-        const { contextScan: contextScan2 } = await Promise.resolve().then(() => (init_context_scan(), context_scan_exports));
-        await contextScan2();
-        fixed.push(`ran context-scan to refresh specs/context/`);
-        continue;
-      } catch (err) {
-        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
-        continue;
+var COMMON_PLUGINS, JS_PLUGINS, JavaScriptScanner, jsScanner;
+var init_javascript = __esm({
+  "src/code-map/scanners/javascript.ts"() {
+    "use strict";
+    init_common();
+    COMMON_PLUGINS = [
+      "classProperties",
+      "classPrivateProperties",
+      "classPrivateMethods",
+      "decorators-legacy",
+      "topLevelAwait",
+      "dynamicImport",
+      "optionalChaining",
+      "nullishCoalescingOperator",
+      "objectRestSpread",
+      "asyncGenerators",
+      "numericSeparator",
+      "logicalAssignment"
+    ];
+    JS_PLUGINS = ["jsx", ...COMMON_PLUGINS];
+    JavaScriptScanner = class {
+      extensions = [".js"];
+      async scan(absolutePath, repoRoot) {
+        let source;
+        try {
+          source = readFileSync14(absolutePath, "utf8");
+        } catch (err) {
+          throw err;
+        }
+        if (isBinary(source)) {
+          return null;
+        }
+        const relPath = canonicalRelPath(absolutePath, repoRoot);
+        return parseJsSource(source, relPath);
       }
-    }
-    if (/code-map stale|code-map\.yml is missing/i.test(finding.message)) {
-      try {
-        const { codeMap: codeMap2 } = await Promise.resolve().then(() => (init_code_map(), code_map_exports));
-        await codeMap2({ path: ".", out: ".cdd/code-map.yml", include: [], exclude: [], check: false, maxLines: 1e5 });
-        fixed.push("regenerated .cdd/code-map.yml");
-        continue;
-      } catch (err) {
-        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
-        continue;
+    };
+    jsScanner = new JavaScriptScanner();
+  }
+});
+
+// src/code-map/scanners/typescript.ts
+var typescript_exports = {};
+__export(typescript_exports, {
+  tsScanner: () => tsScanner
+});
+import { readFileSync as readFileSync15 } from "fs";
+var TypeScriptScanner, tsScanner;
+var init_typescript = __esm({
+  "src/code-map/scanners/typescript.ts"() {
+    "use strict";
+    init_common();
+    init_javascript();
+    TypeScriptScanner = class {
+      extensions = [".ts", ".tsx"];
+      async scan(absolutePath, repoRoot) {
+        let source;
+        try {
+          source = readFileSync15(absolutePath, "utf8");
+        } catch (err) {
+          throw err;
+        }
+        if (isBinary(source)) {
+          return null;
+        }
+        const isTsx = absolutePath.toLowerCase().endsWith(".tsx");
+        const plugins = isTsx ? ["typescript", "jsx", ...COMMON_PLUGINS] : ["typescript", ...COMMON_PLUGINS];
+        const r = parseAndExtract(source, { plugins, extractTsTypes: true });
+        if (!r)
+          return null;
+        const relPath = canonicalRelPath(absolutePath, repoRoot);
+        const total_lines = countSourceLines(source);
+        return {
+          path: relPath,
+          total_lines,
+          imports: r.imports,
+          constants: r.constants,
+          classes: r.classes,
+          functions: r.functions,
+          interfaces: r.interfaces,
+          types: r.types,
+          enums: r.enums
+        };
       }
-    }
-    if (/model-policy\.json has no role bindings/i.test(finding.message)) {
-      const policyPath = join18(cwd, ".cdd", "model-policy.json");
-      try {
-        let existing = {};
+    };
+    tsScanner = new TypeScriptScanner();
+  }
+});
+
+// src/code-map/scanners/vue.ts
+var vue_exports = {};
+__export(vue_exports, {
+  vueScanner: () => vueScanner
+});
+import { readFileSync as readFileSync16 } from "fs";
+import { parse as parse2 } from "@vue/compiler-sfc";
+var VueScanner, vueScanner;
+var init_vue = __esm({
+  "src/code-map/scanners/vue.ts"() {
+    "use strict";
+    init_common();
+    init_javascript();
+    VueScanner = class {
+      extensions = [".vue"];
+      async scan(absolutePath, repoRoot) {
+        let source;
         try {
-          existing = JSON.parse(readFileSync16(policyPath, "utf8"));
-        } catch {
+          source = readFileSync16(absolutePath, "utf8");
+        } catch (err) {
+          throw err;
         }
-        const merged = {
-          ...existing,
-          roles: {
-            "change-classifier": "claude-opus-4-7",
-            "spec-architect": "claude-opus-4-7",
-            "qa-reviewer": "claude-opus-4-7",
-            "contract-reviewer": "claude-sonnet-4-6",
-            "test-strategist": "claude-sonnet-4-6",
-            "backend-engineer": "claude-sonnet-4-6",
-            "frontend-engineer": "claude-sonnet-4-6",
-            "ci-cd-gatekeeper": "claude-sonnet-4-6",
-            "e2e-resilience-engineer": "claude-sonnet-4-6",
-            "monkey-test-engineer": "claude-sonnet-4-6",
-            "stress-soak-engineer": "claude-sonnet-4-6",
-            "ui-ux-reviewer": "claude-sonnet-4-6",
-            "visual-reviewer": "claude-haiku-4-5-20251001",
-            "dependency-security-reviewer": "claude-sonnet-4-6",
-            "spec-drift-auditor": "claude-opus-4-7",
-            "repo-context-scanner": "claude-haiku-4-5-20251001"
+        if (isBinary(source)) {
+          return null;
+        }
+        const relPath = canonicalRelPath(absolutePath, repoRoot);
+        const total_lines = source.split(/\r?\n/).length - (source.endsWith("\n") || source.endsWith("\r\n") ? 1 : 0);
+        const { descriptor } = parse2(source, { filename: absolutePath });
+        const allImports = [];
+        const allConstants = [];
+        const allFunctions = [];
+        const allClasses = [];
+        const warnings = [];
+        const scriptBlocks = [descriptor.script, descriptor.scriptSetup].filter(Boolean);
+        if (scriptBlocks.length === 0) {
+          return {
+            path: relPath,
+            total_lines,
+            imports: [],
+            constants: [],
+            classes: [],
+            functions: []
+          };
+        }
+        for (const block of scriptBlocks) {
+          if (!block)
+            continue;
+          if (block.lang === "ts" || block.lang === "tsx") {
+            warnings.push({
+              path: relPath,
+              message: `skipping <script lang=${block.lang}> block (TypeScript not supported in v1)`
+            });
+            continue;
+          }
+          const blockContent = block.content;
+          const lineOffset = block.loc.start.line;
+          const scriptEntry = parseJsSource(blockContent, relPath);
+          if (!scriptEntry) {
+            warnings.push({ path: relPath, message: "parse error in script block" });
+            continue;
+          }
+          const offset = lineOffset - 1;
+          for (const imp of scriptEntry.imports) {
+            allImports.push({ ...imp, line: imp.line + offset });
+          }
+          for (const c of scriptEntry.constants) {
+            allConstants.push({ ...c, line: c.line + offset });
+          }
+          for (const fn of scriptEntry.functions) {
+            allFunctions.push({
+              ...fn,
+              lines: [fn.lines[0] + offset, fn.lines[1] + offset]
+            });
+          }
+          for (const cls of scriptEntry.classes) {
+            allClasses.push({
+              ...cls,
+              lines: [cls.lines[0] + offset, cls.lines[1] + offset],
+              methods: cls.methods.map((m) => ({
+                ...m,
+                lines: [m.lines[0] + offset, m.lines[1] + offset]
+              }))
+            });
           }
+        }
+        return {
+          path: relPath,
+          total_lines,
+          imports: allImports,
+          constants: allConstants,
+          classes: allClasses,
+          functions: allFunctions
         };
-        const { writeFileSync: writeFileSync13 } = await import("fs");
-        writeFileSync13(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
-        fixed.push(`populated .cdd/model-policy.json with default role bindings`);
-        continue;
-      } catch (err) {
-        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
-        continue;
       }
-    }
-    if (/\.cdd\/.*is missing|run cdd-kit upgrade/i.test(finding.message)) {
-      remaining.push({
-        level: "warning",
-        message: `${finding.message} (run \`cdd-kit upgrade --yes\` manually \u2014 too invasive for --fix)`
-      });
-      continue;
-    }
-    remaining.push(finding);
+    };
+    vueScanner = new VueScanner();
   }
-  return { fixed, remaining };
-}
-async function doctor(opts = {}) {
-  const cwd = process.cwd();
-  let report = await buildDoctorReport(cwd, opts);
-  if (opts.fix && !opts.json) {
-    log.blank();
-    log.info("Doctor --fix: attempting safe auto-resolutions\u2026");
-    const { fixed, remaining } = await attemptAutoFixes(cwd, report);
-    for (const f of fixed)
-      log.ok(`fixed: ${f}`);
-    if (fixed.length > 0) {
-      report = await buildDoctorReport(cwd, opts);
-    } else {
-      log.info("no auto-fixable findings");
+});
+
+// src/commands/code-map.ts
+var code_map_exports = {};
+__export(code_map_exports, {
+  codeMap: () => codeMap
+});
+import { existsSync as existsSync16, mkdirSync as mkdirSync8, readFileSync as readFileSync17, writeFileSync as writeFileSync9 } from "fs";
+import { resolve, dirname as dirname5 } from "path";
+import { createRequire } from "module";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { join as join19 } from "path";
+async function codeMap(opts) {
+  const root = resolve(process.cwd(), opts.path);
+  const start = Date.now();
+  let cfg;
+  try {
+    cfg = loadCodeMapConfig(root);
+  } catch (err) {
+    log.error(`code-map: ${err.message}`);
+    return 1;
+  }
+  const include = [...cfg.include, ...opts.include];
+  const exclude = [...cfg.exclude, ...opts.exclude];
+  const files = walkRepo(root, { include, exclude });
+  const buckets = bucketByExtension(files);
+  const result = { entries: [], warnings: [] };
+  const tasks = [];
+  if (buckets[".py"]?.length) {
+    const { pythonScanner: pythonScanner2 } = await Promise.resolve().then(() => (init_python(), python_exports));
+    if (pythonScanner2.scanBatch) {
+      tasks.push(pythonScanner2.scanBatch(buckets[".py"], root));
     }
   }
-  if (opts.json) {
-    console.log(JSON.stringify(report, null, 2));
-    if (!report.ok)
-      process.exit(1);
-    return;
+  const jsFiles = [
+    ...buckets[".js"] ?? [],
+    ...buckets[".jsx"] ?? [],
+    ...buckets[".mjs"] ?? [],
+    ...buckets[".cjs"] ?? []
+  ];
+  if (jsFiles.length) {
+    const { jsScanner: jsScanner2 } = await Promise.resolve().then(() => (init_javascript(), javascript_exports));
+    tasks.push(scanInProcess(jsScanner2, jsFiles, root));
   }
-  log.blank();
-  log.info(`Doctor provider: ${report.provider}`);
-  for (const finding of report.findings) {
-    if (finding.level === "ok")
-      log.ok(finding.message);
-    else if (finding.level === "warning")
-      log.warn(finding.message);
-    else
-      log.error(finding.message);
+  const tsFiles = [
+    ...buckets[".ts"] ?? [],
+    ...buckets[".tsx"] ?? []
+  ];
+  if (tsFiles.length) {
+    const { tsScanner: tsScanner2 } = await Promise.resolve().then(() => (init_typescript(), typescript_exports));
+    tasks.push(scanInProcess(tsScanner2, tsFiles, root));
   }
-  log.blank();
-  if (!report.ok) {
-    log.error(report.strict && report.errors === 0 ? `doctor failed in strict mode with ${report.warnings} warning(s)` : `doctor failed with ${report.errors} error(s)`);
-    process.exit(1);
+  if (buckets[".vue"]?.length) {
+    const { vueScanner: vueScanner2 } = await Promise.resolve().then(() => (init_vue(), vue_exports));
+    tasks.push(scanInProcess(vueScanner2, buckets[".vue"], root));
+  }
+  for (const r of await Promise.all(tasks)) {
+    result.entries.push(...r.entries);
+    result.warnings.push(...r.warnings);
+  }
+  result.entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  for (const e of result.entries) {
+    if (e.total_lines > opts.maxLines) {
+      result.warnings.push({
+        path: e.path,
+        message: `file exceeds --max-lines (${e.total_lines} > ${opts.maxLines})`
+      });
+    }
+  }
+  const yamlBody = renderYaml(result.entries, { generator: `cdd-kit ${_pkg.version}` });
+  const totalSrc = result.entries.reduce((s, e) => s + e.total_lines, 0);
+  const mapLines = yamlBody.split("\n").length;
+  const compression = totalSrc === 0 ? 0 : totalSrc / mapLines;
+  const summaryLine = `scanned ${result.entries.length} files, ${totalSrc} src lines -> ${opts.out} (${mapLines} lines, compression ${compression.toFixed(1)}x)`;
+  for (const w of result.warnings) {
+    log.warn(`${w.path}: ${w.message}`);
   }
-  if (report.warnings > 0) {
-    log.warn(`doctor completed with ${report.warnings} warning(s)`);
-  } else {
-    log.ok("doctor passed");
+  if (opts.check) {
+    const existing = existsSync16(opts.out) ? readFileSync17(opts.out, "utf8") : "";
+    const normalize = (s) => s.replace(/^# generated: [^\n]+\n/m, "# generated: <normalized>\n");
+    if (normalize(existing) !== normalize(yamlBody)) {
+      log.error(`code-map out of date: ${opts.out} would change. Run \`cdd-kit code-map\` to regenerate.`);
+      return 1;
+    }
+    log.ok(`code-map up to date: ${opts.out}`);
+    return 0;
   }
-  log.blank();
+  mkdirSync8(dirname5(opts.out), { recursive: true });
+  writeFileSync9(opts.out, yamlBody, "utf8");
+  log.ok(`${summaryLine} (${Date.now() - start}ms)`);
+  return 0;
 }
-var init_doctor = __esm({
-  "src/commands/doctor.ts"() {
+var _require, _pkgPath, _pkg;
+var init_code_map = __esm({
+  "src/commands/code-map.ts"() {
     "use strict";
     init_logger();
-    init_provider();
-    init_freshness();
+    init_yaml_writer();
+    init_orchestrator();
+    init_config();
+    _require = createRequire(import.meta.url);
+    _pkgPath = join19(fileURLToPath2(import.meta.url), "..", "..", "..", "package.json");
+    _pkg = JSON.parse(readFileSync17(_pkgPath, "utf8"));
   }
 });
 
-// src/commands/migrate.ts
-var migrate_exports = {};
-__export(migrate_exports, {
-  migrate: () => migrate
+// src/commands/refresh.ts
+var refresh_exports = {};
+__export(refresh_exports, {
+  refresh: () => refresh
 });
-import { join as join19 } from "path";
-import { cpSync as cpSync2, existsSync as existsSync16, mkdirSync as mkdirSync7, readdirSync as readdirSync9, readFileSync as readFileSync17, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync8 } from "fs";
-import yaml3 from "js-yaml";
-function backupChangeDir(cwd, changeId, sessionStamp) {
-  const backupRoot = join19(cwd, ".cdd", "migrate-backup", sessionStamp);
-  const backupDir2 = join19(backupRoot, changeId);
-  mkdirSync7(backupRoot, { recursive: true });
-  const sourceDir = join19(cwd, "specs", "changes", changeId);
-  if (existsSync16(sourceDir)) {
-    cpSync2(sourceDir, backupDir2, { recursive: true });
+import { existsSync as existsSync17, mkdirSync as mkdirSync9, readdirSync as readdirSync10, copyFileSync as copyFileSync4, readFileSync as readFileSync18, writeFileSync as writeFileSync10 } from "fs";
+import { dirname as dirname6, join as join20, relative as relative5 } from "path";
+import { createHash as createHash4 } from "crypto";
+function fileHash2(filePath) {
+  return createHash4("sha256").update(readFileSync18(filePath)).digest("hex");
+}
+function planForceRefresh(srcDir, destDir, sectionLabel) {
+  const plan = [];
+  if (!existsSync17(srcDir))
+    return plan;
+  function walk(curSrc, curDest) {
+    let items;
+    try {
+      items = readdirSync10(curSrc, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const item of items) {
+      const sp = join20(curSrc, item.name);
+      const dp = join20(curDest, item.name);
+      if (item.isDirectory()) {
+        walk(sp, dp);
+        continue;
+      }
+      if (!item.isFile())
+        continue;
+      const rel = join20(sectionLabel, relative5(srcDir, sp)).replace(/\\/g, "/");
+      if (!existsSync17(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" });
+      } else {
+        plan.push({ src: sp, dest: dp, rel, action: "skip" });
+      }
+    }
   }
-  return backupDir2;
+  walk(srcDir, destDir);
+  return plan;
 }
-function buildLegacyContextManifest(changeId) {
-  return [
-    "# Context Manifest",
-    "",
-    "Generated by `cdd-kit migrate` for an existing change.",
-    "Legacy manifest. Forbidden paths come from `.cdd/context-policy.json`.",
-    "",
-    "## Affected Surfaces",
-    "- legacy-unknown",
-    "",
-    "## Allowed Paths",
-    `- specs/changes/${changeId}/`,
-    "",
-    "## Required Contracts",
-    "- legacy-unknown",
-    "",
-    "## Required Tests",
-    "- legacy-unknown",
-    "",
-    "## Agent Work Packets",
-    "",
-    "## Context Expansion Requests",
-    "-",
-    "",
-    "## Approved Expansions",
-    "-",
-    ""
-  ].join("\n");
+function planSingleFile(src, dest, rel) {
+  if (!existsSync17(src))
+    return null;
+  if (!existsSync17(dest))
+    return { src, dest, rel, action: "add" };
+  if (fileHash2(src) !== fileHash2(dest))
+    return { src, dest, rel, action: "overwrite" };
+  return { src, dest, rel, action: "skip" };
+}
+function ensureGitignoreEntry2(cwd, entry) {
+  const path = join20(cwd, ".gitignore");
+  const trimmed = entry.trim();
+  if (!trimmed)
+    return false;
+  const re = new RegExp(`^\\s*${trimmed.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*$`, "m");
+  let existing = "";
+  if (existsSync17(path))
+    existing = readFileSync18(path, "utf8");
+  if (re.test(existing))
+    return false;
+  const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const block = existing.length === 0 ? `# cdd-kit generated backups (do not commit)
+${trimmed}
+` : `${sep}
+# cdd-kit generated backups (do not commit)
+${trimmed}
+`;
+  writeFileSync10(path, existing + block, "utf8");
+  return true;
 }
-function buildContextGovernedManifest(changeId) {
-  return [
-    "# Context Manifest",
-    "",
-    "Generated by `cdd-kit migrate --enable-context-governance` for an existing change.",
-    "Review and narrow the allowed paths before assigning implementation work.",
-    "Forbidden paths come from `.cdd/context-policy.json`.",
-    "",
-    "## Affected Surfaces",
-    "- legacy-unknown",
-    "",
-    "## Allowed Paths",
-    `- specs/changes/${changeId}/`,
-    "- specs/context/project-map.md",
-    "- specs/context/contracts-index.md",
-    "",
-    "## Required Contracts",
-    "- legacy-unknown",
-    "",
-    "## Required Tests",
-    "- legacy-unknown",
-    "",
-    "## Agent Work Packets",
-    "",
-    "### change-classifier",
-    "- allowed:",
-    `  - specs/changes/${changeId}/`,
-    "  - specs/context/project-map.md",
-    "  - specs/context/contracts-index.md",
-    "",
-    "## Context Expansion Requests",
-    "",
-    "<!--",
-    "Agents must request context expansion instead of reading outside their work packet.",
-    "Use this format only for real requests:",
-    "",
-    "- request-id: CER-001",
-    "  requested_paths:",
-    "    - src/example.ts",
-    "  reason: why this file is required",
-    "  status: pending",
-    "-->",
-    "",
-    "## Approved Expansions",
-    "-",
-    ""
-  ].join("\n");
+function applyPlan(plan, backupRoot) {
+  let added = 0;
+  let overwritten = 0;
+  for (const item of plan) {
+    if (item.action === "skip")
+      continue;
+    if (item.action === "overwrite") {
+      const backupPath = join20(backupRoot, item.rel);
+      mkdirSync9(dirname6(backupPath), { recursive: true });
+      copyFileSync4(item.dest, backupPath);
+      overwritten += 1;
+    } else {
+      added += 1;
+    }
+    mkdirSync9(dirname6(item.dest), { recursive: true });
+    copyFileSync4(item.src, item.dest);
+  }
+  return { added, overwritten };
 }
-function parseLegacyFrontmatter(content) {
+function parseAgentFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m)
     return {};
-  const out = {};
+  const fm = {};
   for (const line of m[1].split(/\r?\n/)) {
-    const colon = line.indexOf(":");
-    if (colon === -1)
-      continue;
-    const key = line.slice(0, colon).trim();
-    if (!key)
-      continue;
-    out[key] = line.slice(colon + 1).trim();
-  }
-  return out;
-}
-function parseListField(raw) {
-  if (!raw)
-    return [];
-  const trimmed = raw.trim();
-  if (!trimmed || trimmed === "[]")
-    return [];
-  const inner = trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
-  return inner.split(",").map((item) => item.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
-}
-function parseLegacyTaskList(body) {
-  const lines = body.split(/\r?\n/);
-  const rows = [];
-  let currentSection;
-  for (const raw of lines) {
-    const headerMatch = raw.match(/^##\s+\d+\.\s+(.*)\s*$/);
-    if (headerMatch) {
-      currentSection = headerMatch[1].trim();
+    const km = line.match(/^([a-zA-Z_-]+):\s*(.+?)\s*$/);
+    if (!km)
       continue;
+    if (km[1] === "name")
+      fm.name = km[2].trim();
+    if (km[1] === "model")
+      fm.model = km[2].trim();
+  }
+  return fm;
+}
+function resyncModelPolicy(cwd) {
+  const policyPath = join20(cwd, ".cdd", "model-policy.json");
+  const result = { changed: false, diff: [], policyPath };
+  if (!existsSync17(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 = readFileSync18(join20(AGENTS_HOME, f.name), "utf8");
+    const fm = parseAgentFrontmatter(content);
+    if (fm.name && fm.model)
+      desired[fm.name] = fm.model;
+  }
+  if (Object.keys(desired).length === 0)
+    return result;
+  let existing = {};
+  if (existsSync17(policyPath)) {
+    try {
+      existing = JSON.parse(readFileSync18(policyPath, "utf8"));
+    } catch {
     }
-    const itemMatch = raw.match(/^\s*-\s*\[([ xX\-])\]\s+(\d+(?:\.\d+)*)\s+(.*)\s*$/);
-    if (!itemMatch)
-      continue;
-    const mark = itemMatch[1];
-    const id = itemMatch[2];
-    const title = itemMatch[3].trim();
-    let status = "pending";
-    if (mark === "x" || mark === "X")
-      status = "done";
-    else if (mark === "-")
-      status = "skipped";
-    rows.push({ id, title, status, section: currentSection });
   }
-  return rows;
-}
-function migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pendingWrites, pendingDeletes) {
-  const newPath = join19(changeDir, "tasks.yml");
-  const legacyPath = join19(changeDir, "tasks.md");
-  if (existsSync16(newPath)) {
-    return;
+  const existingRoles = existing.roles && typeof existing.roles === "object" ? existing.roles : {};
+  for (const [agent, model] of Object.entries(desired)) {
+    if (existingRoles[agent] !== model) {
+      result.diff.push({ agent, from: existingRoles[agent] ?? null, to: model });
+    }
   }
-  if (!existsSync16(legacyPath)) {
-    warnings.push("tasks.md not found and tasks.yml missing \u2014 skipping tasks migration");
-    return;
+  if (result.diff.length === 0)
+    return result;
+  const merged = {
+    ...existing,
+    roles: desired
+  };
+  if (!("schema-version" in merged))
+    merged["schema-version"] = "0.2.0";
+  if (!("provider" in merged))
+    merged["provider"] = "claude";
+  mkdirSync9(dirname6(policyPath), { recursive: true });
+  writeFileSync10(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  result.changed = true;
+  return result;
+}
+function planTemplateRefresh(cwd) {
+  const sections = [];
+  sections.push({
+    name: "specs/templates",
+    plan: planForceRefresh(ASSET.specsTemplates, join20(cwd, "specs", "templates"), "specs/templates")
+  });
+  sections.push({
+    name: "tests/templates",
+    plan: planForceRefresh(ASSET.testsTemplates, join20(cwd, "tests", "templates"), "tests/templates")
+  });
+  const ciTemplatesAsset = join20(ASSET.ci, "..", "ci-templates");
+  if (existsSync17(ciTemplatesAsset)) {
+    sections.push({
+      name: "ci-templates",
+      plan: planForceRefresh(ciTemplatesAsset, join20(cwd, "ci-templates"), "ci-templates")
+    });
   }
-  const raw = readFileSync17(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;
-  const tasksRows = parseLegacyTaskList(body);
-  const data = {};
-  data["change-id"] = fm["change-id"] || changeId;
-  data["status"] = fm["status"] || "in-progress";
-  if (fm["tier"] && /^\d+$/.test(fm["tier"])) {
-    data["tier"] = parseInt(fm["tier"], 10);
-  } else if (detectedTier) {
-    data["tier"] = parseInt(detectedTier, 10);
+  const wfAsset = join20(ASSET.githubWorkflows, "contract-driven-gates.yml");
+  const wfDest = join20(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] });
+  const total = sections.flatMap((s) => s.plan);
+  return { sections, total };
+}
+function summarizePlan(items) {
+  return {
+    add: items.filter((i) => i.action === "add").length,
+    overwrite: items.filter((i) => i.action === "overwrite").length,
+    skip: items.filter((i) => i.action === "skip").length
+  };
+}
+async function refresh(opts) {
+  const cwd = process.cwd();
+  const apply = !!opts.yes;
+  log.blank();
+  log.info(apply ? "cdd-kit refresh \u2014 applying changes" : "cdd-kit refresh \u2014 dry-run preview (re-run with --yes to apply)");
+  log.blank();
+  if (!opts.noUpdate) {
+    log.info("[1/6] ~/.claude/agents and ~/.claude/skills (via cdd-kit update)");
+    await update({ yes: apply, provider: opts.provider ?? "auto" });
   } else {
-    data["tier"] = null;
+    log.dim("[1/6] skipped (--no-update)");
   }
-  if (enableContextGovernance || fm["context-governance"] === "v1") {
-    data["context-governance"] = "v1";
+  log.blank();
+  if (!opts.noUpgrade) {
+    log.info("[2/6] add missing project files (via cdd-kit upgrade)");
+    await upgrade({ yes: apply, provider: opts.provider ?? "auto" });
+  } else {
+    log.dim("[2/6] skipped (--no-upgrade)");
   }
-  const archive2 = parseListField(fm["archive-tasks"]);
-  data["archive-tasks"] = archive2.length > 0 ? archive2 : ["7.1", "7.2"];
-  const deps = parseListField(fm["depends-on"]);
-  data["depends-on"] = deps;
-  data["tasks"] = tasksRows.map((r) => {
-    const out = { id: r.id, title: r.title, status: r.status };
-    if (r.section)
-      out["section"] = r.section;
-    return out;
-  });
-  const yamlOut = yaml3.dump(data, { lineWidth: -1, noRefs: true });
-  pendingWrites.push({ path: newPath, content: yamlOut });
-  pendingDeletes.push({ path: legacyPath });
-  changed.push(`tasks.md -> tasks.yml (${tasksRows.length} task(s) migrated)`);
-}
-function parseLegacyAgentLog(content) {
-  const lines = content.split(/\r?\n/);
-  const data = {};
-  let i = 0;
-  const topFieldRe = /^[ ]{0,1}-\s*([\w-]+):\s*(.*)$/;
-  while (i < lines.length) {
-    const line = lines[i];
-    const fieldMatch = line.match(topFieldRe);
-    if (!fieldMatch) {
-      i++;
-      continue;
-    }
-    const key = fieldMatch[1];
-    const inline = fieldMatch[2].trim();
-    if (key === "files-read" || key === "artifacts") {
-      const items = [];
-      let j = i + 1;
-      while (j < lines.length) {
-        const sub = lines[j];
-        if (topFieldRe.test(sub))
-          break;
-        if (/^#/.test(sub))
-          break;
-        const itemMatch = sub.match(/^\s{2,}-\s+(.+?)\s*$/);
-        if (itemMatch) {
-          items.push(itemMatch[1].trim());
+  log.blank();
+  let templateAdded = 0;
+  let templateOverwritten = 0;
+  let backupRoot = null;
+  if (!opts.noTemplates) {
+    log.info("[3/6] force-refresh kit-shipped templates");
+    const { sections, total } = planTemplateRefresh(cwd);
+    const summary = summarizePlan(total);
+    if (summary.add === 0 && summary.overwrite === 0) {
+      log.ok("  templates already up to date");
+    } else {
+      for (const s of sections) {
+        const ss = summarizePlan(s.plan);
+        if (ss.add === 0 && ss.overwrite === 0)
+          continue;
+        log.info(`  ${s.name}: +${ss.add}  ~${ss.overwrite}  =${ss.skip}`);
+        for (const item of s.plan.filter((i) => i.action !== "skip")) {
+          log.dim(`    ${item.action === "add" ? "+" : "~"} ${item.rel}`);
+        }
+      }
+      if (apply) {
+        const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+        backupRoot = join20(cwd, ".cdd", ".refresh-backup", ts);
+        const result = applyPlan(total, backupRoot);
+        templateAdded = result.added;
+        templateOverwritten = result.overwritten;
+        log.ok(`  applied: +${templateAdded} added, ~${templateOverwritten} overwritten`);
+        if (templateOverwritten > 0) {
+          log.info(`  backup saved to: ${relative5(cwd, backupRoot).replace(/\\/g, "/")}`);
+          if (ensureGitignoreEntry2(cwd, ".cdd/.refresh-backup/")) {
+            log.info("  added `.cdd/.refresh-backup/` to .gitignore");
+          }
         }
-        j++;
-      }
-      if (key === "files-read") {
-        data["files-read"] = items;
       } else {
-        data["artifacts"] = items.map((s) => {
-          const idx = s.indexOf(":");
-          if (idx === -1) {
-            return { type: "note", pointer: s };
-          }
-          const type = s.slice(0, idx).trim();
-          const pointer = s.slice(idx + 1).trim();
-          return { type, pointer };
-        });
+        log.dim("  (dry-run \u2014 no changes written)");
       }
-      i = j;
-      continue;
     }
-    data[key] = inline;
-    i++;
-  }
-  return data;
-}
-function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
-  const agentLogDir = join19(changeDir, "agent-log");
-  if (!existsSync16(agentLogDir))
-    return;
-  const mdLogs = readdirSync9(agentLogDir).filter((f) => f.endsWith(".md"));
-  for (const f of mdLogs) {
-    const fullPath = join19(agentLogDir, f);
-    const yamlName = f.replace(/\.md$/, ".yml");
-    const yamlFull = join19(agentLogDir, yamlName);
-    if (existsSync16(yamlFull))
-      continue;
-    const raw = readFileSync17(fullPath, "utf8");
-    const parsed = parseLegacyAgentLog(raw);
-    const yamlOut = yaml3.dump(parsed, { lineWidth: -1, noRefs: true });
-    pendingWrites.push({ path: yamlFull, content: yamlOut });
-    pendingDeletes.push({ path: fullPath });
-    changed.push(`agent-log/${f} -> agent-log/${yamlName}`);
+  } else {
+    log.dim("[3/6] skipped (--no-templates)");
   }
-}
-function migrateOne(changeId, changeDir, enableContextGovernance) {
-  const changed = [];
-  const warnings = [];
-  const pending = [];
-  const deletes = [];
-  let detectedTier = null;
-  const classifPath = join19(changeDir, "change-classification.md");
-  if (existsSync16(classifPath)) {
-    const content = readFileSync17(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)
-      detectedTier = oldMatch[1];
-    if (!hasNewTierFormat) {
-      if (detectedTier) {
-        const addition = `
-## Tier
-- ${detectedTier}
-`;
-        if (!content.includes("\n## Tier\n")) {
-          changed.push(
-            `change-classification.md: appended "## Tier\\n- ${detectedTier}" (converted from old format)`
-          );
-          pending.push({ path: classifPath, content: content + addition });
+  log.blank();
+  if (!opts.noHooks) {
+    const markerPath = join20(cwd, HOOKS_MARKER_PATH);
+    if (existsSync17(markerPath)) {
+      log.info("[4/6] re-install code-map pre-commit hook (marker found)");
+      if (apply) {
+        try {
+          await installCodeMapHook(cwd);
+        } catch (err) {
+          log.warn(`  hook re-install skipped: ${err.message}`);
         }
       } else {
-        warnings.push(
-          "change-classification.md: could not detect tier (no **Tier:** N or ## Tier N found). Set `tier: <0-5>` in tasks.yml frontmatter to enable tier-based gate checks."
-        );
+        log.dim("  (dry-run \u2014 would re-install)");
       }
     } else {
-      const structured = content.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
-      if (structured)
-        detectedTier = structured[1];
+      log.dim("[4/6] no .cdd/.hooks-installed marker \u2014 skipping (run `cdd-kit init --hooks` to install)");
     }
+  } else {
+    log.dim("[4/6] skipped (--no-hooks)");
   }
-  migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pending, deletes);
-  migrateAgentLogs(changeDir, changed, pending, deletes);
-  const manifestPath = join19(changeDir, "context-manifest.md");
-  if (!existsSync16(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,
-      content: enableContextGovernance ? buildContextGovernedManifest(changeId) : buildLegacyContextManifest(changeId)
-    });
-  } else if (enableContextGovernance) {
-    warnings.push("context-manifest.md already exists \u2014 review allowed paths before relying on context-governance: v1");
-  }
-  return { result: { changed, warnings }, pending, deletes };
-}
-function commitWritesAtomically(pending, deletes) {
-  const renames = [];
-  try {
-    for (const write of pending) {
-      const tmp = `${write.path}.cdd-migrate.tmp`;
-      writeFileSync8(tmp, write.content, "utf8");
-      renames.push({ tmp, final: write.path });
+  log.blank();
+  log.info("[5/6] resync .cdd/model-policy.json roles from agent frontmatter");
+  if (apply) {
+    const r = resyncModelPolicy(cwd);
+    if (r.diff.length === 0) {
+      log.ok("  roles already match agent prompts");
+    } else {
+      for (const d of r.diff) {
+        log.info(`  ${d.agent}: ${d.from ?? "(absent)"} \u2192 ${d.to}`);
+      }
+      log.ok(`  ${r.diff.length} role binding(s) updated`);
     }
-  } catch (err) {
-    for (const r of renames) {
+  } else {
+    const fakeApply = () => {
+    };
+    fakeApply();
+    log.dim("  (dry-run \u2014 drift will be reported only when applied)");
+  }
+  log.blank();
+  if (!opts.noCodeMap) {
+    log.info("[6/6] regenerate .cdd/code-map.yml");
+    if (apply) {
       try {
-        rmSync2(r.tmp, { force: true });
-      } catch {
+        await codeMap({
+          path: ".",
+          out: ".cdd/code-map.yml",
+          include: [],
+          exclude: [],
+          check: false,
+          maxLines: 600
+        });
+      } catch (err) {
+        log.warn(`  code-map skipped: ${err.message}`);
       }
+    } else {
+      log.dim("  (dry-run \u2014 would regenerate)");
     }
-    throw err;
+  } else {
+    log.dim("[6/6] skipped (--no-code-map)");
   }
-  for (const r of renames) {
-    renameSync(r.tmp, r.final);
+  log.blank();
+  if (apply) {
+    log.ok("refresh complete.");
+    if (backupRoot) {
+      log.info(`Backup of overwritten templates: ${relative5(cwd, backupRoot).replace(/\\/g, "/")}`);
+    }
+    log.info("Next: review changes with `git diff`, then commit:");
+    log.dim("  git add .cdd/code-map.yml .cdd/model-policy.json specs/templates tests/templates ci-templates .github/workflows");
+    log.dim('  git commit -m "chore: cdd-kit refresh"');
+  } else {
+    log.info("Dry-run finished. Re-run with `--yes` to apply.");
   }
-  for (const d of deletes) {
-    try {
-      rmSync2(d.path, { force: true });
-    } catch {
-    }
+  log.blank();
+}
+var HOOKS_MARKER_PATH;
+var init_refresh = __esm({
+  "src/commands/refresh.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    init_update();
+    init_upgrade();
+    init_code_map();
+    init_code_map_hook();
+    HOOKS_MARKER_PATH = ".cdd/.hooks-installed";
   }
+});
+
+// src/commands/doctor.ts
+var doctor_exports = {};
+__export(doctor_exports, {
+  doctor: () => doctor
+});
+import { existsSync as existsSync18, readdirSync as readdirSync11, readFileSync as readFileSync19 } from "fs";
+import { createHash as createHash5 } from "crypto";
+import { join as join21 } from "path";
+function fileExists(cwd, relPath) {
+  return existsSync18(join21(cwd, relPath));
 }
-async function migrate(changeId, opts = {}) {
-  const cwd = process.cwd();
-  const dryRun = opts.dryRun ?? false;
-  const enableContextGovernance = opts.enableContextGovernance ?? false;
-  const noBackup = opts.noBackup ?? false;
-  const idsToMigrate = [];
-  if (opts.all) {
-    const changesDir = join19(cwd, "specs", "changes");
-    if (!existsSync16(changesDir)) {
-      log.info("No specs/changes/ directory found \u2014 nothing to migrate.");
-      return;
-    }
-    idsToMigrate.push(
-      ...readdirSync9(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
-    );
-  } else if (changeId) {
-    const specificDir = join19(cwd, "specs", "changes", changeId);
-    if (!existsSync16(specificDir)) {
-      log.error(`Change not found: specs/changes/${changeId}`);
-      process.exit(1);
-    }
-    idsToMigrate.push(changeId);
-  } else {
-    log.error("Usage: cdd-kit migrate <change-id>  |  cdd-kit migrate --all  [--dry-run] [--no-backup]");
-    process.exit(1);
+function findFiles(dir, predicate, found = []) {
+  if (!existsSync18(dir))
+    return found;
+  for (const entry of readdirSync11(dir, { withFileTypes: true })) {
+    const fullPath = join21(dir, entry.name);
+    if (entry.isDirectory())
+      findFiles(fullPath, predicate, found);
+    else if (entry.isFile() && predicate(entry.name))
+      found.push(fullPath);
   }
-  if (idsToMigrate.length === 0) {
-    log.info("No changes found to migrate.");
-    return;
+  return found;
+}
+function sha256OfFile3(path) {
+  try {
+    return createHash5("sha256").update(readFileSync19(path)).digest("hex");
+  } catch {
+    return "";
   }
-  if (dryRun) {
-    log.info("Dry run \u2014 no files will be written.");
-    log.blank();
+}
+function inputDigest(paths) {
+  const combined = paths.slice().sort().map((p) => `${p}:${sha256OfFile3(p)}`).join("\n");
+  return createHash5("sha256").update(combined).digest("hex");
+}
+function readContextIndexMetadata(filePath) {
+  if (!existsSync18(filePath))
+    return {};
+  const text = readFileSync19(filePath, "utf8");
+  const out = {};
+  const digestMatch = text.match(/^inputs-digest:\s*([a-f0-9]+)/m);
+  if (digestMatch)
+    out.inputsDigest = digestMatch[1];
+  const missingMatch = text.match(/^missing-summary-count:\s*(\d+)/m);
+  if (missingMatch)
+    out.missingSummary = Number(missingMatch[1]);
+  return out;
+}
+function checkContextFreshness(cwd) {
+  const findings = [];
+  const projectMap = join21(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join21(cwd, "specs", "context", "contracts-index.md");
+  const contextPolicy = join21(cwd, ".cdd", "context-policy.json");
+  const contractFiles = findFiles(
+    join21(cwd, "contracts"),
+    (name) => name.endsWith(".md") && name !== "INDEX.md" && name !== "CHANGELOG.md"
+  );
+  if (!existsSync18(projectMap) || !existsSync18(contractsIndex)) {
+    findings.push({
+      level: "warning",
+      message: "specs/context indexes are missing; run cdd-kit context-scan before classification"
+    });
+    return findings;
   }
-  const sessionStamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  let migratedCount = 0;
-  let upToDateCount = 0;
-  const backupRoot = join19(cwd, ".cdd", "migrate-backup", sessionStamp);
-  for (const id of idsToMigrate) {
-    const changeDir = join19(cwd, "specs", "changes", id);
-    if (!existsSync16(changeDir)) {
-      log.warn(`  ${id}: directory not found \u2014 skipping`);
-      continue;
-    }
-    const { result, pending, deletes } = migrateOne(id, changeDir, enableContextGovernance);
-    const { changed, warnings } = result;
-    if (changed.length === 0) {
-      log.info(`  ${id}: already up to date`);
-      upToDateCount++;
-      for (const w of warnings)
-        log.warn(`  ${id}: ${w}`);
-      continue;
-    }
-    if (!dryRun) {
-      try {
-        if (!noBackup)
-          backupChangeDir(cwd, id, sessionStamp);
-        commitWritesAtomically(pending, deletes);
-      } catch (err) {
-        log.error(`  ${id}: migration failed \u2014 ${err.message}`);
-        if (!noBackup) {
-          log.error(`  ${id}: restore from .cdd/migrate-backup/${sessionStamp}/${id}/`);
-        }
-        process.exit(1);
+  const projectMapMeta = readContextIndexMetadata(projectMap);
+  const contractsIndexMeta = readContextIndexMetadata(contractsIndex);
+  const projectInputDigest = inputDigest([contextPolicy].filter(existsSync18));
+  if (projectMapMeta.inputsDigest === void 0) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/project-map.md was generated by an older cdd-kit (no inputs-digest); re-run cdd-kit context-scan"
+    });
+  } else if (projectInputDigest && projectMapMeta.inputsDigest !== projectInputDigest) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/project-map.md inputs changed (.cdd/context-policy.json); re-run cdd-kit context-scan"
+    });
+  }
+  const contractsInputDigest = inputDigest(contractFiles);
+  if (contractsIndexMeta.inputsDigest === void 0) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/contracts-index.md was generated by an older cdd-kit (no inputs-digest); re-run cdd-kit context-scan"
+    });
+  } else if (contractsInputDigest && contractsIndexMeta.inputsDigest !== contractsInputDigest) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/contracts-index.md inputs changed (contracts/*); re-run cdd-kit context-scan"
+    });
+  }
+  if (contractsIndexMeta.missingSummary !== void 0 && contractsIndexMeta.missingSummary > 0) {
+    findings.push({
+      level: "warning",
+      message: `contracts-index reports ${contractsIndexMeta.missingSummary} contract(s) without deterministic summary metadata`
+    });
+  }
+  if (findings.length === 0) {
+    findings.push({ level: "ok", message: "context indexes are present and fresh" });
+  }
+  return findings;
+}
+function readAgentModel(path) {
+  try {
+    const text = readFileSync19(path, "utf8");
+    const m = text.match(/^model:\s*(\S+)/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+function checkModelPolicyDrift(cwd) {
+  const policyPath = join21(cwd, ".cdd", "model-policy.json");
+  if (!existsSync18(policyPath))
+    return [];
+  let policy;
+  try {
+    policy = JSON.parse(readFileSync19(policyPath, "utf8"));
+  } catch {
+    return [{ level: "warning", message: ".cdd/model-policy.json is not valid JSON" }];
+  }
+  const roles = policy.roles ?? {};
+  if (Object.keys(roles).length === 0) {
+    return [{
+      level: "warning",
+      message: ".cdd/model-policy.json has no role bindings; run cdd-kit upgrade to install defaults"
+    }];
+  }
+  const candidateDirs = [
+    join21(cwd, ".claude", "agents"),
+    process.env.HOME ? join21(process.env.HOME, ".claude", "agents") : "",
+    process.env.USERPROFILE ? join21(process.env.USERPROFILE, ".claude", "agents") : ""
+  ].filter((p) => p && existsSync18(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 = join21(dir, `${role}.md`);
+      if (!existsSync18(path))
+        continue;
+      foundAny = true;
+      const actual = readAgentModel(path);
+      if (actual && actual !== expected) {
+        findings.push({
+          level: "warning",
+          message: `model-policy drift: ${role} expected ${expected}, agent prompt uses ${actual} (${path})`
+        });
       }
     }
-    log.ok(`  ${id}: migrated`);
-    for (const c of changed)
-      log.info(`    + ${c}`);
-    migratedCount++;
-    for (const w of warnings)
-      log.warn(`  ${id}: ${w}`);
-  }
-  log.blank();
-  if (dryRun) {
-    log.info(`Dry run complete: ${migratedCount} change(s) would be updated, ${upToDateCount} already up to date.`);
-  } else {
-    log.ok(`Migration complete: ${migratedCount} updated, ${upToDateCount} already up to date.`);
-    if (migratedCount > 0 && !noBackup) {
-      log.info(`Backup: ${backupRoot}`);
-      log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to YAML format"');
-      log.info("When stable, remove backup: rm -rf .cdd/migrate-backup/");
+    if (!foundAny) {
     }
   }
-}
-var init_migrate = __esm({
-  "src/commands/migrate.ts"() {
-    "use strict";
-    init_logger();
+  if (findings.length === 0) {
+    findings.push({ level: "ok", message: "model-policy roles match installed agent prompts" });
   }
-});
-
-// src/commands/upgrade.ts
-var upgrade_exports = {};
-__export(upgrade_exports, {
-  upgrade: () => upgrade
-});
-import { existsSync as existsSync17, mkdirSync as mkdirSync8, readdirSync as readdirSync10, copyFileSync as copyFileSync3, readFileSync as readFileSync18, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname5, join as join20, relative as relative4 } from "path";
-function planMissingFiles(srcDir, destDir, label, planned) {
-  if (!existsSync17(srcDir))
-    return;
-  for (const entry of readdirSync10(srcDir, { withFileTypes: true })) {
-    const src = join20(srcDir, entry.name);
-    const dest = join20(destDir, entry.name);
-    if (entry.isDirectory()) {
-      planMissingFiles(src, dest, join20(label, entry.name), planned);
-      continue;
+  return findings;
+}
+async function checkAgentLint(cwd) {
+  const agentsDir = join21(cwd, ".claude", "agents");
+  if (!existsSync18(agentsDir))
+    return [];
+  try {
+    const { readdirSync: rds, readFileSync: rfs } = await import("fs");
+    const files = rds(agentsDir).filter((f) => f.endsWith(".md"));
+    if (files.length === 0)
+      return [];
+    const findings = [];
+    for (const filename of files) {
+      const content = rfs(join21(agentsDir, filename), "utf8");
+      const artifactsSection = content.match(
+        /### Required artifacts for this agent\s*\n[\s\S]*?(?=\n#{2,3} |\n---|\s*$)/
+      )?.[0];
+      if (!artifactsSection || !/```ya?ml\s*\nartifacts:/.test(artifactsSection)) {
+        findings.push({
+          level: "warning",
+          message: `lint-agents: ${filename}: missing artifacts YAML block in Required artifacts section`
+        });
+      }
+      const readScopeCount = (content.match(/^## Read scope\s*$/gm) ?? []).length;
+      if (readScopeCount > 1) {
+        findings.push({
+          level: "warning",
+          message: `lint-agents: ${filename}: duplicate ## Read scope headings (${readScopeCount})`
+        });
+      }
     }
-    if (!existsSync17(dest)) {
-      planned.push({ src, dest, rel: join20(label, relative4(srcDir, src)) });
+    if (findings.length === 0) {
+      findings.push({ level: "ok", message: "lint-agents: all agent prompts pass shape checks" });
     }
+    return findings;
+  } catch {
+    return [];
   }
 }
-function planProviderGuidance(cwd, provider, planned) {
-  if (provider === "claude" || provider === "both") {
-    if (!existsSync17(join20(cwd, "CLAUDE.md"))) {
-      planned.push({ src: ASSET.claudeTemplate, dest: join20(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
-    }
-    if (!existsSync17(join20(cwd, "AGENTS.md"))) {
-      planned.push({ src: ASSET.agentsTemplate, dest: join20(cwd, "AGENTS.md"), rel: "AGENTS.md" });
+function checkCodeMap(cwd) {
+  const findings = [];
+  const mapPath = join21(cwd, ".cdd", "code-map.yml");
+  if (!existsSync18(mapPath)) {
+    const probe2 = checkCodeMapFreshness(cwd);
+    if (probe2.status === "config-error") {
+      findings.push({ level: "warning", message: `.cdd/code-map-config.yml is invalid: ${probe2.configError}` });
+    } else if (probe2.status === "missing-with-sources") {
+      findings.push({ level: "warning", message: ".cdd/code-map.yml is missing; run `cdd-kit code-map`" });
     }
+    return findings;
+  }
+  const probe = checkCodeMapFreshness(cwd);
+  if (probe.status === "config-error") {
+    findings.push({ level: "warning", message: `.cdd/code-map-config.yml is invalid: ${probe.configError}` });
+    return findings;
   }
-  if ((provider === "codex" || provider === "both") && !existsSync17(join20(cwd, "CODEX.md"))) {
-    planned.push({ src: ASSET.codexTemplate, dest: join20(cwd, "CODEX.md"), rel: "CODEX.md" });
+  if (probe.status === "stale") {
+    const top = probe.staleFiles.slice(0, 3).join(", ");
+    const more = probe.staleCount > 3 ? ` (+${probe.staleCount - 3} more)` : "";
+    findings.push({ level: "warning", message: `code-map stale: ${top}${more}; run \`cdd-kit code-map\`` });
   }
-}
-function applyCopy(plan) {
-  for (const item of plan) {
-    mkdirSync8(dirname5(item.dest), { recursive: true });
-    copyFileSync3(item.src, item.dest);
+  const text = readFileSync19(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` });
+  } else {
+    findings.push({ level: "warning", message: ".cdd/code-map.yml has no metadata header (regenerate with cdd-kit 2.0.5+)" });
   }
+  return findings;
 }
-async function upgrade(opts = {}) {
-  const cwd = process.cwd();
+async function buildDoctorReport(cwd, opts) {
   const requestedProvider = opts.provider ?? "auto";
   if (!validateProviderOption(requestedProvider)) {
     log.error(`Invalid provider: ${requestedProvider}. Use auto, claude, codex, or both.`);
     process.exit(1);
   }
+  const strict = opts.strict ?? false;
   const provider = inferProvider(cwd, requestedProvider);
-  const plan = [];
-  planMissingFiles(ASSET.contracts, join20(cwd, "contracts"), "contracts", plan);
-  planMissingFiles(ASSET.specsTemplates, join20(cwd, "specs", "templates"), "specs/templates", plan);
-  planMissingFiles(ASSET.testsTemplates, join20(cwd, "tests", "templates"), "tests/templates", plan);
-  planMissingFiles(ASSET.ci, join20(cwd, "ci"), "ci", plan);
-  planMissingFiles(ASSET.githubWorkflows, join20(cwd, ".github", "workflows"), ".github/workflows", plan);
-  planMissingFiles(ASSET.cddConfig, join20(cwd, ".cdd"), ".cdd", plan);
-  planProviderGuidance(cwd, provider, plan);
-  log.blank();
-  log.info(`Upgrade provider: ${provider}`);
-  if (plan.length === 0) {
-    log.ok("No missing cdd-kit project files found.");
-    if (opts.migrateChanges) {
-      log.blank();
-      log.info("Running change migration flow...");
-      await migrate(void 0, {
-        all: true,
-        dryRun: !opts.yes,
-        enableContextGovernance: opts.enableContextGovernance
-      });
-    }
-    log.blank();
-    return;
+  const findings = [];
+  for (const relPath of ["contracts", "specs/templates", ".cdd/context-policy.json", ".cdd/model-policy.json"]) {
+    findings.push(fileExists(cwd, relPath) ? { level: "ok", message: `${relPath} exists` } : { level: "warning", message: `${relPath} is missing; run cdd-kit upgrade --yes` });
   }
-  log.info(`${plan.length} missing file(s) detected:`);
-  for (const item of plan)
-    log.dim(`  + ${item.rel.replace(/\\/g, "/")}`);
-  if (!opts.yes) {
-    log.blank();
-    log.info("Dry run only. Re-run with --yes to write missing files.");
-    if (opts.migrateChanges) {
-      log.blank();
-      log.info("Previewing existing change migration because --migrate-changes was requested.");
-      await migrate(void 0, {
-        all: true,
-        dryRun: true,
-        enableContextGovernance: opts.enableContextGovernance
+  if ((provider === "claude" || provider === "both") && !fileExists(cwd, "CLAUDE.md")) {
+    findings.push({ level: "warning", message: "CLAUDE.md is missing for Claude provider; run cdd-kit upgrade --provider claude --yes" });
+  }
+  if ((provider === "claude" || provider === "both") && !fileExists(cwd, "AGENTS.md")) {
+    findings.push({ level: "warning", message: "AGENTS.md is missing for Claude provider; run cdd-kit upgrade --provider claude --yes" });
+  }
+  if ((provider === "codex" || provider === "both") && !fileExists(cwd, "CODEX.md")) {
+    findings.push({ level: "warning", message: "CODEX.md is missing for Codex provider; run cdd-kit upgrade --provider codex --yes" });
+  }
+  findings.push(...checkContextFreshness(cwd));
+  findings.push(...checkModelPolicyDrift(cwd));
+  findings.push(...await checkAgentLint(cwd));
+  findings.push(...checkCodeMap(cwd));
+  const errors = findings.filter((finding) => finding.level === "error").length;
+  const warnings = findings.filter((finding) => finding.level === "warning").length;
+  return {
+    provider,
+    strict,
+    findings,
+    errors,
+    warnings,
+    ok: errors === 0 && (!strict || warnings === 0)
+  };
+}
+async function attemptAutoFixes(cwd, report) {
+  const fixed = [];
+  const remaining = [];
+  for (const finding of report.findings) {
+    if (finding.level !== "warning") {
+      remaining.push(finding);
+      continue;
+    }
+    if (/specs\/context indexes are missing|inputs changed|older cdd-kit|older than/i.test(finding.message)) {
+      try {
+        const { contextScan: contextScan2 } = await Promise.resolve().then(() => (init_context_scan(), context_scan_exports));
+        await contextScan2();
+        fixed.push(`ran context-scan to refresh specs/context/`);
+        continue;
+      } catch (err) {
+        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
+        continue;
+      }
+    }
+    if (/code-map stale|code-map\.yml is missing/i.test(finding.message)) {
+      try {
+        const { codeMap: codeMap2 } = await Promise.resolve().then(() => (init_code_map(), code_map_exports));
+        await codeMap2({ path: ".", out: ".cdd/code-map.yml", include: [], exclude: [], check: false, maxLines: 1e5 });
+        fixed.push("regenerated .cdd/code-map.yml");
+        continue;
+      } catch (err) {
+        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
+        continue;
+      }
+    }
+    if (/model-policy\.json has no role bindings/i.test(finding.message)) {
+      const policyPath = join21(cwd, ".cdd", "model-policy.json");
+      try {
+        let existing = {};
+        try {
+          existing = JSON.parse(readFileSync19(policyPath, "utf8"));
+        } catch {
+        }
+        const merged = {
+          ...existing,
+          roles: {
+            "change-classifier": "claude-opus-4-7",
+            "spec-architect": "claude-opus-4-7",
+            "qa-reviewer": "claude-opus-4-7",
+            "contract-reviewer": "claude-sonnet-4-6",
+            "test-strategist": "claude-sonnet-4-6",
+            "backend-engineer": "claude-sonnet-4-6",
+            "frontend-engineer": "claude-sonnet-4-6",
+            "ci-cd-gatekeeper": "claude-sonnet-4-6",
+            "e2e-resilience-engineer": "claude-sonnet-4-6",
+            "monkey-test-engineer": "claude-sonnet-4-6",
+            "stress-soak-engineer": "claude-sonnet-4-6",
+            "ui-ux-reviewer": "claude-sonnet-4-6",
+            "visual-reviewer": "claude-haiku-4-5-20251001",
+            "dependency-security-reviewer": "claude-sonnet-4-6",
+            "spec-drift-auditor": "claude-opus-4-7",
+            "repo-context-scanner": "claude-haiku-4-5-20251001"
+          }
+        };
+        const { writeFileSync: writeFileSync14 } = await import("fs");
+        writeFileSync14(policyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        fixed.push(`populated .cdd/model-policy.json with default role bindings`);
+        continue;
+      } catch (err) {
+        remaining.push({ level: "warning", message: `${finding.message} (auto-fix failed: ${err.message})` });
+        continue;
+      }
+    }
+    if (/\.cdd\/.*is missing|run cdd-kit upgrade/i.test(finding.message)) {
+      remaining.push({
+        level: "warning",
+        message: `${finding.message} (run \`cdd-kit upgrade --yes\` manually \u2014 too invasive for --fix)`
       });
+      continue;
     }
+    remaining.push(finding);
+  }
+  return { fixed, remaining };
+}
+async function doctor(opts = {}) {
+  const cwd = process.cwd();
+  let report = await buildDoctorReport(cwd, opts);
+  if (opts.fix && !opts.json) {
     log.blank();
+    log.info("Doctor --fix: attempting safe auto-resolutions\u2026");
+    const { fixed, remaining } = await attemptAutoFixes(cwd, report);
+    for (const f of fixed)
+      log.ok(`fixed: ${f}`);
+    if (fixed.length > 0) {
+      report = await buildDoctorReport(cwd, opts);
+    } else {
+      log.info("no auto-fixable findings");
+    }
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.ok)
+      process.exit(1);
     return;
   }
-  applyCopy(plan);
-  const modelPolicyPath = join20(cwd, ".cdd", "model-policy.json");
-  if (existsSync17(modelPolicyPath)) {
-    let existing = {};
-    try {
-      existing = JSON.parse(readFileSync18(modelPolicyPath, "utf8"));
-    } catch {
-    }
-    const merged = {
-      ...existing,
-      provider,
-      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
-      roles: existing.roles && typeof existing.roles === "object" ? existing.roles : {}
-    };
-    writeFileSync9(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  log.blank();
+  log.info(`Doctor provider: ${report.provider}`);
+  for (const finding of report.findings) {
+    if (finding.level === "ok")
+      log.ok(finding.message);
+    else if (finding.level === "warning")
+      log.warn(finding.message);
+    else
+      log.error(finding.message);
   }
   log.blank();
-  log.ok(`Upgrade complete: ${plan.length} missing file(s) added.`);
-  log.info("Existing project guidance and contracts were preserved.");
-  if (opts.migrateChanges) {
-    log.blank();
-    log.info("Running change migration flow...");
-    await migrate(void 0, {
-      all: true,
-      dryRun: false,
-      enableContextGovernance: opts.enableContextGovernance
-    });
+  if (!report.ok) {
+    log.error(report.strict && report.errors === 0 ? `doctor failed in strict mode with ${report.warnings} warning(s)` : `doctor failed with ${report.errors} error(s)`);
+    process.exit(1);
+  }
+  if (report.warnings > 0) {
+    log.warn(`doctor completed with ${report.warnings} warning(s)`);
+  } else {
+    log.ok("doctor passed");
   }
   log.blank();
 }
-var init_upgrade = __esm({
-  "src/commands/upgrade.ts"() {
+var init_doctor = __esm({
+  "src/commands/doctor.ts"() {
     "use strict";
-    init_paths();
     init_logger();
     init_provider();
-    init_migrate();
+    init_freshness();
   }
 });
 
@@ -9347,8 +9919,8 @@ var lint_agents_exports = {};
 __export(lint_agents_exports, {
   lintAgents: () => lintAgents
 });
-import { readdirSync as readdirSync11, readFileSync as readFileSync19 } from "fs";
-import { join as join21 } from "path";
+import { readdirSync as readdirSync12, readFileSync as readFileSync20 } from "fs";
+import { join as join22 } from "path";
 import { load as yamlLoad2 } from "js-yaml";
 function extractRequiredArtifactsSection(content) {
   const match = content.match(
@@ -9389,20 +9961,20 @@ function hasFlatBacktickKeysWithoutFence(section) {
 }
 async function lintAgents(opts) {
   const cwd = process.cwd();
-  const agentsDir = join21(cwd, ".claude", "agents");
+  const agentsDir = join22(cwd, ".claude", "agents");
   let files;
   try {
-    files = readdirSync11(agentsDir).filter((f) => f.endsWith(".md")).sort();
+    files = readdirSync12(agentsDir).filter((f) => f.endsWith(".md")).sort();
   } catch {
     log.error(`lint-agents: cannot read ${agentsDir} \u2014 is this a cdd-kit project?`);
     return 1;
   }
   const violations = [];
   for (const filename of files) {
-    const filePath = join21(agentsDir, filename);
+    const filePath = join22(agentsDir, filename);
     let content;
     try {
-      content = readFileSync19(filePath, "utf8");
+      content = readFileSync20(filePath, "utf8");
     } catch {
       violations.push({
         file: filename,
@@ -9514,28 +10086,28 @@ var archive_exports = {};
 __export(archive_exports, {
   archive: () => archive
 });
-import { join as join22 } from "path";
-import { existsSync as existsSync18, mkdirSync as mkdirSync9, renameSync as renameSync2, readFileSync as readFileSync20, writeFileSync as writeFileSync10, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
+import { join as join23 } from "path";
+import { existsSync as existsSync19, mkdirSync as mkdirSync10, renameSync as renameSync2, readFileSync as readFileSync21, writeFileSync as writeFileSync11, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
 import yaml4 from "js-yaml";
 async function archive(changeId) {
   const cwd = process.cwd();
-  const changeDir = join22(cwd, "specs", "changes", changeId);
+  const changeDir = join23(cwd, "specs", "changes", changeId);
   const archiveYear = (/* @__PURE__ */ new Date()).getFullYear().toString();
-  const archiveBase = join22(cwd, "specs", "archive", archiveYear);
-  const archiveDir = join22(archiveBase, changeId);
-  const indexPath = join22(cwd, "specs", "archive", "INDEX.md");
-  if (!existsSync18(changeDir)) {
+  const archiveBase = join23(cwd, "specs", "archive", archiveYear);
+  const archiveDir = join23(archiveBase, changeId);
+  const indexPath = join23(cwd, "specs", "archive", "INDEX.md");
+  if (!existsSync19(changeDir)) {
     log.error(`Change not found: specs/changes/${changeId}`);
     process.exit(1);
   }
-  if (existsSync18(archiveDir)) {
+  if (existsSync19(archiveDir)) {
     log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
     process.exit(1);
   }
-  const tasksPath = join22(changeDir, "tasks.yml");
-  if (existsSync18(tasksPath)) {
+  const tasksPath = join23(changeDir, "tasks.yml");
+  if (existsSync19(tasksPath)) {
     try {
-      const raw = readFileSync20(tasksPath, "utf8");
+      const raw = readFileSync21(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).");
@@ -9548,8 +10120,8 @@ async function archive(changeId) {
       log.warn("tasks.yml could not be parsed \u2014 archiving anyway.");
     }
   }
-  if (!existsSync18(archiveBase)) {
-    mkdirSync9(archiveBase, { recursive: true });
+  if (!existsSync19(archiveBase)) {
+    mkdirSync10(archiveBase, { recursive: true });
   }
   try {
     renameSync2(changeDir, archiveDir);
@@ -9565,8 +10137,8 @@ async function archive(changeId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const indexLine = `| ${changeId} | ${archiveYear} | ${today} | specs/archive/${archiveYear}/${changeId}/ |
 `;
-  if (!existsSync18(indexPath)) {
-    writeFileSync10(indexPath, `# Archive Index
+  if (!existsSync19(indexPath)) {
+    writeFileSync11(indexPath, `# Archive Index
 
 | change-id | year | archived-date | path |
 |---|---|---|---|
@@ -9590,37 +10162,37 @@ var abandon_exports = {};
 __export(abandon_exports, {
   abandon: () => abandon
 });
-import { join as join23 } from "path";
-import { existsSync as existsSync19, readFileSync as readFileSync21, writeFileSync as writeFileSync11, appendFileSync as appendFileSync2, mkdirSync as mkdirSync10 } from "fs";
+import { join as join24 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync22, writeFileSync as writeFileSync12, appendFileSync as appendFileSync2, mkdirSync as mkdirSync11 } from "fs";
 import yaml5 from "js-yaml";
 async function abandon(changeId, opts) {
   const cwd = process.cwd();
-  const changeDir = join23(cwd, "specs", "changes", changeId);
-  const tasksPath = join23(changeDir, "tasks.yml");
-  if (!existsSync19(changeDir)) {
+  const changeDir = join24(cwd, "specs", "changes", changeId);
+  const tasksPath = join24(changeDir, "tasks.yml");
+  if (!existsSync20(changeDir)) {
     log.error(`Change not found: specs/changes/${changeId}`);
     process.exit(1);
   }
-  if (existsSync19(tasksPath)) {
-    const raw = readFileSync21(tasksPath, "utf8");
+  if (existsSync20(tasksPath)) {
+    const raw = readFileSync22(tasksPath, "utf8");
     const data = yaml5.load(raw) ?? {};
     data["status"] = "abandoned";
     if (!data["change-id"]) {
       data["change-id"] = changeId;
     }
-    writeFileSync11(tasksPath, yaml5.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
+    writeFileSync12(tasksPath, yaml5.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const archiveDir = join23(cwd, "specs", "archive");
-  const indexPath = join23(archiveDir, "INDEX.md");
+  const archiveDir = join24(cwd, "specs", "archive");
+  const indexPath = join24(archiveDir, "INDEX.md");
   const reason = opts.reason ?? "no reason given";
   const indexLine = `| ${changeId} | abandoned | ${today} | ${reason} |
 `;
-  if (!existsSync19(archiveDir)) {
-    mkdirSync10(archiveDir, { recursive: true });
+  if (!existsSync20(archiveDir)) {
+    mkdirSync11(archiveDir, { recursive: true });
   }
-  if (!existsSync19(indexPath)) {
-    writeFileSync11(indexPath, `# Archive Index
+  if (!existsSync20(indexPath)) {
+    writeFileSync12(indexPath, `# Archive Index
 
 | change-id | status | date | notes |
 |---|---|---|---|
@@ -9644,28 +10216,28 @@ var list_changes_exports = {};
 __export(list_changes_exports, {
   listChanges: () => listChanges
 });
-import { join as join24 } from "path";
-import { existsSync as existsSync20, readdirSync as readdirSync12, readFileSync as readFileSync22 } from "fs";
+import { join as join25 } from "path";
+import { existsSync as existsSync21, readdirSync as readdirSync13, readFileSync as readFileSync23 } from "fs";
 import yaml6 from "js-yaml";
 async function listChanges() {
   const cwd = process.cwd();
-  const changesDir = join24(cwd, "specs", "changes");
+  const changesDir = join25(cwd, "specs", "changes");
   log.blank();
   const active = [];
-  if (existsSync20(changesDir)) {
-    active.push(...readdirSync12(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name));
+  if (existsSync21(changesDir)) {
+    active.push(...readdirSync13(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 = join24(changesDir, id, "tasks.yml");
+      const tasksPath = join25(changesDir, id, "tasks.yml");
       let status = "in-progress";
       let pending = 0;
-      if (existsSync20(tasksPath)) {
+      if (existsSync21(tasksPath)) {
         try {
-          const raw = readFileSync22(tasksPath, "utf8");
+          const raw = readFileSync23(tasksPath, "utf8");
           const data = yaml6.load(raw);
           if (data?.status)
             status = data.status;
@@ -9696,8 +10268,8 @@ __export(context_exports, {
   rejectContextExpansion: () => rejectContextExpansion,
   requestContextExpansion: () => requestContextExpansion
 });
-import { existsSync as existsSync21, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync24, writeFileSync as writeFileSync13 } from "fs";
+import { join as join26 } from "path";
 function normalizePath(path) {
   return path.replace(/\\/g, "/").replace(/^\.\//, "").trim();
 }
@@ -9711,18 +10283,18 @@ function validateRepoRelativePath(path) {
   return null;
 }
 function manifestPathFor(changeId) {
-  return join25(process.cwd(), "specs", "changes", changeId, "context-manifest.md");
+  return join26(process.cwd(), "specs", "changes", changeId, "context-manifest.md");
 }
 function readManifest(changeId) {
   const manifestPath = manifestPathFor(changeId);
-  if (!existsSync21(manifestPath)) {
+  if (!existsSync22(manifestPath)) {
     log.error(`context manifest not found: specs/changes/${changeId}/context-manifest.md`);
     process.exit(1);
   }
-  return readFileSync23(manifestPath, "utf8");
+  return readFileSync24(manifestPath, "utf8");
 }
 function writeManifest(changeId, content) {
-  writeFileSync12(manifestPathFor(changeId), content.endsWith("\n") ? content : `${content}
+  writeFileSync13(manifestPathFor(changeId), content.endsWith("\n") ? content : `${content}
 `, "utf8");
 }
 function sectionBody(content, heading) {
@@ -9947,9 +10519,9 @@ var init_context = __esm({
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync24 } from "fs";
+import { readFileSync as readFileSync25 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { dirname as dirname6, join as join26 } from "path";
+import { dirname as dirname7, join as join27 } from "path";
 import { Command } from "commander";
 
 // src/commands/init.ts
@@ -10364,167 +10936,8 @@ async function init(opts) {
   log.blank();
 }
 
-// src/commands/update.ts
-init_paths();
-init_logger();
-init_provider();
-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 { createHash } from "crypto";
-import { homedir as homedir2 } from "os";
-function fileHash(filePath) {
-  const buf = readFileSync5(filePath);
-  return createHash("sha256").update(buf).digest("hex");
-}
-function diffDir(src, dest) {
-  const entries = [];
-  if (!existsSync6(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);
-      if (item.isDirectory()) {
-        walk(srcPath, destPath);
-      } else {
-        if (!existsSync6(destPath)) {
-          entries.push({ src: srcPath, dest: destPath, action: "add" });
-        } else if (fileHash(srcPath) !== fileHash(destPath)) {
-          entries.push({ src: srcPath, dest: destPath, action: "overwrite" });
-        } else {
-          entries.push({ src: srcPath, dest: destPath, action: "skip" });
-        }
-      }
-    }
-  }
-  walk(src, dest);
-  return entries;
-}
-function applyDir(entries) {
-  let count = 0;
-  for (const e of entries) {
-    if (e.action === "skip")
-      continue;
-    mkdirSync3(join7(e.dest, ".."), { recursive: true });
-    copyFileSync2(e.src, e.dest);
-    count += 1;
-  }
-  return count;
-}
-function backupDir(dir, backupDest) {
-  if (!existsSync6(dir))
-    return;
-  mkdirSync3(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);
-      if (item.isDirectory()) {
-        mkdirSync3(d, { recursive: true });
-        walk(s, d);
-      } else
-        copyFileSync2(s, d);
-    }
-  }
-  walk(dir, backupDest);
-}
-async function update(opts) {
-  if (opts.postinstall) {
-    if (!existsSync6(join7(SKILLS_HOME, "contract-driven-delivery"))) {
-      return;
-    }
-    opts.yes = true;
-    opts.provider = "claude";
-  }
-  const quiet = !!opts.postinstall;
-  if (!quiet)
-    log.blank();
-  const cwd = process.cwd();
-  const requestedProvider = opts.provider ?? "auto";
-  if (!validateProviderOption(requestedProvider)) {
-    log.error(`Invalid provider: ${requestedProvider}. Use auto, claude, codex, or both.`);
-    process.exit(1);
-  }
-  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 toWrite = [...agentDiff, ...skillDiff].filter((e) => e.action !== "skip");
-  const toAdd = toWrite.filter((e) => e.action === "add");
-  const toOver = toWrite.filter((e) => e.action === "overwrite");
-  const toSkip = [...agentDiff, ...skillDiff].filter((e) => e.action === "skip");
-  if (!quiet) {
-    log.info(`Provider: ${provider}`);
-    if (updateClaudeAssets) {
-      log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
-      log.info(`Dry-run diff \u2014 skills: ${SKILLS_HOME}`);
-    } else {
-      log.info("Codex provider has no global cdd-kit assets to update.");
-      log.info("Project files are preserved; run cdd-kit init --local-only --provider codex to add missing local guidance.");
-    }
-    log.blank();
-    if (toAdd.length)
-      log.info(`  + ${toAdd.length} file(s) would be added`);
-    if (toOver.length)
-      log.warn(`  ~ ${toOver.length} file(s) would be overwritten (user edits lost without backup)`);
-    if (toSkip.length)
-      log.dim(`    ${toSkip.length} file(s) unchanged (skipped)`);
-  }
-  if (toWrite.length === 0) {
-    if (!quiet) {
-      log.blank();
-      log.ok("Already up to date \u2014 nothing to write.");
-      log.blank();
-    }
-    return;
-  }
-  if (!quiet && !opts.yes) {
-    log.blank();
-    log.info("Run with --yes to apply changes. Example:");
-    log.dim("  cdd-kit update --yes");
-    log.blank();
-    return;
-  }
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const backupRoot = join7(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"));
-  if (!quiet)
-    log.ok(`Backup complete: ${backupRoot}`);
-  if (!quiet)
-    log.blank();
-  let totalSynced = 0;
-  if (updateClaudeAssets) {
-    if (!quiet)
-      log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
-    const agentCount = applyDir(agentDiff);
-    if (!quiet)
-      log.ok(`${agentCount} agent file(s) updated.`);
-    totalSynced += agentCount;
-    if (!quiet)
-      log.info(`Updating skills \u2192 ${SKILLS_HOME}`);
-    const skillCount = applyDir(skillDiff);
-    if (!quiet)
-      log.ok(`${skillCount} skill file(s) updated.`);
-    totalSynced += skillCount;
-  }
-  if (quiet) {
-    if (totalSynced > 0)
-      log.ok(`cdd-kit: synced ${totalSynced} file(s) to ~/.claude/`);
-  } else {
-    log.blank();
-    log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
-    log.ok("Update complete.");
-    log.info(`Backup saved to: ${backupRoot}`);
-    log.blank();
-  }
-}
+// src/cli/index.ts
+init_update();
 
 // src/commands/new-change.ts
 init_paths();
@@ -11513,8 +11926,8 @@ async function installHooks() {
 }
 
 // src/cli/index.ts
-var __dirname2 = dirname6(fileURLToPath3(import.meta.url));
-var pkg = JSON.parse(readFileSync24(join26(__dirname2, "..", "..", "package.json"), "utf8"));
+var __dirname2 = dirname7(fileURLToPath3(import.meta.url));
+var pkg = JSON.parse(readFileSync25(join27(__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(
@@ -11529,6 +11942,18 @@ program.command("init").description(
   })
 );
 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 }));
+program.command("refresh").description("Complete upgrade: refresh agents, skills, templates, hooks, model-policy, and code-map in one command").option("--yes", "Apply changes (default is dry-run)", false).option("--no-templates", "Skip force-refresh of specs/templates, tests/templates, ci-templates, .github/workflows").option("--no-hooks", "Skip pre-commit hook re-installation").option("--no-code-map", "Skip code-map regeneration").option("--no-update", "Skip ~/.claude update step").option("--no-upgrade", "Skip project add-missing step").option("--provider <provider>", "Provider adapter: auto, claude, codex, or both", "auto").action(async (opts) => {
+  const { refresh: refresh2 } = await Promise.resolve().then(() => (init_refresh(), refresh_exports));
+  await refresh2({
+    yes: opts.yes,
+    noTemplates: opts.templates === false,
+    noHooks: opts.hooks === false,
+    noCodeMap: opts.codeMap === false,
+    noUpdate: opts.update === false,
+    noUpgrade: opts.upgrade === false,
+    provider: opts.provider
+  });
+});
 program.command("doctor").description("Inspect cdd-kit repo health, provider guidance, and context index freshness").option("--strict", "Treat warnings as errors", false).option("--json", "Print a machine-readable health report", false).option("--provider <provider>", "Provider adapter to inspect: auto, claude, codex, or both", "auto").option("--fix", "Auto-resolve safe warnings (stale context indexes, missing role bindings)", false).action(async (opts) => {
   const { doctor: doctor2 } = await Promise.resolve().then(() => (init_doctor(), doctor_exports));
   await doctor2({ strict: opts.strict, json: opts.json, provider: opts.provider, fix: opts.fix });