@dzhechkov/skills-feature-adr 1.3.22 → 1.3.26

package/CHANGELOG.md

@@ -1,10 +1,31 @@
 # Changelog
 
+### Follow-up (QE LOW gaps closed before publish)
+- **Upstream deletions**: `update` now removes files the template dropped (manifest-tracked orphans only; user-created untracked files are never touched) — previously `diff.missing` was computed but ignored. Shown in the summary + `--dry-run` (`- DEL`). Tests: Case G/H.
+- Removed a dead `unchanged` branch in the directory update path (unreachable — `diff.modified` guarantees bytes differ).
+- `safeHashFile` guards the TOCTOU window (file vanishing mid-update → skip+warn, not a crash).
+
+
 All notable changes to `@dzhechkov/skills-feature-adr` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.23] - 2026-07-06
+
+### Fixed
+
+- **`update` no longer silently drops upstream changes (false "locally modified").** The manifest previously stored installed files as an array of paths only, so `update` could only do a 2-way content compare between the new template and the currently-installed file. A template file that evolved upstream but that the user never edited (`src != dest`) was wrongly classified `modified` and kept — the upstream update was silently not applied. `update` now performs a true **three-way merge** (baseline / mine / theirs): an evolved-but-unedited file **is updated**, and a genuinely user-edited file **is kept** with a now-*true* "locally modified, kept" warning.
+
+### Added
+
+- **Per-file SHA-256 baseline in the manifest.** `init` records a new additive `hashes` map (`{ "<relpath>": "<sha256 of the template bytes as installed>" }`) alongside the existing `files` array. `files` stays an array, so `remove` / `doctor` / `list` are unchanged. `update` reads these baselines to classify each file three-way and rewrites them to the new template's hashes afterward (idempotent re-runs).
+- **`node:test` suite** (`test/`) with a `"test"` script (`node --test`), zero new dependencies. Covers the load-bearing truth table and the two inverse-error boundaries (evolved-unedited → updated; user-edited → kept), plus legacy fallback, `--force`/`.bak`, self-heal, back-compat, and idempotence.
+
+### Notes
+
+- **Backward compatible.** A manifest from any prior version (no `hashes` key) is treated as "legacy — no baseline": every differing file falls back to today's conservative keep+warn (no clobber). The first `update` writes a fresh `hashes` map (self-heal), so true 3-way is available from the next run. A pre-fix install whose upgrade only *modifies* existing files may need one `update` (to self-heal the baseline) or a `--force` before evolved-but-unedited files auto-apply. Old CLI versions ignore the additive `hashes` key, so a downgrade stays safe.
+
 ## [1.3.13] - 2026-07-03
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.22",
+  "version": "1.3.26",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"
@@ -58,5 +58,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  }
 }

package/src/commands/init.js

@@ -8,7 +8,7 @@ const {
   fileExists, readJSON,
   ensureDir, getRelativePaths, getRelativePathsFiltered,
   createManifest, readManifest, writeManifest, getTemplatesDir,
-  toManifestPath, fromManifestPath,
+  toManifestPath, fromManifestPath, hashFile,
   COMPONENTS, OPTIONAL_COMPONENTS, MANIFEST_FILE, getComponentFilter,
 } = require('../utils');
 
@@ -61,7 +61,7 @@ function showKeysariumIntegration(keysariumManifest) {
 // Returns { missing, fileCount } where `missing` means the template source
 // was absent on disk and `fileCount` is how many files the template provides.
 function installComponent(key, comp, templatesDir, targetDir, opts) {
-  const { force, dryRun, written, preserved } = opts;
+  const { force, dryRun, written, preserved, hashes } = opts;
   const src = path.join(templatesDir, comp.src);
   const destRoot = path.join(targetDir, comp.src);
 
@@ -96,6 +96,13 @@ function installComponent(key, comp, templatesDir, targetDir, opts) {
     if (!dryRun) {
       ensureDir(path.dirname(entry.destFile));
       fs.copyFileSync(entry.srcFile, entry.destFile);
+      // Record the SHA-256 of the TEMPLATE bytes we just installed (not the
+      // dest) as this file's baseline. This makes baseline == mine immediately
+      // after init — the invariant the 3-way `update` decision relies on.
+      // Preserved (pre-existing, not written by us) files get NO baseline: we
+      // did not install those bytes, so they fall through to update's
+      // conservative "no baseline → legacy" path. dry-run computes none.
+      if (hashes) hashes[entry.rel] = hashFile(entry.srcFile);
     }
     written.push(entry.rel);
   }
@@ -224,6 +231,7 @@ async function run(options) {
   // ── e) Install components (classify-only when --dry-run) ────────────────
   const totalComponents = componentKeys.length + optionalKeys.length;
   const installedFiles = [];   // files written (or would-write in dry-run)
+  const installedHashes = {};  // rel -> sha256 of the TEMPLATE bytes installed (baseline)
   const preservedFiles = [];   // pre-existing files NOT overwritten (no --force)
   const completedKeys = [];    // component keys processed so far (for partial manifest)
   const installedOptionalKeys = [];
@@ -238,6 +246,7 @@ async function run(options) {
 
       installComponent(key, comp, templatesDir, targetDir, {
         force, dryRun, written: installedFiles, preserved: preservedFiles,
+        hashes: installedHashes,
       });
       completedKeys.push(key);
     }
@@ -253,6 +262,7 @@ async function run(options) {
 
       const res = installComponent(key, comp, templatesDir, targetDir, {
         force, dryRun, written: installedFiles, preserved: preservedFiles,
+        hashes: installedHashes,
       });
       if (!res.missing && res.fileCount > 0) {
         installedOptionalKeys.push(key);
@@ -269,7 +279,8 @@ async function run(options) {
         const partialManifest = createManifest(
           failPkg ? failPkg.version : '0.0.0',
           completedKeys,
-          installedFiles.sort()
+          installedFiles.sort(),
+          installedHashes
         );
         partialManifest.partial = true;
         writeManifest(targetDir, partialManifest);
@@ -319,7 +330,7 @@ async function run(options) {
 
   // Only manifest components whose templates were actually present on disk
   const allKeys = [...componentKeys, ...installedOptionalKeys];
-  const manifest = createManifest(version, allKeys, installedFiles.sort());
+  const manifest = createManifest(version, allKeys, installedFiles.sort(), installedHashes);
 
   // Track optional features in manifest based on actual installs
   manifest.optional = {

package/src/commands/update.js

@@ -3,12 +3,12 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  green, yellow, cyan, bold, dim,
+  green, red, yellow, cyan, bold, dim,
   info, success, warn, error: logError, step,
   copyDirRecursive, copyDirFiltered, fileExists, readJSON,
   ensureDir, getRelativePaths, getRelativePathsFiltered, diffFiles,
   readManifest, writeManifest, getTemplatesDir,
-  toManifestPath,
+  toManifestPath, fromManifestPath, hashFile, safeHashFile, classifyThreeWay,
   COMPONENTS, OPTIONAL_COMPONENTS, MANIFEST_FILE, getComponentFilter,
 } = require('../utils');
 
@@ -50,6 +50,10 @@ async function run(options) {
   console.log('');
 
   // ── c) Diff each component ────────────────────────────────────────────
+  // Per-file SHA-256 baseline hashes written at init/last-update (may be absent on a
+  // legacy array-only manifest → null → every differing file is treated as
+  // "no baseline → legacy" and gets the conservative 2-way keep+warn).
+  const manifestHashes = manifest.hashes || null;
   let totalAdded = 0;
   let totalModified = 0;
   let totalUnchanged = 0;
@@ -86,16 +90,30 @@ async function run(options) {
       if (!fileExists(destBase)) {
         filesToCopy.push({ src: srcBase, dest: destBase, status: 'added', relPath: comp.src });
         totalAdded++;
-      } else if (!fs.readFileSync(srcBase).equals(fs.readFileSync(destBase))) {
-        const entry = { src: srcBase, dest: destBase, status: 'modified', relPath: comp.src };
-        if (force) {
-          filesToCopy.push(entry);
-          totalModified++;
+      } else {
+        const mine = safeHashFile(destBase);
+        if (mine === null) {
+          warn(`Skipped ${comp.src} — could not read the installed file (removed mid-update?).`);
+          continue;
+        }
+        const theirs = hashFile(srcBase);
+        if (mine === theirs) {
+          totalUnchanged++;
         } else {
-          keptModified.push(entry);
+          const posix = toManifestPath(comp.src);
+          const baseline = manifestHashes ? manifestHashes[posix] : undefined;
+          const verdict = classifyThreeWay({ baseline, mine, theirs });
+          const entry = { src: srcBase, dest: destBase, status: 'modified', relPath: comp.src };
+          // 'update' → user did NOT edit, upstream evolved → APPLY (the fix).
+          // 'keep'/'legacy' → keep + warn (true "locally modified"); --force
+          // still overwrites either after a .bak.
+          if (verdict === 'update' || force) {
+            filesToCopy.push(entry);
+            totalModified++;
+          } else {
+            keptModified.push(entry);
+          }
         }
-      } else {
-        totalUnchanged++;
       }
       continue;
     }
@@ -113,17 +131,38 @@ async function run(options) {
       totalAdded++;
     }
 
+    // diff.modified = "src bytes != dest bytes" only. That collapses two very
+    // different cases: (a) the user edited the file, (b) the template evolved
+    // upstream and the user never touched it. The per-file baseline lets us
+    // tell them apart via a true 3-way compare instead of blindly keeping both.
     for (const rel of diff.modified) {
-      const entry = {
-        src: path.join(srcBase, rel),
-        dest: path.join(destBase, rel),
-        status: 'modified',
-        relPath: path.join(comp.src, rel),
-      };
-      if (force) {
+      const srcFile = path.join(srcBase, rel);
+      const destFile = path.join(destBase, rel);
+      const relPath = path.join(comp.src, rel);
+      const posix = toManifestPath(relPath);
+      const baseline = manifestHashes ? manifestHashes[posix] : undefined;
+      const mine = safeHashFile(destFile);    // current installed bytes (null if vanished mid-update)
+      if (mine === null) {
+        warn(`Skipped ${relPath} — could not read the installed file (removed mid-update?).`);
+        continue;
+      }
+      const theirs = hashFile(srcFile);   // new template bytes
+      const verdict = classifyThreeWay({ baseline, mine, theirs });
+      const entry = { src: srcFile, dest: destFile, status: 'modified', relPath };
+
+      // NB: diff.modified guarantees the bytes already differ, so mine !== theirs
+      // here and classifyThreeWay never returns 'unchanged' on this path — the
+      // three reachable verdicts are 'update', 'keep', 'legacy'.
+      if (verdict === 'update' || force) {
+        // 'update' → baseline == mine → user did NOT edit → apply upstream (the bug
+        //   fix: previously this was silently reported "locally modified, kept").
+        // force   → overwrite a genuine edit too, after a .bak (copy-loop below).
         filesToCopy.push(entry);
         totalModified++;
       } else {
+        // 'keep'  → baseline != mine AND theirs != mine → genuine local edit
+        //           (now a TRUE "locally modified, kept").
+        // 'legacy'→ no baseline → conservative fallback (differs ⇒ keep+warn).
         keptModified.push(entry);
       }
     }
@@ -131,10 +170,95 @@ async function run(options) {
     totalUnchanged += diff.unchanged.length;
   }
 
+  // Re-derive the manifest's `files` array and the per-file `hashes` baseline
+  // from the CURRENT template set. `hashes[rel]` is set to the NEW template's
+  // bytes (D4): uniform "baseline = theirs" makes the next `update` idempotent
+  // (an applied file becomes 'unchanged', a kept edit stays 'keep', a legacy
+  // file self-heals into the 3-way regime — all with zero further writes) and a
+  // file whose template no longer exists keeps whatever baseline it had. Records
+  // from the TEMPLATE source only — NEVER scans destPath, or user-owned files
+  // get adopted into manifest.files (and a later remove would delete them).
+  function rebuildManifestData() {
+    const allFiles = [];
+    const newHashes = {};
+    const oldHashes = manifest.hashes || {};
+    const prevFiles = Array.isArray(manifest.files) ? manifest.files : [];
+    for (const key of installedKeys) {
+      const comp = COMPONENTS[key] || OPTIONAL_COMPONENTS[key];
+      if (!comp) continue;
+
+      const srcPath = path.join(templatesDir, comp.src);
+      const destPath = path.join(targetDir, comp.src);
+      const filterFn = getComponentFilter(comp);
+
+      // Template source missing → keep the previous manifest entries verbatim.
+      if (!fileExists(srcPath)) {
+        // Compare in POSIX form so old manifests with native (backslash)
+        // separators still match; re-store the kept entries POSIX-normalized.
+        const compPosix = toManifestPath(comp.src);
+        const kept = prevFiles.filter((rel) => {
+          const relPosix = toManifestPath(rel);
+          return relPosix === compPosix || relPosix.startsWith(compPosix + '/');
+        });
+        for (const rel of kept) {
+          const relPosix = toManifestPath(rel);
+          allFiles.push(relPosix);
+          // No template to re-hash — preserve the prior baseline if we had one.
+          if (oldHashes[relPosix] != null) newHashes[relPosix] = oldHashes[relPosix];
+        }
+        warn(`component '${key}' not found in current templates — manifest entries kept as-is`);
+        continue;
+      }
+
+      // Single-file components: record the file itself. getRelativePaths() would
+      // readdir it — without this branch the 3 learning files silently drop out
+      // of the manifest on every rebuild, and a later `remove` strands them.
+      if (comp.isFile) {
+        if (fileExists(destPath)) {
+          const posix = toManifestPath(comp.src);
+          allFiles.push(posix);
+          newHashes[posix] = hashFile(srcPath); // theirs = new template bytes
+        }
+        continue;
+      }
+
+      if (fileExists(destPath)) {
+        const paths = filterFn
+          ? getRelativePathsFiltered(srcPath, filterFn)
+          : getRelativePaths(srcPath);
+        for (const rel of paths) {
+          const posix = toManifestPath(path.join(comp.src, rel));
+          allFiles.push(posix);
+          newHashes[posix] = hashFile(path.join(srcPath, rel)); // theirs
+        }
+      }
+    }
+    return { allFiles, newHashes };
+  }
+
+  // ── Upstream DELETIONS ────────────────────────────────────────────────
+  // Files this install previously tracked (manifest.files) that the CURRENT
+  // template no longer provides. They were ours — the old manifest says so — so a
+  // proper update removes them instead of letting them linger (diffFiles computed
+  // `missing` but the old update never consumed it). User-created files are NEVER
+  // in the manifest, so they can never be orphaned here. `rebuildManifestData`'s
+  // allFiles is the authoritative NEW set (and already re-keeps a whole component
+  // whose template dir went missing), so old − new = true upstream deletions.
+  const newFileSet = new Set(rebuildManifestData().allFiles.map(toManifestPath));
+  const prevManifestFiles = Array.isArray(manifest.files) ? manifest.files : [];
+  const orphans = prevManifestFiles
+    .map(toManifestPath)
+    .filter((rel, i, a) => a.indexOf(rel) === i) // dedup
+    .filter((rel) => !newFileSet.has(rel))
+    .filter((rel) => fileExists(path.join(targetDir, fromManifestPath(rel))));
+
   // ── Show diff summary ─────────────────────────────────────────────────
   info(bold('Update summary:'));
   console.log(`  ${green('+')} ${totalAdded} file(s) to add`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) to update`);
+  if (orphans.length > 0) {
+    console.log(`  ${red('-')} ${orphans.length} file(s) to remove (dropped from template)`);
+  }
   if (keptModified.length > 0) {
     console.log(`  ${yellow('\u26a0')} ${keptModified.length} file(s) locally modified, kept`);
   }
@@ -149,8 +273,21 @@ async function run(options) {
     console.log('');
   }
 
-  if (totalAdded === 0 && totalModified === 0) {
+  if (totalAdded === 0 && totalModified === 0 && orphans.length === 0) {
     if (keptModified.length > 0) {
+      // Nothing to copy, but files were kept. Refresh the per-file baseline so a
+      // legacy (no-hashes) install self-heals into the 3-way regime and a kept
+      // conflict records the current template as its baseline (D3/D4). We do NOT
+      // bump the version \u2014 no template bytes were actually applied. Never write
+      // under --dry-run.
+      if (!dryRun) {
+        const { newHashes } = rebuildManifestData();
+        if (Object.keys(newHashes).length > 0) {
+          manifest.hashes = newHashes;
+          manifest.updatedAt = new Date().toISOString();
+          writeManifest(targetDir, manifest);
+        }
+      }
       success('No files to update \u2014 locally modified file(s) kept.');
     } else {
       success('Everything is up to date!');
@@ -165,6 +302,9 @@ async function run(options) {
       const note = f.status === 'modified' ? dim(' (will back up to .bak)') : '';
       console.log(`  ${marker}  ${f.relPath}${note}`);
     }
+    for (const rel of orphans) {
+      console.log(`  ${red('- DEL')}  ${rel} ${dim('(dropped from template)')}`);
+    }
     console.log('');
     warn('Dry run \u2014 no files were written.');
     process.exit(0);
@@ -186,53 +326,30 @@ async function run(options) {
     fs.copyFileSync(f.src, f.dest);
   }
 
-  // ── e) Update manifest ────────────────────────────────────────────────
-  const allFiles = [];
-  const prevFiles = Array.isArray(manifest.files) ? manifest.files : [];
-  for (const key of installedKeys) {
-    const comp = COMPONENTS[key] || OPTIONAL_COMPONENTS[key];
-    if (!comp) continue;
-
-    const srcPath = path.join(templatesDir, comp.src);
-    const destPath = path.join(targetDir, comp.src);
-    const filterFn = getComponentFilter(comp);
-
-    // Record from the TEMPLATE source only — NEVER scan destPath, or user-owned
-    // files get adopted into manifest.files (and a later remove would delete
-    // them). If the template source is missing, keep the previous manifest
-    // entries for this component verbatim.
-    if (!fileExists(srcPath)) {
-      // Compare in POSIX form so old manifests with native (backslash)
-      // separators still match; re-store the kept entries POSIX-normalized.
-      const compPosix = toManifestPath(comp.src);
-      const kept = prevFiles.filter((rel) => {
-        const relPosix = toManifestPath(rel);
-        return relPosix === compPosix || relPosix.startsWith(compPosix + '/');
-      });
-      allFiles.push(...kept.map(toManifestPath));
-      warn(`component '${key}' not found in current templates — manifest entries kept as-is`);
-      continue;
-    }
-
-    // Single-file components: record the file itself. getRelativePaths() would
-    // readdir it — without this branch the 3 learning files silently drop out of
-    // the manifest on every rebuild, and a later `remove` strands them.
-    if (comp.isFile) {
-      if (fileExists(destPath)) allFiles.push(toManifestPath(comp.src));
-      continue;
-    }
-
-    if (fileExists(destPath)) {
-      const paths = filterFn
-        ? getRelativePathsFiltered(srcPath, filterFn)
-        : getRelativePaths(srcPath);
-      allFiles.push(...paths.map((rel) => toManifestPath(path.join(comp.src, rel))));
+  // ── d2) Remove upstream-dropped files (manifest-tracked orphans) ──────
+  let removed = 0;
+  for (const rel of orphans) {
+    const abs = path.join(targetDir, fromManifestPath(rel));
+    try {
+      fs.rmSync(abs);
+      console.log(`         ${red('- removed')} ${rel} ${dim('(dropped from template)')}`);
+      removed++;
+    } catch {
+      warn(`could not remove ${rel} (already gone?) — skipped`);
     }
   }
 
+  // ── e) Update manifest ────────────────────────────────────────────────
+  const { allFiles, newHashes } = rebuildManifestData();
+
   manifest.version = newVersion;
   manifest.updatedAt = new Date().toISOString();
   manifest.files = allFiles.sort();
+  // Additive: only attach `hashes` when we actually have baseline hashes, so a
+  // no-op/empty rebuild never introduces an empty key.
+  if (Object.keys(newHashes).length > 0) {
+    manifest.hashes = newHashes;
+  }
 
   writeManifest(targetDir, manifest);
   info(`Updated ${MANIFEST_FILE} manifest`);
@@ -242,6 +359,9 @@ async function run(options) {
   success(bold('Update complete!'));
   console.log(`  ${green('+')} ${totalAdded} file(s) added`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) updated`);
+  if (removed > 0) {
+    console.log(`  ${red('-')} ${removed} file(s) removed (dropped from template)`);
+  }
   if (keptModified.length > 0) {
     console.log(`  ${yellow('⚠')} ${keptModified.length} file(s) locally modified, kept`);
   }

package/src/utils.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 // ===========================================================================
 // Colors — ANSI escape codes (zero dependencies)
@@ -202,6 +203,52 @@ function diffFiles(srcDir, destDir, filterFn) {
   return { added, modified, unchanged, missing };
 }
 
+// ===========================================================================
+// Content hashing — SHA-256 baseline for the 3-way update decision
+//
+// The manifest stores, per file, the SHA-256 of the TEMPLATE bytes that were
+// installed at init time. `update` then knows three inputs — baseline (what
+// init wrote), mine (current install), theirs (new template) — and can tell a
+// user edit apart from an upstream evolution instead of collapsing both to
+// "src != dest". Pure Node built-in `crypto`; zero dependencies.
+// ===========================================================================
+
+// Hash an arbitrary Buffer/string. Used by tests and by hashFile.
+function hashBytes(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// Hash a file's bytes on disk. Synchronous, matching the rest of this module.
+function hashFile(absPath) {
+  return hashBytes(fs.readFileSync(absPath));
+}
+
+// Best-effort hashFile: returns null if the file cannot be read (e.g. it vanished
+// between the diff scan and the re-hash — a TOCTOU window in `update`). Callers
+// treat a null hash as "can't classify this file" and skip it with a warning
+// instead of crashing the whole update with an uncaught stack trace.
+function safeHashFile(absPath) {
+  try {
+    return hashFile(absPath);
+  } catch {
+    return null;
+  }
+}
+
+// PURE three-way classifier — the whole truth table, no I/O, unit-testable.
+//   baseline == null (or absent) → 'legacy'   → caller falls back to the
+//                                                conservative 2-way keep+warn
+//   mine === theirs              → 'unchanged' → already matches upstream
+//   baseline === mine            → 'update'    → user did NOT edit → take theirs
+//   else                         → 'keep'      → user edited AND upstream moved
+//                                                → true "locally modified, kept"
+function classifyThreeWay({ baseline, mine, theirs }) {
+  if (baseline == null) return 'legacy';
+  if (mine === theirs) return 'unchanged';
+  if (baseline === mine) return 'update';
+  return 'keep';
+}
+
 // ===========================================================================
 // Manifest — .skills-feature-adr.json management
 // ===========================================================================
@@ -230,13 +277,20 @@ function writeManifest(targetDir, data) {
   writeJSON(path.join(targetDir, MANIFEST_FILE), data);
 }
 
-function createManifest(version, components, files) {
-  return {
+function createManifest(version, components, files, hashes) {
+  const manifest = {
     version: version,
     installedAt: new Date().toISOString(),
     components: components,
     files: files,
   };
+  // `hashes` is additive and optional: include it only when a non-empty map is
+  // supplied so legacy/partial callers (3-arg) stay byte-for-byte compatible
+  // and old manifests keep their array-only shape.
+  if (hashes && Object.keys(hashes).length > 0) {
+    manifest.hashes = hashes;
+  }
+  return manifest;
 }
 
 // ===========================================================================
@@ -386,6 +440,12 @@ module.exports = {
   getRelativePathsFiltered,
   diffFiles,
 
+  // Content hashing / 3-way classifier
+  hashBytes,
+  hashFile,
+  safeHashFile,
+  classifyThreeWay,
+
   // Manifest
   MANIFEST_FILE,
   toManifestPath,

package/templates/.claude/rules/feature-adr-ultracode.md

@@ -25,6 +25,23 @@ The pipeline ALWAYS runs the feature-adr Pattern memory loop **in-process** —
 - **Step 0** recalls learned patterns (`dz recall`) → folds the top ones into requirements/ADR as `{LEARNED_PATTERNS}` + records the recalled count in the live panel (`dz statusline --fa-record`).
 - **Step 8** teaches the durable lessons back (`dz teach`) + records the stored count. The loop pays off (recall) and grows (teach) every run.
 
+## Optional Codex planner (opt-in, pre-flight ASK)
+
+feature-adr can route the **planning step (Step 6)** to Codex's top model instead of Claude. It is
+**opt-in and graceful**: absent/declined/failed → the default Claude planner runs (the pipeline never
+blocks on Codex).
+
+Pre-flight, BEFORE launching a feature-adr run, detect Codex readiness:
+```
+node "<codex-plugin>/scripts/codex-companion.mjs" setup --json   → { ready: true }
+```
+If `ready`, **ASK the user once**: *"Use the top Codex model for the planning step?"* On yes, pass
+`args.planner: 'codex'` (the workflow routes Step 6 to the `codex:codex-rescue` agentType, with a
+Claude fallback and `plannerUsed` in the result). On no / not-ready, omit `planner` (Claude plans).
+For the interactive SKILL (plain `/feature-adr`), make the same offer at the planning checkpoint.
+Codex needs a headless login on a VPS: `codex login --device-auth` (code + URL) or
+`printenv OPENAI_API_KEY | codex login --with-api-key`.
+
 ## Hybrid checkpoints (router decides)
 
 - **S / M** → run autonomously to completion; present a final consolidated review (ADR + plan + QE).

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -355,6 +355,12 @@ Step 0 (Complexity Router) checks:
   description, code, tier, stopAfter, repo, dzBin } })`. Hybrid checkpoints: S/M autonomous; L/XL return
   after the Plan phase for your steer. See `.claude/rules/feature-adr-ultracode.md`.
 
+**Optional Codex planner (opt-in).** When Codex is installed + logged in (`codex login --device-auth`
+on a headless VPS, or `printenv OPENAI_API_KEY | codex login --with-api-key`), the pipeline can route the
+**planning step to Codex's top model**. It ALWAYS asks first — a pre-flight *"Use the top Codex model for
+planning?"* — and falls back to Claude if you decline or Codex is unavailable (never blocks). ultracode:
+pass `args.planner: 'codex'`. Plain `/feature-adr`: the same offer appears at the planning checkpoint.
+
 ### Pattern memory loop (self-learning — runs in ALL modes)
 
 **Self-learning is MANDATORY on EVERY `/feature-adr` run — including plain `/feature-adr` without any

package/templates/.claude/workflows/feature-adr.js

@@ -1,7 +1,7 @@
 export const meta = {
   name: 'feature-adr',
-  description: 'Canonical /feature-adr --full-qe-extended pipeline as a reusable workflow: router+RECALL then design(ADR, applies learned patterns) then plan then code then agentic-qe QE+TEACH, producing features/<slug>/00-09 artifacts. MANDATORY in-process self-learning loop (Step-0 recall, apply, Step-8 teach). Hybrid checkpoints (S/M autonomous; L/XL stop-after-plan).',
-  whenToUse: 'ultracode + a feature implementation. Invoke via Workflow({scriptPath:".claude/workflows/feature-adr.js", args:{slug, description, code, tier, stopAfter}}) instead of an ad-hoc orchestration, so every feature ships with an ADR + inline agentic-qe QE + self-learning.',
+  description: 'Canonical /feature-adr --full-qe-extended pipeline as a reusable workflow: router+RECALL then design(ADR, applies learned patterns) then plan then code then agentic-qe QE+TEACH, producing features/<slug>/00-09 artifacts. MANDATORY in-process self-learning loop (Step-0 recall, apply, Step-8 teach). OPTIONAL Codex planner (args.planner=codex → Step-6 routed to codex:codex-rescue top model, graceful fallback to Claude). Hybrid checkpoints (S/M autonomous; L/XL stop-after-plan).',
+  whenToUse: 'ultracode + a feature implementation. Invoke via Workflow({scriptPath:".claude/workflows/feature-adr.js", args:{slug, description, code, tier, stopAfter, planner}}) instead of an ad-hoc orchestration, so every feature ships with an ADR + inline agentic-qe QE + self-learning.',
   phases: [
     { title: 'Router', detail: 'Step 0 - classify + self-learning recall' },
     { title: 'Design', detail: 'Steps 1-5 - requirements, ADR, QCSD, architecture (tier-gated)' },
@@ -58,14 +58,32 @@ if (isMplus) {
 }
 const design = await parallel(designThunks)
 
-// Step 6: Plan
+// Step 6: Plan — optionally routed to Codex's top model (opt-in via args.planner='codex').
+// The user opts in at pre-flight ('use the top Codex model for planning?'); we route the Plan step to
+// the codex:codex-rescue runtime and GRACEFULLY FALL BACK to the default (Claude) planner if Codex is
+// unavailable/errors — the pipeline never blocks on Codex.
 phase('Plan')
-const plan = await agent('Step 6 (SPARC-GOAP implementation plan) of /feature-adr for "' + DESC + '" (' + SLUG + ', tier ' + tier + '). Given the requirements + ADR + architecture in ' + FDIR + ', decompose into milestones + concrete tasks with success metrics. Write ' + FDIR + '/06_implementation_plan.md. Return wrote[] + summary.', { label: 'plan', phase: 'Plan', schema: ARTIFACT })
+const PLANNER = (A.planner === 'codex') ? 'codex' : 'claude'
+const planPrompt = 'Step 6 (SPARC-GOAP implementation plan) of /feature-adr for "' + DESC + '" (' + SLUG + ', tier ' + tier + '). Given the requirements + ADR + architecture in ' + FDIR + ', decompose into milestones + concrete tasks with success metrics. Write ' + FDIR + '/06_implementation_plan.md. Return wrote[] + summary.'
+let plan = null
+if (PLANNER === 'codex') {
+  const codexPlan = await agent(planPrompt, { label: 'plan:codex', phase: 'Plan', agentType: 'codex:codex-rescue' })
+  if (codexPlan) {
+    plan = { wrote: [FDIR + '/06_implementation_plan.md'], summary: String(codexPlan).slice(0, 500), planner: 'codex' }
+    log('Plan: Codex (top model)')
+  } else {
+    log('Plan: Codex unavailable — falling back to the default planner')
+  }
+}
+if (plan === null) {
+  const claudePlan = await agent(planPrompt, { label: 'plan', phase: 'Plan', schema: ARTIFACT })
+  plan = claudePlan ? { wrote: claudePlan.wrote, summary: claudePlan.summary, planner: PLANNER === 'codex' ? 'claude-fallback' : 'claude' } : null
+}
 
 // Hybrid checkpoint for L/XL
 const stopHere = STOP_AFTER === 'plan' || (isLplus && STOP_AFTER !== 'none')
 if (stopHere) {
-  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, plan: (plan ? plan.summary : null), note: 'L/XL checkpoint - review the ADR + plan, then re-invoke with args.stopAfter="none" to implement + QE.' }
+  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, planner: (plan ? plan.planner : null), plan: (plan ? plan.summary : null), note: 'L/XL checkpoint - review the ADR + plan, then re-invoke with args.stopAfter="none" to implement + QE.' }
 }
 
 // Step 7: Code
@@ -100,6 +118,7 @@ return {
   codeTestsAdequate: qe ? qe.codeTestsAdequate : null,
   docTestsPresent: qe ? qe.docTestsPresent : null,
   fleetQE: fleet,
+  plannerUsed: plan ? plan.planner : null,
   selfLearning: 'recall@Step0 + teach@Step8 (mandatory)',
   promiseTags: tags,
 }