contract-driven-delivery 1.0.1 → 1.6.0

package/dist/cli/index.js

@@ -1,8 +1,12 @@
 // src/cli/index.ts
+import { readFileSync as readFileSync6 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname3, join as join10 } from "path";
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
+import { rmSync, readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3 } from "fs";
 
 // src/utils/paths.ts
 import { join, dirname } from "path";
@@ -21,6 +25,7 @@ var ASSET = {
   specsTemplates: join(ASSETS_DIR, "specs-templates"),
   testsTemplates: join(ASSETS_DIR, "tests-templates"),
   ci: join(ASSETS_DIR, "ci"),
+  hooks: join(ASSETS_DIR, "hooks"),
   claudeTemplate: join(ASSETS_DIR, "CLAUDE.template.md"),
   agentsTemplate: join(ASSETS_DIR, "AGENTS.template.md")
 };
@@ -66,21 +71,25 @@ var log = {
 function ensureDir(dir) {
   mkdirSync(dir, { recursive: true });
 }
-function copyDir(src, dest, opts = {}) {
+function copyDirTracked(src, dest, opts = {}) {
   const { overwrite = true, label } = opts;
   if (!existsSync(src)) {
     log.warn(`source not found, skipping: ${label ?? src}`);
-    return 0;
+    return { count: 0, created: [] };
   }
   ensureDir(dest);
   let count = 0;
+  const created = [];
   function walk(currentSrc, currentDest) {
     const entries = readdirSync(currentSrc, { withFileTypes: true });
     for (const entry of entries) {
       const srcPath = join2(currentSrc, entry.name);
       const destPath = join2(currentDest, entry.name);
       if (entry.isDirectory()) {
+        const isNew = !existsSync(destPath);
         ensureDir(destPath);
+        if (isNew)
+          created.push(destPath);
         walk(srcPath, destPath);
       } else {
         if (!overwrite && existsSync(destPath)) {
@@ -88,17 +97,24 @@ function copyDir(src, dest, opts = {}) {
           log.dim(`skip ${relPath}`);
           continue;
         }
+        const isNew = !existsSync(destPath);
         ensureDir(dirname2(destPath));
         copyFileSync(srcPath, destPath);
+        if (isNew)
+          created.push(destPath);
         count += 1;
       }
     }
   }
   walk(src, dest);
-  return count;
+  return { count, created };
 }
 function copyFile(src, dest, opts = {}) {
   const { overwrite = true, label } = opts;
+  if (!existsSync(src)) {
+    log.warn(`source not found, skipping: ${label ?? src}`);
+    return false;
+  }
   if (!overwrite && existsSync(dest)) {
     log.dim(`skip ${label ?? dest}`);
     return false;
@@ -107,68 +123,258 @@ function copyFile(src, dest, opts = {}) {
   copyFileSync(src, dest);
   return true;
 }
+function copyFileTracked(src, dest, opts = {}) {
+  const { overwrite = true, label } = opts;
+  if (!existsSync(src)) {
+    log.warn(`source not found, skipping: ${label ?? src}`);
+    return { written: false, created: false };
+  }
+  if (!overwrite && existsSync(dest)) {
+    log.dim(`skip ${label ?? dest}`);
+    return { written: false, created: false };
+  }
+  const isNew = !existsSync(dest);
+  ensureDir(dirname2(dest));
+  copyFileSync(src, dest);
+  return { written: true, created: isNew };
+}
+
+// src/utils/stack-detect.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { join as join3 } from "path";
+function safeExists(filePath) {
+  try {
+    return existsSync2(filePath);
+  } catch {
+    return false;
+  }
+}
+function safeRead(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+function detectPython(repoRoot) {
+  if (safeExists(join3(repoRoot, "environment.yml")) || safeExists(join3(repoRoot, "conda-lock.yml")) || safeExists(join3(repoRoot, "meta.yaml"))) {
+    return "conda";
+  }
+  if (safeExists(join3(repoRoot, "pyproject.toml"))) {
+    const content = safeRead(join3(repoRoot, "pyproject.toml"));
+    if (content.includes("[tool.poetry]")) {
+      return "poetry";
+    }
+    return "uv";
+  }
+  if (safeExists(join3(repoRoot, "requirements.txt"))) {
+    return "pip";
+  }
+  return null;
+}
+function detectJS(repoRoot) {
+  if (!safeExists(join3(repoRoot, "package.json"))) {
+    return null;
+  }
+  if (safeExists(join3(repoRoot, "pnpm-lock.yaml")))
+    return "pnpm";
+  if (safeExists(join3(repoRoot, "bun.lockb")))
+    return "bun";
+  if (safeExists(join3(repoRoot, "yarn.lock")))
+    return "yarn";
+  return "npm";
+}
+function detectGo(repoRoot) {
+  return safeExists(join3(repoRoot, "go.mod")) ? "go" : null;
+}
+function detectRust(repoRoot) {
+  return safeExists(join3(repoRoot, "Cargo.toml")) ? "rust" : null;
+}
+function detectStack(repoRoot) {
+  const candidates = [];
+  const python = detectPython(repoRoot);
+  if (python)
+    candidates.push(python);
+  const js = detectJS(repoRoot);
+  if (js)
+    candidates.push(js);
+  const go = detectGo(repoRoot);
+  if (go)
+    candidates.push(go);
+  const rust = detectRust(repoRoot);
+  if (rust)
+    candidates.push(rust);
+  if (candidates.length === 0) {
+    return { primary: "unknown", candidates: [], polyglot: false };
+  }
+  const PYTHON_STACKS = ["conda", "poetry", "uv", "pip"];
+  const JS_STACKS = ["pnpm", "bun", "yarn", "npm"];
+  const hasPython = candidates.some((c) => PYTHON_STACKS.includes(c));
+  const hasJS = candidates.some((c) => JS_STACKS.includes(c));
+  const hasGo = candidates.includes("go");
+  const hasRust = candidates.includes("rust");
+  const languageCount = [hasPython, hasJS, hasGo, hasRust].filter(Boolean).length;
+  const polyglot = languageCount > 1;
+  return {
+    primary: candidates[0],
+    candidates,
+    polyglot
+  };
+}
 
 // src/commands/init.ts
+function loadCiTemplate(stack) {
+  const templatePath = join4(ASSETS_DIR, "ci-templates", `${stack}.yml`);
+  if (!existsSync3(templatePath))
+    return null;
+  try {
+    return readFileSync2(templatePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function patchFastGateYml(baseYml, fragment, stack) {
+  const lines = baseYml.split("\n");
+  const PLACEHOLDER_NAME = "      - name: Repository-specific fast gate";
+  const startIdx = lines.findIndex((l) => l.startsWith(PLACEHOLDER_NAME));
+  if (startIdx === -1) {
+    return baseYml;
+  }
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length) {
+    const line = lines[endIdx];
+    if (line.startsWith("      - ") && endIdx > startIdx || line.match(/^  \S/) && !line.startsWith("      ")) {
+      break;
+    }
+    endIdx++;
+  }
+  const fragmentLines = fragment.trimEnd().split("\n").map((l) => l === "" ? "" : "      " + l);
+  const before = lines.slice(0, startIdx);
+  const after = lines.slice(endIdx);
+  return [...before, ...fragmentLines, ...after].join("\n");
+}
 async function init(opts) {
   if (opts.globalOnly && opts.localOnly) {
     log.error("--global-only and --local-only are mutually exclusive.");
     process.exit(1);
   }
   const cwd = process.cwd();
+  const createdPaths = [];
+  function track(paths) {
+    createdPaths.push(...paths);
+  }
+  function rollback() {
+    log.warn("Rolling back created paths due to error\u2026");
+    for (const p of [...createdPaths].reverse()) {
+      try {
+        rmSync(p, { recursive: true, force: true });
+        log.dim(`rolled back: ${p}`);
+      } catch {
+        log.warn(`could not remove: ${p}`);
+      }
+    }
+  }
   log.blank();
   log.info("Initialising contract-driven-delivery kit\u2026");
   log.blank();
-  if (!opts.localOnly) {
-    log.info(`Installing agents \u2192 ${AGENTS_HOME}`);
-    const agentCount = copyDir(ASSET.agents, AGENTS_HOME, { overwrite: true });
-    log.ok(`${agentCount} agent file(s) installed.`);
-    const skillDest = join3(SKILLS_HOME, "contract-driven-delivery");
-    log.info(`Installing skill  \u2192 ${skillDest}`);
-    const skillCount = copyDir(ASSET.skill, skillDest, { overwrite: true });
-    log.ok(`${skillCount} skill file(s) installed.`);
-    log.blank();
-  }
-  if (!opts.globalOnly) {
-    log.info(`Scaffolding project files in ${cwd}`);
-    const contractsCount = copyDir(
-      ASSET.contracts,
-      join3(cwd, "contracts"),
-      { overwrite: opts.force, label: "contracts" }
-    );
-    log.ok(`contracts/ \u2014 ${contractsCount} file(s) written.`);
-    const specsCount = copyDir(
-      ASSET.specsTemplates,
-      join3(cwd, "specs", "templates"),
-      { overwrite: opts.force, label: "specs/templates" }
-    );
-    log.ok(`specs/templates/ \u2014 ${specsCount} file(s) written.`);
-    const testsCount = copyDir(
-      ASSET.testsTemplates,
-      join3(cwd, "tests", "templates"),
-      { overwrite: opts.force, label: "tests/templates" }
-    );
-    log.ok(`tests/templates/ \u2014 ${testsCount} file(s) written.`);
-    const ciCount = copyDir(
-      ASSET.ci,
-      join3(cwd, "ci"),
-      { overwrite: opts.force, label: "ci" }
-    );
-    log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
-    const claudeWritten = copyFile(
-      ASSET.claudeTemplate,
-      join3(cwd, "CLAUDE.md"),
-      { overwrite: false, label: "CLAUDE.md" }
-    );
-    if (claudeWritten)
-      log.ok("CLAUDE.md created.");
-    const agentsWritten = copyFile(
-      ASSET.agentsTemplate,
-      join3(cwd, "AGENTS.md"),
-      { overwrite: false, label: "AGENTS.md" }
-    );
-    if (agentsWritten)
-      log.ok("AGENTS.md created.");
-    log.blank();
+  try {
+    if (!opts.localOnly) {
+      log.info(`Installing agents \u2192 ${AGENTS_HOME}`);
+      const { count: agentCount, created: agentCreated } = copyDirTracked(ASSET.agents, AGENTS_HOME, { overwrite: true });
+      track(agentCreated);
+      log.ok(`${agentCount} agent file(s) installed.`);
+      const skillDest = join4(SKILLS_HOME, "contract-driven-delivery");
+      log.info(`Installing skill  \u2192 ${skillDest}`);
+      const { count: skillCount, created: skillCreated } = copyDirTracked(ASSET.skill, skillDest, { overwrite: true });
+      track(skillCreated);
+      log.ok(`${skillCount} skill file(s) installed.`);
+      log.blank();
+    }
+    if (!opts.globalOnly) {
+      log.info(`Scaffolding project files in ${cwd}`);
+      const { count: contractsCount, created: contractsCreated } = copyDirTracked(
+        ASSET.contracts,
+        join4(cwd, "contracts"),
+        { overwrite: opts.force, label: "contracts" }
+      );
+      track(contractsCreated);
+      log.ok(`contracts/ \u2014 ${contractsCount} file(s) written.`);
+      const { count: specsCount, created: specsCreated } = copyDirTracked(
+        ASSET.specsTemplates,
+        join4(cwd, "specs", "templates"),
+        { overwrite: opts.force, label: "specs/templates" }
+      );
+      track(specsCreated);
+      log.ok(`specs/templates/ \u2014 ${specsCount} file(s) written.`);
+      const { count: testsCount, created: testsCreated } = copyDirTracked(
+        ASSET.testsTemplates,
+        join4(cwd, "tests", "templates"),
+        { overwrite: opts.force, label: "tests/templates" }
+      );
+      track(testsCreated);
+      log.ok(`tests/templates/ \u2014 ${testsCount} file(s) written.`);
+      const { count: ciCount, created: ciCreated } = copyDirTracked(
+        ASSET.ci,
+        join4(cwd, "ci"),
+        { overwrite: opts.force, label: "ci" }
+      );
+      track(ciCreated);
+      log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
+      const detection = detectStack(cwd);
+      if (detection.polyglot) {
+        const PYTHON_STACKS = ["conda", "poetry", "uv", "pip"];
+        const JS_STACKS = ["pnpm", "bun", "yarn", "npm"];
+        const other = detection.candidates.find((c) => {
+          if (PYTHON_STACKS.includes(detection.primary))
+            return !PYTHON_STACKS.includes(c);
+          if (JS_STACKS.includes(detection.primary))
+            return !JS_STACKS.includes(c);
+          return c !== detection.primary;
+        });
+        log.warn(
+          `Polyglot detected: ${detection.primary} and ${other ?? detection.candidates[1]}. Generated config for ${detection.primary}.`
+        );
+      } else if (detection.primary !== "unknown") {
+        log.info(`Detected stack: ${detection.primary}`);
+      } else {
+        log.warn("Could not detect stack \u2014 CI placeholder left in place.");
+      }
+      const ciYmlDest = join4(cwd, "ci", "github-actions", "contract-driven-gates.yml");
+      if (existsSync3(ciYmlDest)) {
+        const template = loadCiTemplate(detection.primary);
+        if (template) {
+          const original = readFileSync2(ciYmlDest, "utf8");
+          const patched = patchFastGateYml(original, template, detection.primary);
+          if (patched !== original) {
+            writeFileSync(ciYmlDest, patched, "utf8");
+            log.ok(`CI fast-gate patched for stack: ${detection.primary}`);
+          }
+        }
+      }
+      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.");
+      log.blank();
+    }
+  } catch (err) {
+    log.error(`Init failed: ${err instanceof Error ? err.message : String(err)}`);
+    rollback();
+    process.exit(1);
   }
   log.ok("Done.");
   log.blank();
@@ -177,27 +383,123 @@ async function init(opts) {
 }
 
 // src/commands/update.ts
-import { join as join4 } from "path";
-async function update() {
+import { join as join5 } from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync as readdirSync2, copyFileSync as copyFileSync2, readFileSync as readFileSync3 } from "fs";
+import { createHash } from "crypto";
+import { homedir as homedir2 } from "os";
+function fileHash(filePath) {
+  const buf = readFileSync3(filePath);
+  return createHash("sha256").update(buf).digest("hex");
+}
+function diffDir(src, dest) {
+  const entries = [];
+  if (!existsSync4(src))
+    return entries;
+  function walk(currentSrc, currentDest) {
+    const items = readdirSync2(currentSrc, { withFileTypes: true });
+    for (const item of items) {
+      const srcPath = join5(currentSrc, item.name);
+      const destPath = join5(currentDest, item.name);
+      if (item.isDirectory()) {
+        walk(srcPath, destPath);
+      } else {
+        if (!existsSync4(destPath)) {
+          entries.push({ src: srcPath, dest: destPath, action: "add" });
+        } else if (fileHash(srcPath) !== fileHash(destPath)) {
+          entries.push({ src: srcPath, dest: destPath, action: "overwrite" });
+        } else {
+          entries.push({ src: srcPath, dest: destPath, action: "skip" });
+        }
+      }
+    }
+  }
+  walk(src, dest);
+  return entries;
+}
+function applyDir(entries) {
+  let count = 0;
+  for (const e of entries) {
+    if (e.action === "skip")
+      continue;
+    mkdirSync2(join5(e.dest, ".."), { recursive: true });
+    copyFileSync2(e.src, e.dest);
+    count += 1;
+  }
+  return count;
+}
+function backupDir(dir, backupDest) {
+  if (!existsSync4(dir))
+    return;
+  mkdirSync2(backupDest, { recursive: true });
+  function walk(src, dst) {
+    const items = readdirSync2(src, { withFileTypes: true });
+    for (const item of items) {
+      const s = join5(src, item.name);
+      const d = join5(dst, item.name);
+      if (item.isDirectory()) {
+        mkdirSync2(d, { recursive: true });
+        walk(s, d);
+      } else
+        copyFileSync2(s, d);
+    }
+  }
+  walk(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 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.blank();
+  if (toAdd.length)
+    log.info(`  + ${toAdd.length} file(s) would be added`);
+  if (toOver.length)
+    log.warn(`  ~ ${toOver.length} file(s) would be overwritten (user edits lost without backup)`);
+  if (toSkip.length)
+    log.dim(`    ${toSkip.length} file(s) unchanged (skipped)`);
+  if (toWrite.length === 0) {
+    log.blank();
+    log.ok("Already up to date \u2014 nothing to write.");
+    log.blank();
+    return;
+  }
+  if (!opts.yes) {
+    log.blank();
+    log.info("Run with --yes to apply changes. Example:");
+    log.dim("  cdd-kit update --yes");
+    log.blank();
+    return;
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupRoot = join5(homedir2(), ".claude", ".cdd-kit-backup", timestamp);
   log.blank();
-  log.info("Updating ~/.claude agents and skill\u2026");
+  log.info(`Backing up to ${backupRoot} \u2026`);
+  backupDir(AGENTS_HOME, join5(backupRoot, "agents"));
+  backupDir(skillDest, join5(backupRoot, "skill"));
+  log.ok(`Backup complete: ${backupRoot}`);
   log.blank();
   log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
-  const agentCount = copyDir(ASSET.agents, AGENTS_HOME, { overwrite: true });
+  const agentCount = applyDir(agentDiff);
   log.ok(`${agentCount} agent file(s) updated.`);
-  const skillDest = join4(SKILLS_HOME, "contract-driven-delivery");
   log.info(`Updating skill  \u2192 ${skillDest}`);
-  const skillCount = copyDir(ASSET.skill, skillDest, { overwrite: true });
+  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.");
+  log.info(`Backup saved to: ${backupRoot}`);
   log.blank();
 }
 
 // src/commands/new-change.ts
-import { join as join5 } from "path";
-import { existsSync as existsSync2 } from "fs";
+import { join as join6 } from "path";
+import { existsSync as existsSync5, readdirSync as readdirSync3 } from "fs";
 var REQUIRED_TEMPLATES = [
   "change-request.md",
   "change-classification.md",
@@ -205,16 +507,14 @@ var REQUIRED_TEMPLATES = [
   "ci-gates.md",
   "tasks.md"
 ];
-var OPTIONAL_TEMPLATES = [
-  "current-behavior.md",
-  "proposal.md",
-  "spec.md",
-  "design.md",
-  "contracts.md",
-  "qa-report.md",
-  "regression-report.md",
-  "archive.md"
-];
+function listOptional() {
+  try {
+    const all = readdirSync3(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;
 async function newChange(name, opts) {
   if (!SAFE_NAME.test(name)) {
@@ -222,25 +522,30 @@ async function newChange(name, opts) {
     process.exit(1);
   }
   const cwd = process.cwd();
-  const changeDir = join5(cwd, "specs", "changes", name);
-  if (existsSync2(changeDir)) {
-    log.warn(`Change directory already exists: ${changeDir}`);
-    log.warn("Aborting \u2014 remove or rename the directory to re-scaffold.");
-    return;
+  const changeDir = join6(cwd, "specs", "changes", name);
+  if (existsSync5(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.");
+    } else {
+      log.warn(`Change directory already exists: ${changeDir}`);
+      log.warn("Aborting \u2014 remove or rename the directory to re-scaffold.");
+      return;
+    }
   }
   log.blank();
   log.info(`Creating change scaffold: specs/changes/${name}`);
   ensureDir(changeDir);
-  const templates = opts.all ? [...REQUIRED_TEMPLATES, ...OPTIONAL_TEMPLATES] : [...REQUIRED_TEMPLATES];
+  const templates = opts.all ? [...REQUIRED_TEMPLATES, ...listOptional()] : [...REQUIRED_TEMPLATES];
   let written = 0;
   for (const tmpl of templates) {
-    const src = join5(ASSET.specsTemplates, tmpl);
-    const dest = join5(changeDir, tmpl);
-    if (!existsSync2(src)) {
+    const src = join6(ASSET.specsTemplates, tmpl);
+    const dest = join6(changeDir, tmpl);
+    if (!existsSync5(src)) {
       log.warn(`Template not found, skipping: ${tmpl}`);
       continue;
     }
-    copyFile(src, dest, { overwrite: false });
+    copyFile(src, dest, { overwrite: opts.force });
     log.dim(tmpl);
     written += 1;
   }
@@ -250,22 +555,29 @@ async function newChange(name, opts) {
 }
 
 // src/commands/validate.ts
-import { join as join6 } from "path";
-import { existsSync as existsSync3 } from "fs";
-import { execSync } from "child_process";
+import { join as join7 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { spawnSync } from "child_process";
 var VALIDATORS = [
-  { flag: "contracts", script: "validate_contracts.py", label: "contracts" },
+  {
+    flag: "contracts",
+    script: "validate_contracts.py",
+    label: "contracts",
+    chain: [
+      { script: "validate_api_semantic.py", label: "API semantic" },
+      { script: "validate_env_semantic.py", label: "Env semantic" }
+    ]
+  },
   { flag: "env", script: "validate_env_contract.py", label: "env contract" },
   { flag: "ci", script: "validate_ci_gates.py", label: "CI gates" },
-  { flag: "spec", script: "validate_spec_traceability.py", label: "spec traceability" }
+  { flag: "spec", script: "validate_spec_traceability.py", label: "spec traceability" },
+  { flag: "versions", script: "validate_contract_versions.py", label: "contract versions" }
 ];
 function resolvePython() {
   for (const cmd of ["python3", "python"]) {
-    try {
-      execSync(`${cmd} --version`, { stdio: "ignore" });
+    const r = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+    if (r.status === 0)
       return cmd;
-    } catch {
-    }
   }
   throw new Error("Python not found. Install Python 3.8+ and ensure it is on PATH.");
 }
@@ -277,28 +589,47 @@ async function validate(opts) {
     log.error(e instanceof Error ? e.message : String(e));
     process.exit(1);
   }
-  const scriptsDir = join6(ASSET.skill, "scripts");
-  const runAll = !opts.contracts && !opts.env && !opts.ci && !opts.spec;
+  const scriptsDir = join7(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 = join6(scriptsDir, v.script);
-    if (!existsSync3(scriptPath)) {
+    const scriptPath = join7(scriptsDir, v.script);
+    if (!existsSync6(scriptPath)) {
       log.warn(`${v.label}: script not found, skipping (${v.script})`);
       log.blank();
       continue;
     }
     log.info(`Validating ${v.label}\u2026`);
-    try {
-      execSync(`${py} "${scriptPath}"`, { stdio: "inherit", cwd: process.cwd() });
-      log.ok(`${v.label} passed.`);
-    } catch {
+    const r = spawnSync(py, [scriptPath, ...v.args ?? []], { stdio: "inherit", cwd: process.cwd() });
+    if (r.status !== 0) {
       log.error(`${v.label} validation failed.`);
       failed = true;
+    } else {
+      log.ok(`${v.label} passed.`);
     }
     log.blank();
+    if (v.chain) {
+      for (const chained of v.chain) {
+        const chainedPath = join7(scriptsDir, chained.script);
+        if (!existsSync6(chainedPath)) {
+          log.warn(`${chained.label}: script not found, skipping (${chained.script})`);
+          log.blank();
+          continue;
+        }
+        log.info(`Validating ${chained.label}\u2026`);
+        const cr = spawnSync(py, [chainedPath], { stdio: "inherit", cwd: process.cwd() });
+        if (cr.status !== 0) {
+          log.error(`${chained.label} validation failed.`);
+          failed = true;
+        } else {
+          log.ok(`${chained.label} passed.`);
+        }
+        log.blank();
+      }
+    }
   }
   if (failed) {
     log.error("One or more validations failed.");
@@ -309,9 +640,145 @@ async function validate(opts) {
   }
 }
 
+// src/commands/gate.ts
+import { existsSync as existsSync7, readFileSync as readFileSync4, readdirSync as readdirSync4 } from "fs";
+import { join as join8 } 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"
+];
+var TIER_PATTERN = /\b(tier\s*[0-5]|low|medium|high|critical)\b/i;
+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;
+}
+async function gate(changeId) {
+  const cwd = process.cwd();
+  const changeDir = join8(cwd, "specs", "changes", changeId);
+  if (!existsSync7(changeDir)) {
+    log.error(`change not found: ${changeId} (looked in ${changeDir})`);
+    process.exit(1);
+  }
+  const errors = [];
+  for (const f of REQUIRED_FILES) {
+    if (!existsSync7(join8(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 (meaningfulChars(content) < 100) {
+        errors.push(`${f}: appears to be a stub (< 100 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 agentLogDir = join8(changeDir, "agent-log");
+  if (existsSync7(agentLogDir)) {
+    const logFiles = readdirSync4(agentLogDir).filter((f) => f.endsWith(".md"));
+    for (const f of logFiles) {
+      const content = readFileSync4(join8(agentLogDir, f), "utf8");
+      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)`);
+        continue;
+      }
+      const status = statusMatch[1];
+      if (status === "blocked") {
+        const nextActionMatch = content.match(/^\s*-\s*next-action:\s*(.+)$/m);
+        if (!nextActionMatch || nextActionMatch[1].trim().toLowerCase() === "none" || nextActionMatch[1].trim().length < 10) {
+          errors.push(`agent-log/${f}: status=blocked requires concrete "next-action:" line (>= 10 chars, not "none")`);
+        }
+      }
+    }
+  }
+  if (errors.length > 0) {
+    log.error(`gate failed for change: ${changeId}`);
+    for (const e of errors) {
+      log.error(`  ${e}`);
+    }
+    process.exit(1);
+  }
+  log.info(`gate: running contract validators for ${changeId}\u2026`);
+  const r = spawnSync2(process.execPath, [process.argv[1], "validate"], {
+    cwd,
+    stdio: "inherit"
+  });
+  if (r.status !== 0) {
+    log.error(`gate failed for change: ${changeId} (validators returned non-zero)`);
+    process.exit(1);
+  }
+  log.ok(`gate passed for change: ${changeId}`);
+}
+
+// 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";
+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)) {
+    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");
+  let final;
+  if (!existsSync8(dest)) {
+    final = ourHook;
+  } else {
+    const existing = readFileSync5(dest, "utf8");
+    const startIdx = existing.indexOf(START_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+    if (startIdx >= 0 && endIdx > startIdx) {
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx + END_MARKER.length);
+      const ourStart = ourHook.indexOf(START_MARKER);
+      const ourEnd = ourHook.indexOf(END_MARKER) + END_MARKER.length;
+      const ourBlock = ourHook.slice(ourStart, ourEnd);
+      final = before + ourBlock + after;
+    } else {
+      const ourStart = ourHook.indexOf(START_MARKER);
+      const ourEnd = ourHook.indexOf(END_MARKER) + END_MARKER.length;
+      const ourBlock = ourHook.slice(ourStart, ourEnd);
+      if (existing.startsWith("#!")) {
+        const firstNewline = existing.indexOf("\n");
+        const shebang = existing.slice(0, firstNewline + 1);
+        const rest = existing.slice(firstNewline + 1);
+        final = shebang + "\n" + ourBlock + "\n" + rest;
+      } else {
+        final = "#!/bin/sh\n" + ourBlock + "\n" + existing;
+      }
+    }
+  }
+  writeFileSync2(dest, final, "utf8");
+  try {
+    chmodSync(dest, 493);
+  } catch {
+  }
+  log.ok(`pre-commit hook installed at ${dest}`);
+  log.info("cdd-kit gate will now run automatically before each commit affecting specs/changes/");
+}
+
 // src/cli/index.ts
+var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync6(join10(__dirname2, "..", "..", "package.json"), "utf8"));
 var program = new Command();
-program.name("cdd-kit").description("Contract-Driven Delivery Kit CLI").version("1.0.0");
+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(
@@ -321,16 +788,36 @@ program.command("init").description(
     force: opts.force
   })
 );
-program.command("update").description("Update ~/.claude agents and skill (does not touch project files)").action(() => update());
-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).action(
-  (name, opts) => newChange(name, { all: opts.all })
+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("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).action(
+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({
     contracts: opts.contracts,
     env: opts.env,
     ci: opts.ci,
-    spec: opts.spec
+    spec: opts.spec,
+    versions: opts.versions
   })
 );
+program.command("gate <change-id>").description("Run full orchestration gate for a change (required artifacts, content, tier, contracts)").action(async (id) => {
+  await gate(id);
+});
+program.command("install-hooks").description("Install pre-commit hook that runs cdd-kit gate on staged changes").action(async () => {
+  await installHooks();
+});
+program.command("detect-stack").description("Detect the project tech stack and print the result").action(() => {
+  const cwd = process.cwd();
+  const result = detectStack(cwd);
+  console.log(`Detected stack: ${result.primary}`);
+  if (result.candidates.length > 1) {
+    console.log(`Candidates (in order): ${result.candidates.join(", ")}`);
+  }
+  if (result.polyglot) {
+    console.log(
+      `Polyglot: yes (config will be generated for ${result.primary})`
+    );
+  }
+});
 program.parse();