@dzhechkov/skills-feature-adr 1.3.8 → 1.3.10

package/README.md

@@ -4,7 +4,7 @@
 
 An 11-step, complexity-routed pipeline that makes an AI coding agent build a feature the way a
 disciplined engineering team does: **spec first, code last.** Every phase emits a durable,
-versioned, human-approved **specification artifact** (`00_…`–`08_…`), and code is *generated from
+versioned, human-approved **specification artifact** (`00_…`–`09_…`), and code is *generated from
 the frozen spec* — not reverse-documented after the fact. Scales from a 3-file config change to a
 cross-cutting 30+ file refactor via a Complexity Router (S/M/L/XL). Integrates 15 skills from
 [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe) for quality engineering. Part of
@@ -14,7 +14,7 @@ the [Keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium) ecosystem.
 > onboarding doc for free, every decision captured as an ADR, and machine-checked back against the
 > code by the QE phase. See **[Spec-Driven Development](#spec-driven-development-sdd)** below.
 >
-> 👉 **Onboarding a team? Start here:** [**Feature ADR — Team Onboarding**](https://unpkg.com/@dzhechkov/skills-feature-adr/docs/team-onboarding.md) — a single read-top-to-bottom playbook (install → first feature → SDD mechanics → model routing incl. Fable → self-learning layers → team PR workflow → FAQ). It also ships **inside this package** at `node_modules/@dzhechkov/skills-feature-adr/docs/team-onboarding.md`, so every install has it locally.
+> 👉 **Onboarding a team? Start here:** [**Feature ADR — Team Onboarding**](https://github.com/djd1m/dz-skill-bundles/blob/main/docs/feature-adr-team-onboarding.md) — a single read-top-to-bottom playbook (install → first feature → SDD mechanics → model routing incl. Fable → self-learning layers → team PR workflow → FAQ). It also ships **inside this package** at `node_modules/@dzhechkov/skills-feature-adr/docs/team-onboarding.md` ([raw copy on unpkg](https://unpkg.com/@dzhechkov/skills-feature-adr/docs/team-onboarding.md)), so every install has it locally.
 
 ---
 
@@ -76,13 +76,13 @@ npx @dzhechkov/skills-feature-adr doctor             # Health check
 ## Feature ADR Pipeline
 
 ```
-Step 0        Step 1          Step 2       Step 3     Step 4
-COMPLEXITY → REQUIREMENTS → RESEARCH  →   ADR    →   DDD
-  ROUTER                   (L/XL only)  (M+ only)  (L/XL only)
+Step 0        Step 1          Step 2       Step 3      Step 3.5      Step 4
+COMPLEXITY → REQUIREMENTS → RESEARCH  →   ADR    →  QCSD SWARM  →   DDD
+  ROUTER                   (L/XL only)  (M+ only)   (M+ only)    (L/XL only)
 
-Step 5         Step 6            Step 7     Step 8
-ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE
-(M+ only)       PLAN
+Step 5         Step 6            Step 7     Step 8     Step 9
+ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE    →  FLEET QE
+(M+ only)       PLAN                                (L/XL only)
 ```
 
 ### Usage in Claude Code
@@ -197,7 +197,7 @@ gate — not discovered in production.
 | Tier | Scope | Active Steps | Time Budget |
 |------|-------|-------------|-------------|
 | **S** | 1-3 files, 1 domain | 0→1→6→7→8 | ~15 min |
-| **M** | 4-10 files, 1-2 domains | 0→1→3→5→6→7→8 | ~45 min |
+| **M** | 4-10 files, 1-2 domains | 0→1→3→3.5→5→6→7→8 | ~45 min |
 | **L** | 11-30 files, 2-4 domains | Full pipeline with parallelism | ~2 hours |
 | **XL** | 30+ files, cross-cutting | Full DAG + multi-agent swarm | ~4+ hours |
 
@@ -461,9 +461,10 @@ npx @dzhechkov/skills-feature-adr init     # Feature development
 
 ## Links
 
-- **Team Onboarding playbook (public):** [unpkg.com/@dzhechkov/skills-feature-adr/docs/team-onboarding.md](https://unpkg.com/@dzhechkov/skills-feature-adr/docs/team-onboarding.md) — also shipped in the package at `docs/team-onboarding.md`
-- **GitHub:** [https://github.com/dzhechko/product-keysarium-2026](https://github.com/dzhechko/product-keysarium-2026)
-- **Issues:** [https://github.com/dzhechko/product-keysarium-2026/issues](https://github.com/dzhechko/product-keysarium-2026/issues)
+- **Team Onboarding playbook (public, rendered):** [dz-skill-bundles/docs/feature-adr-team-onboarding.md](https://github.com/djd1m/dz-skill-bundles/blob/main/docs/feature-adr-team-onboarding.md) — also shipped in this package at `docs/team-onboarding.md` ([raw on unpkg](https://unpkg.com/@dzhechkov/skills-feature-adr/docs/team-onboarding.md))
+- **GitHub (public docs & bundles):** [https://github.com/djd1m/dz-skill-bundles](https://github.com/djd1m/dz-skill-bundles)
+- **Issues:** [https://github.com/djd1m/dz-skill-bundles/issues](https://github.com/djd1m/dz-skill-bundles/issues)
+- *Note: the source monorepo (`djd1m/dz-harness-hub`) is private; the links above are the public entry points.*
 - **npm:** [https://www.npmjs.com/package/@dzhechkov/skills-feature-adr](https://www.npmjs.com/package/@dzhechkov/skills-feature-adr)
 - **Keysarium:** [https://www.npmjs.com/package/@dzhechkov/keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium)
 - **BTO:** [https://www.npmjs.com/package/@dzhechkov/skills-bto](https://www.npmjs.com/package/@dzhechkov/skills-bto)

package/docs/team-onboarding.md

@@ -6,7 +6,7 @@ This is the practical guide for a dev team adopting `@dzhechkov/skills-feature-a
 from zero to your first spec-driven feature, then explains the mechanics, the model routing, the
 self-learning options, and the team conventions.
 
-- 📦 npm: <https://www.npmjs.com/package/@dzhechkov/skills-feature-adr> (current: **1.3.6**)
+- 📦 npm: <https://www.npmjs.com/package/@dzhechkov/skills-feature-adr>
 - 📄 Full reference README: same npm page (this doc is the *team playbook*, not a reference dump)
 - 🧭 Deep design: `packages/@dzhechkov/skills-meta/feature-adr/SKILL.md` + its `references/`
 
@@ -15,7 +15,7 @@ self-learning options, and the team conventions.
 ## TL;DR — what & why
 
 An AI agent, left alone, jumps straight to code. Feature ADR forces the opposite: **spec first,
-code last.** Each phase emits a durable, human-approved specification artifact (`00_…`–`08_…`), and
+code last.** Each phase emits a durable, human-approved specification artifact (`00_…`–`09_…`), and
 code is *generated from the frozen spec* — then verified back against it.
 
 **Why your team should care:**
@@ -133,7 +133,7 @@ features/<feature-slug>/
 | Tier | Scope | Active steps | Budget |
 |------|-------|--------------|--------|
 | **S** | 1–3 files, 1 domain | 0→1→6→7→8 (no ADR/DDD/architecture) | ~15 min |
-| **M** | 4–10 files | 0→1→3→5→6→7→8 | ~45 min |
+| **M** | 4–10 files | 0→1→3→3.5→5→6→7→8 | ~45 min |
 | **L** | 11–30 files | Full pipeline with parallelism | ~2 h |
 | **XL** | 30+ files, cross-cutting | Full DAG + multi-agent swarm | ~4 h+ |
 
@@ -230,7 +230,7 @@ uses agentdb, and even there it's optional (lexical recall works without it).
   fixed for the run — restart if scope changes drastically mid-pipeline.
 - **"`--full-qe` did nothing extra."** `agentic-qe` isn't installed → it silently falls back to
   Reference mode with a warning. Install it (`npm i -g agentic-qe && aqe init --auto`).
-- **"Do I have to use all 9 steps?"** No — the Complexity Router picks the active subset per tier.
+- **"Do I have to use all 11 steps?"** No — the Complexity Router picks the active subset per tier.
 - **"Where's the learning stored / how do I reset it?"** Layer A: delete `.keysarium/memory/`.
   B: `.agentic-qe/`. C: `.dz/`. They're independent.
 - **"Can I change which model a step uses?"** Yes — the `Model` column is a default. See §6.

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "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.",
-  "main": "src/cli.js",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"
   },
@@ -43,9 +42,9 @@
     "url": "https://github.com/djd1m/dz-harness-hub.git",
     "directory": "packages/@dzhechkov/skills-feature-adr"
   },
-  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/skills-feature-adr#readme",
+  "homepage": "https://github.com/djd1m/dz-skill-bundles/blob/main/docs/feature-adr-team-onboarding.md",
   "bugs": {
-    "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+    "url": "https://github.com/djd1m/dz-skill-bundles/issues"
   },
   "peerDependencies": {
     "@dzhechkov/keysarium-core": "^1.0.0"

package/src/cli.js

@@ -138,24 +138,19 @@ function main() {
 
   switch (resolvedCommand) {
     case 'init':
-      require('./commands/init')(flags);
-      break;
+      return require('./commands/init')(flags);
 
     case 'update':
-      require('./commands/update')(flags);
-      break;
+      return require('./commands/update')(flags);
 
     case 'remove':
-      require('./commands/remove')(flags);
-      break;
+      return require('./commands/remove')(flags);
 
     case 'list':
-      require('./commands/list')(flags);
-      break;
+      return require('./commands/list')(flags);
 
     case 'doctor':
-      require('./commands/doctor')(flags);
-      break;
+      return require('./commands/doctor')(flags);
 
     default:
       error(`Unknown command: "${resolvedCommand}"`);
@@ -166,4 +161,11 @@ function main() {
   }
 }
 
-main();
+// Command handlers may be async — catch rejections so they never surface as
+// unhandled promise rejections (finding: un-awaited run()).
+Promise.resolve()
+  .then(() => main())
+  .catch((err) => {
+    console.error('✗ ' + (err && err.message ? err.message : err));
+    process.exit(1);
+  });

package/src/commands/doctor.js

@@ -35,15 +35,33 @@ function check(name, fn) {
 function checkFilesExist(manifest, targetDir) {
   return check('Files exist', () => {
     const files = manifest.files || [];
+    const resolvedTarget = path.resolve(targetDir);
     const missing = [];
+    const suspicious = [];
 
     for (const relPath of files) {
-      const absPath = path.join(targetDir, relPath);
+      const absPath = path.resolve(resolvedTarget, relPath);
+
+      // Manifest entries must stay inside the project — anything that
+      // resolves outside is suspicious (possible tampering), not checked.
+      if (absPath !== resolvedTarget && !absPath.startsWith(resolvedTarget + path.sep)) {
+        suspicious.push(relPath);
+        continue;
+      }
+
       if (!fileExists(absPath)) {
         missing.push(relPath);
       }
     }
 
+    if (suspicious.length > 0) {
+      return {
+        passed: false,
+        detail: `${suspicious.length} suspicious manifest entr${suspicious.length === 1 ? 'y' : 'ies'} outside the project (possible tampering): ${suspicious.slice(0, 5).join(', ')}${suspicious.length > 5 ? '...' : ''}`,
+        fix: `Inspect ${cyan(MANIFEST_FILE)} and remove entries pointing outside the project, or reinstall with ${cyan('@dzhechkov/skills-feature-adr init --force')}.`,
+      };
+    }
+
     if (missing.length === 0) {
       return {
         passed: true,
@@ -112,7 +130,7 @@ function checkSkillComplete(targetDir) {
 }
 
 function checkModulesComplete(targetDir) {
-  return check('Pipeline modules (9 steps)', () => {
+  return check('Pipeline modules (11)', () => {
     const modulesDir = path.join(targetDir, '.claude', 'skills', 'feature-adr', 'modules');
 
     if (!fileExists(modulesDir)) {
@@ -128,11 +146,13 @@ function checkModulesComplete(targetDir) {
       '01-requirements.md',
       '02-research.md',
       '03-adr.md',
+      '03.5-ideation-swarm.md',
       '04-ddd.md',
       '05-architecture.md',
       '06-implementation-plan.md',
       '07-code.md',
       '08-qe.md',
+      '09-fleet-qe.md',
     ];
 
     const missing = [];
@@ -145,7 +165,7 @@ function checkModulesComplete(targetDir) {
     if (missing.length === 0) {
       return {
         passed: true,
-        detail: `All 9 pipeline modules present`,
+        detail: `All 11 pipeline modules present`,
       };
     }
 

package/src/commands/init.js

@@ -5,7 +5,7 @@ const path = require('path');
 const {
   green, yellow, cyan, bold, dim,
   info, success, warn, error: logError, step,
-  copyDirRecursive, copyDirFiltered, fileExists, readJSON,
+  fileExists, readJSON,
   ensureDir, getRelativePaths, getRelativePathsFiltered,
   createManifest, writeManifest, getTemplatesDir,
   COMPONENTS, OPTIONAL_COMPONENTS, MANIFEST_FILE, getComponentFilter,
@@ -27,7 +27,9 @@ function showKeysariumIntegration(keysariumManifest) {
   console.log('');
   console.log(cyan('  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510'));
   console.log(cyan('  \u2502') + bold(' @dzhechkov/keysarium detected!') + '                    ' + cyan('\u2502'));
-  console.log(cyan('  \u2502') + ` Version: ${dim(keysariumManifest.version)}` + ' '.repeat(39 - keysariumManifest.version.length) + cyan('\u2502'));
+  const v = keysariumManifest.version;
+  const kv = typeof v === 'string' && v.length ? v : 'unknown';
+  console.log(cyan('  \u2502') + ` Version: ${dim(kv)}` + ' '.repeat(Math.max(0, 39 - kv.length)) + cyan('\u2502'));
   console.log(cyan('  \u2502') + ' Feature ADR integrates with existing Keysarium.   ' + cyan('\u2502'));
   console.log(cyan('  \u2502') + ' Shared: .claude/commands, rules, skills            ' + cyan('\u2502'));
   console.log(cyan('  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518'));
@@ -38,34 +40,67 @@ function showKeysariumIntegration(keysariumManifest) {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function installComponent(key, comp, templatesDir, targetDir) {
+// Copies a component file-by-file with per-file overwrite protection:
+//   - destination missing            -> write, record in `written`
+//   - destination exists + --force   -> overwrite, record in `written`
+//   - destination exists, no --force -> do NOT write, record in `preserved`
+// In dry-run mode nothing is written, but the same written/preserved
+// classification is produced.
+// 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 src = path.join(templatesDir, comp.src);
-  const dest = path.join(targetDir, comp.src);
+  const destRoot = path.join(targetDir, comp.src);
 
   if (!fileExists(src)) {
     warn(`Template source not found: ${comp.src} \u2014 skipping.`);
-    return [];
+    return { missing: true, fileCount: 0 };
   }
 
-  // Single file copy (for isFile components)
+  // Build the file list from the TEMPLATE source, never a scan of the destination — otherwise
+  // user-created files inside a component dir get adopted into the manifest and a later
+  // `remove` deletes them (finding #8).
+  let entries;
   if (comp.isFile) {
-    ensureDir(path.dirname(dest));
-    fs.copyFileSync(src, dest);
-    return [comp.src];
+    entries = [{ srcFile: src, destFile: destRoot, rel: comp.src }];
+  } else {
+    const filterFn = getComponentFilter(comp);
+    const rels = filterFn ? getRelativePathsFiltered(src, filterFn) : getRelativePaths(src);
+    entries = rels.map((rel) => ({
+      srcFile: path.join(src, rel),
+      destFile: path.join(destRoot, rel),
+      rel: path.join(comp.src, rel),
+    }));
   }
 
-  const filterFn = getComponentFilter(comp);
-
-  // Track files from the TEMPLATE source, never a scan of the destination — otherwise
-  // user-created files inside a component dir get adopted into the manifest and a later
-  // `remove` deletes them (finding #8). The filtered/plain copy still writes to dest.
-  if (filterFn) {
-    copyDirFiltered(src, dest, filterFn);
-    return getRelativePathsFiltered(src, filterFn).map((rel) => path.join(comp.src, rel));
+  for (const entry of entries) {
+    if (fileExists(entry.destFile) && !force) {
+      preserved.push(entry.rel);
+      continue;
+    }
+    if (!dryRun) {
+      ensureDir(path.dirname(entry.destFile));
+      fs.copyFileSync(entry.srcFile, entry.destFile);
+    }
+    written.push(entry.rel);
   }
 
-  copyDirRecursive(src, dest);
-  return getRelativePaths(src).map((rel) => path.join(comp.src, rel));
+  return { missing: false, fileCount: entries.length };
+}
+
+// Print the block of pre-existing files that were (or would be) preserved
+function printPreservedBlock(preserved, dryRun) {
+  console.log('');
+  const verb = dryRun ? 'would be preserved' : 'preserved';
+  warn(`${preserved.length} pre-existing file(s) ${verb} (not overwritten, not tracked by the manifest) — use --force to overwrite:`);
+  const MAX_SHOWN = 10;
+  for (const rel of preserved.slice(0, MAX_SHOWN)) {
+    console.log(`  ${yellow('⚠')} ${rel}`);
+  }
+  if (preserved.length > MAX_SHOWN) {
+    console.log(dim(`  …and ${preserved.length - MAX_SHOWN} more`));
+  }
 }
 
 // Resolve which optional component keys to install based on flags
@@ -151,40 +186,81 @@ async function run(options) {
 
   console.log('');
 
-  if (dryRun) {
-    warn('Dry run \u2014 no files were written.');
-    process.exit(0);
-  }
-
-  // ── e) Install core components ─────────────────────────────────────────
+  // ── e) Install components (classify-only when --dry-run) ────────────────
   const totalComponents = componentKeys.length + optionalKeys.length;
-  const installedFiles = [];
+  const installedFiles = [];   // files written (or would-write in dry-run)
+  const preservedFiles = [];   // pre-existing files NOT overwritten (no --force)
+  const completedKeys = [];    // component keys processed so far (for partial manifest)
+  const installedOptionalKeys = [];
   let stepNum = 0;
+  const installVerb = dryRun ? 'Checking' : 'Installing';
+
+  try {
+    for (const key of componentKeys) {
+      stepNum++;
+      const comp = COMPONENTS[key];
+      step(stepNum, totalComponents, `${installVerb} ${comp.label}...`);
+
+      installComponent(key, comp, templatesDir, targetDir, {
+        force, dryRun, written: installedFiles, preserved: preservedFiles,
+      });
+      completedKeys.push(key);
+    }
 
-  for (const key of componentKeys) {
-    stepNum++;
-    const comp = COMPONENTS[key];
-    step(stepNum, totalComponents, `Installing ${comp.label}...`);
-
-    const files = installComponent(key, comp, templatesDir, targetDir);
-    installedFiles.push(...files);
+    // ── e2) Install optional components — track which actually installed ──
+    // Components whose template source is missing report missing=true;
+    // we must NOT record them in the manifest, otherwise `update` reports
+    // "Unknown component" on subsequent runs.
+    for (const key of optionalKeys) {
+      stepNum++;
+      const comp = OPTIONAL_COMPONENTS[key];
+      step(stepNum, totalComponents, `${installVerb} ${comp.label}...`);
+
+      const res = installComponent(key, comp, templatesDir, targetDir, {
+        force, dryRun, written: installedFiles, preserved: preservedFiles,
+      });
+      if (!res.missing && res.fileCount > 0) {
+        installedOptionalKeys.push(key);
+        completedKeys.push(key);
+      }
+    }
+  } catch (err) {
+    // ── Non-atomic install recovery: record what WAS written so far ───────
+    console.log('');
+    logError(`Install failed: ${err && err.message ? err.message : err}`);
+    if (!dryRun) {
+      try {
+        const failPkg = readJSON(path.resolve(__dirname, '../../package.json'));
+        const partialManifest = createManifest(
+          failPkg ? failPkg.version : '0.0.0',
+          completedKeys,
+          installedFiles.sort()
+        );
+        partialManifest.partial = true;
+        writeManifest(targetDir, partialManifest);
+      } catch (writeErr) {
+        logError(`Could not write partial manifest: ${writeErr && writeErr.message ? writeErr.message : writeErr}`);
+      }
+      info(`Partial install recorded in ${MANIFEST_FILE} — run \`npx @dzhechkov/skills-feature-adr remove\` to clean up, or fix the cause and re-run init.`);
+    }
+    process.exit(1);
   }
 
-  // ── e2) Install optional components — track which actually installed ──
-  // Components whose template source is missing return [] from installComponent;
-  // we must NOT record them in the manifest, otherwise `update` reports
-  // "Unknown component" on subsequent runs.
-  const installedOptionalKeys = [];
-  for (const key of optionalKeys) {
-    stepNum++;
-    const comp = OPTIONAL_COMPONENTS[key];
-    step(stepNum, totalComponents, `Installing ${comp.label}...`);
-
-    const files = installComponent(key, comp, templatesDir, targetDir);
-    if (files.length > 0) {
-      installedFiles.push(...files);
-      installedOptionalKeys.push(key);
+  // ── e3) Dry-run report: same would-write / would-preserve classification ─
+  if (dryRun) {
+    console.log('');
+    info(`Dry run: ${installedFiles.length} file(s) would be written, ${preservedFiles.length} pre-existing file(s) would be preserved.`);
+    if (preservedFiles.length > 0) {
+      printPreservedBlock(preservedFiles, true);
     }
+    console.log('');
+    warn('Dry run — no files were written.');
+    process.exit(0);
+  }
+
+  if (preservedFiles.length > 0) {
+    printPreservedBlock(preservedFiles, false);
+    console.log('');
   }
 
   // ── f) Write manifest ──────────────────────────────────────────────────
@@ -238,9 +314,9 @@ async function run(options) {
 
   console.log(bold('Complexity Tiers:'));
   console.log(`  ${green('S')}  ${dim('\u2014 1-3 files, ~15 min  (Steps: 0\u21921\u21926\u21927\u21928)')}`);
-  console.log(`  ${yellow('M')}  ${dim('\u2014 4-10 files, ~45 min (Steps: 0\u21921\u21923\u21925\u21926\u21927\u21928)')}`);
-  console.log(`  ${cyan('L')}  ${dim('\u2014 11-30 files, ~2h    (Full pipeline with parallelism)')}`);
-  console.log(`  ${bold('XL')} ${dim('\u2014 30+ files, ~4h+     (Full DAG + multi-agent swarm)')}`);
+  console.log(`  ${yellow('M')}  ${dim('\u2014 4-10 files, ~45 min (Steps: 0\u21921\u21923\u21923.5\u21925\u21926\u21927\u21928)')}`);
+  console.log(`  ${cyan('L')}  ${dim('\u2014 11-30 files, ~2h    (Steps: 0\u21921\u21922\u21923\u21923.5\u21924\u21925\u21926\u21927\u21928\u21929)')}`);
+  console.log(`  ${bold('XL')} ${dim('\u2014 30+ files, ~4h+     (Full DAG with parallelism + fleet QE)')}`);
   console.log('');
 
   if (!withLearning && !knowledgeExtractor && !keysariumDetected) {

package/src/commands/remove.js

@@ -43,8 +43,11 @@ function removeFile(filePath) {
 
 function removeEmptyDirs(dirPath, stopDir) {
   try {
-    let current = dirPath;
-    while (current !== stopDir && current !== path.dirname(current)) {
+    const root = path.resolve(stopDir);
+    let current = path.resolve(dirPath);
+
+    // Containment-based loop: never stat/rmdir/climb outside the project root
+    while (current !== root && current.startsWith(root + path.sep)) {
       if (!fileExists(current)) {
         current = path.dirname(current);
         continue;
@@ -66,12 +69,57 @@ function removeEmptyDirs(dirPath, stopDir) {
   }
 }
 
+// Directories shared with @dzhechkov/keysarium — never delete their files
+// when keysarium is installed in the same project.
+const KEYSARIUM_SHARED_DIRS = [
+  ['.claude', 'skills', 'explore'],
+  ['.claude', 'skills', 'problem-solver-enhanced'],
+  ['.claude', 'skills', 'frontend-design'],
+];
+
+function isKeysariumShared(relParts) {
+  return KEYSARIUM_SHARED_DIRS.some(
+    (dir) => relParts.length > dir.length && dir.every((seg, i) => relParts[i] === seg)
+  );
+}
+
+// Classify a manifest entry:
+//   'outside' — resolves outside the project root (possible tampering)
+//   'shared'  — lives in a keysarium-shared directory (preserve)
+//   'ok'      — safe to remove
+function classifyManifestEntry(relPath, resolvedTarget, keysariumDetected) {
+  const absPath = path.resolve(resolvedTarget, relPath);
+
+  if (absPath !== resolvedTarget && !absPath.startsWith(resolvedTarget + path.sep)) {
+    return { absPath, kind: 'outside' };
+  }
+
+  if (keysariumDetected) {
+    const relParts = path.relative(resolvedTarget, absPath).split(path.sep);
+    if (isKeysariumShared(relParts)) {
+      return { absPath, kind: 'shared' };
+    }
+  }
+
+  return { absPath, kind: 'ok' };
+}
+
+function printOutsideWarning(outsideEntries) {
+  console.log(
+    `  ${yellow('⚠')} ${outsideEntries.length} manifest entr${outsideEntries.length === 1 ? 'y' : 'ies'} outside the project ${outsideEntries.length === 1 ? 'was' : 'were'} skipped (possible tampering):`
+  );
+  for (const p of outsideEntries) {
+    console.log(`    ${dim(p)}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main command
 // ---------------------------------------------------------------------------
 
 async function run(options) {
   const { force, dryRun, targetDir } = options;
+  const resolvedTarget = path.resolve(targetDir);
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Read manifest ──────────────────────────────────────────────────
@@ -105,20 +153,35 @@ async function run(options) {
   console.log('');
 
   const keysariumPath = path.join(targetDir, '.keysarium.json');
-  if (fileExists(keysariumPath)) {
+  const keysariumDetected = fileExists(keysariumPath);
+  if (keysariumDetected) {
     info('@dzhechkov/keysarium detected \u2014 shared directories will be preserved.');
   }
 
   if (dryRun) {
     console.log(bold('Files to be removed:'));
+    const outsideDry = [];
     for (const relPath of files) {
-      const absPath = path.join(targetDir, relPath);
+      const { absPath, kind } = classifyManifestEntry(relPath, resolvedTarget, keysariumDetected);
+      if (kind === 'outside') {
+        outsideDry.push(relPath);
+        console.log(`  ${yellow('- OUT')}  ${relPath}`);
+        continue;
+      }
+      if (kind === 'shared') {
+        console.log(`  ${dim('- KEEP')} ${relPath} ${dim('(shared with Keysarium)')}`);
+        continue;
+      }
       const exists = fileExists(absPath);
       const marker = exists ? red('- DEL') : dim('- N/A');
       console.log(`  ${marker}  ${relPath}`);
     }
     console.log(`  ${red('- DEL')}  ${MANIFEST_FILE}`);
     console.log('');
+    if (outsideDry.length > 0) {
+      printOutsideWarning(outsideDry);
+      console.log('');
+    }
     warn('Dry run \u2014 no files were removed.');
     process.exit(0);
   }
@@ -138,11 +201,25 @@ async function run(options) {
   // ── d) Remove files ───────────────────────────────────────────────────
   let removedCount = 0;
   let skippedCount = 0;
+  let preservedCount = 0;
+  const outsideEntries = [];
   const dirsToCheck = new Set();
 
   for (let i = 0; i < files.length; i++) {
     const relPath = files[i];
-    const absPath = path.join(targetDir, relPath);
+    const { absPath, kind } = classifyManifestEntry(relPath, resolvedTarget, keysariumDetected);
+
+    if (kind === 'outside') {
+      outsideEntries.push(relPath);
+      step(i + 1, files.length, `Skipping ${relPath} (outside project)`);
+      continue;
+    }
+
+    if (kind === 'shared') {
+      preservedCount++;
+      step(i + 1, files.length, `Preserving ${relPath} (shared with Keysarium)`);
+      continue;
+    }
 
     step(i + 1, files.length, `Removing ${relPath}`);
 
@@ -154,10 +231,12 @@ async function run(options) {
     }
   }
 
-  // Remove empty directories (bottom-up), only feature-adr-exclusive ones
+  // Remove empty directories (bottom-up), only feature-adr-exclusive ones.
+  // dirsToCheck contains only parents of files actually deleted, so preserved
+  // (keysarium-shared) directories are never pruned.
   const sortedDirs = Array.from(dirsToCheck).sort((a, b) => b.length - a.length);
   for (const dir of sortedDirs) {
-    removeEmptyDirs(dir, targetDir);
+    removeEmptyDirs(dir, resolvedTarget);
   }
 
   // ── e) Remove manifest ────────────────────────────────────────────────
@@ -168,9 +247,15 @@ async function run(options) {
   console.log('');
   success(bold('Feature ADR skill pack removal complete!'));
   console.log(`  ${green('\u2713')} ${removedCount} file(s) removed`);
+  if (preservedCount > 0) {
+    console.log(`  ${green('\u2713')} preserved (shared with Keysarium): ${preservedCount} file(s)`);
+  }
   if (skippedCount > 0) {
     console.log(`  ${dim('-')} ${skippedCount} file(s) already missing (skipped)`);
   }
+  if (outsideEntries.length > 0) {
+    printOutsideWarning(outsideEntries);
+  }
   console.log('');
   info(`To reinstall, run: ${cyan('@dzhechkov/skills-feature-adr init')}`);
   console.log('');

package/src/commands/update.js

@@ -16,7 +16,7 @@ const {
 // ---------------------------------------------------------------------------
 
 async function run(options) {
-  const { dryRun, targetDir } = options;
+  const { dryRun, force, targetDir } = options;
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Read existing manifest ─────────────────────────────────────────
@@ -53,6 +53,10 @@ async function run(options) {
   let totalModified = 0;
   let totalUnchanged = 0;
   const filesToCopy = [];
+  // Files the user has locally modified. These are markdown prompt files users
+  // are expected to tune, so by default we KEEP them (never clobber). Only
+  // --force overwrites them, and then only after writing a .bak sibling.
+  const keptModified = [];
 
   for (const key of installedKeys) {
     // Optional components (--with-learning / --knowledge-extractor) live in
@@ -73,6 +77,28 @@ async function run(options) {
       continue;
     }
 
+    // Single-file components (--with-learning / --knowledge-extractor extras like
+    // lib/memory-protocol.md): diffFiles/getRelativePaths readdir a DIRECTORY and
+    // cannot handle them \u2014 without this branch, a deleted learning file is never
+    // detected ("Everything is up to date!" while doctor flags it missing).
+    if (comp.isFile) {
+      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 {
+          keptModified.push(entry);
+        }
+      } else {
+        totalUnchanged++;
+      }
+      continue;
+    }
+
     const filterFn = getComponentFilter(comp);
     const diff = diffFiles(srcBase, destBase, filterFn);
 
@@ -87,13 +113,18 @@ async function run(options) {
     }
 
     for (const rel of diff.modified) {
-      filesToCopy.push({
+      const entry = {
         src: path.join(srcBase, rel),
         dest: path.join(destBase, rel),
         status: 'modified',
         relPath: path.join(comp.src, rel),
-      });
-      totalModified++;
+      };
+      if (force) {
+        filesToCopy.push(entry);
+        totalModified++;
+      } else {
+        keptModified.push(entry);
+      }
     }
 
     totalUnchanged += diff.unchanged.length;
@@ -103,11 +134,26 @@ async function run(options) {
   info(bold('Update summary:'));
   console.log(`  ${green('+')} ${totalAdded} file(s) to add`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) to update`);
+  if (keptModified.length > 0) {
+    console.log(`  ${yellow('\u26a0')} ${keptModified.length} file(s) locally modified, kept`);
+  }
   console.log(`  ${dim('=')} ${totalUnchanged} file(s) unchanged`);
   console.log('');
 
+  if (keptModified.length > 0) {
+    console.log(yellow('\u26a0') + ' ' + bold('locally modified, kept (use --force to overwrite):'));
+    for (const f of keptModified) {
+      console.log(`  ${yellow('~ KEEP')} ${f.relPath}`);
+    }
+    console.log('');
+  }
+
   if (totalAdded === 0 && totalModified === 0) {
-    success('Everything is up to date!');
+    if (keptModified.length > 0) {
+      success('No files to update \u2014 locally modified file(s) kept.');
+    } else {
+      success('Everything is up to date!');
+    }
     process.exit(0);
   }
 
@@ -115,7 +161,8 @@ async function run(options) {
     console.log(bold('Files to be changed:'));
     for (const f of filesToCopy) {
       const marker = f.status === 'added' ? green('+ ADD') : yellow('~ MOD');
-      console.log(`  ${marker}  ${f.relPath}`);
+      const note = f.status === 'modified' ? dim(' (will back up to .bak)') : '';
+      console.log(`  ${marker}  ${f.relPath}${note}`);
     }
     console.log('');
     warn('Dry run \u2014 no files were written.');
@@ -129,11 +176,18 @@ async function run(options) {
     step(i + 1, filesToCopy.length, `${label} ${f.relPath}`);
 
     ensureDir(path.dirname(f.dest));
+    // --force on a locally modified file: preserve the user's version as a
+    // sibling .bak before overwriting.
+    if (f.status === 'modified' && fileExists(f.dest)) {
+      fs.copyFileSync(f.dest, `${f.dest}.bak`);
+      console.log(`         ${dim(`backed up to ${f.relPath}.bak`)}`);
+    }
     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;
@@ -142,12 +196,31 @@ async function run(options) {
     const destPath = path.join(targetDir, comp.src);
     const filterFn = getComponentFilter(comp);
 
-    // Record from the TEMPLATE source, not a dest scan, so user files aren't adopted.
-    const scanBase = fileExists(srcPath) ? srcPath : destPath;
+    // 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)) {
+      const kept = prevFiles.filter(
+        (rel) => rel === comp.src || rel.startsWith(comp.src + path.sep)
+      );
+      allFiles.push(...kept);
+      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(comp.src);
+      continue;
+    }
+
     if (fileExists(destPath)) {
       const paths = filterFn
-        ? getRelativePathsFiltered(scanBase, filterFn)
-        : getRelativePaths(scanBase);
+        ? getRelativePathsFiltered(srcPath, filterFn)
+        : getRelativePaths(srcPath);
       allFiles.push(...paths.map((rel) => path.join(comp.src, rel)));
     }
   }
@@ -164,6 +237,9 @@ async function run(options) {
   success(bold('Update complete!'));
   console.log(`  ${green('+')} ${totalAdded} file(s) added`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) updated`);
+  if (keptModified.length > 0) {
+    console.log(`  ${yellow('⚠')} ${keptModified.length} file(s) locally modified, kept`);
+  }
   console.log(`  ${dim('=')} ${totalUnchanged} file(s) unchanged`);
   console.log('');