contract-driven-delivery 1.11.0 → 1.12.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,184 @@ var init_logger = __esm({
   }
 });
 
-// src/commands/archive.ts
-var archive_exports = {};
-__export(archive_exports, {
-  archive: () => archive
-});
-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);
-  }
-  if (existsSync9(archiveDir)) {
-    log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
-    process.exit(1);
-  }
-  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).");
-    }
-    const pending = (content.match(/^\s*-\s*\[ \]/gm) || []).length;
-    if (pending > 0) {
-      log.warn(`${pending} task(s) still pending ([ ]). Archive anyway.`);
-    }
-  }
-  if (!existsSync9(archiveBase)) {
-    mkdirSync4(archiveBase, { recursive: true });
-  }
-  try {
-    renameSync(changeDir, archiveDir);
-  } catch (err) {
-    if (err.code === "EXDEV") {
-      cpSync2(changeDir, archiveDir, { recursive: true });
-      rmSync2(changeDir, { recursive: true, force: true });
-    } else {
-      throw err;
+// 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 {
     }
   }
-  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 (!existsSync9(indexPath)) {
-    writeFileSync3(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`);
+  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_archive = __esm({
-  "src/commands/archive.ts"() {
+var init_provider = __esm({
+  "src/utils/provider.ts"() {
     "use strict";
-    init_logger();
   }
 });
 
-// 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 { existsSync as existsSync10, readdirSync as readdirSync6, readFileSync as readFileSync8, statSync as statSync2 } from "fs";
 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}`);
+function fileExists(cwd, relPath) {
+  return existsSync10(join11(cwd, relPath));
+}
+function findFiles(dir, predicate, found = []) {
+  if (!existsSync10(dir))
+    return found;
+  for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+    const fullPath = join11(dir, entry.name);
+    if (entry.isDirectory())
+      findFiles(fullPath, predicate, found);
+    else if (entry.isFile() && predicate(entry.name))
+      found.push(fullPath);
+  }
+  return found;
+}
+function newestMtime(paths) {
+  let newest = 0;
+  for (const path of paths) {
+    try {
+      newest = Math.max(newest, statSync2(path).mtimeMs);
+    } catch {
+    }
+  }
+  return newest;
+}
+function readMissingSummaryCount(cwd) {
+  const indexPath = join11(cwd, "specs", "context", "contracts-index.md");
+  if (!existsSync10(indexPath))
+    return null;
+  const match = readFileSync8(indexPath, "utf8").match(/^missing-summary-count:\s*(\d+)/m);
+  return match ? Number(match[1]) : null;
+}
+function checkContextFreshness(cwd) {
+  const findings = [];
+  const projectMap = join11(cwd, "specs", "context", "project-map.md");
+  const contractsIndex = join11(cwd, "specs", "context", "contracts-index.md");
+  const contextPolicy = join11(cwd, ".cdd", "context-policy.json");
+  const contractFiles = findFiles(join11(cwd, "contracts"), (name) => name.endsWith(".md"));
+  if (!existsSync10(projectMap) || !existsSync10(contractsIndex)) {
+    findings.push({
+      level: "warning",
+      message: "specs/context indexes are missing; run cdd-kit context-scan before classification"
+    });
+    return findings;
+  }
+  const projectInputs = [contextPolicy].filter(existsSync10);
+  if (projectInputs.length > 0 && statSync2(projectMap).mtimeMs < newestMtime(projectInputs)) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/project-map.md is older than .cdd/context-policy.json; run cdd-kit context-scan"
+    });
+  }
+  if (contractFiles.length > 0 && statSync2(contractsIndex).mtimeMs < newestMtime(contractFiles)) {
+    findings.push({
+      level: "warning",
+      message: "specs/context/contracts-index.md is older than contracts/; run cdd-kit context-scan"
+    });
+  }
+  const missingSummaryCount = readMissingSummaryCount(cwd);
+  if (missingSummaryCount !== null && missingSummaryCount > 0) {
+    findings.push({
+      level: "warning",
+      message: `contracts-index reports ${missingSummaryCount} contract(s) without deterministic summary metadata`
+    });
+  }
+  if (findings.length === 0) {
+    findings.push({ level: "ok", message: "context indexes are present and fresh" });
+  }
+  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");
-    } else {
-      content = `---
-change-id: ${changeId}
-status: abandoned
----
-
-` + content;
-    }
-    writeFileSync4(tasksPath, content, "utf8");
+  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` });
   }
-  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 ((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 (!existsSync10(indexPath)) {
-    writeFileSync4(indexPath, `# Archive Index
-
-| change-id | status | date | notes |
-|---|---|---|---|
-${indexLine}`, "utf8");
+  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));
+  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 doctor(opts = {}) {
+  const report = buildDoctorReport(process.cwd(), opts);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.ok)
+      process.exit(1);
+    return;
+  }
+  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();
   }
 });
 
@@ -176,15 +261,126 @@ __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 { existsSync as existsSync11, readdirSync as readdirSync7, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+function buildLegacyContextManifest(changeId) {
+  return [
+    "# Context Manifest",
+    "",
+    "Generated by `cdd-kit migrate` for an existing change.",
+    "This legacy manifest records a conservative default context boundary without enabling context-governance: v1.",
+    "",
+    "## Affected Surfaces",
+    "- legacy-unknown",
+    "",
+    "## Allowed Paths",
+    `- specs/changes/${changeId}/`,
+    "",
+    "## Forbidden Paths",
+    "- .claude/worktrees/**",
+    "- .git/**",
+    "- node_modules/**",
+    "- dist/**",
+    "- build/**",
+    "- assets/**",
+    "- specs/archive/**",
+    `- specs/changes/* except 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.",
+    "",
+    "## Affected Surfaces",
+    "- legacy-unknown",
+    "",
+    "## Allowed Paths",
+    `- specs/changes/${changeId}/`,
+    "- specs/context/project-map.md",
+    "- specs/context/contracts-index.md",
+    "",
+    "## Forbidden Paths",
+    "- .claude/worktrees/**",
+    "- .git/**",
+    "- node_modules/**",
+    "- dist/**",
+    "- build/**",
+    "- assets/**",
+    "- specs/archive/**",
+    `- specs/changes/* except specs/changes/${changeId}/`,
+    "",
+    "## 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, dryRun, enableContextGovernance) {
   const changed = [];
   const warnings = [];
   const tasksPath = join12(changeDir, "tasks.md");
   if (existsSync11(tasksPath)) {
-    let content = readFileSync8(tasksPath, "utf8");
+    let content = readFileSync9(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 +394,7 @@ status: ${inferredStatus}
 
 ` + content;
       modified = true;
+      taskChanges.push("added YAML frontmatter");
     }
     if (!content.includes("[x]=done")) {
       content = content.replace(
@@ -207,18 +404,24 @@ 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");
+      changed.push(`tasks.md: ${taskChanges.join("; ")}`);
       if (!dryRun)
-        writeFileSync5(tasksPath, content, "utf8");
+        writeFileSync4(tasksPath, content, "utf8");
     }
   } 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 content = readFileSync9(classifPath, "utf8");
     const hasNewTierFormat = /^## Tier\s*\n\s*-\s*\d\s*$/m.test(content);
     if (!hasNewTierFormat) {
       const oldMatch = content.match(/\*\*Tier[:\*]+\s*(?:Tier\s*)?(\d)/i) ?? content.match(/^-?\s*Tier:\s*(?:Tier\s*)?(\d)/mi);
@@ -233,7 +436,7 @@ status: ${inferredStatus}
             `change-classification.md: appended "## Tier\\n- ${detectedTier}" (converted from old format)`
           );
           if (!dryRun)
-            writeFileSync5(classifPath, content + addition, "utf8");
+            writeFileSync4(classifPath, content + addition, "utf8");
         }
       } else {
         warnings.push(
@@ -242,11 +445,25 @@ status: ${inferredStatus}
       }
     }
   }
+  const manifestPath = join12(changeDir, "context-manifest.md");
+  if (!existsSync11(manifestPath)) {
+    changed.push(enableContextGovernance ? "context-manifest.md: added context-governance v1 manifest scaffold" : "context-manifest.md: added legacy context manifest scaffold");
+    if (!dryRun) {
+      writeFileSync4(
+        manifestPath,
+        enableContextGovernance ? buildContextGovernedManifest(changeId) : buildLegacyContextManifest(changeId),
+        "utf8"
+      );
+    }
+  } else if (enableContextGovernance) {
+    warnings.push("context-manifest.md already exists \u2014 review allowed paths before relying on context-governance: v1");
+  }
   return { changed, warnings };
 }
 async function migrate(changeId, opts = {}) {
   const cwd = process.cwd();
   const dryRun = opts.dryRun ?? false;
+  const enableContextGovernance = opts.enableContextGovernance ?? false;
   const idsToMigrate = [];
   if (opts.all) {
     const changesDir = join12(cwd, "specs", "changes");
@@ -255,7 +472,7 @@ async function migrate(changeId, opts = {}) {
       return;
     }
     idsToMigrate.push(
-      ...readdirSync6(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+      ...readdirSync7(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     );
   } else if (changeId) {
     const specificDir = join12(cwd, "specs", "changes", changeId);
@@ -284,7 +501,7 @@ async function migrate(changeId, opts = {}) {
       log.warn(`  ${id}: directory not found \u2014 skipping`);
       continue;
     }
-    const { changed, warnings } = migrateOne(id, changeDir, dryRun);
+    const { changed, warnings } = migrateOne(id, changeDir, dryRun, enableContextGovernance);
     if (changed.length > 0) {
       log.ok(`  ${id}: migrated`);
       for (const c of changed)
@@ -304,7 +521,7 @@ async function migrate(changeId, opts = {}) {
   } 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"');
+      log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to current cdd-kit format"');
     }
   }
 }
@@ -315,31 +532,283 @@ var init_migrate = __esm({
   }
 });
 
+// src/commands/upgrade.ts
+var upgrade_exports = {};
+__export(upgrade_exports, {
+  upgrade: () => upgrade
+});
+import { existsSync as existsSync12, mkdirSync as mkdirSync4, readdirSync as readdirSync8, copyFileSync as copyFileSync3, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname3, join as join13, relative as relative2 } from "path";
+function planMissingFiles(srcDir, destDir, label, planned) {
+  if (!existsSync12(srcDir))
+    return;
+  for (const entry of readdirSync8(srcDir, { withFileTypes: true })) {
+    const src = join13(srcDir, entry.name);
+    const dest = join13(destDir, entry.name);
+    if (entry.isDirectory()) {
+      planMissingFiles(src, dest, join13(label, entry.name), planned);
+      continue;
+    }
+    if (!existsSync12(dest)) {
+      planned.push({ src, dest, rel: join13(label, relative2(srcDir, src)) });
+    }
+  }
+}
+function planProviderGuidance(cwd, provider, planned) {
+  if (provider === "claude" || provider === "both") {
+    if (!existsSync12(join13(cwd, "CLAUDE.md"))) {
+      planned.push({ src: ASSET.claudeTemplate, dest: join13(cwd, "CLAUDE.md"), rel: "CLAUDE.md" });
+    }
+    if (!existsSync12(join13(cwd, "AGENTS.md"))) {
+      planned.push({ src: ASSET.agentsTemplate, dest: join13(cwd, "AGENTS.md"), rel: "AGENTS.md" });
+    }
+  }
+  if ((provider === "codex" || provider === "both") && !existsSync12(join13(cwd, "CODEX.md"))) {
+    planned.push({ src: ASSET.codexTemplate, dest: join13(cwd, "CODEX.md"), rel: "CODEX.md" });
+  }
+}
+function applyCopy(plan) {
+  for (const item of plan) {
+    mkdirSync4(dirname3(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, join13(cwd, "contracts"), "contracts", plan);
+  planMissingFiles(ASSET.specsTemplates, join13(cwd, "specs", "templates"), "specs/templates", plan);
+  planMissingFiles(ASSET.testsTemplates, join13(cwd, "tests", "templates"), "tests/templates", plan);
+  planMissingFiles(ASSET.ci, join13(cwd, "ci"), "ci", plan);
+  planMissingFiles(ASSET.githubWorkflows, join13(cwd, ".github", "workflows"), ".github/workflows", plan);
+  planMissingFiles(ASSET.cddConfig, join13(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 = join13(cwd, ".cdd", "model-policy.json");
+  if (existsSync12(modelPolicyPath)) {
+    writeFileSync5(modelPolicyPath, JSON.stringify({
+      provider,
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      roles: {}
+    }, 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 join14 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5, renameSync, readFileSync as readFileSync10, writeFileSync as writeFileSync6, appendFileSync, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
+async function archive(changeId) {
+  const cwd = process.cwd();
+  const changeDir = join14(cwd, "specs", "changes", changeId);
+  const archiveYear = (/* @__PURE__ */ new Date()).getFullYear().toString();
+  const archiveBase = join14(cwd, "specs", "archive", archiveYear);
+  const archiveDir = join14(archiveBase, changeId);
+  const indexPath = join14(cwd, "specs", "archive", "INDEX.md");
+  if (!existsSync13(changeDir)) {
+    log.error(`Change not found: specs/changes/${changeId}`);
+    process.exit(1);
+  }
+  if (existsSync13(archiveDir)) {
+    log.error(`Already archived: specs/archive/${archiveYear}/${changeId}`);
+    process.exit(1);
+  }
+  const tasksPath = join14(changeDir, "tasks.md");
+  if (existsSync13(tasksPath)) {
+    const content = readFileSync10(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 (!existsSync13(archiveBase)) {
+    mkdirSync5(archiveBase, { recursive: true });
+  }
+  try {
+    renameSync(changeDir, archiveDir);
+  } catch (err) {
+    if (err.code === "EXDEV") {
+      cpSync2(changeDir, archiveDir, { recursive: true });
+      rmSync2(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 (!existsSync13(indexPath)) {
+    writeFileSync6(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 join15 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync11, writeFileSync as writeFileSync7, appendFileSync as appendFileSync2, mkdirSync as mkdirSync6 } from "fs";
+async function abandon(changeId, opts) {
+  const cwd = process.cwd();
+  const changeDir = join15(cwd, "specs", "changes", changeId);
+  const tasksPath = join15(changeDir, "tasks.md");
+  if (!existsSync14(changeDir)) {
+    log.error(`Change not found: specs/changes/${changeId}`);
+    process.exit(1);
+  }
+  if (existsSync14(tasksPath)) {
+    let content = readFileSync11(tasksPath, "utf8");
+    if (content.match(/^status:/m)) {
+      content = content.replace(/^status: .*/m, "status: abandoned");
+    } else {
+      content = `---
+change-id: ${changeId}
+status: abandoned
+---
+
+` + content;
+    }
+    writeFileSync7(tasksPath, content, "utf8");
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const archiveDir = join15(cwd, "specs", "archive");
+  const indexPath = join15(archiveDir, "INDEX.md");
+  const reason = opts.reason ?? "no reason given";
+  const indexLine = `| ${changeId} | abandoned | ${today} | ${reason} |
+`;
+  if (!existsSync14(archiveDir)) {
+    mkdirSync6(archiveDir, { recursive: true });
+  }
+  if (!existsSync14(indexPath)) {
+    writeFileSync7(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 join16 } from "path";
+import { existsSync as existsSync15, readdirSync as readdirSync9, readFileSync as readFileSync12 } from "fs";
 async function listChanges() {
   const cwd = process.cwd();
-  const changesDir = join13(cwd, "specs", "changes");
+  const changesDir = join16(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 (existsSync15(changesDir)) {
+    active.push(...readdirSync9(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 = join13(changesDir, id, "tasks.md");
+      const tasksPath = join16(changesDir, id, "tasks.md");
       let status = "in-progress";
       let pending = 0;
-      if (existsSync12(tasksPath)) {
-        const content = readFileSync9(tasksPath, "utf8");
+      if (existsSync15(tasksPath)) {
+        const content = readFileSync12(tasksPath, "utf8");
         if (content.includes("status: gate-blocked"))
           status = "gate-blocked";
         else if (content.includes("status: abandoned"))
@@ -359,40 +828,469 @@ var init_list_changes = __esm({
   }
 });
 
+// src/commands/context-scan.ts
+var context_scan_exports = {};
+__export(context_scan_exports, {
+  contextScan: () => contextScan
+});
+import { existsSync as existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync13, readdirSync as readdirSync10, writeFileSync as writeFileSync8 } from "fs";
+import { basename, dirname as dirname4, join as join17, relative as relative3 } from "path";
+function stripGlobSuffix(pattern) {
+  return pattern.replace(/\/\*\*$/, "").replace(/\/\*$/, "");
+}
+function getForbiddenPaths(cwd) {
+  const forbidden = new Set(DEFAULT_FORBIDDEN);
+  const policyPath = join17(cwd, ".cdd", "context-policy.json");
+  try {
+    if (existsSync16(policyPath)) {
+      const policy = JSON.parse(readFileSync13(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.");
+  }
+  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 = readdirSync10(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 = relative3(cwd, join17(dir, entry.name));
+    return !isForbidden(relPath, forbidden);
+  });
+  visible.forEach((entry, index) => {
+    const fullPath = join17(dir, entry.name);
+    const isLast = index === visible.length - 1;
+    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;
+    }
+  });
+  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 (!summary) {
+    const summaryMatch = content.match(/#+\s*Summary\s*\r?\n+([^#\r\n][^\r\n]*)/i);
+    summary = summaryMatch?.[1]?.trim();
+  }
+  return { title: firstHeading(content), summary, metadata };
+}
+function findContractFiles(dir, found = []) {
+  if (!existsSync16(dir))
+    return found;
+  for (const entry of readdirSync10(dir, { withFileTypes: true })) {
+    const fullPath = join17(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() {
+  const cwd = process.cwd();
+  const specsContextDir = join17(cwd, "specs", "context");
+  mkdirSync7(specsContextDir, { recursive: true });
+  const forbidden = getForbiddenPaths(cwd);
+  const treeStats = { dirs: 0, files: 0, omittedDirs: 0 };
+  const tree = buildTree(cwd, cwd, forbidden, treeStats);
+  writeFileSync8(
+    join17(specsContextDir, "project-map.md"),
+    [
+      "---",
+      "artifact: project-map",
+      "generated-by: cdd-kit context-scan",
+      "schema-version: 1",
+      `root: ${basename(cwd)}`,
+      `visible-dirs: ${treeStats.dirs}`,
+      `visible-files: ${treeStats.files}`,
+      `omitted-dirs: ${treeStats.omittedDirs}`,
+      "---",
+      "",
+      "# 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(join17(cwd, "contracts")).sort((a, b) => relative3(cwd, a).localeCompare(relative3(cwd, b)));
+  const contractEntries = [];
+  const inventoryRows = [];
+  let missingSummary = 0;
+  for (const file of contractFiles) {
+    const relPath = relative3(cwd, file).replace(/\\/g, "/");
+    const dir = dirname4(relPath).replace(/\\/g, "/");
+    const { title, summary, metadata } = parseContractMetadata(readFileSync13(file, "utf8"));
+    const contractType = deriveContractType(relPath, metadata);
+    const owner = metadata.owner ?? "unknown";
+    const surface = metadata.surface ?? dir;
+    const summaryText = summary ?? "MISSING - add YAML frontmatter `summary:` or `<!-- cdd: summary: ... -->`.";
+    inventoryRows.push(`| ${relPath} | ${contractType} | ${surface} | ${owner} | ${summary ? "yes" : "no"} |`);
+    let entry = `## ${relPath}
+`;
+    entry += `- path: \`${relPath}\`
+`;
+    entry += `- type: ${contractType}
+`;
+    entry += `- directory: ${dir}
+`;
+    if (title)
+      entry += `- title: ${title}
+`;
+    for (const [key, value] of Object.entries(metadata)) {
+      if (key === "contract")
+        continue;
+      entry += `- ${key}: ${value}
+`;
+    }
+    entry += `- summary: ${summaryText}
+
+`;
+    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}`,
+    "---",
+    "",
+    "# 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");
+  writeFileSync8(join17(specsContextDir, "contracts-index.md"), contractIndex, "utf8");
+  if (missingSummary > 0) {
+    log.warn(`Created specs/context/contracts-index.md with ${missingSummary} missing summary warning(s).`);
+  } else {
+    log.ok("Created specs/context/contracts-index.md");
+  }
+}
+var DEFAULT_FORBIDDEN;
+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"
+    ];
+  }
+});
+
+// src/commands/context.ts
+var context_exports = {};
+__export(context_exports, {
+  approveContextExpansion: () => approveContextExpansion,
+  listContextExpansions: () => listContextExpansions,
+  rejectContextExpansion: () => rejectContextExpansion,
+  requestContextExpansion: () => requestContextExpansion
+});
+import { existsSync as existsSync17, readFileSync as readFileSync14, 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 readFileSync14(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}`);
+  }
+}
+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);
+  }
+  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((path) => `- ${path}`)]);
+  next = setRequestStatus(next, requestId, "approved");
+  writeManifest(changeId, next);
+  log.ok(`approved context expansion ${requestId} for ${changeId}`);
+  for (const path of request.paths)
+    log.info(`  ${path}`);
+}
+async function rejectContextExpansion(changeId, requestId) {
+  const next = setRequestStatus(readManifest(changeId), requestId, "rejected");
+  writeManifest(changeId, next);
+  log.ok(`rejected context expansion ${requestId} 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 readFileSync15 } 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 +1505,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 +1531,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 +1547,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 +1581,21 @@ 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)) {
+        writeFileSync(modelPolicyPath, JSON.stringify({
+          provider: opts.provider,
+          generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+          roles: {}
+        }, null, 2) + "\n", "utf8");
+      }
       const { count: wfCount, created: wfCreated } = copyDirTracked(
         ASSET.githubWorkflows,
         join4(cwd, ".github", "workflows"),
@@ -717,24 +1639,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 +1679,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 +1729,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 +1755,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 +1799,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,15 +1822,17 @@ 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 join7 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync as readdirSync4, writeFileSync as writeFileSync2 } from "fs";
 init_logger();
 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 {
@@ -884,14 +1843,31 @@ function listOptional() {
   }
 }
 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 = join7(cwd, "specs", "changes", name);
+  if (existsSync6(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.");
@@ -907,9 +1883,9 @@ async function newChange(name, opts) {
   const templates = opts.all ? [...REQUIRED_TEMPLATES, ...listOptional()] : [...REQUIRED_TEMPLATES];
   let written = 0;
   for (const tmpl of templates) {
-    const src = join6(ASSET.specsTemplates, tmpl);
-    const dest = join6(changeDir, tmpl);
-    if (!existsSync5(src)) {
+    const src = join7(ASSET.specsTemplates, tmpl);
+    const dest = join7(changeDir, tmpl);
+    if (!existsSync6(src)) {
       log.warn(`Template not found, skipping: ${tmpl}`);
       continue;
     }
@@ -917,16 +1893,26 @@ async function newChange(name, opts) {
     log.dim(tmpl);
     written += 1;
   }
+  if (dependencies.length > 0) {
+    const tasksPath = join7(changeDir, "tasks.md");
+    if (existsSync6(tasksPath)) {
+      const tasks = readFileSync5(tasksPath, "utf8");
+      const nextTasks = tasks.replace(/^depends-on:\s*.*$/m, formatDependsOn(dependencies));
+      writeFileSync2(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 join8 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { spawnSync } from "child_process";
 var VALIDATORS = [
   {
     flag: "contracts",
@@ -958,15 +1944,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 = join8(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 = join8(scriptsDir, v.script);
+    if (!existsSync7(scriptPath)) {
       log.warn(`${v.label}: script not found, skipping (${v.script})`);
       log.blank();
       continue;
@@ -982,8 +1968,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 = join8(scriptsDir, chained.script);
+        if (!existsSync7(chainedPath)) {
           log.warn(`${chained.label}: script not found, skipping (${chained.script})`);
           log.blank();
           continue;
@@ -1011,15 +1997,16 @@ 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 { existsSync as existsSync8, readFileSync as readFileSync6, readdirSync as readdirSync5 } from "fs";
+import { join as join9 } from "path";
 import { spawnSync as spawnSync2 } from "child_process";
 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,45 +2014,251 @@ 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 = join9(cwd, ".cdd", "context-policy.json");
+  if (!existsSync8(policyPath))
+    return defaults;
+  try {
+    const custom = JSON.parse(readFileSync6(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 = join9(changeDir, "tasks.md");
+  if (!existsSync8(tasksPath))
+    return false;
+  return /^context-governance:\s*v1\b/m.test(readFileSync6(tasksPath, "utf8"));
+}
+function parseDependsOn2(content) {
+  const lineMatch = content.match(/^depends-on:\s*(.+)$/m);
+  if (!lineMatch)
+    return [];
+  const raw = lineMatch[1].trim();
+  if (!raw || raw === "[]")
+    return [];
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    return raw.slice(1, -1).split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return raw.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function parseTaskStatus(content) {
+  const match = content.match(/^status:\s*([a-zA-Z0-9_-]+)/m);
+  return match ? match[1].trim().toLowerCase() : "in-progress";
+}
+function isArchivedChange(cwd, changeId) {
+  const archiveRoot = join9(cwd, "specs", "archive");
+  if (!existsSync8(archiveRoot))
+    return false;
+  const years = readdirSync5(archiveRoot, { withFileTypes: true }).filter((d) => d.isDirectory());
+  return years.some((year) => existsSync8(join9(archiveRoot, year.name, changeId)));
+}
+function validateDependencies(cwd, changeId, changeDir) {
+  const tasksPath = join9(changeDir, "tasks.md");
+  if (!existsSync8(tasksPath))
+    return [];
+  const dependencies = parseDependsOn2(readFileSync6(tasksPath, "utf8"));
+  const errors = [];
+  for (const dep of dependencies) {
+    if (dep === changeId) {
+      errors.push(`tasks.md: change cannot depend on itself (${dep})`);
+      continue;
+    }
+    const upstreamDir = join9(cwd, "specs", "changes", dep);
+    if (existsSync8(upstreamDir)) {
+      const upstreamTasks = join9(upstreamDir, "tasks.md");
+      if (!existsSync8(upstreamTasks)) {
+        errors.push(`dependency ${dep}: missing tasks.md`);
+        continue;
+      }
+      const status = parseTaskStatus(readFileSync6(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 cwd = process.cwd();
-  const changeDir = join8(cwd, "specs", "changes", changeId);
-  if (!existsSync7(changeDir)) {
+  const changeDir = join9(cwd, "specs", "changes", changeId);
+  if (!existsSync8(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 = join9(changeDir, "context-manifest.md");
+  const hasManifest = existsSync8(manifestPath);
+  let allowedPaths = [];
+  let approvedExpansions = [];
+  errors.push(...validateDependencies(cwd, changeId, changeDir));
+  if (hasManifest) {
+    const manifest = parseContextManifest(readFileSync6(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 (!existsSync8(join9(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 = readFileSync6(join9(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");
+    const classifPath = join9(changeDir, "change-classification.md");
+    if (existsSync8(classifPath)) {
+      const text = readFileSync6(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 tasksPath = join8(changeDir, "tasks.md");
-  if (existsSync7(tasksPath)) {
-    const tasksContent = readFileSync4(tasksPath, "utf8");
+  const tasksPath = join9(changeDir, "tasks.md");
+  if (existsSync8(tasksPath)) {
+    const tasksContent = readFileSync6(tasksPath, "utf8");
     const nonArchivePending = (tasksContent.match(/^\s*-\s*\[ \] (?!7\.[12])/gm) || []).length;
     if (nonArchivePending > 0) {
       if (strict) {
@@ -1075,11 +2268,34 @@ async function gate(changeId, opts = {}) {
       }
     }
   }
-  const agentLogDir = join8(changeDir, "agent-log");
-  if (existsSync7(agentLogDir)) {
+  const agentLogDir = join9(changeDir, "agent-log");
+  if (existsSync8(agentLogDir)) {
     const logFiles = readdirSync5(agentLogDir).filter((f) => f.endsWith(".md"));
     for (const f of logFiles) {
-      const content = readFileSync4(join8(agentLogDir, f), "utf8");
+      const content = readFileSync6(join9(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 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)`);
@@ -1100,8 +2316,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 = join9(cwd, pathPart);
+              if (!existsSync8(abs)) {
                 errors.push(`agent-log/${f}: artifact pointer not found: ${pathPart}`);
               }
             }
@@ -1109,9 +2325,9 @@ async function gate(changeId, opts = {}) {
         }
       }
     }
-    const classifPath = join8(changeDir, "change-classification.md");
-    if (existsSync7(classifPath)) {
-      const classificationContent = readFileSync4(classifPath, "utf8");
+    const classifPath = join9(changeDir, "change-classification.md");
+    if (existsSync8(classifPath)) {
+      const classificationContent = readFileSync6(classifPath, "utf8");
       const tierMatch = classificationContent.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
       const tier = tierMatch ? parseInt(tierMatch[1]) : null;
       if (tier !== null) {
@@ -1133,9 +2349,9 @@ async function gate(changeId, opts = {}) {
       }
     }
   } else {
-    const classifPath = join8(changeDir, "change-classification.md");
-    if (existsSync7(classifPath)) {
-      const classificationContent = readFileSync4(classifPath, "utf8");
+    const classifPath = join9(changeDir, "change-classification.md");
+    if (existsSync8(classifPath)) {
+      const classificationContent = readFileSync6(classifPath, "utf8");
       const tierMatch = classificationContent.match(/^## Tier\s*\n\s*-\s*(\d)\s*$/m);
       const tier = tierMatch ? parseInt(tierMatch[1]) : null;
       if (tier !== null) {
@@ -1178,27 +2394,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 existsSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync3, chmodSync, mkdirSync as mkdirSync3 } from "fs";
+import { join as join10 } 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 = join10(cwd, ".git");
+  if (!existsSync9(gitDir)) {
     log.error("not a git repository (no .git/ found in cwd)");
     process.exit(1);
   }
-  const hooksDir = join9(gitDir, "hooks");
+  const hooksDir = join10(gitDir, "hooks");
   mkdirSync3(hooksDir, { recursive: true });
-  const dest = join9(hooksDir, "pre-commit");
-  const ourHook = readFileSync5(join9(ASSET.hooks, "pre-commit"), "utf8");
+  const dest = join10(hooksDir, "pre-commit");
+  const ourHook = readFileSync7(join10(ASSET.hooks, "pre-commit"), "utf8");
   let final;
-  if (!existsSync8(dest)) {
+  if (!existsSync9(dest)) {
     final = ourHook;
   } else {
-    const existing = readFileSync5(dest, "utf8");
+    const existing = readFileSync7(dest, "utf8");
     const startIdx = existing.indexOf(START_MARKER);
     const endIdx = existing.indexOf(END_MARKER);
     if (startIdx >= 0 && endIdx > startIdx) {
@@ -1222,7 +2439,7 @@ async function installHooks() {
       }
     }
   }
-  writeFileSync2(dest, final, "utf8");
+  writeFileSync3(dest, final, "utf8");
   try {
     chmodSync(dest, 493);
   } catch {
@@ -1232,22 +2449,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(readFileSync15(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").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 });
+});
+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").action(
+  (name, opts) => newChange(name, { all: opts.all, force: opts.force, dependsOn: opts.dependsOn })
 );
 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({
@@ -1269,7 +2500,7 @@ 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).action(async (changeId, opts = {}) => {
   const { migrate: migrate2 } = await Promise.resolve().then(() => (init_migrate(), migrate_exports));
   await migrate2(changeId, opts);
 });
@@ -1293,4 +2524,25 @@ 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").action(async () => {
+  const { contextScan: contextScan2 } = await Promise.resolve().then(() => (init_context_scan(), context_scan_exports));
+  await contextScan2();
+});
+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 and add its paths to Approved Expansions").action(async (changeId, requestId) => {
+  const { approveContextExpansion: approveContextExpansion2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  await approveContextExpansion2(changeId, requestId);
+});
+context.command("reject <change-id> <request-id>").description("Reject a pending Context Expansion Request").action(async (changeId, requestId) => {
+  const { rejectContextExpansion: rejectContextExpansion2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  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();