@dzhechkov/p-replicator 1.3.0 → 1.5.2

package/README.md

@@ -4,6 +4,14 @@
 
 Transform a product idea into a fully documented, validated, toolkit-equipped project ready for development.
 
+## Documentation
+
+- 🇷🇺 [Документация на русском](./README/ru/README.md)
+- 🇬🇧 [English documentation](./README/eng/README.md)
+
+Each language pack includes 7 sections: Quick start, User guide, Admin guide,
+API reference, Architecture, Troubleshooting, Changelog.
+
 ## Quick Start
 
 ```bash
@@ -19,6 +27,53 @@ claude
 
 The system walks you through 4-5 phases with interactive checkpoints. At each checkpoint you review the output and confirm before proceeding. Estimated time: 45-90 minutes for the full pipeline.
 
+### Already have technical documentation?
+
+If you already have tech specs, architecture notes, or API docs for the project,
+you can skip Phase 0 (Product Discovery) and feed your existing docs into Phase 1
+as input:
+
+```bash
+mkdir -p docs/existing
+cp your-tech-doc-*.md docs/existing/   # place your existing docs here
+
+claude
+/replicate "Use my existing docs in docs/existing/, skip Phase 0"
+```
+
+Three sub-paths are supported:
+- **A. Full pipeline** — `/replicate` reads your docs, generates the 11 SPARC docs + validation + toolkit + scaffold
+- **B. SPARC docs only** — invoke the `sparc-prd-mini` skill directly, no toolkit/scaffold
+- **C. Validation-only** — rename existing docs to SPARC slot names + invoke the `requirements-validator` skill
+
+Full recipe with caveats: see [User Guide](./README/eng/02_user_guide.md#starting-from-existing-tech-docs)
+([RU](./README/ru/02_user_guide.md#альтернативный-вход-у-вас-уже-есть-техдокументация)).
+
+### Adding features to an existing project?
+
+If you already have a working project (stack, PRD, CLAUDE.md, Specification
+defined) and want to **add new features** with the same SPARC-mini validation
+cycle that `/replicate` provides — use `/feature` (Mode 2):
+
+```bash
+cd existing-project
+npx @dzhechkov/p-replicator init      # idempotent — preserves CLAUDE.md
+claude
+/feature add-stripe-payments          # 4-phase: PLAN → VALIDATE → IMPLEMENT → REVIEW
+```
+
+`/feature` runs the same validation pipeline as `/replicate` Phase 2, scoped
+to a single feature. Same verdicts: 🟢 READY (≥70) / 🟡 CAVEATS (50-69) /
+🔴 NEEDS WORK (<50). Same retry logic. Same `brutal-honesty-review` post-implementation.
+
+Three sub-paths:
+- **A. /feature directly** — single feature, full 4-phase lifecycle
+- **B. /go auto-router** — picks /plan vs /feature based on complexity
+- **C. Direct skill invocation** — only the validation cycle, no full lifecycle
+
+Full recipe: see [User Guide](./README/eng/02_user_guide.md#feature-workflow-in-an-existing-project-mode-2)
+([RU](./README/ru/02_user_guide.md#feature-workflow-в-существующем-проекте-mode-2)).
+
 ## What Gets Installed
 
 | Component | Count | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/p-replicator",
-  "version": "1.3.0",
+  "version": "1.5.2",
   "description": "P-Replicator — Claude Code toolkit for AI-assisted product development (Vibe Coding). Full /replicate pipeline, 10 modular skills (194K+ chars), /harvest knowledge extraction, swarm agents, quality gates, security patterns, cross-project learning.",
   "main": "src/cli.js",
   "bin": {
@@ -12,7 +12,12 @@
     "templates/"
   ],
   "scripts": {
-    "test": "node bin/cli.js doctor",
+    "test": "node --test tests/unit/utils.test.js tests/e2e/lifecycle.test.js tests/snapshot/templates.test.js",
+    "test:unit": "node --test tests/unit/utils.test.js",
+    "test:e2e": "node --test tests/e2e/lifecycle.test.js",
+    "test:snapshot": "node --test tests/snapshot/templates.test.js",
+    "test:doctor": "node bin/cli.js doctor",
+    "snapshot:baseline": "node tests/snapshot/update-baseline.js",
     "prepublishOnly": "node scripts/sync-templates.js"
   },
   "keywords": [

package/src/cli.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { bold, cyan, dim, green, yellow, error } = require('./utils');
+const { bold, cyan, dim, green, yellow, error, COMPONENTS } = require('./utils');
 
 // ---------------------------------------------------------------------------
 // Banner
@@ -33,11 +33,13 @@ function showHelp() {
   console.log('  ' + green('update') + '    Update to latest version');
   console.log('  ' + green('remove') + '    Remove P-Replicator from project');
   console.log('  ' + green('list') + '      List installed components');
-  console.log('  ' + green('doctor') + '    Check installation health');
+  console.log('  ' + green('doctor') + '    Check installation health (pre-shipped artifacts)');
+  console.log('  ' + green('verify') + '    Verify pre-shipped + post-/replicate artifacts');
   console.log('');
   console.log(bold('Options:'));
   console.log('  ' + yellow('--force') + '      Overwrite existing files without prompting');
   console.log('  ' + yellow('--dry-run') + '    Show what would be done without making changes');
+  console.log('  ' + yellow('--reset-settings') + ' Force-overwrite settings.json (default: merge with user customizations)');
   console.log('  ' + yellow('--help, -h') + '   Show this help message');
   console.log('  ' + yellow('--version, -v') + ' Show version number');
   console.log('');
@@ -47,14 +49,21 @@ function showHelp() {
   console.log(dim('  $ ') + 'npx @dzhechkov/p-replicator update --dry-run');
   console.log(dim('  $ ') + 'npx @dzhechkov/p-replicator doctor');
   console.log('');
+  // Counts derived from utils.COMPONENTS.items (SSOT) — fixes prior "1 rule" drift.
+  const c = {
+    skills:   Object.keys(COMPONENTS.skills.items).length,
+    commands: Object.keys(COMPONENTS.commands.items).length,
+    agents:   Object.keys(COMPONENTS.agents.items).length,
+    rules:    Object.keys(COMPONENTS.rules.items).length,
+  };
   console.log(bold('What gets installed:'));
-  console.log('  10 skills      SPARC docs, research, problem-solving, validation, review,');
+  console.log(`  ${c.skills} skills      SPARC docs, research, problem-solving, validation, review,`);
   console.log('                 reverse engineering, toolkit generation, pipeline forge,');
   console.log('                 knowledge extraction, task exploration');
-  console.log('  2 commands     /replicate (full pipeline), /harvest (knowledge extraction)');
-  console.log('  4 agents       replicate-coordinator, product-discoverer, doc-validator,');
+  console.log(`  ${c.commands} commands     /replicate (full pipeline), /harvest (knowledge extraction)`);
+  console.log(`  ${c.agents} agents       replicate-coordinator, product-discoverer, doc-validator,`);
   console.log('                 harvest-coordinator');
-  console.log('  1 rule         replicate-pipeline (phase constraints)');
+  console.log(`  ${c.rules} rule${c.rules === 1 ? '' : 's'}        replicate-pipeline, skill-interface-protocol`);
   console.log('');
   console.log(bold('After installation:'));
   console.log('  1. Open ' + cyan('Claude Code') + ' in this directory');
@@ -75,6 +84,7 @@ function parseArgs(argv) {
   const flags = {
     force: false,
     dryRun: false,
+    resetSettings: false,
     targetDir: process.cwd(),
   };
 
@@ -88,6 +98,9 @@ function parseArgs(argv) {
       case '--dry-run':
         flags.dryRun = true;
         break;
+      case '--reset-settings':
+        flags.resetSettings = true;
+        break;
       case '--help':
       case '-h':
         command = 'help';
@@ -148,6 +161,10 @@ function main() {
       require('./commands/doctor')(flags);
       break;
 
+    case 'verify':
+      require('./commands/verify')(flags);
+      break;
+
     default:
       error(`Unknown command: "${resolvedCommand}"`);
       console.log('');

package/src/commands/doctor.js

@@ -2,40 +2,22 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 const {
   green, red, yellow, cyan, bold, dim,
   info, success, warn, error: logError,
   readManifest, fileExists,
-  MANIFEST_FILE,
+  MANIFEST_FILE, COMPONENTS,
 } = require('../utils');
 
 // ---------------------------------------------------------------------------
-// Expected components
+// Expected components — derived from utils.COMPONENTS.items (SSOT)
 // ---------------------------------------------------------------------------
 
-const EXPECTED_SKILLS = [
-  'explore',
-  'sparc-prd-mini',
-  'goap-research-ed25519',
-  'problem-solver-enhanced',
-  'requirements-validator',
-  'brutal-honesty-review',
-  'cc-toolkit-generator-enhanced',
-  'reverse-engineering-unicorn',
-  'pipeline-forge',
-  'knowledge-extractor',
-];
-
-const EXPECTED_COMMANDS = ['replicate', 'harvest'];
-
-const EXPECTED_AGENTS = [
-  'replicate-coordinator',
-  'product-discoverer',
-  'doc-validator',
-  'harvest-coordinator',
-];
-
-const EXPECTED_RULES = ['replicate-pipeline', 'skill-interface-protocol'];
+const EXPECTED_SKILLS   = Object.keys(COMPONENTS.skills.items);
+const EXPECTED_COMMANDS = Object.keys(COMPONENTS.commands.items);
+const EXPECTED_AGENTS   = Object.keys(COMPONENTS.agents.items);
+const EXPECTED_RULES    = Object.keys(COMPONENTS.rules.items);
 
 function run(options) {
   const { targetDir } = options;
@@ -74,7 +56,7 @@ function run(options) {
   console.log('');
 
   // ── 3) Skills ───────────────────────────────────────────────────────────
-  console.log(bold('Skills (expected 10):'));
+  console.log(bold(`Skills (expected ${EXPECTED_SKILLS.length}):`));
   for (const skill of EXPECTED_SKILLS) {
     const skillPath = path.join(claudeDir, 'skills', skill, 'SKILL.md');
     if (fileExists(skillPath)) {
@@ -86,7 +68,7 @@ function run(options) {
   console.log('');
 
   // ── 4) Commands ─────────────────────────────────────────────────────────
-  console.log(bold('Commands (expected 2):'));
+  console.log(bold(`Commands (expected ${EXPECTED_COMMANDS.length}):`));
   for (const cmd of EXPECTED_COMMANDS) {
     const cmdPath = path.join(claudeDir, 'commands', `${cmd}.md`);
     if (fileExists(cmdPath)) {
@@ -98,7 +80,7 @@ function run(options) {
   console.log('');
 
   // ── 5) Agents ───────────────────────────────────────────────────────────
-  console.log(bold('Agents (expected 4):'));
+  console.log(bold(`Agents (expected ${EXPECTED_AGENTS.length}):`));
   for (const agent of EXPECTED_AGENTS) {
     const agentPath = path.join(claudeDir, 'agents', `${agent}.md`);
     if (fileExists(agentPath)) {
@@ -110,7 +92,7 @@ function run(options) {
   console.log('');
 
   // ── 6) Rules ────────────────────────────────────────────────────────────
-  console.log(bold('Rules (expected 2):'));
+  console.log(bold(`Rules (expected ${EXPECTED_RULES.length}):`));
   for (const rule of EXPECTED_RULES) {
     const rulePath = path.join(claudeDir, 'rules', `${rule}.md`);
     if (fileExists(rulePath)) {
@@ -121,6 +103,41 @@ function run(options) {
   }
   console.log('');
 
+  // ── 6b) Settings (hooks config) ─────────────────────────────────────────
+  console.log(bold('Hooks (settings.json):'));
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  if (fileExists(settingsPath)) {
+    pass('settings.json');
+  } else {
+    fail('settings.json — missing (SessionStart + Stop hooks not configured)');
+  }
+  console.log('');
+
+  // ── 6c) Hook scripts (cross-platform Node, v1.4.1+) ─────────────────────
+  if (COMPONENTS.hooks) {
+    const hookKeys = Object.keys(COMPONENTS.hooks.items);
+    console.log(bold(`Hook scripts (expected ${hookKeys.length}):`));
+    for (const hook of hookKeys) {
+      const hookPath = path.join(claudeDir, 'hooks', `${hook}.cjs`);
+      if (fileExists(hookPath)) {
+        pass(`${hook}.cjs`);
+      } else {
+        fail(`${hook}.cjs — missing (referenced by settings.json)`);
+      }
+    }
+    console.log('');
+  }
+
+  // ── 6d) Prerequisites (system tools the package relies on) ──────────────
+  console.log(bold('Prerequisites:'));
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe' });
+    pass('git on PATH');
+  } catch {
+    fail('git NOT on PATH — autocommit hooks (roadmap, insights, plans) will silently no-op');
+  }
+  console.log('');
+
   // ── 7) Keysarium integration ────────────────────────────────────────────
   console.log(bold('Integration:'));
   const keysariumManifest = path.join(targetDir, '.keysarium.json');

package/src/commands/init.js

@@ -3,11 +3,12 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  green, cyan, bold, dim,
+  green, cyan, bold, dim, yellow,
   info, success, warn, error: logError, step,
-  copyDirRecursive, fileExists, readJSON,
-  createManifest, writeManifest, getTemplatesDir, getRelativePaths,
+  copyDirRecursive, fileExists, readJSON, writeJSON, ensureDir,
+  createManifest, writeManifest, readManifest, getTemplatesDir, getRelativePaths,
   COMPONENTS, MANIFEST_FILE,
+  mergeSettingsJson, removeOrphanHooks,
 } = require('../utils');
 
 // ---------------------------------------------------------------------------
@@ -37,7 +38,7 @@ function showKeysariumIntegration(keysariumManifest) {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function installComponent(key, comp, templatesDir, targetDir) {
+function installComponent(key, comp, templatesDir, targetDir, options) {
   const src = path.join(templatesDir, comp.src);
   const dest = path.join(targetDir, comp.src);
 
@@ -46,7 +47,44 @@ function installComponent(key, comp, templatesDir, targetDir) {
     return [];
   }
 
+  // settings.json merge (v1.4.2 + v1.4.3 orphan detection): on --force, run
+  // orphan cleanup (v1.4.3) using shippedDefaults from previous manifest, then
+  // merge new template into the cleaned user settings. Use --reset-settings to
+  // force full overwrite.
+  if (
+    comp.isFile &&
+    comp.src.endsWith('.json') &&
+    fileExists(dest) &&
+    !(options && options.resetSettings)
+  ) {
+    try {
+      const tplJson = readJSON(src);
+      const existingJson = readJSON(dest);
+      const fileKey = comp.src.split(/[/\\]/).pop();
+      const oldTplJson =
+        (options && options.previousManifest && options.previousManifest.shippedDefaults &&
+         options.previousManifest.shippedDefaults[fileKey]) || null;
+
+      // v1.4.3: remove hooks that were defaults in the old shipped template
+      // but no longer exist in the new template (true orphans).
+      const cleaned = removeOrphanHooks(existingJson, oldTplJson, tplJson);
+      const mergedJson = mergeSettingsJson(cleaned, tplJson);
+      writeJSON(dest, mergedJson);
+      info(`Merged user customizations into ${comp.src} ${dim('(use --reset-settings to overwrite)')}`);
+      return [comp.src];
+    } catch (err) {
+      warn(`settings merge failed (${err.message}) \u2014 falling back to overwrite`);
+    }
+  }
+
   copyDirRecursive(src, dest);
+
+  // Single-file components (e.g., settings.json): manifest tracks the file directly,
+  // since getRelativePaths(file) returns [] (it expects a directory).
+  if (fs.statSync(src).isFile()) {
+    return [comp.src];
+  }
+
   return getRelativePaths(dest).map((rel) => path.join(comp.src, rel));
 }
 
@@ -55,10 +93,13 @@ function installComponent(key, comp, templatesDir, targetDir) {
 // ---------------------------------------------------------------------------
 
 function run(options) {
-  const { force, dryRun, targetDir } = options;
+  const { force, dryRun, targetDir, resetSettings } = options;
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Check for existing installation ──────────────────────────────────
+  // Read previous manifest BEFORE we overwrite it. Used by installComponent
+  // for orphan-hook detection in settings.json (v1.4.3).
+  const previousManifest = readManifest(targetDir);
   if (fileExists(manifestPath)) {
     if (!force) {
       warn('P-Replicator is already installed in this directory.');
@@ -75,7 +116,11 @@ function run(options) {
   }
 
   // ── c) Show plan ────────────────────────────────────────────────────────
-  const componentKeys = Object.keys(COMPONENTS);
+  // Install only pre-shipped groups; project-generated groups have no `src` —
+  // they describe artifacts created by /replicate at a later phase.
+  const componentKeys = Object.keys(COMPONENTS).filter(
+    (k) => COMPONENTS[k].kind === 'pre-shipped'
+  );
   const templatesDir = getTemplatesDir();
 
   console.log('');
@@ -103,7 +148,7 @@ function run(options) {
     const comp = COMPONENTS[key];
     step(i + 1, totalComponents, `Installing ${comp.label}...`);
 
-    const files = installComponent(key, comp, templatesDir, targetDir);
+    const files = installComponent(key, comp, templatesDir, targetDir, { resetSettings, previousManifest });
     installedFiles.push(...files);
   }
 
@@ -112,7 +157,15 @@ function run(options) {
   const pkg = readJSON(pkgPath);
   const version = pkg ? pkg.version : '0.0.0';
 
-  const manifest = createManifest(version, componentKeys, installedFiles.sort());
+  // v1.4.3: snapshot the settings.json template we just shipped, so the NEXT
+  // upgrade can detect orphan hooks (hooks we used to ship but no longer do).
+  const shippedDefaults = {};
+  const settingsTemplatePath = path.join(templatesDir, '.claude', 'settings.json');
+  if (fileExists(settingsTemplatePath)) {
+    const tplContent = readJSON(settingsTemplatePath);
+    if (tplContent) shippedDefaults['settings.json'] = tplContent;
+  }
+  const manifest = createManifest(version, componentKeys, installedFiles.sort(), shippedDefaults);
   writeManifest(targetDir, manifest);
   info(`Created ${MANIFEST_FILE} manifest`);
 

package/src/commands/list.js

@@ -6,37 +6,16 @@ const {
   green, cyan, bold, dim, yellow,
   info, warn,
   readManifest, fileExists,
-  MANIFEST_FILE,
+  MANIFEST_FILE, COMPONENTS,
 } = require('../utils');
 
 // ---------------------------------------------------------------------------
-// Skill details for rich listing
+// Display details \u2014 pulled from utils.COMPONENTS.items (SSOT)
 // ---------------------------------------------------------------------------
 
-const SKILL_DETAILS = {
-  'explore':                       'Socratic task clarification',
-  'sparc-prd-mini':                'SPARC documentation generator (11 docs)',
-  'goap-research-ed25519':         'Verified research with Ed25519 anti-hallucination',
-  'problem-solver-enhanced':       'First principles + TRIZ (9 modules)',
-  'requirements-validator':        'INVEST/SMART validation + BDD scenarios',
-  'brutal-honesty-review':         'Unvarnished technical criticism',
-  'cc-toolkit-generator-enhanced': 'Modular toolkit generator (9 modules, ~165K chars)',
-  'reverse-engineering-unicorn':   'Company reverse engineering + playbook',
-  'pipeline-forge':                'Meta-skill: build AI pipelines from patterns',
-  'knowledge-extractor':           'Extract reusable knowledge from projects',
-};
-
-const COMMAND_DETAILS = {
-  'replicate': 'Full pipeline: idea \u2192 validated docs \u2192 toolkit',
-  'harvest':   'Knowledge extraction from projects',
-};
-
-const AGENT_DETAILS = {
-  'replicate-coordinator': 'Pipeline orchestration (Phases 0-4)',
-  'product-discoverer':    'Market research (Phase 0)',
-  'doc-validator':         'Documentation validation swarm (Phase 2)',
-  'harvest-coordinator':   'Knowledge extraction swarm',
-};
+const SKILL_DETAILS   = COMPONENTS.skills.items;
+const COMMAND_DETAILS = COMPONENTS.commands.items;
+const AGENT_DETAILS   = COMPONENTS.agents.items;
 
 function run(options) {
   const { targetDir } = options;

package/src/commands/update.js

@@ -1,17 +1,19 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const {
   green, yellow, cyan, bold, dim,
   info, success, warn, error: logError, step,
-  copyDirRecursive, fileExists, readJSON,
+  copyDirRecursive, fileExists, readJSON, writeJSON,
   diffFiles, getRelativePaths,
   readManifest, writeManifest, createManifest, getTemplatesDir,
   COMPONENTS, MANIFEST_FILE,
+  mergeSettingsJson, removeOrphanHooks,
 } = require('../utils');
 
 function run(options) {
-  const { force, dryRun, targetDir } = options;
+  const { force, dryRun, targetDir, resetSettings } = options;
 
   // ── a) Check for existing installation ──────────────────────────────────
   const manifest = readManifest(targetDir);
@@ -75,24 +77,88 @@ function run(options) {
   }
 
   // ── d) Apply updates ───────────────────────────────────────────────────
+  // For each modified/added file: regular copy, EXCEPT settings.json — which
+  // gets the same merge + orphan-cleanup treatment as init --force (v1.4.3).
   const filesToUpdate = [...added, ...modified];
   let updated = 0;
+  const oldSettingsTpl = manifest.shippedDefaults && manifest.shippedDefaults['settings.json'];
 
   for (const rel of filesToUpdate) {
     const src = path.join(templateClaude, rel);
     const dest = path.join(projectClaude, rel);
-    copyDirRecursive(src, dest);
+    const normalized = rel.replace(/\\/g, '/');
+    const isSettings = normalized === 'settings.json' || normalized.endsWith('/settings.json');
+
+    if (isSettings && fileExists(dest) && !resetSettings) {
+      try {
+        const tplJson = readJSON(src);
+        const existingJson = readJSON(dest);
+        const cleaned = removeOrphanHooks(existingJson, oldSettingsTpl || null, tplJson);
+        const mergedJson = mergeSettingsJson(cleaned, tplJson);
+        writeJSON(dest, mergedJson);
+        info(`Merged settings.json with user customizations ${dim('(use --reset-settings to overwrite)')}`);
+      } catch (err) {
+        warn(`settings merge failed (${err.message}) — falling back to overwrite`);
+        copyDirRecursive(src, dest);
+      }
+    } else {
+      copyDirRecursive(src, dest);
+    }
     updated++;
   }
 
   // ── e) Update manifest ─────────────────────────────────────────────────
-  const allFiles = getRelativePaths(projectClaude).map((f) => '.claude/' + f);
-  const componentKeys = Object.keys(COMPONENTS);
-  const newManifest = createManifest(newVersion, componentKeys, allFiles.sort());
+  // Track ONLY files shipped by the package's templates — never walk the user's
+  // .claude/ tree. Walking projectClaude would capture project-generated files
+  // (e.g. /replicate output: start.md, feature.md, plan.md) into manifest.files,
+  // and a subsequent `remove` would then delete them, contradicting remove.js's
+  // own "project-specific files were NOT removed" guarantee.
+  const newTrackedFiles = getRelativePaths(templateClaude).map((f) => '.claude/' + f);
+  const newTrackedSet = new Set(newTrackedFiles);
+
+  // Orphan cleanup: files previously tracked by the package but no longer
+  // shipped (skill removed in a new package version, etc.). Safe to delete
+  // because they were package-owned. Project-generated files are never in the
+  // old manifest, so they are never considered orphans.
+  const oldTrackedFiles = manifest.files || [];
+  const orphans = oldTrackedFiles.filter(
+    (f) => f.startsWith('.claude/') && !newTrackedSet.has(f)
+  );
+
+  let removedOrphans = 0;
+  for (const orphan of orphans) {
+    const fullPath = path.join(targetDir, orphan);
+    if (fileExists(fullPath)) {
+      try {
+        fs.unlinkSync(fullPath);
+        removedOrphans++;
+      } catch (err) {
+        warn(`Could not remove orphan: ${orphan} (${err.message})`);
+      }
+    }
+  }
+
+  // Manifest tracks only pre-shipped groups (project-generated groups describe
+  // /replicate Phase 3 outputs, not files this package owns).
+  const componentKeys = Object.keys(COMPONENTS).filter(
+    (k) => COMPONENTS[k].kind === 'pre-shipped'
+  );
+  // v1.4.3: refresh shippedDefaults snapshot for the next upgrade to use.
+  const shippedDefaults = {};
+  const settingsTemplatePath = path.join(templateClaude, 'settings.json');
+  if (fileExists(settingsTemplatePath)) {
+    const tplContent = readJSON(settingsTemplatePath);
+    if (tplContent) shippedDefaults['settings.json'] = tplContent;
+  }
+  const newManifest = createManifest(newVersion, componentKeys, newTrackedFiles.sort(), shippedDefaults);
   writeManifest(targetDir, newManifest);
 
   console.log('');
-  success(`Updated ${updated} files to version ${bold(newVersion)}`);
+  let summary = `Updated ${updated} files to version ${bold(newVersion)}`;
+  if (removedOrphans > 0) {
+    summary += dim(` (+ ${removedOrphans} orphan${removedOrphans === 1 ? '' : 's'} removed)`);
+  }
+  success(summary);
   console.log('');
 
   process.exit(0);