contract-driven-delivery 1.11.0 → 1.16.0

package/dist/cli/index.js

@@ -8,6 +8,38 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/utils/paths.ts
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+var __dirname, PACKAGE_ROOT, ASSETS_DIR, CLAUDE_HOME, AGENTS_HOME, SKILLS_HOME, ASSET;
+var init_paths = __esm({
+  "src/utils/paths.ts"() {
+    "use strict";
+    __dirname = dirname(fileURLToPath(import.meta.url));
+    PACKAGE_ROOT = join(__dirname, "..", "..");
+    ASSETS_DIR = join(PACKAGE_ROOT, "assets");
+    CLAUDE_HOME = join(homedir(), ".claude");
+    AGENTS_HOME = join(CLAUDE_HOME, "agents");
+    SKILLS_HOME = join(CLAUDE_HOME, "skills");
+    ASSET = {
+      agents: join(ASSETS_DIR, "agents"),
+      skills: join(ASSETS_DIR, "skills"),
+      skill: join(ASSETS_DIR, "skills", "contract-driven-delivery"),
+      contracts: join(ASSETS_DIR, "contracts"),
+      specsTemplates: join(ASSETS_DIR, "specs-templates"),
+      testsTemplates: join(ASSETS_DIR, "tests-templates"),
+      ci: join(ASSETS_DIR, "ci"),
+      githubWorkflows: join(ASSETS_DIR, "github-workflows"),
+      hooks: join(ASSETS_DIR, "hooks"),
+      claudeTemplate: join(ASSETS_DIR, "CLAUDE.template.md"),
+      codexTemplate: join(ASSETS_DIR, "CODEX.template.md"),
+      agentsTemplate: join(ASSETS_DIR, "AGENTS.template.md"),
+      cddConfig: join(ASSETS_DIR, "cdd")
+    };
+  }
+});
+
 // src/utils/logger.ts
 var RESET, CYAN, GREEN, YELLOW, RED, DIM, log;
 var init_logger = __esm({
@@ -42,131 +74,621 @@ var init_logger = __esm({
   }
 });
 
-// src/commands/archive.ts
-var archive_exports = {};
-__export(archive_exports, {
-  archive: () => archive
+// src/utils/provider.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { join as join5 } from "path";
+function validateProviderOption(provider) {
+  return provider === "auto" || provider === "claude" || provider === "codex" || provider === "both";
+}
+function inferProvider(cwd, requested = "auto") {
+  if (requested !== "auto")
+    return requested;
+  const modelPolicyPath = join5(cwd, ".cdd", "model-policy.json");
+  if (existsSync4(modelPolicyPath)) {
+    try {
+      const policy = JSON.parse(readFileSync3(modelPolicyPath, "utf8"));
+      if (policy.provider === "claude" || policy.provider === "codex" || policy.provider === "both") {
+        return policy.provider;
+      }
+    } catch {
+    }
+  }
+  const hasClaude = existsSync4(join5(cwd, "CLAUDE.md")) || existsSync4(join5(cwd, "AGENTS.md"));
+  const hasCodex = existsSync4(join5(cwd, "CODEX.md"));
+  if (hasClaude && hasCodex)
+    return "both";
+  if (hasCodex)
+    return "codex";
+  return "claude";
+}
+var init_provider = __esm({
+  "src/utils/provider.ts"() {
+    "use strict";
+  }
 });
-import { join as join10 } from "path";
-import { existsSync as existsSync9, mkdirSync as mkdirSync4, renameSync, readFileSync as readFileSync6, writeFileSync as writeFileSync3, appendFileSync, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
-async function archive(changeId) {
-  const cwd = process.cwd();
-  const changeDir = join10(cwd, "specs", "changes", changeId);
-  const archiveYear = (/* @__PURE__ */ new Date()).getFullYear().toString();
-  const archiveBase = join10(cwd, "specs", "archive", archiveYear);
-  const archiveDir = join10(archiveBase, changeId);
-  const indexPath = join10(cwd, "specs", "archive", "INDEX.md");
-  if (!existsSync9(changeDir)) {
-    log.error(`Change not found: specs/changes/${changeId}`);
-    process.exit(1);
+
+// src/commands/context-scan.ts
+var context_scan_exports = {};
+__export(context_scan_exports, {
+  contextScan: () => contextScan
+});
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync5, readdirSync as readdirSync4, writeFileSync as writeFileSync2 } from "fs";
+import { createHash as createHash2 } from "crypto";
+import { basename, dirname as dirname3, join as join7, relative as relative2 } from "path";
+function sha256OfFile(path) {
+  try {
+    return createHash2("sha256").update(readFileSync5(path)).digest("hex");
+  } catch {
+    return "";
   }
-  if (existsSync9(archiveDir)) {
-    log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
-    process.exit(1);
+}
+function inputsDigest(paths) {
+  const combined = paths.slice().sort().map((p) => `${p}:${sha256OfFile(p)}`).join("\n");
+  return createHash2("sha256").update(combined).digest("hex");
+}
+function stripGlobSuffix(pattern) {
+  return pattern.replace(/\/\*\*$/, "").replace(/\/\*$/, "");
+}
+function getForbiddenPaths(cwd) {
+  const forbidden = new Set(DEFAULT_FORBIDDEN);
+  const policyPath = join7(cwd, ".cdd", "context-policy.json");
+  try {
+    if (existsSync6(policyPath)) {
+      const policy = JSON.parse(readFileSync5(policyPath, "utf8"));
+      for (const pattern of policy.forbiddenPaths ?? []) {
+        forbidden.add(stripGlobSuffix(pattern));
+      }
+    }
+  } catch {
+    log.warn("Could not parse .cdd/context-policy.json; using default context-scan excludes.");
   }
-  const tasksPath = join10(changeDir, "tasks.md");
-  if (existsSync9(tasksPath)) {
-    const content = readFileSync6(tasksPath, "utf8");
-    if (content.includes("status: gate-blocked")) {
-      log.warn("tasks.md has status: gate-blocked \u2014 archiving anyway (change was paused).");
+  return [...forbidden];
+}
+function isForbidden(relPath, forbidden) {
+  const normalized = relPath.replace(/\\/g, "/");
+  return forbidden.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`));
+}
+function buildTree(dir, cwd, forbidden, stats, prefix = "", depth = 0) {
+  const entries = readdirSync4(dir, { withFileTypes: true }).sort((a, b) => {
+    if (a.isDirectory() === b.isDirectory())
+      return a.name.localeCompare(b.name);
+    return a.isDirectory() ? -1 : 1;
+  });
+  let output = "";
+  const visible = entries.filter((entry) => {
+    const relPath = relative2(cwd, join7(dir, entry.name));
+    return !isForbidden(relPath, forbidden);
+  });
+  const truncated = visible.length > PER_DIR_ENTRY_CAP;
+  const shown = truncated ? visible.slice(0, PER_DIR_ENTRY_CAP) : visible;
+  if (truncated)
+    stats.truncatedDirs += 1;
+  shown.forEach((entry, index) => {
+    const fullPath = join7(dir, entry.name);
+    const isLast = index === shown.length - 1 && !truncated;
+    const connector = isLast ? "\\-- " : "|-- ";
+    output += `${prefix}${connector}${entry.name}${entry.isDirectory() ? "/" : ""}
+`;
+    if (entry.isDirectory()) {
+      stats.dirs += 1;
+      if (depth >= 3) {
+        stats.omittedDirs += 1;
+        output += `${prefix}${isLast ? "    " : "|   "}\\-- ... (max depth)
+`;
+      } else {
+        output += buildTree(fullPath, cwd, forbidden, stats, prefix + (isLast ? "    " : "|   "), depth + 1);
+      }
+    } else {
+      stats.files += 1;
     }
-    const pending = (content.match(/^\s*-\s*\[ \]/gm) || []).length;
-    if (pending > 0) {
-      log.warn(`${pending} task(s) still pending ([ ]). Archive anyway.`);
+  });
+  if (truncated) {
+    output += `${prefix}\\-- ... (${visible.length - PER_DIR_ENTRY_CAP} more entries truncated; cap=${PER_DIR_ENTRY_CAP})
+`;
+  }
+  return output;
+}
+function firstHeading(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match?.[1]?.trim();
+}
+function deriveContractType(relPath, metadata) {
+  if (metadata.contract)
+    return metadata.contract;
+  const parts = relPath.split("/");
+  return parts.length >= 2 ? parts[1] : "unknown";
+}
+function parseContractMetadata(content) {
+  const metadata = {};
+  let summary;
+  const cddMatch = content.match(/<!--\s*cdd:([\s\S]*?)-->/);
+  const yamlMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const block = cddMatch?.[1] ?? yamlMatch?.[1];
+  if (block) {
+    for (const line of block.split(/\r?\n/)) {
+      const colon = line.indexOf(":");
+      if (colon === -1)
+        continue;
+      const key = line.slice(0, colon).trim();
+      const value = line.slice(colon + 1).trim();
+      if (!key || !value)
+        continue;
+      if (key === "summary")
+        summary = value;
+      else
+        metadata[key] = value;
     }
   }
-  if (!existsSync9(archiveBase)) {
-    mkdirSync4(archiveBase, { recursive: true });
+  if (!summary) {
+    const summaryMatch = content.match(/#+\s*Summary\s*\r?\n+([^#\r\n][^\r\n]*)/i);
+    summary = summaryMatch?.[1]?.trim();
   }
-  try {
-    renameSync(changeDir, archiveDir);
-  } catch (err) {
-    if (err.code === "EXDEV") {
-      cpSync2(changeDir, archiveDir, { recursive: true });
-      rmSync2(changeDir, { recursive: true, force: true });
-    } else {
-      throw err;
+  return { title: firstHeading(content), summary, metadata };
+}
+function findContractFiles(dir, found = []) {
+  if (!existsSync6(dir))
+    return found;
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    const fullPath = join7(dir, entry.name);
+    if (entry.isDirectory())
+      findContractFiles(fullPath, found);
+    else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "INDEX.md" && entry.name !== "CHANGELOG.md")
+      found.push(fullPath);
+  }
+  return found;
+}
+async function contextScan(opts = {}) {
+  const cwd = process.cwd();
+  const specsContextDir = join7(cwd, "specs", "context");
+  mkdirSync3(specsContextDir, { recursive: true });
+  const forbidden = getForbiddenPaths(cwd);
+  const surface = opts.surface;
+  let scanRoot = cwd;
+  if (surface) {
+    const resolvedSurface = join7(cwd, surface);
+    if (!existsSync6(resolvedSurface)) {
+      log.error(`--surface path not found: ${surface}`);
+      process.exit(1);
     }
-  }
-  log.ok(`Archived: specs/changes/${changeId} \u2192 specs/archive/${archiveYear}/${changeId}`);
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const indexLine = `| ${changeId} | ${archiveYear} | ${today} | specs/archive/${archiveYear}/${changeId}/ |
+    if (!resolvedSurface.startsWith(cwd)) {
+      log.error(`--surface must be inside the repo: ${surface}`);
+      process.exit(1);
+    }
+    scanRoot = resolvedSurface;
+  }
+  const treeStats = { dirs: 0, files: 0, omittedDirs: 0, truncatedDirs: 0 };
+  const tree = buildTree(scanRoot, cwd, forbidden, treeStats);
+  const policyPath = join7(cwd, ".cdd", "context-policy.json");
+  const projectMapInputs = [policyPath].filter(existsSync6);
+  writeFileSync2(
+    join7(specsContextDir, "project-map.md"),
+    [
+      "---",
+      "artifact: project-map",
+      "generated-by: cdd-kit context-scan",
+      "schema-version: 1",
+      `root: ${basename(cwd)}`,
+      ...surface ? [`surface: ${surface}`] : [],
+      `visible-dirs: ${treeStats.dirs}`,
+      `visible-files: ${treeStats.files}`,
+      `omitted-dirs: ${treeStats.omittedDirs}`,
+      `truncated-dirs: ${treeStats.truncatedDirs}`,
+      `inputs-digest: ${inputsDigest(projectMapInputs)}`,
+      "---",
+      "",
+      "# Project Map",
+      "",
+      "Use this deterministic map to choose candidate context paths before reading files.",
+      "",
+      "## Excluded Paths",
+      ...forbidden.map((path) => `- ${path}`),
+      "",
+      "## Tree",
+      "",
+      "```",
+      `${basename(cwd)}/`,
+      tree.trimEnd(),
+      "```",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  log.ok("Created specs/context/project-map.md");
+  const contractFiles = findContractFiles(join7(cwd, "contracts")).sort((a, b) => relative2(cwd, a).localeCompare(relative2(cwd, b)));
+  const contractEntries = [];
+  const inventoryRows = [];
+  let missingSummary = 0;
+  for (const file of contractFiles) {
+    const relPath = relative2(cwd, file).replace(/\\/g, "/");
+    const dir = dirname3(relPath).replace(/\\/g, "/");
+    const { title, summary, metadata } = parseContractMetadata(readFileSync5(file, "utf8"));
+    const contractType = deriveContractType(relPath, metadata);
+    const owner = metadata.owner ?? "unknown";
+    const surface2 = metadata.surface ?? dir;
+    const summaryText = summary ?? "MISSING - add YAML frontmatter `summary:` or `<!-- cdd: summary: ... -->`.";
+    inventoryRows.push(`| ${relPath} | ${contractType} | ${surface2} | ${owner} | ${summary ? "yes" : "no"} |`);
+    let entry = `## ${relPath}
+`;
+    entry += `- path: \`${relPath}\`
+`;
+    entry += `- type: ${contractType}
+`;
+    entry += `- directory: ${dir}
 `;
-  if (!existsSync9(indexPath)) {
-    writeFileSync3(indexPath, `# Archive Index
+    if (title)
+      entry += `- title: ${title}
+`;
+    for (const [key, value] of Object.entries(metadata)) {
+      if (key === "contract")
+        continue;
+      entry += `- ${key}: ${value}
+`;
+    }
+    entry += `- summary: ${summaryText}
 
-| change-id | year | archived-date | path |
-|---|---|---|---|
-${indexLine}`, "utf8");
+`;
+    contractEntries.push(entry);
+    if (!summary) {
+      missingSummary += 1;
+    }
+  }
+  const contractIndex = [
+    "---",
+    "artifact: contracts-index",
+    "generated-by: cdd-kit context-scan",
+    "schema-version: 1",
+    `contract-count: ${contractFiles.length}`,
+    `missing-summary-count: ${missingSummary}`,
+    `inputs-digest: ${inputsDigest(contractFiles)}`,
+    "---",
+    "",
+    "# Contracts Index",
+    "",
+    "Generated from deterministic metadata. Add YAML frontmatter fields such as `summary`, `owner`, and `surface` to improve classifier accuracy.",
+    "",
+    "## Contract Inventory",
+    "",
+    "| path | type | surface | owner | has-summary |",
+    "|---|---|---|---|---|",
+    ...inventoryRows,
+    "",
+    "## Contract Details",
+    "",
+    ...contractEntries
+  ].join("\n");
+  writeFileSync2(join7(specsContextDir, "contracts-index.md"), contractIndex, "utf8");
+  if (missingSummary > 0) {
+    log.warn(`Created specs/context/contracts-index.md with ${missingSummary} missing summary warning(s).`);
   } else {
-    appendFileSync(indexPath, indexLine, "utf8");
+    log.ok("Created specs/context/contracts-index.md");
   }
-  log.ok(`Index updated: specs/archive/INDEX.md`);
-  log.blank();
-  log.info(`Next: promote durable learnings from archive.md to contracts/ or CLAUDE.md`);
 }
-var init_archive = __esm({
-  "src/commands/archive.ts"() {
+var DEFAULT_FORBIDDEN, PER_DIR_ENTRY_CAP;
+var init_context_scan = __esm({
+  "src/commands/context-scan.ts"() {
     "use strict";
     init_logger();
+    DEFAULT_FORBIDDEN = [
+      ".claude",
+      ".git",
+      "node_modules",
+      "dist",
+      "build",
+      "assets",
+      "specs/archive",
+      "specs/changes"
+    ];
+    PER_DIR_ENTRY_CAP = 50;
   }
 });
 
-// src/commands/abandon.ts
-var abandon_exports = {};
-__export(abandon_exports, {
-  abandon: () => abandon
+// src/commands/doctor.ts
+var doctor_exports = {};
+__export(doctor_exports, {
+  doctor: () => doctor
 });
-import { join as join11 } from "path";
-import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync4, appendFileSync as appendFileSync2, mkdirSync as mkdirSync5 } from "fs";
-async function abandon(changeId, opts) {
-  const cwd = process.cwd();
-  const changeDir = join11(cwd, "specs", "changes", changeId);
-  const tasksPath = join11(changeDir, "tasks.md");
-  if (!existsSync10(changeDir)) {
-    log.error(`Change not found: specs/changes/${changeId}`);
+import { existsSync as existsSync11, readdirSync as readdirSync7, readFileSync as readFileSync9 } from "fs";
+import { createHash as createHash4 } from "crypto";
+import { join as join12 } from "path";
+function fileExists(cwd, relPath) {
+  return existsSync11(join12(cwd, relPath));
+}
+function findFiles(dir, predicate, found = []) {
+  if (!existsSync11(dir))
+    return found;
+  for (const entry of readdirSync7(dir, { withFileTypes: true })) {
+    const fullPath = join12(dir, entry.name);
+    if (entry.isDirectory())
+      findFiles(fullPath, predicate, found);
+    else if (entry.isFile() && predicate(entry.name))
+      found.push(fullPath);
+  }
+  return found;
+}
+function sha256OfFile3(path) {
+  try {
+    return createHash4("sha256").update(readFileSync9(path)).digest("hex");
+  } catch {
+    return "";
+  }
+}
+function inputDigest(paths) {
+  const combined = paths.slice().sort().map((p) => `${p}:${sha256OfFile3(p)}`).join("\n");
+  return createHash4("sha256").update(combined).digest("hex");
+}
+function readContextIndexMetadata(filePath) {
+  if (!existsSync11(filePath))
+    return {};
+  const text = readFileSync9(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 = join12(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join12(cwd, "specs", "context", "contracts-index.md");
+  const contextPolicy = join12(cwd, ".cdd", "context-policy.json");
+  const contractFiles = findFiles(
+    join12(cwd, "contracts"),
+    (name) => name.endsWith(".md") && name !== "INDEX.md" && name !== "CHANGELOG.md"
+  );
+  if (!existsSync11(projectMap) || !existsSync11(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(existsSync11));
+  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 = readFileSync9(path, "utf8");
+    const m = text.match(/^model:\s*(\S+)/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+function checkModelPolicyDrift(cwd) {
+  const policyPath = join12(cwd, ".cdd", "model-policy.json");
+  if (!existsSync11(policyPath))
+    return [];
+  let policy;
+  try {
+    policy = JSON.parse(readFileSync9(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 = [
+    join12(cwd, ".claude", "agents"),
+    process.env.HOME ? join12(process.env.HOME, ".claude", "agents") : "",
+    process.env.USERPROFILE ? join12(process.env.USERPROFILE, ".claude", "agents") : ""
+  ].filter((p) => p && existsSync11(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 = join12(dir, `${role}.md`);
+      if (!existsSync11(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})`
+        });
+      }
+    }
+    if (!foundAny) {
+    }
+  }
+  if (findings.length === 0) {
+    findings.push({ level: "ok", message: "model-policy roles match installed agent prompts" });
+  }
+  return findings;
+}
+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 (existsSync10(tasksPath)) {
-    let content = readFileSync7(tasksPath, "utf8");
-    if (content.match(/^status:/m)) {
-      content = content.replace(/^status: .*/m, "status: abandoned");
+  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 ((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));
+  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 (/model-policy\.json has no role bindings/i.test(finding.message)) {
+      const policyPath = join12(cwd, ".cdd", "model-policy.json");
+      try {
+        let existing = {};
+        try {
+          existing = JSON.parse(readFileSync9(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-sonnet-4-6",
+            "dependency-security-reviewer": "claude-sonnet-4-6",
+            "spec-drift-auditor": "claude-sonnet-4-6",
+            "repo-context-scanner": "claude-haiku-4-5"
+          }
+        };
+        const { writeFileSync: writeFileSync10 } = await import("fs");
+        writeFileSync10(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 = 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 = buildDoctorReport(cwd, opts);
     } else {
-      content = `---
-change-id: ${changeId}
-status: abandoned
----
-
-` + content;
+      log.info("no auto-fixable findings");
     }
-    writeFileSync4(tasksPath, content, "utf8");
   }
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const archiveDir = join11(cwd, "specs", "archive");
-  const indexPath = join11(archiveDir, "INDEX.md");
-  const reason = opts.reason ?? "no reason given";
-  const indexLine = `| ${changeId} | abandoned | ${today} | ${reason} |
-`;
-  if (!existsSync10(archiveDir)) {
-    mkdirSync5(archiveDir, { recursive: true });
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.ok)
+      process.exit(1);
+    return;
   }
-  if (!existsSync10(indexPath)) {
-    writeFileSync4(indexPath, `# Archive Index
-
-| change-id | status | date | notes |
-|---|---|---|---|
-${indexLine}`, "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();
+  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 {
-    appendFileSync2(indexPath, indexLine, "utf8");
+    log.ok("doctor passed");
   }
-  log.ok(`Change ${changeId} marked as abandoned.`);
-  log.info(`specs/changes/${changeId}/ remains on disk (git history preserved).`);
-  log.info(`Run \`cdd-kit archive ${changeId}\` to physically move it, or leave it for git history.`);
+  log.blank();
 }
-var init_abandon = __esm({
-  "src/commands/abandon.ts"() {
+var init_doctor = __esm({
+  "src/commands/doctor.ts"() {
     "use strict";
     init_logger();
+    init_provider();
   }
 });
 
@@ -175,16 +697,120 @@ var migrate_exports = {};
 __export(migrate_exports, {
   migrate: () => migrate
 });
-import { join as join12 } from "path";
-import { existsSync as existsSync11, readdirSync as readdirSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
-function migrateOne(changeId, changeDir, dryRun) {
+import { join as join13 } from "path";
+import { cpSync as cpSync2, existsSync as existsSync12, mkdirSync as mkdirSync5, readdirSync as readdirSync8, readFileSync as readFileSync10, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
+function backupChangeDir(cwd, changeId, sessionStamp) {
+  const backupRoot = join13(cwd, ".cdd", "migrate-backup", sessionStamp);
+  const backupDir2 = join13(backupRoot, changeId);
+  mkdirSync5(backupRoot, { recursive: true });
+  const sourceDir = join13(cwd, "specs", "changes", changeId);
+  if (existsSync12(sourceDir)) {
+    cpSync2(sourceDir, backupDir2, { recursive: true });
+  }
+  return backupDir2;
+}
+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 upsertFrontmatterField(content, field, value) {
+  if (!content.startsWith("---\n"))
+    return content;
+  const closing = content.indexOf("\n---", 4);
+  if (closing === -1)
+    return content;
+  const frontmatter = content.slice(4, closing);
+  const body = content.slice(closing);
+  const fieldPattern = new RegExp(`^${field}:.*$`, "m");
+  const nextFrontmatter = fieldPattern.test(frontmatter) ? frontmatter.replace(fieldPattern, `${field}: ${value}`) : `${frontmatter.trimEnd()}
+${field}: ${value}`;
+  return `---
+${nextFrontmatter}${body}`;
+}
+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 migrateOne(changeId, changeDir, enableContextGovernance) {
   const changed = [];
   const warnings = [];
-  const tasksPath = join12(changeDir, "tasks.md");
-  if (existsSync11(tasksPath)) {
-    let content = readFileSync8(tasksPath, "utf8");
+  const pending = [];
+  let detectedTier = null;
+  const tasksPath = join13(changeDir, "tasks.md");
+  if (existsSync12(tasksPath)) {
+    let content = readFileSync10(tasksPath, "utf8");
     const norm = content.replace(/\r\n/g, "\n");
     let modified = false;
+    const taskChanges = [];
     if (!norm.startsWith("---")) {
       const bareStatusMatch = norm.match(/^status:\s*(\S+)/m);
       const inferredStatus = bareStatusMatch ? bareStatusMatch[1] : "in-progress";
@@ -198,6 +824,7 @@ status: ${inferredStatus}
 
 ` + content;
       modified = true;
+      taskChanges.push("added YAML frontmatter");
     }
     if (!content.includes("[x]=done")) {
       content = content.replace(
@@ -207,22 +834,28 @@ status: ${inferredStatus}
 `
       );
       modified = true;
+      taskChanges.push("added [x]/[-]/[ ] legend comment");
+    }
+    if (enableContextGovernance && !/^context-governance:\s*v1\b/m.test(content)) {
+      content = upsertFrontmatterField(content, "context-governance", "v1");
+      modified = true;
+      taskChanges.push("enabled context-governance: v1");
     }
     if (modified) {
-      changed.push("tasks.md: added YAML frontmatter (status: in-progress) + legend comment");
-      if (!dryRun)
-        writeFileSync5(tasksPath, content, "utf8");
+      changed.push(`tasks.md: ${taskChanges.join("; ")}`);
+      pending.push({ path: tasksPath, content });
     }
   } else {
     warnings.push("tasks.md not found \u2014 skipping frontmatter migration");
   }
-  const classifPath = join12(changeDir, "change-classification.md");
-  if (existsSync11(classifPath)) {
-    const content = readFileSync8(classifPath, "utf8");
+  const classifPath = join13(changeDir, "change-classification.md");
+  if (existsSync12(classifPath)) {
+    const content = readFileSync10(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) {
-      const oldMatch = content.match(/\*\*Tier[:\*]+\s*(?:Tier\s*)?(\d)/i) ?? content.match(/^-?\s*Tier:\s*(?:Tier\s*)?(\d)/mi);
-      const detectedTier = oldMatch ? oldMatch[1] : null;
       if (detectedTier) {
         const addition = `
 ## Tier
@@ -232,40 +865,100 @@ status: ${inferredStatus}
           changed.push(
             `change-classification.md: appended "## Tier\\n- ${detectedTier}" (converted from old format)`
           );
-          if (!dryRun)
-            writeFileSync5(classifPath, content + addition, "utf8");
+          pending.push({ path: classifPath, content: content + addition });
         }
       } else {
         warnings.push(
-          "change-classification.md: could not detect tier (no **Tier:** N or ## Tier N found). gate tier-based agent-log checks will be skipped for this change."
+          "change-classification.md: could not detect tier (no **Tier:** N or ## Tier N found). Set `tier: <0-5>` in tasks.md frontmatter to enable tier-based gate checks."
         );
       }
+    } else {
+      const structured = content.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
+      if (structured)
+        detectedTier = structured[1];
+    }
+  }
+  if (existsSync12(tasksPath)) {
+    const tasksWrite = pending.find((p) => p.path === tasksPath);
+    let content = tasksWrite ? tasksWrite.content : readFileSync10(tasksPath, "utf8");
+    let modified = false;
+    const subChanges = [];
+    if (detectedTier && !/^tier:\s*\d/m.test(content)) {
+      content = upsertFrontmatterField(content, "tier", detectedTier);
+      modified = true;
+      subChanges.push(`backfilled tier: ${detectedTier}`);
+    }
+    if (!/^archive-tasks:/m.test(content)) {
+      content = upsertFrontmatterField(content, "archive-tasks", '["7.1", "7.2"]');
+      modified = true;
+      subChanges.push("added default archive-tasks list");
+    }
+    if (modified) {
+      if (tasksWrite) {
+        tasksWrite.content = content;
+      } else {
+        pending.push({ path: tasksPath, content });
+      }
+      changed.push(`tasks.md: ${subChanges.join("; ")}`);
+    }
+  }
+  const manifestPath = join13(changeDir, "context-manifest.md");
+  if (!existsSync12(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 };
+}
+function commitWritesAtomically(pending) {
+  const renames = [];
+  try {
+    for (const write of pending) {
+      const tmp = `${write.path}.cdd-migrate.tmp`;
+      writeFileSync5(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);
   }
-  return { changed, warnings };
 }
 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 = join12(cwd, "specs", "changes");
-    if (!existsSync11(changesDir)) {
+    const changesDir = join13(cwd, "specs", "changes");
+    if (!existsSync12(changesDir)) {
       log.info("No specs/changes/ directory found \u2014 nothing to migrate.");
       return;
     }
     idsToMigrate.push(
-      ...readdirSync6(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+      ...readdirSync8(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     );
   } else if (changeId) {
-    const specificDir = join12(cwd, "specs", "changes", changeId);
-    if (!existsSync11(specificDir)) {
+    const specificDir = join13(cwd, "specs", "changes", changeId);
+    if (!existsSync12(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]");
+    log.error("Usage: cdd-kit migrate <change-id>  |  cdd-kit migrate --all  [--dry-run] [--no-backup]");
     process.exit(1);
   }
   if (idsToMigrate.length === 0) {
@@ -276,35 +969,54 @@ async function migrate(changeId, opts = {}) {
     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 = join13(cwd, ".cdd", "migrate-backup", sessionStamp);
   for (const id of idsToMigrate) {
-    const changeDir = join12(cwd, "specs", "changes", id);
-    if (!existsSync11(changeDir)) {
+    const changeDir = join13(cwd, "specs", "changes", id);
+    if (!existsSync12(changeDir)) {
       log.warn(`  ${id}: directory not found \u2014 skipping`);
       continue;
     }
-    const { changed, warnings } = migrateOne(id, changeDir, dryRun);
-    if (changed.length > 0) {
-      log.ok(`  ${id}: migrated`);
-      for (const c of changed)
-        log.info(`    + ${c}`);
-      migratedCount++;
-    } else {
+    const { result, pending } = 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;
     }
-    for (const w of warnings) {
-      log.warn(`  ${id}: ${w}`);
+    if (!dryRun) {
+      try {
+        if (!noBackup)
+          backupChangeDir(cwd, id, sessionStamp);
+        commitWritesAtomically(pending);
+      } 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) {
-      log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to v1.11.0 format"');
+    if (migratedCount > 0 && !noBackup) {
+      log.info(`Backup: ${backupRoot}`);
+      log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to current cdd-kit format"');
+      log.info("When stable, remove backup: rm -rf .cdd/migrate-backup/");
     }
   }
 }
@@ -315,84 +1027,580 @@ var init_migrate = __esm({
   }
 });
 
+// src/commands/upgrade.ts
+var upgrade_exports = {};
+__export(upgrade_exports, {
+  upgrade: () => upgrade
+});
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readdirSync as readdirSync9, copyFileSync as copyFileSync3, readFileSync as readFileSync11, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname4, join as join14, relative as relative3 } from "path";
+function planMissingFiles(srcDir, destDir, label, planned) {
+  if (!existsSync13(srcDir))
+    return;
+  for (const entry of readdirSync9(srcDir, { withFileTypes: true })) {
+    const src = join14(srcDir, entry.name);
+    const dest = join14(destDir, entry.name);
+    if (entry.isDirectory()) {
+      planMissingFiles(src, dest, join14(label, entry.name), planned);
+      continue;
+    }
+    if (!existsSync13(dest)) {
+      planned.push({ src, dest, rel: join14(label, relative3(srcDir, src)) });
+    }
+  }
+}
+function planProviderGuidance(cwd, provider, planned) {
+  if (provider === "claude" || provider === "both") {
+    if (!existsSync13(join14(cwd, "CLAUDE.md"))) {
+      planned.push({ src: ASSET.claudeTemplate, dest: join14(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
+    }
+    if (!existsSync13(join14(cwd, "AGENTS.md"))) {
+      planned.push({ src: ASSET.agentsTemplate, dest: join14(cwd, "AGENTS.md"), rel: "AGENTS.md" });
+    }
+  }
+  if ((provider === "codex" || provider === "both") && !existsSync13(join14(cwd, "CODEX.md"))) {
+    planned.push({ src: ASSET.codexTemplate, dest: join14(cwd, "CODEX.md"), rel: "CODEX.md" });
+  }
+}
+function applyCopy(plan) {
+  for (const item of plan) {
+    mkdirSync6(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, join14(cwd, "contracts"), "contracts", plan);
+  planMissingFiles(ASSET.specsTemplates, join14(cwd, "specs", "templates"), "specs/templates", plan);
+  planMissingFiles(ASSET.testsTemplates, join14(cwd, "tests", "templates"), "tests/templates", plan);
+  planMissingFiles(ASSET.ci, join14(cwd, "ci"), "ci", plan);
+  planMissingFiles(ASSET.githubWorkflows, join14(cwd, ".github", "workflows"), ".github/workflows", plan);
+  planMissingFiles(ASSET.cddConfig, join14(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;
+  }
+  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;
+  }
+  applyCopy(plan);
+  const modelPolicyPath = join14(cwd, ".cdd", "model-policy.json");
+  if (existsSync13(modelPolicyPath)) {
+    let existing = {};
+    try {
+      existing = JSON.parse(readFileSync11(modelPolicyPath, "utf8"));
+    } catch {
+    }
+    const merged = {
+      ...existing,
+      provider,
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      roles: existing.roles && typeof existing.roles === "object" ? existing.roles : {}
+    };
+    writeFileSync6(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  }
+  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
+    });
+  }
+  log.blank();
+}
+var init_upgrade = __esm({
+  "src/commands/upgrade.ts"() {
+    "use strict";
+    init_paths();
+    init_logger();
+    init_provider();
+    init_migrate();
+  }
+});
+
+// src/commands/archive.ts
+var archive_exports = {};
+__export(archive_exports, {
+  archive: () => archive
+});
+import { join as join15 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync7, renameSync as renameSync2, readFileSync as readFileSync12, writeFileSync as writeFileSync7, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
+async function archive(changeId) {
+  const cwd = process.cwd();
+  const changeDir = join15(cwd, "specs", "changes", changeId);
+  const archiveYear = (/* @__PURE__ */ new Date()).getFullYear().toString();
+  const archiveBase = join15(cwd, "specs", "archive", archiveYear);
+  const archiveDir = join15(archiveBase, changeId);
+  const indexPath = join15(cwd, "specs", "archive", "INDEX.md");
+  if (!existsSync14(changeDir)) {
+    log.error(`Change not found: specs/changes/${changeId}`);
+    process.exit(1);
+  }
+  if (existsSync14(archiveDir)) {
+    log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
+    process.exit(1);
+  }
+  const tasksPath = join15(changeDir, "tasks.md");
+  if (existsSync14(tasksPath)) {
+    const content = readFileSync12(tasksPath, "utf8");
+    if (content.includes("status: gate-blocked")) {
+      log.warn("tasks.md has status: gate-blocked \u2014 archiving anyway (change was paused).");
+    }
+    const pending = (content.match(/^\s*-\s*\[ \]/gm) || []).length;
+    if (pending > 0) {
+      log.warn(`${pending} task(s) still pending ([ ]). Archive anyway.`);
+    }
+  }
+  if (!existsSync14(archiveBase)) {
+    mkdirSync7(archiveBase, { recursive: true });
+  }
+  try {
+    renameSync2(changeDir, archiveDir);
+  } catch (err) {
+    if (err.code === "EXDEV") {
+      cpSync3(changeDir, archiveDir, { recursive: true });
+      rmSync3(changeDir, { recursive: true, force: true });
+    } else {
+      throw err;
+    }
+  }
+  log.ok(`Archived: specs/changes/${changeId} \u2192 specs/archive/${archiveYear}/${changeId}`);
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const indexLine = `| ${changeId} | ${archiveYear} | ${today} | specs/archive/${archiveYear}/${changeId}/ |
+`;
+  if (!existsSync14(indexPath)) {
+    writeFileSync7(indexPath, `# Archive Index
+
+| change-id | year | archived-date | path |
+|---|---|---|---|
+${indexLine}`, "utf8");
+  } else {
+    appendFileSync(indexPath, indexLine, "utf8");
+  }
+  log.ok(`Index updated: specs/archive/INDEX.md`);
+  log.blank();
+  log.info(`Next: promote durable learnings from archive.md to contracts/ or CLAUDE.md`);
+}
+var init_archive = __esm({
+  "src/commands/archive.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
+// src/commands/abandon.ts
+var abandon_exports = {};
+__export(abandon_exports, {
+  abandon: () => abandon
+});
+import { join as join16 } from "path";
+import { existsSync as existsSync15, readFileSync as readFileSync13, writeFileSync as writeFileSync8, appendFileSync as appendFileSync2, mkdirSync as mkdirSync8 } from "fs";
+async function abandon(changeId, opts) {
+  const cwd = process.cwd();
+  const changeDir = join16(cwd, "specs", "changes", changeId);
+  const tasksPath = join16(changeDir, "tasks.md");
+  if (!existsSync15(changeDir)) {
+    log.error(`Change not found: specs/changes/${changeId}`);
+    process.exit(1);
+  }
+  if (existsSync15(tasksPath)) {
+    let content = readFileSync13(tasksPath, "utf8");
+    if (content.match(/^status:/m)) {
+      content = content.replace(/^status: .*/m, "status: abandoned");
+    } else {
+      content = `---
+change-id: ${changeId}
+status: abandoned
+---
+
+` + content;
+    }
+    writeFileSync8(tasksPath, content, "utf8");
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const archiveDir = join16(cwd, "specs", "archive");
+  const indexPath = join16(archiveDir, "INDEX.md");
+  const reason = opts.reason ?? "no reason given";
+  const indexLine = `| ${changeId} | abandoned | ${today} | ${reason} |
+`;
+  if (!existsSync15(archiveDir)) {
+    mkdirSync8(archiveDir, { recursive: true });
+  }
+  if (!existsSync15(indexPath)) {
+    writeFileSync8(indexPath, `# Archive Index
+
+| change-id | status | date | notes |
+|---|---|---|---|
+${indexLine}`, "utf8");
+  } else {
+    appendFileSync2(indexPath, indexLine, "utf8");
+  }
+  log.ok(`Change ${changeId} marked as abandoned.`);
+  log.info(`specs/changes/${changeId}/ remains on disk (git history preserved).`);
+  log.info(`Run \`cdd-kit archive ${changeId}\` to physically move it, or leave it for git history.`);
+}
+var init_abandon = __esm({
+  "src/commands/abandon.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
 // src/commands/list-changes.ts
 var list_changes_exports = {};
 __export(list_changes_exports, {
   listChanges: () => listChanges
 });
-import { join as join13 } from "path";
-import { existsSync as existsSync12, readdirSync as readdirSync7, readFileSync as readFileSync9 } from "fs";
+import { join as join17 } from "path";
+import { existsSync as existsSync16, readdirSync as readdirSync10, readFileSync as readFileSync14 } from "fs";
 async function listChanges() {
   const cwd = process.cwd();
-  const changesDir = join13(cwd, "specs", "changes");
+  const changesDir = join17(cwd, "specs", "changes");
   log.blank();
   const active = [];
-  if (existsSync12(changesDir)) {
-    active.push(...readdirSync7(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name));
+  if (existsSync16(changesDir)) {
+    active.push(...readdirSync10(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 = join17(changesDir, id, "tasks.md");
+      let status = "in-progress";
+      let pending = 0;
+      if (existsSync16(tasksPath)) {
+        const content = readFileSync14(tasksPath, "utf8");
+        if (content.includes("status: gate-blocked"))
+          status = "gate-blocked";
+        else if (content.includes("status: abandoned"))
+          status = "abandoned";
+        pending = (content.match(/^\s*-\s*\[ \]/gm) || []).length;
+      }
+      const pendingStr = pending > 0 ? ` (${pending} pending)` : "";
+      log.info(`  ${id}  [${status}]${pendingStr}`);
+    }
+  }
+  log.blank();
+}
+var init_list_changes = __esm({
+  "src/commands/list-changes.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
+// src/commands/context.ts
+var context_exports = {};
+__export(context_exports, {
+  approveAllPending: () => approveAllPending,
+  approveContextExpansion: () => approveContextExpansion,
+  listContextExpansions: () => listContextExpansions,
+  rejectAllPending: () => rejectAllPending,
+  rejectContextExpansion: () => rejectContextExpansion,
+  requestContextExpansion: () => requestContextExpansion
+});
+import { existsSync as existsSync17, readFileSync as readFileSync15, writeFileSync as writeFileSync9 } from "fs";
+import { join as join18 } from "path";
+function normalizePath(path) {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "").trim();
+}
+function validateRepoRelativePath(path) {
+  if (/^[a-zA-Z]:\//.test(path) || path.startsWith("/")) {
+    return `requested path must be repo-relative: ${path}`;
+  }
+  if (path.split("/").includes("..")) {
+    return `requested path must not contain "..": ${path}`;
+  }
+  return null;
+}
+function manifestPathFor(changeId) {
+  return join18(process.cwd(), "specs", "changes", changeId, "context-manifest.md");
+}
+function readManifest(changeId) {
+  const manifestPath = manifestPathFor(changeId);
+  if (!existsSync17(manifestPath)) {
+    log.error(`context manifest not found: specs/changes/${changeId}/context-manifest.md`);
+    process.exit(1);
+  }
+  return readFileSync15(manifestPath, "utf8");
+}
+function writeManifest(changeId, content) {
+  writeFileSync9(manifestPathFor(changeId), content.endsWith("\n") ? content : `${content}
+`, "utf8");
+}
+function sectionBody(content, heading) {
+  const match = content.match(new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`));
+  return match?.[1] ?? "";
+}
+function parseRequests(content) {
+  const body = sectionBody(content, "Context Expansion Requests");
+  if (!body.trim())
+    return [];
+  const requests = [];
+  const blocks = body.split(/(?=^\s*-\s*request-id:\s*)/m);
+  for (const block of blocks) {
+    const idMatch = block.match(/^\s*-\s*request-id:\s*(\S+)/m);
+    if (!idMatch)
+      continue;
+    const statusMatch = block.match(/^\s*status:\s*(\S+)/im);
+    const reasonMatch = block.match(/^\s*reason:\s*(.+)$/im);
+    const paths = [];
+    let inPaths = false;
+    for (const line of block.split(/\r?\n/)) {
+      if (/^\s*requested_paths:\s*$/.test(line)) {
+        inPaths = true;
+        continue;
+      }
+      if (!inPaths)
+        continue;
+      const item = line.match(/^\s*-\s+(.+?)\s*$/);
+      if (item) {
+        paths.push(normalizePath(item[1]));
+        continue;
+      }
+      if (/^\s*[a-zA-Z_-]+:\s*/.test(line))
+        break;
+    }
+    requests.push({
+      requestId: idMatch[1],
+      paths,
+      reason: reasonMatch?.[1]?.trim(),
+      status: statusMatch?.[1]?.trim().toLowerCase() ?? "unknown"
+    });
+  }
+  return requests;
+}
+function approvedExpansionSet(content) {
+  const body = sectionBody(content, "Approved Expansions");
+  const approved = /* @__PURE__ */ new Set();
+  for (const line of body.split(/\r?\n/)) {
+    const item = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (!item)
+      continue;
+    const value = normalizePath(item[1]);
+    if (value && value !== "-")
+      approved.add(value);
+  }
+  return approved;
+}
+function replaceSection(content, heading, lines) {
+  const nextSection = [`## ${heading}`, ...lines, ""].join("\n");
+  const pattern = new RegExp(`## ${heading}\\s*\\n[\\s\\S]*?(?=\\n## |$)`);
+  if (pattern.test(content))
+    return content.replace(pattern, nextSection.trimEnd());
+  return `${content.trimEnd()}
+
+${nextSection}`;
+}
+function renderRequests(requests) {
+  if (requests.length === 0)
+    return ["-"];
+  const lines = [];
+  for (const request of requests) {
+    lines.push(`- request-id: ${request.requestId}`);
+    lines.push("  requested_paths:");
+    for (const path of request.paths)
+      lines.push(`    - ${path}`);
+    if (request.reason)
+      lines.push(`  reason: ${request.reason}`);
+    lines.push(`  status: ${request.status}`);
+    lines.push("");
+  }
+  if (lines[lines.length - 1] === "")
+    lines.pop();
+  return lines;
+}
+function setRequestStatus(content, requestId, status) {
+  const requests = parseRequests(content);
+  const target = requests.find((request) => request.requestId === requestId);
+  if (!target) {
+    log.error(`context expansion request not found: ${requestId}`);
+    process.exit(1);
+  }
+  if (target.status !== "pending") {
+    log.error(`pending context expansion request not found: ${requestId}`);
+    process.exit(1);
+  }
+  const next = requests.map((request) => request.requestId === requestId ? { ...request, status } : request);
+  return replaceSection(content, "Context Expansion Requests", renderRequests(next));
+}
+async function requestContextExpansion(changeId, requestId, paths, reason) {
+  if (paths.length === 0) {
+    log.error("at least one --path value is required");
+    process.exit(1);
+  }
+  const normalizedPaths = [...new Set(paths.map(normalizePath).filter(Boolean))];
+  for (const path of normalizedPaths) {
+    const validationError = validateRepoRelativePath(path);
+    if (validationError) {
+      log.error(validationError);
+      process.exit(1);
+    }
+  }
+  const content = readManifest(changeId);
+  const requests = parseRequests(content);
+  if (requests.some((request) => request.requestId === requestId)) {
+    log.error(`context expansion request already exists: ${requestId}`);
+    process.exit(1);
+  }
+  const next = replaceSection(content, "Context Expansion Requests", renderRequests([
+    ...requests,
+    { requestId, paths: normalizedPaths, reason, status: "pending" }
+  ]));
+  writeManifest(changeId, next);
+  log.ok(`recorded context expansion request ${requestId} for ${changeId}`);
+  for (const path of normalizedPaths)
+    log.info(`  ${path}`);
+}
+async function listContextExpansions(changeId, json = false) {
+  const requests = parseRequests(readManifest(changeId));
+  if (json) {
+    console.log(JSON.stringify({ changeId, requests }, null, 2));
+    return;
+  }
+  if (requests.length === 0) {
+    log.info(`no context expansion requests for ${changeId}`);
+    return;
+  }
+  log.info(`context expansion requests for ${changeId}`);
+  for (const request of requests) {
+    log.info(`- ${request.requestId} [${request.status}] ${request.reason ?? ""}`.trimEnd());
+    for (const path of request.paths)
+      log.dim(`    ${path}`);
+  }
+}
+function applyApproval(content, request) {
+  for (const path of request.paths) {
+    const validationError = validateRepoRelativePath(path);
+    if (validationError) {
+      log.error(validationError);
+      process.exit(1);
+    }
+  }
+  const approved = approvedExpansionSet(content);
+  for (const path of request.paths)
+    approved.add(path);
+  let next = replaceSection(content, "Approved Expansions", [...approved].sort().map((p) => `- ${p}`));
+  next = setRequestStatus(next, request.requestId, "approved");
+  return next;
+}
+async function approveContextExpansion(changeId, requestId) {
+  const content = readManifest(changeId);
+  const request = parseRequests(content).find((item) => item.requestId === requestId && item.status === "pending");
+  if (!request) {
+    log.error(`pending context expansion request not found: ${requestId}`);
+    process.exit(1);
+  }
+  if (request.paths.length === 0) {
+    log.error(`context expansion request has no requested_paths: ${requestId}`);
+    process.exit(1);
   }
-  if (active.length === 0) {
-    log.info("No active changes in specs/changes/");
-  } else {
-    log.info("Active changes:");
-    for (const id of active) {
-      const tasksPath = join13(changesDir, id, "tasks.md");
-      let status = "in-progress";
-      let pending = 0;
-      if (existsSync12(tasksPath)) {
-        const content = readFileSync9(tasksPath, "utf8");
-        if (content.includes("status: gate-blocked"))
-          status = "gate-blocked";
-        else if (content.includes("status: abandoned"))
-          status = "abandoned";
-        pending = (content.match(/^\s*-\s*\[ \]/gm) || []).length;
-      }
-      const pendingStr = pending > 0 ? ` (${pending} pending)` : "";
-      log.info(`  ${id}  [${status}]${pendingStr}`);
+  const next = applyApproval(content, request);
+  writeManifest(changeId, next);
+  log.ok(`approved context expansion ${requestId} for ${changeId}`);
+  for (const path of request.paths)
+    log.info(`  ${path}`);
+}
+async function approveAllPending(changeId) {
+  let content = readManifest(changeId);
+  const pending = parseRequests(content).filter((r) => r.status === "pending");
+  if (pending.length === 0) {
+    log.info(`no pending context expansion requests for ${changeId}`);
+    return;
+  }
+  const skipped = [];
+  let approvedCount = 0;
+  for (const request of pending) {
+    if (request.paths.length === 0) {
+      skipped.push(`${request.requestId} (no requested_paths)`);
+      continue;
     }
+    content = applyApproval(content, request);
+    approvedCount += 1;
+  }
+  writeManifest(changeId, content);
+  log.ok(`approved ${approvedCount} pending context expansion request(s) for ${changeId}`);
+  for (const reason of skipped) {
+    log.warn(`  skipped ${reason}`);
   }
-  log.blank();
 }
-var init_list_changes = __esm({
-  "src/commands/list-changes.ts"() {
+async function rejectContextExpansion(changeId, requestId) {
+  const next = setRequestStatus(readManifest(changeId), requestId, "rejected");
+  writeManifest(changeId, next);
+  log.ok(`rejected context expansion ${requestId} for ${changeId}`);
+}
+async function rejectAllPending(changeId) {
+  let content = readManifest(changeId);
+  const pending = parseRequests(content).filter((r) => r.status === "pending");
+  if (pending.length === 0) {
+    log.info(`no pending context expansion requests for ${changeId}`);
+    return;
+  }
+  for (const request of pending) {
+    content = setRequestStatus(content, request.requestId, "rejected");
+  }
+  writeManifest(changeId, content);
+  log.ok(`rejected ${pending.length} pending context expansion request(s) for ${changeId}`);
+}
+var init_context = __esm({
+  "src/commands/context.ts"() {
     "use strict";
     init_logger();
   }
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync16 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname3, join as join14 } from "path";
+import { dirname as dirname5, join as join19 } from "path";
 import { Command } from "commander";
 
 // src/commands/init.ts
+init_paths();
 import { join as join4 } from "path";
 import { rmSync, readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
 
-// src/utils/paths.ts
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { homedir } from "os";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var PACKAGE_ROOT = join(__dirname, "..", "..");
-var ASSETS_DIR = join(PACKAGE_ROOT, "assets");
-var CLAUDE_HOME = join(homedir(), ".claude");
-var AGENTS_HOME = join(CLAUDE_HOME, "agents");
-var SKILLS_HOME = join(CLAUDE_HOME, "skills");
-var ASSET = {
-  agents: join(ASSETS_DIR, "agents"),
-  skills: join(ASSETS_DIR, "skills"),
-  skill: join(ASSETS_DIR, "skills", "contract-driven-delivery"),
-  contracts: join(ASSETS_DIR, "contracts"),
-  specsTemplates: join(ASSETS_DIR, "specs-templates"),
-  testsTemplates: join(ASSETS_DIR, "tests-templates"),
-  ci: join(ASSETS_DIR, "ci"),
-  githubWorkflows: join(ASSETS_DIR, "github-workflows"),
-  hooks: join(ASSETS_DIR, "hooks"),
-  claudeTemplate: join(ASSETS_DIR, "CLAUDE.template.md"),
-  agentsTemplate: join(ASSETS_DIR, "AGENTS.template.md")
-};
-
 // src/utils/copy.ts
 init_logger();
 import {
@@ -607,8 +1815,14 @@ async function init(opts) {
     log.error("--global-only and --local-only are mutually exclusive.");
     process.exit(1);
   }
+  if (!["claude", "codex", "both"].includes(opts.provider)) {
+    log.error(`Invalid provider: ${opts.provider}. Use claude, codex, or both.`);
+    process.exit(1);
+  }
   const cwd = process.cwd();
   const createdPaths = [];
+  const installClaude = opts.provider === "claude" || opts.provider === "both";
+  const installCodex = opts.provider === "codex" || opts.provider === "both";
   function track(paths) {
     createdPaths.push(...paths);
   }
@@ -627,7 +1841,7 @@ async function init(opts) {
   log.info("Initialising contract-driven-delivery kit\u2026");
   log.blank();
   try {
-    if (!opts.localOnly) {
+    if (!opts.localOnly && installClaude) {
       log.info(`Installing agents \u2192 ${AGENTS_HOME}`);
       const { count: agentCount, created: agentCreated } = copyDirTracked(ASSET.agents, AGENTS_HOME, { overwrite: true });
       track(agentCreated);
@@ -643,6 +1857,9 @@ async function init(opts) {
       }
       log.ok(`${totalSkillFiles} skill file(s) installed (${skillDirs.length} skills).`);
       log.blank();
+    } else if (!opts.localOnly && installCodex) {
+      log.info("No global assets for provider: codex.");
+      log.blank();
     }
     if (!opts.globalOnly) {
       log.info(`Scaffolding project files in ${cwd}`);
@@ -674,6 +1891,28 @@ async function init(opts) {
       );
       track(ciCreated);
       log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
+      const { count: cddConfigCount, created: cddConfigCreated } = copyDirTracked(
+        ASSET.cddConfig,
+        join4(cwd, ".cdd"),
+        { overwrite: opts.force, label: ".cdd" }
+      );
+      track(cddConfigCreated);
+      log.ok(`.cdd/ - ${cddConfigCount} file(s) written.`);
+      const modelPolicyPath = join4(cwd, ".cdd", "model-policy.json");
+      if (existsSync3(modelPolicyPath)) {
+        let existing = {};
+        try {
+          existing = JSON.parse(readFileSync2(modelPolicyPath, "utf8"));
+        } catch {
+        }
+        const merged = {
+          ...existing,
+          provider: opts.provider,
+          generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+          roles: existing.roles && typeof existing.roles === "object" && Object.keys(existing.roles).length > 0 ? existing.roles : {}
+        };
+        writeFileSync(modelPolicyPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+      }
       const { count: wfCount, created: wfCreated } = copyDirTracked(
         ASSET.githubWorkflows,
         join4(cwd, ".github", "workflows"),
@@ -717,24 +1956,37 @@ async function init(opts) {
           }
         }
       }
-      const { written: claudeWritten, created: claudeCreated } = copyFileTracked(
-        ASSET.claudeTemplate,
-        join4(cwd, "CLAUDE.md"),
-        { overwrite: false, label: "CLAUDE.md" }
-      );
-      if (claudeCreated)
-        track([join4(cwd, "CLAUDE.md")]);
-      if (claudeWritten)
-        log.ok("CLAUDE.md created.");
-      const { written: agentsWritten, created: agentsCreated } = copyFileTracked(
-        ASSET.agentsTemplate,
-        join4(cwd, "AGENTS.md"),
-        { overwrite: false, label: "AGENTS.md" }
-      );
-      if (agentsCreated)
-        track([join4(cwd, "AGENTS.md")]);
-      if (agentsWritten)
-        log.ok("AGENTS.md created.");
+      if (installClaude) {
+        const { written: claudeWritten, created: claudeCreated } = copyFileTracked(
+          ASSET.claudeTemplate,
+          join4(cwd, "CLAUDE.md"),
+          { overwrite: false, label: "CLAUDE.md" }
+        );
+        if (claudeCreated)
+          track([join4(cwd, "CLAUDE.md")]);
+        if (claudeWritten)
+          log.ok("CLAUDE.md created.");
+        const { written: agentsWritten, created: agentsCreated } = copyFileTracked(
+          ASSET.agentsTemplate,
+          join4(cwd, "AGENTS.md"),
+          { overwrite: false, label: "AGENTS.md" }
+        );
+        if (agentsCreated)
+          track([join4(cwd, "AGENTS.md")]);
+        if (agentsWritten)
+          log.ok("AGENTS.md created.");
+      }
+      if (installCodex) {
+        const { written: codexWritten, created: codexCreated } = copyFileTracked(
+          ASSET.codexTemplate,
+          join4(cwd, "CODEX.md"),
+          { overwrite: false, label: "CODEX.md" }
+        );
+        if (codexCreated)
+          track([join4(cwd, "CODEX.md")]);
+        if (codexWritten)
+          log.ok("CODEX.md created.");
+      }
       log.blank();
     }
   } catch (err) {
@@ -744,33 +1996,39 @@ async function init(opts) {
   }
   log.ok("Done.");
   log.blank();
-  log.info("Use the contract-driven-delivery skill in Claude Code to scan this repo.");
+  if (opts.provider === "codex") {
+    log.info("Use CODEX.md and cdd-kit commands to run the contract-driven workflow.");
+  } else {
+    log.info("Use the contract-driven-delivery skill in Claude Code to scan this repo.");
+  }
   log.blank();
 }
 
 // src/commands/update.ts
-import { join as join5 } from "path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync as readdirSync3, copyFileSync as copyFileSync2, readFileSync as readFileSync3 } from "fs";
-import { createHash } from "crypto";
+init_paths();
 init_logger();
+init_provider();
+import { join as join6 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readdirSync as readdirSync3, copyFileSync as copyFileSync2, readFileSync as readFileSync4 } from "fs";
+import { createHash } from "crypto";
 import { homedir as homedir2 } from "os";
 function fileHash(filePath) {
-  const buf = readFileSync3(filePath);
+  const buf = readFileSync4(filePath);
   return createHash("sha256").update(buf).digest("hex");
 }
 function diffDir(src, dest) {
   const entries = [];
-  if (!existsSync4(src))
+  if (!existsSync5(src))
     return entries;
   function walk(currentSrc, currentDest) {
     const items = readdirSync3(currentSrc, { withFileTypes: true });
     for (const item of items) {
-      const srcPath = join5(currentSrc, item.name);
-      const destPath = join5(currentDest, item.name);
+      const srcPath = join6(currentSrc, item.name);
+      const destPath = join6(currentDest, item.name);
       if (item.isDirectory()) {
         walk(srcPath, destPath);
       } else {
-        if (!existsSync4(destPath)) {
+        if (!existsSync5(destPath)) {
           entries.push({ src: srcPath, dest: destPath, action: "add" });
         } else if (fileHash(srcPath) !== fileHash(destPath)) {
           entries.push({ src: srcPath, dest: destPath, action: "overwrite" });
@@ -788,21 +2046,21 @@ function applyDir(entries) {
   for (const e of entries) {
     if (e.action === "skip")
       continue;
-    mkdirSync2(join5(e.dest, ".."), { recursive: true });
+    mkdirSync2(join6(e.dest, ".."), { recursive: true });
     copyFileSync2(e.src, e.dest);
     count += 1;
   }
   return count;
 }
 function backupDir(dir, backupDest) {
-  if (!existsSync4(dir))
+  if (!existsSync5(dir))
     return;
   mkdirSync2(backupDest, { recursive: true });
   function walk(src, dst) {
     const items = readdirSync3(src, { withFileTypes: true });
     for (const item of items) {
-      const s = join5(src, item.name);
-      const d = join5(dst, item.name);
+      const s = join6(src, item.name);
+      const d = join6(dst, item.name);
       if (item.isDirectory()) {
         mkdirSync2(d, { recursive: true });
         walk(s, d);
@@ -814,15 +2072,29 @@ function backupDir(dir, backupDest) {
 }
 async function update(opts) {
   log.blank();
-  const skillDest = join5(SKILLS_HOME, "contract-driven-delivery");
-  const agentDiff = diffDir(ASSET.agents, AGENTS_HOME);
-  const skillDiff = diffDir(ASSET.skill, skillDest);
+  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 skillDest = join6(SKILLS_HOME, "contract-driven-delivery");
+  const agentDiff = updateClaudeAssets ? diffDir(ASSET.agents, AGENTS_HOME) : [];
+  const skillDiff = updateClaudeAssets ? diffDir(ASSET.skill, skillDest) : [];
   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");
-  log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
-  log.info(`Dry-run diff \u2014 skill:  ${skillDest}`);
+  log.info(`Provider: ${provider}`);
+  if (updateClaudeAssets) {
+    log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
+    log.info(`Dry-run diff \u2014 skill:  ${skillDest}`);
+  } 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`);
@@ -844,19 +2116,21 @@ async function update(opts) {
     return;
   }
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const backupRoot = join5(homedir2(), ".claude", ".cdd-kit-backup", timestamp);
+  const backupRoot = join6(homedir2(), ".claude", ".cdd-kit-backup", timestamp);
   log.blank();
   log.info(`Backing up to ${backupRoot} \u2026`);
-  backupDir(AGENTS_HOME, join5(backupRoot, "agents"));
-  backupDir(skillDest, join5(backupRoot, "skill"));
+  backupDir(AGENTS_HOME, join6(backupRoot, "agents"));
+  backupDir(skillDest, join6(backupRoot, "skill"));
   log.ok(`Backup complete: ${backupRoot}`);
   log.blank();
-  log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
-  const agentCount = applyDir(agentDiff);
-  log.ok(`${agentCount} agent file(s) updated.`);
-  log.info(`Updating skill  \u2192 ${skillDest}`);
-  const skillCount = applyDir(skillDiff);
-  log.ok(`${skillCount} skill file(s) updated.`);
+  if (updateClaudeAssets) {
+    log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
+    const agentCount = applyDir(agentDiff);
+    log.ok(`${agentCount} agent file(s) updated.`);
+    log.info(`Updating skill  \u2192 ${skillDest}`);
+    const skillCount = applyDir(skillDiff);
+    log.ok(`${skillCount} skill file(s) updated.`);
+  }
   log.blank();
   log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
   log.ok("Update complete.");
@@ -865,33 +2139,101 @@ async function update(opts) {
 }
 
 // src/commands/new-change.ts
-import { join as join6 } from "path";
-import { existsSync as existsSync5, readdirSync as readdirSync4 } from "fs";
+init_paths();
+import { join as join8 } from "path";
+import { createHash as createHash3 } from "crypto";
+import { existsSync as existsSync7, readFileSync as readFileSync6, readdirSync as readdirSync5, writeFileSync as writeFileSync3 } from "fs";
 init_logger();
+init_context_scan();
+function sha256OfFile2(path) {
+  try {
+    return createHash3("sha256").update(readFileSync6(path)).digest("hex");
+  } catch {
+    return "";
+  }
+}
+function inputsDigest2(paths) {
+  const combined = paths.slice().sort().map((p) => `${p}:${sha256OfFile2(p)}`).join("\n");
+  return createHash3("sha256").update(combined).digest("hex");
+}
+function findContractFiles2(dir, found = []) {
+  if (!existsSync7(dir))
+    return found;
+  for (const entry of readdirSync5(dir, { withFileTypes: true })) {
+    const fullPath = join8(dir, entry.name);
+    if (entry.isDirectory())
+      findContractFiles2(fullPath, found);
+    else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "INDEX.md" && entry.name !== "CHANGELOG.md") {
+      found.push(fullPath);
+    }
+  }
+  return found;
+}
+function readIndexDigest(filePath) {
+  if (!existsSync7(filePath))
+    return null;
+  const m = readFileSync6(filePath, "utf8").match(/^inputs-digest:\s*([a-f0-9]+)/m);
+  return m ? m[1] : null;
+}
+async function ensureFreshContextIndexes(cwd) {
+  const projectMap = join8(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join8(cwd, "specs", "context", "contracts-index.md");
+  const policyPath = join8(cwd, ".cdd", "context-policy.json");
+  const policyInputs = [policyPath].filter(existsSync7);
+  const contractFiles = findContractFiles2(join8(cwd, "contracts"));
+  const wantProjectDigest = inputsDigest2(policyInputs);
+  const wantContractsDigest = inputsDigest2(contractFiles);
+  const haveProjectDigest = readIndexDigest(projectMap);
+  const haveContractsDigest = readIndexDigest(contractsIndex);
+  const needsScan = !existsSync7(projectMap) || !existsSync7(contractsIndex) || haveProjectDigest !== wantProjectDigest || haveContractsDigest !== wantContractsDigest;
+  if (!needsScan)
+    return;
+  log.info("context indexes missing or stale \u2014 running cdd-kit context-scan\u2026");
+  await contextScan();
+  log.dim("  (skip with --skip-scan)");
+}
 var REQUIRED_TEMPLATES = [
   "change-request.md",
   "change-classification.md",
   "test-plan.md",
   "ci-gates.md",
-  "tasks.md"
+  "tasks.md",
+  "context-manifest.md"
 ];
 function listOptional() {
   try {
-    const all = readdirSync4(ASSET.specsTemplates).filter((f) => f.endsWith(".md"));
+    const all = readdirSync5(ASSET.specsTemplates).filter((f) => f.endsWith(".md"));
     return all.filter((f) => !REQUIRED_TEMPLATES.includes(f));
   } catch {
     return [];
   }
 }
 var SAFE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+function parseDependsOn(raw) {
+  if (!raw)
+    return [];
+  return raw.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function formatDependsOn(ids) {
+  if (ids.length === 0)
+    return "depends-on: []";
+  return `depends-on: [${ids.join(", ")}]`;
+}
 async function newChange(name, opts) {
   if (!SAFE_NAME.test(name)) {
     log.error(`Invalid change name: "${name}". Use letters, numbers, hyphens, or underscores (max 64 chars).`);
     process.exit(1);
   }
+  const dependencies = parseDependsOn(opts.dependsOn);
+  for (const dep of dependencies) {
+    if (!SAFE_NAME.test(dep)) {
+      log.error(`Invalid dependency name: "${dep}". Use letters, numbers, hyphens, or underscores (max 64 chars).`);
+      process.exit(1);
+    }
+  }
   const cwd = process.cwd();
-  const changeDir = join6(cwd, "specs", "changes", name);
-  if (existsSync5(changeDir)) {
+  const changeDir = join8(cwd, "specs", "changes", name);
+  if (existsSync7(changeDir)) {
     if (opts.force) {
       log.warn(`Forcing re-scaffold of existing change directory: ${changeDir}`);
       log.warn("Existing files will NOT be deleted; only template files will be overwritten.");
@@ -901,15 +2243,22 @@ async function newChange(name, opts) {
       return;
     }
   }
+  if (!opts.skipScan) {
+    try {
+      await ensureFreshContextIndexes(cwd);
+    } catch (err) {
+      log.warn(`context-scan failed: ${err.message}; continuing without fresh indexes`);
+    }
+  }
   log.blank();
   log.info(`Creating change scaffold: specs/changes/${name}`);
   ensureDir(changeDir);
   const templates = opts.all ? [...REQUIRED_TEMPLATES, ...listOptional()] : [...REQUIRED_TEMPLATES];
   let written = 0;
   for (const tmpl of templates) {
-    const src = join6(ASSET.specsTemplates, tmpl);
-    const dest = join6(changeDir, tmpl);
-    if (!existsSync5(src)) {
+    const src = join8(ASSET.specsTemplates, tmpl);
+    const dest = join8(changeDir, tmpl);
+    if (!existsSync7(src)) {
       log.warn(`Template not found, skipping: ${tmpl}`);
       continue;
     }
@@ -917,16 +2266,26 @@ async function newChange(name, opts) {
     log.dim(tmpl);
     written += 1;
   }
+  if (dependencies.length > 0) {
+    const tasksPath = join8(changeDir, "tasks.md");
+    if (existsSync7(tasksPath)) {
+      const tasks = readFileSync6(tasksPath, "utf8");
+      const nextTasks = tasks.replace(/^depends-on:\s*.*$/m, formatDependsOn(dependencies));
+      writeFileSync3(tasksPath, nextTasks, "utf8");
+      log.dim(`depends-on: ${dependencies.join(", ")}`);
+    }
+  }
   log.blank();
   log.ok(`${written} template(s) created in specs/changes/${name}`);
   log.blank();
 }
 
 // src/commands/validate.ts
-import { join as join7 } from "path";
-import { existsSync as existsSync6 } from "fs";
-import { spawnSync } from "child_process";
+init_paths();
 init_logger();
+import { join as join9 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { spawnSync } from "child_process";
 var VALIDATORS = [
   {
     flag: "contracts",
@@ -958,15 +2317,15 @@ async function validate(opts) {
     log.error(e instanceof Error ? e.message : String(e));
     process.exit(1);
   }
-  const scriptsDir = join7(ASSET.skill, "scripts");
+  const scriptsDir = join9(ASSET.skill, "scripts");
   const runAll = !opts.contracts && !opts.env && !opts.ci && !opts.spec && !opts.versions;
   log.blank();
   let failed = false;
   for (const v of VALIDATORS) {
     if (!runAll && !opts[v.flag])
       continue;
-    const scriptPath = join7(scriptsDir, v.script);
-    if (!existsSync6(scriptPath)) {
+    const scriptPath = join9(scriptsDir, v.script);
+    if (!existsSync8(scriptPath)) {
       log.warn(`${v.label}: script not found, skipping (${v.script})`);
       log.blank();
       continue;
@@ -982,8 +2341,8 @@ async function validate(opts) {
     log.blank();
     if (v.chain) {
       for (const chained of v.chain) {
-        const chainedPath = join7(scriptsDir, chained.script);
-        if (!existsSync6(chainedPath)) {
+        const chainedPath = join9(scriptsDir, chained.script);
+        if (!existsSync8(chainedPath)) {
           log.warn(`${chained.label}: script not found, skipping (${chained.script})`);
           log.blank();
           continue;
@@ -1011,15 +2370,15 @@ async function validate(opts) {
 
 // src/commands/gate.ts
 init_logger();
-import { existsSync as existsSync7, readFileSync as readFileSync4, readdirSync as readdirSync5 } from "fs";
-import { join as join8 } from "path";
-import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync as readdirSync6 } from "fs";
+import { join as join10 } from "path";
 var REQUIRED_FILES = [
   "change-request.md",
   "change-classification.md",
   "test-plan.md",
   "ci-gates.md",
-  "tasks.md"
+  "tasks.md",
+  "context-manifest.md"
 ];
 var TIER_PATTERN = /\b(tier\s*[0-5]|low|medium|high|critical)\b/i;
 var MIN_CHARS = {
@@ -1027,46 +2386,426 @@ var MIN_CHARS = {
   "test-plan.md": 200,
   "ci-gates.md": 150,
   "change-request.md": 100,
-  "tasks.md": 100
+  "tasks.md": 100,
+  "context-manifest.md": 50
 };
 function meaningfulChars(text) {
   return text.split("\n").map((l) => l.trim()).filter((l) => l).filter((l) => !l.startsWith("#")).filter((l) => !/^[|\s\-:]+$/.test(l)).filter((l) => !l.startsWith("<!--")).join("").length;
 }
+function stripHtmlComments(text) {
+  return text.replace(/<!--[\s\S]*?-->/g, "");
+}
+function pathMatches(relPath, patterns, currentChangeId) {
+  const normalized = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+  return patterns.some((rawPattern) => {
+    const pattern = rawPattern.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (pattern === "specs/changes/*" && currentChangeId) {
+      const current = `specs/changes/${currentChangeId}`;
+      if (normalized === current || normalized.startsWith(`${current}/`))
+        return false;
+      return normalized.startsWith("specs/changes/");
+    }
+    if (pattern.endsWith("/**")) {
+      const base = pattern.slice(0, -3);
+      return normalized === base || normalized.startsWith(`${base}/`);
+    }
+    if (pattern.endsWith("/*")) {
+      const base = pattern.slice(0, -2);
+      if (!normalized.startsWith(`${base}/`))
+        return false;
+      return !normalized.slice(base.length + 1).includes("/");
+    }
+    return normalized === pattern || normalized.startsWith(`${pattern}/`);
+  });
+}
+function parseListSection(content, heading) {
+  const clean = stripHtmlComments(content);
+  const match = clean.match(new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?:\\n## |$)`));
+  if (!match)
+    return [];
+  return match[1].split(/\r?\n/).map((line) => line.replace(/^\s*-\s*/, "").trim()).filter((item) => item && item !== "-" && item.toLowerCase() !== "none");
+}
+function parseContextManifest(content) {
+  const clean = stripHtmlComments(content);
+  const requestMatch = clean.match(/## Context Expansion Requests\s*\n([\s\S]*?)(?:\n## |$)/);
+  const pendingExpansions = requestMatch ? (requestMatch[1].match(/^\s*-\s*status:\s*pending\b/gim) || []).length : 0;
+  return {
+    allowedPaths: parseListSection(content, "Allowed Paths"),
+    approvedExpansions: parseListSection(content, "Approved Expansions"),
+    pendingExpansions
+  };
+}
+function loadContextPolicy(cwd) {
+  const defaults = {
+    forbiddenPaths: [
+      ".claude/worktrees/**",
+      ".git/**",
+      "node_modules/**",
+      "dist/**",
+      "build/**",
+      "assets/**",
+      "specs/archive/**",
+      "specs/changes/*"
+    ],
+    audit: {
+      requireFilesRead: true,
+      unknownFilesRead: "warn-for-legacy-fail-for-new"
+    }
+  };
+  const policyPath = join10(cwd, ".cdd", "context-policy.json");
+  if (!existsSync9(policyPath))
+    return defaults;
+  try {
+    const custom = JSON.parse(readFileSync7(policyPath, "utf8"));
+    return {
+      ...defaults,
+      ...custom,
+      forbiddenPaths: Array.from(/* @__PURE__ */ new Set([...defaults.forbiddenPaths, ...custom.forbiddenPaths ?? []])),
+      audit: { ...defaults.audit, ...custom.audit ?? {} }
+    };
+  } catch {
+    log.warn("could not parse .cdd/context-policy.json; using default context policy");
+    return defaults;
+  }
+}
+function isContextGovernedChange(changeDir) {
+  const tasksPath = join10(changeDir, "tasks.md");
+  if (!existsSync9(tasksPath))
+    return false;
+  return /^context-governance:\s*v1\b/m.test(readFileSync7(tasksPath, "utf8"));
+}
+var KNOWN_FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+  "change-id",
+  "status",
+  "tier",
+  "archive-tasks",
+  "context-governance",
+  "depends-on",
+  // Allowed but informational only:
+  "token-budget",
+  "created",
+  "completed"
+]);
+var VALID_TASK_STATUSES = /* @__PURE__ */ new Set(["in-progress", "completed", "complete", "done", "gate-blocked", "abandoned", "needs-review"]);
+function lintFrontmatter(content, errors, warnings) {
+  const fm = parseTaskFrontmatter(content);
+  if (!fm["change-id"]) {
+    errors.push("tasks.md frontmatter: missing required `change-id`");
+  }
+  if (!fm.status) {
+    errors.push("tasks.md frontmatter: missing required `status`");
+  } else if (!VALID_TASK_STATUSES.has(fm.status.toLowerCase())) {
+    errors.push(`tasks.md frontmatter: invalid status \`${fm.status}\` (expected one of: ${[...VALID_TASK_STATUSES].join(", ")})`);
+  }
+  if (fm.tier !== void 0 && fm.tier !== "") {
+    const n = parseInt(fm.tier, 10);
+    if (Number.isNaN(n) || n < 0 || n > 5) {
+      errors.push(`tasks.md frontmatter: invalid tier \`${fm.tier}\` (expected 0-5)`);
+    }
+  }
+  for (const key of Object.keys(fm)) {
+    if (!KNOWN_FRONTMATTER_KEYS.has(key)) {
+      const lower = key.toLowerCase();
+      const suggestion = KNOWN_FRONTMATTER_KEYS.has(lower) ? ` (did you mean \`${lower}\`?)` : "";
+      warnings.push(`tasks.md frontmatter: unknown key \`${key}\`${suggestion}`);
+    }
+  }
+}
+function parseTaskFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match)
+    return {};
+  const out = {};
+  for (const line of match[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 parseDependsOn2(content) {
+  return parseListField(parseTaskFrontmatter(content)["depends-on"]);
+}
+function parseTaskStatus(content) {
+  const fm = parseTaskFrontmatter(content);
+  return (fm.status ?? "in-progress").toLowerCase();
+}
+function resolveTier(changeDir) {
+  const classifPath = join10(changeDir, "change-classification.md");
+  const classificationPresent = existsSync9(classifPath);
+  const classificationText = classificationPresent ? readFileSync7(classifPath, "utf8") : "";
+  const classificationHasLooseMarker = classificationPresent && TIER_PATTERN.test(classificationText);
+  const tasksPath = join10(changeDir, "tasks.md");
+  if (existsSync9(tasksPath)) {
+    const fm = parseTaskFrontmatter(readFileSync7(tasksPath, "utf8"));
+    const raw = fm.tier;
+    if (raw && raw !== "") {
+      const n = parseInt(raw, 10);
+      if (!Number.isNaN(n) && n >= 0 && n <= 5) {
+        return { tier: n, source: "tasks-frontmatter", classificationPresent, classificationHasLooseMarker };
+      }
+    }
+  }
+  if (classificationPresent) {
+    const structured = classificationText.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
+    if (structured) {
+      const n = parseInt(structured[1], 10);
+      if (!Number.isNaN(n) && n >= 0 && n <= 5) {
+        return { tier: n, source: "classification-structured", classificationPresent, classificationHasLooseMarker };
+      }
+    }
+    const bold = classificationText.match(/\*\*Tier:\*\*\s*Tier\s*(\d)\b/i);
+    if (bold) {
+      const n = parseInt(bold[1], 10);
+      if (!Number.isNaN(n) && n >= 0 && n <= 5) {
+        return { tier: n, source: "classification-bold", classificationPresent, classificationHasLooseMarker };
+      }
+    }
+  }
+  return { tier: null, source: "none", classificationPresent, classificationHasLooseMarker };
+}
+var DEFAULT_ARCHIVE_TASKS = ["7.1", "7.2"];
+function getArchiveTaskIds(content) {
+  const fm = parseTaskFrontmatter(content);
+  const parsed = parseListField(fm["archive-tasks"]);
+  return parsed.length > 0 ? parsed : DEFAULT_ARCHIVE_TASKS;
+}
+function enforceTierRequirements(changeDir, agentLogDir, errors, warnings) {
+  const resolution = resolveTier(changeDir);
+  if (resolution.tier === null) {
+    if (resolution.classificationPresent && !resolution.classificationHasLooseMarker) {
+      errors.push(
+        "change-classification.md: missing tier marker. Set `tier: <0-5>` in tasks.md frontmatter (preferred) or include `## Tier\\n- N` in change-classification.md."
+      );
+    }
+    return;
+  }
+  if (resolution.source === "classification-bold") {
+    warnings.push(
+      "tier marker is bold-text only (legacy format); set `tier: <0-5>` in tasks.md frontmatter so tier-specific agent requirements are enforced."
+    );
+    return;
+  }
+  const tier = resolution.tier;
+  const agentLogFiles = agentLogDir && existsSync9(agentLogDir) ? readdirSync6(agentLogDir).map((f) => f.replace(".md", "")) : [];
+  if (tier <= 1) {
+    for (const required of ["e2e-resilience-engineer", "monkey-test-engineer", "stress-soak-engineer"]) {
+      if (!agentLogFiles.includes(required)) {
+        errors.push(`Tier ${tier} change requires agent-log/${required}.md (high-risk change \u2014 E2E/monkey/stress testing mandatory)`);
+      }
+    }
+  }
+  if (tier <= 3) {
+    for (const required of ["contract-reviewer", "qa-reviewer"]) {
+      if (!agentLogFiles.includes(required)) {
+        errors.push(`Tier ${tier} change requires agent-log/${required}.md`);
+      }
+    }
+  }
+  if (resolution.source === "tasks-frontmatter" && resolution.classificationPresent) {
+    const text = readFileSync7(join10(changeDir, "change-classification.md"), "utf8");
+    const structured = text.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
+    const bold = text.match(/\*\*Tier:\*\*\s*Tier\s*(\d)\b/i);
+    const classifTier = structured ? parseInt(structured[1], 10) : bold ? parseInt(bold[1], 10) : NaN;
+    if (!Number.isNaN(classifTier) && classifTier !== tier) {
+      warnings.push(
+        `tier mismatch: tasks.md frontmatter says ${tier}, change-classification.md says ${classifTier} (frontmatter wins; reconcile classification).`
+      );
+    }
+  }
+}
+function isArchivedChange(cwd, changeId) {
+  const archiveRoot = join10(cwd, "specs", "archive");
+  if (!existsSync9(archiveRoot))
+    return false;
+  const years = readdirSync6(archiveRoot, { withFileTypes: true }).filter((d) => d.isDirectory());
+  return years.some((year) => existsSync9(join10(archiveRoot, year.name, changeId)));
+}
+function detectDependencyCycle(cwd, startChangeId) {
+  const visited = /* @__PURE__ */ new Set();
+  const stack = [];
+  function visit(id) {
+    if (stack.includes(id)) {
+      return [...stack.slice(stack.indexOf(id)), id];
+    }
+    if (visited.has(id))
+      return null;
+    visited.add(id);
+    stack.push(id);
+    const tasksPath = join10(cwd, "specs", "changes", id, "tasks.md");
+    if (existsSync9(tasksPath)) {
+      const deps = parseDependsOn2(readFileSync7(tasksPath, "utf8"));
+      for (const dep of deps) {
+        const found = visit(dep);
+        if (found)
+          return found;
+      }
+    }
+    stack.pop();
+    return null;
+  }
+  return visit(startChangeId);
+}
+function validateDependencies(cwd, changeId, changeDir) {
+  const tasksPath = join10(changeDir, "tasks.md");
+  if (!existsSync9(tasksPath))
+    return [];
+  const dependencies = parseDependsOn2(readFileSync7(tasksPath, "utf8"));
+  const errors = [];
+  const cycle = detectDependencyCycle(cwd, changeId);
+  if (cycle) {
+    errors.push(`depends-on cycle detected: ${cycle.join(" \u2192 ")}`);
+  }
+  for (const dep of dependencies) {
+    if (dep === changeId) {
+      errors.push(`tasks.md: change cannot depend on itself (${dep})`);
+      continue;
+    }
+    const upstreamDir = join10(cwd, "specs", "changes", dep);
+    if (existsSync9(upstreamDir)) {
+      const upstreamTasks = join10(upstreamDir, "tasks.md");
+      if (!existsSync9(upstreamTasks)) {
+        errors.push(`dependency ${dep}: missing tasks.md`);
+        continue;
+      }
+      const status = parseTaskStatus(readFileSync7(upstreamTasks, "utf8"));
+      if (!["complete", "completed", "done"].includes(status)) {
+        errors.push(`dependency ${dep}: upstream change is not completed (status: ${status})`);
+      }
+      continue;
+    }
+    if (!isArchivedChange(cwd, dep)) {
+      errors.push(`dependency ${dep}: upstream change not found in specs/changes/ or specs/archive/`);
+    }
+  }
+  return errors;
+}
+function parseFilesRead(content) {
+  const clean = stripHtmlComments(content);
+  const allLines = clean.split(/\r?\n/);
+  const startIndex = allLines.findIndex((line) => /^\s*-\s*files-read:\s*$/.test(line));
+  if (startIndex === -1)
+    return { present: false, files: [], errors: [] };
+  const files = [];
+  const errors = [];
+  const lines = [];
+  for (let i = startIndex + 1; i < allLines.length; i++) {
+    const line = allLines[i];
+    if (/^-\s*[a-zA-Z][\w-]*:\s*/.test(line) || /^#/.test(line))
+      break;
+    lines.push(line);
+  }
+  for (const rawLine of lines) {
+    if (!rawLine.trim())
+      continue;
+    const itemMatch = rawLine.match(/^\s{2,}-\s+(.+?)\s*$/);
+    if (!itemMatch) {
+      errors.push(`invalid files-read entry format: ${rawLine.trim()}`);
+      continue;
+    }
+    const item = itemMatch[1].trim();
+    if (!item || item === "-" || item.toLowerCase() === "none" || item.toLowerCase() === "unknown") {
+      continue;
+    }
+    const normalized = item.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (/^[a-zA-Z]:\//.test(normalized) || normalized.startsWith("/")) {
+      errors.push(`files-read path must be repo-relative: ${item}`);
+      continue;
+    }
+    if (normalized.split("/").includes("..")) {
+      errors.push(`files-read path must not contain "..": ${item}`);
+      continue;
+    }
+    files.push(normalized);
+  }
+  if (files.length === 0 && errors.length === 0) {
+    errors.push("files-read section must list repo-relative paths or omit the section for legacy changes");
+  }
+  return { present: true, files, errors };
+}
 async function gate(changeId, opts = {}) {
   const strict = opts.strict ?? false;
+  const lax = opts.lax ?? false;
   const cwd = process.cwd();
-  const changeDir = join8(cwd, "specs", "changes", changeId);
-  if (!existsSync7(changeDir)) {
+  const changeDir = join10(cwd, "specs", "changes", changeId);
+  if (!existsSync9(changeDir)) {
     log.error(`change not found: ${changeId} (looked in ${changeDir})`);
     process.exit(1);
   }
   const errors = [];
   const warnings = [];
+  const contextPolicy = loadContextPolicy(cwd);
+  const isNewChange = isContextGovernedChange(changeDir);
+  const manifestPath = join10(changeDir, "context-manifest.md");
+  const hasManifest = existsSync9(manifestPath);
+  let allowedPaths = [];
+  let approvedExpansions = [];
+  errors.push(...validateDependencies(cwd, changeId, changeDir));
+  if (hasManifest) {
+    const manifest = parseContextManifest(readFileSync7(manifestPath, "utf8"));
+    allowedPaths = manifest.allowedPaths;
+    approvedExpansions = manifest.approvedExpansions;
+    if (manifest.pendingExpansions > 0) {
+      errors.push(`context-manifest.md: has ${manifest.pendingExpansions} pending context expansion request(s)`);
+    }
+  }
   for (const f of REQUIRED_FILES) {
-    if (!existsSync7(join8(changeDir, f))) {
+    if (f === "context-manifest.md") {
+      if (!hasManifest) {
+        if (isNewChange || strict) {
+          errors.push("missing required artifact: context-manifest.md");
+        } else {
+          warnings.push("missing context-manifest.md (legacy change; run cdd-kit migrate after upgrading)");
+        }
+      }
+      continue;
+    }
+    if (!existsSync9(join10(changeDir, f))) {
       errors.push(`missing required artifact: ${f}`);
     }
   }
   if (errors.length === 0) {
     for (const f of REQUIRED_FILES) {
-      const content = readFileSync4(join8(changeDir, f), "utf8");
+      if (f === "context-manifest.md" && !hasManifest)
+        continue;
+      const content = readFileSync7(join10(changeDir, f), "utf8");
       const minChars = MIN_CHARS[f] ?? 100;
       if (meaningfulChars(content) < minChars) {
         errors.push(`${f}: appears to be a stub (< ${minChars} meaningful chars)`);
       }
     }
-    const classifPath = join8(changeDir, "change-classification.md");
-    if (existsSync7(classifPath)) {
-      const text = readFileSync4(classifPath, "utf8");
-      if (!TIER_PATTERN.test(text)) {
-        errors.push("change-classification.md: missing tier/risk marker (Tier 0-5 or low/medium/high/critical)");
-      }
+    const classifPath = join10(changeDir, "change-classification.md");
+    const tierResolution = resolveTier(changeDir);
+    if (tierResolution.tier === null && existsSync9(classifPath) && !tierResolution.classificationHasLooseMarker) {
+      errors.push("change-classification.md: missing tier/risk marker (set tier in tasks.md frontmatter, or include Tier 0-5 / low|medium|high|critical in change-classification.md)");
     }
   }
-  const tasksPath = join8(changeDir, "tasks.md");
-  if (existsSync7(tasksPath)) {
-    const tasksContent = readFileSync4(tasksPath, "utf8");
-    const nonArchivePending = (tasksContent.match(/^\s*-\s*\[ \] (?!7\.[12])/gm) || []).length;
+  const tasksPath = join10(changeDir, "tasks.md");
+  if (existsSync9(tasksPath)) {
+    const tasksContent = readFileSync7(tasksPath, "utf8");
+    lintFrontmatter(tasksContent, errors, warnings);
+    const archiveTaskIds = new Set(getArchiveTaskIds(tasksContent));
+    const pendingMatches = tasksContent.match(/^\s*-\s*\[ \]\s+([\d.]+)?[^\n]*/gm) || [];
+    const nonArchivePending = pendingMatches.filter((line) => {
+      const idMatch = line.match(/\[ \]\s+([\d.]+)/);
+      const id = idMatch?.[1];
+      if (!id)
+        return true;
+      return !archiveTaskIds.has(id);
+    }).length;
     if (nonArchivePending > 0) {
       if (strict) {
         errors.push(`${nonArchivePending} task(s) still pending (use [-] for N/A items, [x] for done). Run gate without --strict during development.`);
@@ -1075,11 +2814,55 @@ async function gate(changeId, opts = {}) {
       }
     }
   }
-  const agentLogDir = join8(changeDir, "agent-log");
-  if (existsSync7(agentLogDir)) {
-    const logFiles = readdirSync5(agentLogDir).filter((f) => f.endsWith(".md"));
+  const agentLogDir = join10(changeDir, "agent-log");
+  if (existsSync9(agentLogDir)) {
+    const logFiles = readdirSync6(agentLogDir).filter((f) => f.endsWith(".md"));
     for (const f of logFiles) {
-      const content = readFileSync4(join8(agentLogDir, f), "utf8");
+      const content = readFileSync7(join10(agentLogDir, f), "utf8");
+      const filesRead = parseFilesRead(content);
+      if (!filesRead.present) {
+        if (contextPolicy.audit.requireFilesRead) {
+          const msg = `agent-log/${f}: missing "- files-read:" section`;
+          if (isNewChange || strict || contextPolicy.audit.unknownFilesRead !== "warn-for-legacy-fail-for-new") {
+            errors.push(msg);
+          } else {
+            warnings.push(`${msg} (legacy warning only)`);
+          }
+        }
+      } else {
+        for (const parseError of filesRead.errors) {
+          errors.push(`agent-log/${f}: ${parseError}`);
+        }
+        for (const pathRead of filesRead.files) {
+          if (pathMatches(pathRead, contextPolicy.forbiddenPaths, changeId)) {
+            errors.push(`agent-log/${f}: read forbidden path -> ${pathRead}`);
+          }
+          if (hasManifest && allowedPaths.length > 0 && !pathMatches(pathRead, allowedPaths) && !pathMatches(pathRead, approvedExpansions)) {
+            errors.push(`agent-log/${f}: read unauthorized path -> ${pathRead} (not in allowed paths or approved expansions)`);
+          }
+        }
+        const runtimeLog = join10(cwd, ".cdd", "runtime", `${changeId}-files-read.jsonl`);
+        if (existsSync9(runtimeLog)) {
+          const runtimePaths = readFileSync7(runtimeLog, "utf8").split("\n").filter(Boolean).map((line) => {
+            try {
+              return JSON.parse(line).path;
+            } catch {
+              return void 0;
+            }
+          }).filter((p) => Boolean(p)).map((p) => p.replace(/\\/g, "/").replace(/^\.\//, ""));
+          const declared = new Set(filesRead.files);
+          const undeclared = runtimePaths.filter((p) => !declared.has(p));
+          if (undeclared.length > 0) {
+            const sample = undeclared.slice(0, 5).join(", ");
+            const more = undeclared.length > 5 ? ` (+${undeclared.length - 5} more)` : "";
+            const msg = `agent-log/${f}: runtime log shows ${undeclared.length} read(s) not declared in files-read: ${sample}${more}`;
+            if (strict)
+              errors.push(msg);
+            else
+              warnings.push(msg);
+          }
+        }
+      }
       const statusMatch = content.match(/^\s*-\s*status:\s*(complete|needs-review|blocked)\s*$/m);
       if (!statusMatch) {
         errors.push(`agent-log/${f}: missing or invalid "status:" line (must be complete | needs-review | blocked)`);
@@ -1092,7 +2875,7 @@ async function gate(changeId, opts = {}) {
           errors.push(`agent-log/${f}: status=blocked requires concrete "next-action:" line (>= 10 chars, not "none")`);
         }
       }
-      if (strict) {
+      if (!lax) {
         const artifactsMatch = content.match(/- artifacts:([\s\S]*?)(?:\n- |\n#|$)/);
         if (artifactsMatch) {
           const artifactLines = artifactsMatch[1].split("\n").filter((l) => l.trim().startsWith("-"));
@@ -1100,8 +2883,8 @@ async function gate(changeId, opts = {}) {
             const pointer = line.replace(/^\s*-\s*[\w-]+:\s*/, "").trim();
             const pathPart = pointer.split(":")[0];
             if (pathPart.includes("/") && !pointer.startsWith("http")) {
-              const abs = join8(cwd, pathPart);
-              if (!existsSync7(abs)) {
+              const abs = join10(cwd, pathPart);
+              if (!existsSync9(abs)) {
                 errors.push(`agent-log/${f}: artifact pointer not found: ${pathPart}`);
               }
             }
@@ -1109,48 +2892,9 @@ async function gate(changeId, opts = {}) {
         }
       }
     }
-    const classifPath = join8(changeDir, "change-classification.md");
-    if (existsSync7(classifPath)) {
-      const classificationContent = readFileSync4(classifPath, "utf8");
-      const tierMatch = classificationContent.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
-      const tier = tierMatch ? parseInt(tierMatch[1]) : null;
-      if (tier !== null) {
-        const agentLogFiles = readdirSync5(agentLogDir).map((f) => f.replace(".md", ""));
-        if (tier <= 1) {
-          for (const required of ["e2e-resilience-engineer", "monkey-test-engineer", "stress-soak-engineer"]) {
-            if (!agentLogFiles.includes(required)) {
-              errors.push(`Tier ${tier} change requires agent-log/${required}.md (high-risk change \u2014 E2E/monkey/stress testing mandatory)`);
-            }
-          }
-        }
-        if (tier <= 3) {
-          for (const required of ["contract-reviewer", "qa-reviewer"]) {
-            if (!agentLogFiles.includes(required)) {
-              errors.push(`Tier ${tier} change requires agent-log/${required}.md`);
-            }
-          }
-        }
-      }
-    }
+    enforceTierRequirements(changeDir, agentLogDir, errors, warnings);
   } else {
-    const classifPath = join8(changeDir, "change-classification.md");
-    if (existsSync7(classifPath)) {
-      const classificationContent = readFileSync4(classifPath, "utf8");
-      const tierMatch = classificationContent.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
-      const tier = tierMatch ? parseInt(tierMatch[1]) : null;
-      if (tier !== null) {
-        if (tier <= 1) {
-          for (const required of ["e2e-resilience-engineer", "monkey-test-engineer", "stress-soak-engineer"]) {
-            errors.push(`Tier ${tier} change requires agent-log/${required}.md (high-risk change \u2014 E2E/monkey/stress testing mandatory)`);
-          }
-        }
-        if (tier <= 3) {
-          for (const required of ["contract-reviewer", "qa-reviewer"]) {
-            errors.push(`Tier ${tier} change requires agent-log/${required}.md`);
-          }
-        }
-      }
-    }
+    enforceTierRequirements(changeDir, null, errors, warnings);
   }
   for (const w of warnings) {
     log.warn(`  ${w}`);
@@ -1163,12 +2907,10 @@ async function gate(changeId, opts = {}) {
     process.exit(1);
   }
   log.info(`gate: running contract validators for ${changeId}\u2026`);
-  const r = spawnSync2(process.execPath, [process.argv[1], "validate", "--contracts", "--env", "--ci", "--versions"], {
-    cwd,
-    stdio: "inherit"
-  });
-  if (r.status !== 0) {
-    log.error(`gate failed for change: ${changeId} (validators returned non-zero)`);
+  try {
+    await validate({ contracts: true, env: true, ci: true, spec: false, versions: true });
+  } catch (err) {
+    log.error(`gate failed for change: ${changeId} (validators threw): ${err.message}`);
     process.exit(1);
   }
   for (const w of warnings) {
@@ -1178,27 +2920,28 @@ async function gate(changeId, opts = {}) {
 }
 
 // src/commands/install-hooks.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync2, chmodSync, mkdirSync as mkdirSync3 } from "fs";
-import { join as join9 } from "path";
+init_paths();
 init_logger();
+import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync4, chmodSync, mkdirSync as mkdirSync4 } from "fs";
+import { join as join11 } from "path";
 var START_MARKER = "# cdd-kit-managed-block-start";
 var END_MARKER = "# cdd-kit-managed-block-end";
 async function installHooks() {
   const cwd = process.cwd();
-  const gitDir = join9(cwd, ".git");
-  if (!existsSync8(gitDir)) {
+  const gitDir = join11(cwd, ".git");
+  if (!existsSync10(gitDir)) {
     log.error("not a git repository (no .git/ found in cwd)");
     process.exit(1);
   }
-  const hooksDir = join9(gitDir, "hooks");
-  mkdirSync3(hooksDir, { recursive: true });
-  const dest = join9(hooksDir, "pre-commit");
-  const ourHook = readFileSync5(join9(ASSET.hooks, "pre-commit"), "utf8");
+  const hooksDir = join11(gitDir, "hooks");
+  mkdirSync4(hooksDir, { recursive: true });
+  const dest = join11(hooksDir, "pre-commit");
+  const ourHook = readFileSync8(join11(ASSET.hooks, "pre-commit"), "utf8");
   let final;
-  if (!existsSync8(dest)) {
+  if (!existsSync10(dest)) {
     final = ourHook;
   } else {
-    const existing = readFileSync5(dest, "utf8");
+    const existing = readFileSync8(dest, "utf8");
     const startIdx = existing.indexOf(START_MARKER);
     const endIdx = existing.indexOf(END_MARKER);
     if (startIdx >= 0 && endIdx > startIdx) {
@@ -1222,7 +2965,7 @@ async function installHooks() {
       }
     }
   }
-  writeFileSync2(dest, final, "utf8");
+  writeFileSync4(dest, final, "utf8");
   try {
     chmodSync(dest, 493);
   } catch {
@@ -1232,22 +2975,36 @@ async function installHooks() {
 }
 
 // src/cli/index.ts
-var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
-var pkg = JSON.parse(readFileSync10(join14(__dirname2, "..", "..", "package.json"), "utf8"));
+var __dirname2 = dirname5(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync16(join19(__dirname2, "..", "..", "package.json"), "utf8"));
 var program = new Command();
 program.name("cdd-kit").description("Contract-Driven Delivery Kit CLI").version(pkg.version);
 program.command("init").description(
   "Install agents/skill into ~/.claude and scaffold project files in cwd"
-).option("--global-only", "Only install into ~/.claude, skip project files", false).option("--local-only", "Only scaffold project files, skip ~/.claude", false).option("--force", "Overwrite existing project files", false).action(
+).option("--global-only", "Only install into ~/.claude, skip project files", false).option("--local-only", "Only scaffold project files, skip ~/.claude", false).option("--force", "Overwrite existing project files", false).option("--provider <provider>", "Provider adapter to scaffold: claude, codex, or both", "claude").action(
   (opts) => init({
     globalOnly: opts.globalOnly,
     localOnly: opts.localOnly,
-    force: opts.force
+    force: opts.force,
+    provider: opts.provider
   })
 );
-program.command("update").description("Update ~/.claude agents and skill (does not touch project files)").option("--yes", "Apply changes (default is dry-run)", false).action((opts) => update({ yes: opts.yes }));
-program.command("new <name>").description("Scaffold a new change directory under specs/changes/<name>").option("--all", "Include optional templates in addition to required ones", false).option("--force", "Overwrite existing template files in the change folder", false).action(
-  (name, opts) => newChange(name, { all: opts.all, force: opts.force })
+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").action((opts) => update({ yes: opts.yes, 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 });
+});
+program.command("upgrade").description("Add missing cdd-kit repo-level files without overwriting existing project files").option("--yes", "Apply changes (default is dry-run)", false).option("--migrate-changes", "Also migrate existing specs/changes/* directories", false).option("--enable-context-governance", "When migrating changes, opt them into context-governance: v1", false).option("--provider <provider>", "Provider adapter to scaffold: auto, claude, codex, or both", "auto").action(async (opts) => {
+  const { upgrade: upgrade2 } = await Promise.resolve().then(() => (init_upgrade(), upgrade_exports));
+  await upgrade2({
+    yes: opts.yes,
+    migrateChanges: opts.migrateChanges,
+    enableContextGovernance: opts.enableContextGovernance,
+    provider: opts.provider
+  });
+});
+program.command("new <name>").description("Scaffold a new change directory under specs/changes/<name>").option("--all", "Include optional templates in addition to required ones", false).option("--force", "Overwrite existing template files in the change folder", false).option("--depends-on <change-ids>", "Comma-separated upstream change ids that must complete first").option("--skip-scan", "Skip the auto context-scan when indexes are stale (advanced)", false).action(
+  (name, opts) => newChange(name, { all: opts.all, force: opts.force, dependsOn: opts.dependsOn, skipScan: opts.skipScan })
 );
 program.command("validate").description("Run validation scripts (defaults to all)").option("--contracts", "Validate API/data/CSS contracts (use --env separately for env)", false).option("--env", "Validate env contract", false).option("--ci", "Validate CI gate policy", false).option("--spec", "Validate spec traceability", false).option("--versions", "Validate contract frontmatter and version bumps", false).action(
   (opts) => validate({
@@ -1258,8 +3015,8 @@ program.command("validate").description("Run validation scripts (defaults to all
     versions: opts.versions
   })
 );
-program.command("gate <change-id>").description("Run full orchestration gate for a change (required artifacts, content, tier, contracts)").option("--strict", "Treat pending tasks (except section 7) as errors, and validate artifact pointers", false).action(async (id, opts) => {
-  await gate(id, { strict: opts.strict });
+program.command("gate <change-id>").description("Run full orchestration gate for a change (required artifacts, content, tier, contracts)").option("--strict", "Treat pending tasks (except section 7) as errors, and treat runtime/declared files-read drift as errors", false).option("--lax", "Skip artifact-pointer existence check (for legacy repos with stale logs)", false).action(async (id, opts) => {
+  await gate(id, { strict: opts.strict, lax: opts.lax });
 });
 program.command("archive <change-id>").description("Move a completed change from specs/changes/ to specs/archive/<year>/").action(async (changeId) => {
   const { archive: archive2 } = await Promise.resolve().then(() => (init_archive(), archive_exports));
@@ -1269,9 +3026,14 @@ program.command("abandon <change-id>").description("Mark a change as abandoned (
   const { abandon: abandon2 } = await Promise.resolve().then(() => (init_abandon(), abandon_exports));
   await abandon2(changeId, opts);
 });
-program.command("migrate [change-id]").description("Upgrade existing change directories to v1.11.0 format (tasks.md frontmatter + tier format)").option("--all", "Migrate all changes in specs/changes/", false).option("--dry-run", "Show what would change without writing files", false).action(async (changeId, opts = {}) => {
+program.command("migrate [change-id]").description("Upgrade existing change directories to the current cdd-kit format (tasks.md frontmatter + tier format)").option("--all", "Migrate all changes in specs/changes/", false).option("--dry-run", "Show what would change without writing files", false).option("--enable-context-governance", "Opt legacy changes into context-governance: v1 hard gate behavior", false).option("--no-backup", "Skip the per-session backup at .cdd/migrate-backup/<stamp>/ (not recommended)").action(async (changeId, opts = {}) => {
   const { migrate: migrate2 } = await Promise.resolve().then(() => (init_migrate(), migrate_exports));
-  await migrate2(changeId, opts);
+  await migrate2(changeId, {
+    all: opts.all,
+    dryRun: opts.dryRun,
+    enableContextGovernance: opts.enableContextGovernance,
+    noBackup: opts.backup === false
+  });
 });
 program.command("list").description("List active changes in specs/changes/").action(async () => {
   const { listChanges: listChanges2 } = await Promise.resolve().then(() => (init_list_changes(), list_changes_exports));
@@ -1293,4 +3055,49 @@ program.command("detect-stack").description("Detect the project tech stack and p
     );
   }
 });
+program.command("context-scan").description("Deterministically scan project context and generate specs/context maps").option("--surface <path>", "Limit project-map tree to a sub-directory (e.g. --surface src/server)").action(async (opts) => {
+  const { contextScan: contextScan2 } = await Promise.resolve().then(() => (init_context_scan(), context_scan_exports));
+  await contextScan2({ surface: opts.surface });
+});
+var context = program.command("context").description("Manage context governance manifests");
+context.command("request <change-id> <request-id>").description("Record a new pending Context Expansion Request").requiredOption("--path <paths...>", "Repo-relative path(s) requested by the agent").option("--reason <text>", "Reason the extra context is required").action(async (changeId, requestId, opts) => {
+  const { requestContextExpansion: requestContextExpansion2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  await requestContextExpansion2(changeId, requestId, opts.path, opts.reason);
+});
+context.command("approve <change-id> [request-id]").description("Approve a pending Context Expansion Request (or all with --all-pending)").option("--all-pending", "Approve every pending Context Expansion Request for this change", false).action(async (changeId, requestId, opts) => {
+  const { approveContextExpansion: approveContextExpansion2, approveAllPending: approveAllPending2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  if (opts.allPending) {
+    if (requestId) {
+      console.error("--all-pending cannot be combined with a request-id");
+      process.exit(1);
+    }
+    await approveAllPending2(changeId);
+  } else {
+    if (!requestId) {
+      console.error("request-id is required (or pass --all-pending)");
+      process.exit(1);
+    }
+    await approveContextExpansion2(changeId, requestId);
+  }
+});
+context.command("reject <change-id> [request-id]").description("Reject a pending Context Expansion Request (or all with --all-pending)").option("--all-pending", "Reject every pending Context Expansion Request for this change", false).action(async (changeId, requestId, opts) => {
+  const { rejectContextExpansion: rejectContextExpansion2, rejectAllPending: rejectAllPending2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  if (opts.allPending) {
+    if (requestId) {
+      console.error("--all-pending cannot be combined with a request-id");
+      process.exit(1);
+    }
+    await rejectAllPending2(changeId);
+  } else {
+    if (!requestId) {
+      console.error("request-id is required (or pass --all-pending)");
+      process.exit(1);
+    }
+    await rejectContextExpansion2(changeId, requestId);
+  }
+});
+context.command("list <change-id>").description("List Context Expansion Requests for a change").option("--json", "Print machine-readable JSON", false).action(async (changeId, opts) => {
+  const { listContextExpansions: listContextExpansions2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  await listContextExpansions2(changeId, opts.json);
+});
 program.parse();