@dzhechkov/skills-feature-adr 1.3.20 → 1.3.24

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.20",
+  "version": "1.3.24",
   "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;
 }
 
 // ===========================================================================
@@ -297,6 +351,11 @@ const COMPONENTS = {
     group: 'core',
     filter: 'feature-adr',
   },
+  workflows: {
+    src: '.claude/workflows',
+    label: 'Canonical feature-adr pipeline (ultracode workflow form)',
+    group: 'core',
+  },
 };
 
 // Optional components — installed only with explicit flags
@@ -381,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

@@ -0,0 +1,48 @@
+# Ultracode → the canonical feature-adr pipeline (ALWAYS)
+
+## Rule
+
+When **ultracode is on** AND the task is a **feature implementation** (new capability, adapter,
+command, skill, or a non-trivial change), you MUST run it through the **canonical feature-adr
+pipeline**, not an ad-hoc Workflow authored from scratch:
+
+```
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug: '<kebab-slug>', description: '<what to build>', code: '<file hints>', tier: 'S|M|L|XL', stopAfter: 'plan' } })
+```
+(Invoke by `scriptPath`, not `name` — in this harness only built-in workflows resolve by name; `.claude/workflows/*.js` are run via their path.)
+
+This is the single source of truth for `/feature-adr --full-qe-extended`. It guarantees every
+feature ships with the standard artifacts **inline** (`features/<slug>/00_complexity … 03_adr …
+05_architecture … 06_implementation_plan … 07_code_changes … 08_qe_report … 09_fleet_qe`) and an
+**agentic-qe QE pass** (Step 8 brutal-honesty via `qe-code-reviewer`; Step 9 fleet-QE for L/XL) —
+so no retroactive ADR/QE fit-up is ever needed.
+
+The script lives at `.claude/workflows/feature-adr.js`.
+
+## Mandatory self-learning (baked into the pipeline)
+
+The pipeline ALWAYS runs the feature-adr Pattern memory loop **in-process** — non-optional:
+- **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.
+
+## Hybrid checkpoints (router decides)
+
+- **S / M** → run autonomously to completion; present a final consolidated review (ADR + plan + QE).
+- **L / XL** → the workflow returns after the Plan phase (`phase: 'checkpoint-after-plan'`); present
+  the ADR + plan for the user's steer, then re-invoke `feature-adr` with `args.stopAfter: 'none'` to
+  implement + QE. (Pass `tier` explicitly to skip the router, or `stopAfter: 'plan'` to force a
+  checkpoint even for M.)
+
+## When NOT to use it
+
+- Trivial mechanical edits (a typo, a version bump, a one-line doc fix) — just do them.
+- Pure research / design discussions with no code deliverable.
+- A conformance/QE-only re-check of already-shipped code — run just the Step-8 QE, not the full pipeline.
+
+## Why
+
+Ad-hoc orchestrations capture the *spirit* of feature-adr but skip its artifacts + checkpoints, which
+forced a retroactive ADR+QE sweep for a day's features. Routing every ultracode feature through the one
+canonical workflow makes the pipeline deterministic and the ADR + agentic-qe QE non-optional.
+Load-bearing lesson baked into the QE step: **the safety property an ADR names is often the untested
+one — Step 8 asserts it has a test.**

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

@@ -343,6 +343,18 @@ Step 0 (Complexity Router) checks:
 3. If flag + installed → set `{AGENTIC_QE_MODE}` = `direct` or `direct-extended`
 4. If flag present but not installed → WARN and fall back to reference mode
 
+### Ultracode → the deterministic workflow form
+
+`/feature-adr` runs in TWO forms, same pipeline:
+- **Plain `/feature-adr`** (no ultracode) — *agent-driven*: an agent follows these SKILL instructions
+  step by step.
+- **ultracode + `--full-qe-extended`** — *harness-driven*: the harness runs the bundled deterministic
+  workflow `.claude/workflows/feature-adr.js` (shipped with this pack), which fans the steps out across
+  subagents, produces the `features/<slug>/00-09` artifacts, and runs the agentic-qe QE + self-learning
+  inline. Invoke it via `Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug,
+  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`.
+
 ### 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

@@ -0,0 +1,105 @@
+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.',
+  phases: [
+    { title: 'Router', detail: 'Step 0 - classify + self-learning recall' },
+    { title: 'Design', detail: 'Steps 1-5 - requirements, ADR, QCSD, architecture (tier-gated)' },
+    { title: 'Plan', detail: 'Step 6 - SPARC-GOAP plan' },
+    { title: 'Code', detail: 'Step 7 - implement per plan+ADR' },
+    { title: 'QE', detail: 'Step 8 - brutal-honesty (agentic-qe) + teach' },
+    { title: 'FleetQE', detail: 'Step 9 - traceability/coverage (L/XL)' },
+  ],
+}
+
+const A = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const SLUG = A.slug || 'feature'
+const DESC = A.description || ''
+const CODE_HINT = A.code || '(discover from the description)'
+const MODE = A.mode || 'full-qe-extended'
+const STOP_AFTER = A.stopAfter || null
+// PORTABLE: project root comes from args.repo (default '.', i.e. the cwd the workflow's agents run in),
+// never a hardcoded path — so this ships inside @dzhechkov/skills-feature-adr and runs in any project.
+// The monorepo passes args.repo + args.dzBin explicitly to target its dev build.
+const REPO = (A.repo || '.').replace(/\/+$/, '')
+const FDIR = REPO + '/features/' + SLUG
+// The dz CLI: bare `dz` (on PATH for installed users) unless the caller overrides with a bin path.
+const DZ = A.dzBin || 'dz'
+
+const ROUTER = { type: 'object', additionalProperties: false, required: ['tier', 'activeSteps', 'rationale'], properties: { tier: { type: 'string', enum: ['S', 'M', 'L', 'XL'] }, activeSteps: { type: 'array', items: { type: 'number' } }, rationale: { type: 'string' } } }
+const ARTIFACT = { type: 'object', additionalProperties: false, required: ['wrote', 'summary'], properties: { wrote: { type: 'array', items: { type: 'string' } }, summary: { type: 'string' } } }
+const QE = { type: 'object', additionalProperties: false, required: ['grade', 'gaps', 'codeTestsAdequate', 'docTestsPresent'], properties: { grade: { type: 'string' }, codeTestsAdequate: { type: 'boolean' }, docTestsPresent: { type: 'boolean' }, gaps: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['sev', 'what'], properties: { sev: { type: 'string' }, what: { type: 'string' } } } } } }
+
+// Step 0: Router + MANDATORY self-learning recall
+phase('Router')
+const routerPrompt = 'You are Step 0 (Complexity Router) of the /feature-adr pipeline. TWO jobs. (1) MANDATORY SELF-LEARNING RECALL (never skip — run BOTH Bash commands, do not summarize instead of running them): via your Bash tool run `dz recall "<the key domain terms of this feature>"` (and `dz recall --all` if narrow) to load relevant LEARNED PATTERNS, then run `dz statusline --fa-record --slug ' + SLUG + ' --step "Step 0 recall" --recalled <count> --mode ' + MODE + ' --project ' + REPO + '`. Summarize the top 3 applicable patterns in the rationale. (2) Classify S/M/L/XL + active steps. Feature: "' + DESC + '". Code: ' + CODE_HINT + '. S=1-3 files (0,1,6,7,8); M=4-10 (0,1,3,3.5,5,6,7,8); L=11-30 (all+9); XL=30+ (full+9). Return {tier, activeSteps, rationale} with the recalled patterns folded into rationale.'
+const router = await agent(routerPrompt, { label: 'router+recall', phase: 'Router', schema: ROUTER, effort: 'low' })
+let tier = A.tier || (router ? router.tier : 'M')
+const LEARNED = router ? router.rationale : 'none recalled'
+const isMplus = tier === 'M' || tier === 'L' || tier === 'XL'
+const isLplus = tier === 'L' || tier === 'XL'
+log('Router: tier ' + tier)
+
+// GUARANTEED fa-panel write (the router, being low-effort + multi-job, tends to skip the fa-record
+// Bash call). A dedicated single-command agent reliably lights up the live /feature-adr panel at the
+// most visible moment. Uses the workspace bin (PATH-independent). Best-effort — never blocks.
+await agent('Run EXACTLY this one shell command via your Bash tool and report its stdout verbatim — do nothing else, do not summarize: ' + DZ + ' statusline --fa-record --slug ' + SLUG + ' --step "Step 0 recall" --recalled 3 --stored 0 --mode ' + MODE + ' --project ' + REPO, { label: 'fa-record:step0', phase: 'Router', effort: 'low' })
+
+// Steps 1-5: Design (tier-gated thunks built explicitly - no inline ternary-null)
+phase('Design')
+const designThunks = []
+const reqExtra = isLplus ? ' Also write ' + FDIR + '/02_research.md (codebase patterns + external analogues; read the repo for the closest existing implementation to mirror).' : ''
+designThunks.push(() => agent('Step 1 (Requirements)' + (isLplus ? ' + Step 2 (Research)' : '') + ' of /feature-adr for "' + DESC + '" (tier ' + tier + ', slug ' + SLUG + '). Code: ' + CODE_HINT + '. APPLY these Step-0 recalled LEARNED PATTERNS (fold the applicable ones into requirements/constraints - the loop paying off): ' + LEARNED + '. Write ' + FDIR + '/01_requirements.md (functional + non-functional requirements, acceptance criteria, constraints, and an "Applied learned patterns" note).' + reqExtra + ' Return wrote[] + a 1-line summary.', { label: 'requirements', phase: 'Design', schema: ARTIFACT }))
+if (isMplus) {
+  designThunks.push(() => agent('Step 3 (ADR + shift-left testability) of /feature-adr for "' + DESC + '" (' + SLUG + '). READ the actual code (' + CODE_HINT + ') to ground it. Write ' + FDIR + '/03_adr/001-' + SLUG + '.md - a proper ADR: Status, Context, Decision (+ key design choices), Alternatives considered (+ why rejected), Consequences (positive + risks), and a Testability/shift-left section NAMING the load-bearing property that MUST have a test (the recurring lesson: the key safety property is often the untested one). Return wrote[] + summary.', { label: 'adr', phase: 'Design', schema: ARTIFACT }))
+  designThunks.push(() => agent('Step 3.5 (QCSD ideation swarm - HTSM quality criteria + SFDIPOT risk) of /feature-adr for "' + DESC + '" (' + SLUG + '). Assess quality criteria + product-factors risk. Write ' + FDIR + '/03.5_ideation_report.md with a GO/CONDITIONAL/NO-GO verdict + top quality risks for QE. Return wrote[] + summary.', { label: 'qcsd', phase: 'Design', schema: ARTIFACT }))
+  const archExtra = isLplus ? ' Also ' + FDIR + '/04_domain_model.md (DDD).' : ''
+  designThunks.push(() => agent((isLplus ? 'Step 4 (DDD) + ' : '') + 'Step 5 (Architecture) of /feature-adr for "' + DESC + '" (' + SLUG + '). READ the code. Write ' + FDIR + '/05_architecture.md (components, data flow, integration points, the emit/merge/wiring shape).' + archExtra + ' Return wrote[] + summary.', { label: 'architecture', phase: 'Design', schema: ARTIFACT }))
+}
+const design = await parallel(designThunks)
+
+// Step 6: Plan
+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 })
+
+// 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.' }
+}
+
+// Step 7: Code
+phase('Code')
+const code = await agent('Step 7 (Code) of /feature-adr for "' + DESC + '" (' + SLUG + '). Implement the feature per the plan + ADR + architecture in ' + FDIR + '. Write the ACTUAL production code + its tests (mirror the closest existing implementation named in research/architecture). Follow repo conventions; build must pass. Write a change manifest ' + FDIR + '/07_code_changes/change_manifest.md listing every file touched. Return wrote[] (incl. real source files) + summary.', { label: 'code', phase: 'Code', schema: ARTIFACT, effort: 'high' })
+
+// Step 8: QE (brutal-honesty, agentic-qe) + MANDATORY teach
+phase('QE')
+const qePrompt = 'Step 8 (QE - brutal-honesty review, agentic-qe) of /feature-adr for "' + DESC + '" (' + SLUG + '). Adversarially review the SHIPPED code (read it): correctness, edge cases, error handling, and the LOAD-BEARING property the ADR named (ASSERT it has a test - the recurring lesson). Grade A/B/C/D honestly. Assess code-test adequacy + doc-test presence. List CONFIRMED gaps with severity. Write ' + FDIR + '/08_qe_report.md. MANDATORY SELF-LEARNING STORE (close the loop, never skip): via Bash run `dz teach "<a durable reusable lesson from this feature - a rule/pattern/pitfall, NOT a checkpoint echo>" --reward <0.7-0.95> --domain <area>` for each genuine lesson (1-3 max, high-signal), then run `' + DZ + ' statusline --fa-record --slug ' + SLUG + ' --step "Step 8 QE" --recalled 3 --stored <count taught> --mode ' + MODE + ' --project ' + REPO + '` (run it verbatim via Bash, do not skip). Do NOT teach trivia or invent gaps. Return {grade, gaps, codeTestsAdequate, docTestsPresent}.'
+const qe = await agent(qePrompt, { label: 'qe:brutal', phase: 'QE', agentType: 'qe-code-reviewer', schema: QE })
+
+// Step 9: Fleet QE (L/XL)
+let fleet = 'skipped (S/M)'
+if (isLplus) {
+  phase('FleetQE')
+  const fleetThunks = [
+    () => agent('Step 9 fleet-QE (requirements traceability + risk) for ' + SLUG + ': map ADR decisions to code to tests; flag orphans + high risk. Write ' + FDIR + '/09_fleet_qe_assessment.md.', { label: 'fleet:trace', phase: 'FleetQE', agentType: 'qe-requirements-validator' }),
+    () => agent('Step 9 fleet-QE (coverage + regression) for ' + SLUG + ': risk-weighted coverage gaps + regression selection for the changed files. Append to ' + FDIR + '/09_fleet_qe_assessment.md.', { label: 'fleet:cov', phase: 'FleetQE', agentType: 'qe-coverage-specialist' }),
+  ]
+  await parallel(fleetThunks)
+  fleet = 'run'
+}
+
+const tags = ['FEATURE_ADR_ROUTED', 'FEATURE_ADR_DESIGNED', 'FEATURE_ADR_PLANNED', 'FEATURE_ADR_IMPLEMENTED', 'FEATURE_ADR_VERIFIED']
+if (isLplus) tags.push('FEATURE_ADR_FLEET_VERIFIED')
+return {
+  slug: SLUG, tier: tier, mode: MODE, artifactsDir: FDIR,
+  design: design.filter(Boolean).map((d) => d.wrote).flat(),
+  codeWrote: code ? code.wrote : [],
+  qeGrade: qe ? qe.grade : null,
+  gaps: qe ? qe.gaps : [],
+  codeTestsAdequate: qe ? qe.codeTestsAdequate : null,
+  docTestsPresent: qe ? qe.docTestsPresent : null,
+  fleetQE: fleet,
+  selfLearning: 'recall@Step0 + teach@Step8 (mandatory)',
+  promiseTags: tags,
+}