contract-driven-delivery 2.0.8 → 2.0.9

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [2.0.9] - 2026-05-04
+
+Bug-fix patch. Discovered when verifying a real consumer repo (TODOLIST)
+after a successful 2.0.8 upgrade: the user's committed
+`specs/context/project-map.md` listed local kit-generated backup directories
+(`.cdd/.refresh-backup/...`, `.cdd/migrate-backup/...`), which then never
+matched fresh-clone digests — `cdd-kit doctor` reported "inputs changed"
+forever even when nothing was wrong.
+
+### Fixed
+
+- **`cdd-kit context-scan` excludes kit runtime artifacts AND common
+  transient cache directories at any depth**:
+  - `DEFAULT_FORBIDDEN` (path-prefix list) now includes
+    `.cdd/.refresh-backup`, `.cdd/migrate-backup`, `.cdd/runtime`.
+  - New `FORBIDDEN_DIRECTORY_NAMES` (basename-anywhere list) catches
+    Python (`__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`,
+    `.tox`), JS/TS framework caches (`.next`, `.nuxt`, `.svelte-kit`,
+    `.parcel-cache`, `.turbo`, `.nyc_output`), generic build/coverage
+    (`coverage`, `htmlcov`, `.cache`), virtualenvs (`venv`, `.venv`),
+    nested `node_modules`, and IDE noise (`.idea`, `.vscode`, `.DS_Store`).
+  - Mirrors `code-map`'s `BUILTIN_EXCLUDE` so the two indexes ignore the
+    same noise. Previously context-scan only had 8 path-prefix entries
+    (`.claude / .git / node_modules / dist / build / assets / specs/archive /
+    specs/changes`), so locally-generated caches polluted the project-map
+    tree section and broke `inputs-digest` determinism for fresh clones.
+
+### Added
+
+- **`cdd-kit refresh`** auto-appends `.cdd/.refresh-backup/` to `.gitignore`
+  the first time it overwrites a template (idempotent — no duplicate
+  entries on subsequent runs). Logs the action so users know what changed.
+- **`cdd-kit migrate`** auto-appends `.cdd/migrate-backup/` to `.gitignore`
+  with identical idempotent semantics.
+
+### Migration
+
+If you already committed a polluted `specs/context/project-map.md` (signs:
+the tree section contains paths under `.cdd/.refresh-backup/` or
+`.cdd/migrate-backup/`, doctor reports "inputs changed" after a successful
+refresh), recover with:
+
+```bash
+echo ".cdd/.refresh-backup/" >> .gitignore
+rm -rf .cdd/.refresh-backup
+cdd-kit context-scan
+git add .gitignore specs/context/
+git commit -m "fix: exclude cdd-kit refresh-backup from context-scan"
+```
+
+Future refreshes will handle the gitignore entry automatically.
+
 ## [2.0.8] - 2026-05-04
 
 Adds `cdd-kit refresh` — a one-shot complete upgrade command. The previous

package/dist/cli/index.js

@@ -415,7 +415,14 @@ function getForbiddenPaths(cwd) {
 }
 function isForbidden(relPath, forbidden) {
   const normalized = relPath.replace(/\\/g, "/");
-  return forbidden.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`));
+  if (forbidden.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`))) {
+    return true;
+  }
+  for (const segment of normalized.split("/")) {
+    if (FORBIDDEN_DIRECTORY_NAMES.has(segment))
+      return true;
+  }
+  return false;
 }
 function buildTree(dir, cwd, forbidden, stats, prefix = "", depth = 0) {
   const entries = readdirSync4(dir, { withFileTypes: true }).sort((a, b) => {
@@ -632,7 +639,7 @@ async function contextScan(opts = {}) {
     log.ok("Created specs/context/contracts-index.md");
   }
 }
-var DEFAULT_FORBIDDEN, PER_DIR_ENTRY_CAP;
+var DEFAULT_FORBIDDEN, FORBIDDEN_DIRECTORY_NAMES, PER_DIR_ENTRY_CAP;
 var init_context_scan = __esm({
   "src/commands/context-scan.ts"() {
     "use strict";
@@ -645,8 +652,43 @@ var init_context_scan = __esm({
       "build",
       "assets",
       "specs/archive",
-      "specs/changes"
+      "specs/changes",
+      // cdd-kit runtime artifacts. Without these the user's local backups land
+      // in `specs/context/project-map.md`, polluting it and breaking the
+      // inputs-digest match for any fresh clone.
+      ".cdd/.refresh-backup",
+      ".cdd/migrate-backup",
+      ".cdd/runtime"
     ];
+    FORBIDDEN_DIRECTORY_NAMES = /* @__PURE__ */ new Set([
+      // Node — also caught by top-level prefix, but a nested
+      // `frontend/node_modules` requires basename matching
+      "node_modules",
+      // Python
+      "__pycache__",
+      ".pytest_cache",
+      ".mypy_cache",
+      ".ruff_cache",
+      ".tox",
+      // JS/TS frameworks
+      ".next",
+      ".nuxt",
+      ".svelte-kit",
+      ".parcel-cache",
+      ".turbo",
+      ".nyc_output",
+      // Generic build / coverage caches
+      "coverage",
+      "htmlcov",
+      ".cache",
+      // Virtualenvs
+      "venv",
+      ".venv",
+      // IDE / OS noise
+      ".idea",
+      ".vscode",
+      ".DS_Store"
+    ]);
     PER_DIR_ENTRY_CAP = 50;
   }
 });
@@ -8057,11 +8099,35 @@ async function migrate(changeId, opts = {}) {
     log.ok(`Migration complete: ${migratedCount} updated, ${upToDateCount} already up to date.`);
     if (migratedCount > 0 && !noBackup) {
       log.info(`Backup: ${backupRoot}`);
+      if (ensureGitignoreEntry(cwd, ".cdd/migrate-backup/")) {
+        log.info("Added `.cdd/migrate-backup/` to .gitignore");
+      }
       log.info('Next: git add specs/changes/ && git commit -m "chore: migrate changes to YAML format"');
       log.info("When stable, remove backup: rm -rf .cdd/migrate-backup/");
     }
   }
 }
+function ensureGitignoreEntry(cwd, entry) {
+  const path = join16(cwd, ".gitignore");
+  const trimmed = entry.trim();
+  if (!trimmed)
+    return false;
+  const re = new RegExp(`^\\s*${trimmed.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*$`, "m");
+  let existing = "";
+  if (existsSync14(path))
+    existing = readFileSync11(path, "utf8");
+  if (re.test(existing))
+    return false;
+  const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const block = existing.length === 0 ? `# cdd-kit generated backups (do not commit)
+${trimmed}
+` : `${sep}
+# cdd-kit generated backups (do not commit)
+${trimmed}
+`;
+  writeFileSync6(path, existing + block, "utf8");
+  return true;
+}
 var init_migrate = __esm({
   "src/commands/migrate.ts"() {
     "use strict";
@@ -9178,6 +9244,27 @@ function planSingleFile(src, dest, rel) {
     return { src, dest, rel, action: "overwrite" };
   return { src, dest, rel, action: "skip" };
 }
+function ensureGitignoreEntry2(cwd, entry) {
+  const path = join20(cwd, ".gitignore");
+  const trimmed = entry.trim();
+  if (!trimmed)
+    return false;
+  const re = new RegExp(`^\\s*${trimmed.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*$`, "m");
+  let existing = "";
+  if (existsSync17(path))
+    existing = readFileSync18(path, "utf8");
+  if (re.test(existing))
+    return false;
+  const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const block = existing.length === 0 ? `# cdd-kit generated backups (do not commit)
+${trimmed}
+` : `${sep}
+# cdd-kit generated backups (do not commit)
+${trimmed}
+`;
+  writeFileSync10(path, existing + block, "utf8");
+  return true;
+}
 function applyPlan(plan, backupRoot) {
   let added = 0;
   let overwritten = 0;
@@ -9336,6 +9423,9 @@ async function refresh(opts) {
         log.ok(`  applied: +${templateAdded} added, ~${templateOverwritten} overwritten`);
         if (templateOverwritten > 0) {
           log.info(`  backup saved to: ${relative5(cwd, backupRoot).replace(/\\/g, "/")}`);
+          if (ensureGitignoreEntry2(cwd, ".cdd/.refresh-backup/")) {
+            log.info("  added `.cdd/.refresh-backup/` to .gitignore");
+          }
         }
       } else {
         log.dim("  (dry-run \u2014 no changes written)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",