@dtlabs/ai-toolkit 0.10.0 → 0.11.0

package/bin/cli.js

@@ -40,9 +40,6 @@ function banner() {
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
-// User-owned config that must NEVER be copied into a destination. We only verify
-// and advise on these — copying would clobber the user's existing settings.
-const NEVER_COPY = new Set(['settings.json', 'settings.local.json']);
 
 function fileHash(filePath) {
   return crypto.createHash('md5').update(fs.readFileSync(filePath)).digest('hex');
@@ -161,12 +158,10 @@ function expandMappings(mappings) {
     if (!fs.existsSync(src)) continue;
     if (fs.statSync(src).isDirectory()) {
       for (const entry of walkDir(src)) {
-        if (NEVER_COPY.has(path.basename(entry))) continue; // never clobber user config
         const rel = path.relative(src, entry);
         files.push({ src: entry, dest: path.join(dest, rel) });
       }
     } else {
-      if (NEVER_COPY.has(path.basename(src))) continue;
       files.push({ src, dest });
     }
   }
@@ -266,10 +261,20 @@ function computeOrphans(oldFiles, newFiles) {
     .filter(f => !newSet.has(f));
 }
 
+// Timestamp used for the current install/upgrade session — set once so all orphans
+// from the same run land in the same subdirectory, making the trash auditable.
+let _trashTimestamp = null;
+function trashTimestamp() {
+  if (!_trashTimestamp) _trashTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return _trashTimestamp;
+}
+
 function moveToTrash(destRoot, relativePath) {
   const source = path.join(destRoot, relativePath);
   if (!fs.existsSync(source)) return;
-  const trashPath = path.join(destRoot, '.claude', '.ai-toolkit-trash', relativePath);
+  // Each upgrade session gets its own timestamped subdirectory so repeated upgrades
+  // never overwrite previously trashed files. The timestamp is stable for the session.
+  const trashPath = path.join(destRoot, '.claude', '.ai-toolkit-trash', trashTimestamp(), relativePath);
   ensureDir(trashPath);
   try {
     fs.renameSync(source, trashPath);
@@ -283,7 +288,7 @@ function moveToTrash(destRoot, relativePath) {
   }
 }
 
-function writeManifest(destRoot, fileList) {
+function writeManifest(destRoot, fileList, installationMode) {
   const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
   const trashDir = path.join(destRoot, '.claude', '.ai-toolkit-trash');
   const filtered = fileList.filter(rel => {
@@ -293,6 +298,7 @@ function writeManifest(destRoot, fileList) {
   const manifest = {
     version: TOOLKIT_VERSION,
     installedAt: new Date().toISOString(),
+    installationMode: installationMode,
     files: filtered.map(f => f.replace(/\\/g, '/')),
   };
   try {
@@ -305,7 +311,12 @@ function writeManifest(destRoot, fileList) {
 
 // ── install ───────────────────────────────────────────────────────────────────
 
-async function runInstall(label, mappings, force, destRoot) {
+async function runInstall(label, mappings, force, destRoot, dryRun = false, installationMode) {
+  const { getAssetCategories } = require('../lib/asset-catalog');
+  // Catalog runtime-dir prefixes (e.g. '.claude/agents/') — only these paths
+  // belong in the manifest. Documentation and CLAUDE.md are excluded.
+  const catalogPrefixes = getAssetCategories().map(c => c.runtimeDir.replace(/\\/g, '/') + '/');
+
   const files    = expandMappings(mappings);
   const entries  = categorize(files);
 
@@ -315,17 +326,26 @@ async function runInstall(label, mappings, force, destRoot) {
 
   // ── prune phase (before file copy) ───────────────────────────────────────────
   const oldManifest = readManifest(destRoot);
-  const newFileSet  = files.map(f => path.relative(destRoot, f.dest).replace(/\\/g, '/'));
-  const orphans     = computeOrphans(oldManifest.files, newFileSet);
+  const allFileSet  = files.map(f => path.relative(destRoot, f.dest).replace(/\\/g, '/'));
+  // Restrict manifest entries to catalog runtime assets only (no docs, no CLAUDE.md).
+  const newFileSet  = allFileSet.filter(rel => catalogPrefixes.some(p => rel.startsWith(p)));
+  // Filter orphans to catalog prefixes only: entries from old manifests outside catalog dirs
+  // (e.g. docs/, CLAUDE.md written by pre-hotfix installers) must never be treated as orphans.
+  const orphans     = computeOrphans(oldManifest.files, newFileSet)
+    .filter(o => catalogPrefixes.some(p => o.replace(/\\/g, '/').startsWith(p)));
 
   const existingOrphans = orphans.filter(o => fs.existsSync(path.join(destRoot, o)));
 
   if (existingOrphans.length > 0) {
     console.log();
-    console.log(`${bold('📦 Orphan cleanup')}  ${clr('gray', '→')}  ${clr('red', `${existingOrphans.length} stale file(s) found`)}`);
+    const orphanLabel = dryRun
+      ? clr('red', `${existingOrphans.length} stale file(s) would be removed`)
+      : clr('red', `${existingOrphans.length} stale file(s) found`);
+    console.log(`${bold('📦 Orphan cleanup')}  ${clr('gray', '→')}  ${orphanLabel}`);
     console.log(divider());
     for (const orphan of existingOrphans) {
-      console.log(`  ${clr('red', '∅')} ${clr('red', 'REMOVED ')}  ${orphan}`);
+      const marker = dryRun ? clr('red', 'WOULD REMOVE') : clr('red', 'REMOVED ');
+      console.log(`  ${clr('red', '∅')} ${marker}  ${orphan}`);
     }
     console.log(divider());
   }
@@ -333,40 +353,43 @@ async function runInstall(label, mappings, force, destRoot) {
   let removedCount = 0;
   let keptCount    = 0;
 
-  if (force) {
-    for (const orphan of existingOrphans) {
-      moveToTrash(destRoot, orphan);
-      removedCount++;
-      console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
-    }
-  } else {
-    for (const orphan of existingOrphans) {
-      const fullPath = path.join(destRoot, orphan);
-      if (!fs.existsSync(fullPath)) continue;
-      const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
-      if (ok) {
+  if (!dryRun) {
+    if (force) {
+      for (const orphan of existingOrphans) {
         moveToTrash(destRoot, orphan);
-        console.log(`     ${clr('green', '✔')} Moved to trash\n`);
         removedCount++;
-      } else {
-        console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
-        keptCount++;
+        console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+      }
+    } else {
+      for (const orphan of existingOrphans) {
+        const fullPath = path.join(destRoot, orphan);
+        if (!fs.existsSync(fullPath)) continue;
+        const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
+        if (ok) {
+          moveToTrash(destRoot, orphan);
+          console.log(`     ${clr('green', '✔')} Moved to trash\n`);
+          removedCount++;
+        } else {
+          console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
+          keptCount++;
+        }
       }
     }
-  }
 
-  if (existingOrphans.length > 0) {
-    console.log(divider());
-    console.log(
-      `  ${clr('red', `∅ Moved: ${removedCount}`)}` +
-      `  ${clr('gray', `↪ .claude/.ai-toolkit-trash/`)}` +
-      `  ${clr('gray', `✖ Kept: ${keptCount}`)}\n`
-    );
+    if (existingOrphans.length > 0) {
+      console.log(divider());
+      console.log(
+        `  ${clr('red', `∅ Moved: ${removedCount}`)}` +
+        `  ${clr('gray', `↪ .claude/.ai-toolkit-trash/`)}` +
+        `  ${clr('gray', `✖ Kept: ${keptCount}`)}\n`
+      );
+    }
   }
 
   // ── install plan display ──────────────────────────────────────────────────────
   console.log();
-  console.log(`${bold('📦 Install plan')}  ${clr('gray', '→')}  ${clr('cyan', label)}`);
+  const planTitle = dryRun ? bold('📦 Dry run — install plan') : bold('📦 Install plan');
+  console.log(`${planTitle}  ${clr('gray', '→')}  ${clr('cyan', label)}`);
   console.log(divider());
   for (const e of newFiles)  console.log(`  ${clr('green',  '✚')} ${clr('green',  'NEW     ')}  ${dim(path.relative(process.cwd(), e.dest))}`);
   for (const e of modified)  console.log(`  ${clr('yellow', '~')} ${clr('yellow', 'MODIFIED')}  ${path.relative(process.cwd(), e.dest)}`);
@@ -379,6 +402,11 @@ async function runInstall(label, mappings, force, destRoot) {
   );
   console.log();
 
+  if (dryRun) {
+    console.log(`  ${clr('cyan', 'ℹ')}  Dry run — no files were written.\n`);
+    return;
+  }
+
   for (const e of newFiles) {
     ensureDir(e.dest);
     fs.copyFileSync(e.src, e.dest);
@@ -386,7 +414,7 @@ async function runInstall(label, mappings, force, destRoot) {
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
-    writeManifest(destRoot, newFileSet);
+    writeManifest(destRoot, newFileSet, installationMode);
     return;
   }
 
@@ -397,7 +425,7 @@ async function runInstall(label, mappings, force, destRoot) {
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
-    writeManifest(destRoot, newFileSet);
+    writeManifest(destRoot, newFileSet, installationMode);
     return;
   }
 
@@ -426,7 +454,7 @@ async function runInstall(label, mappings, force, destRoot) {
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
 
-  writeManifest(destRoot, newFileSet);
+  writeManifest(destRoot, newFileSet, installationMode);
 }
 
 // ── subagent spawn-depth check (verify & advise only — never write) ────────────
@@ -644,19 +672,912 @@ function updateGitignore(destDir) {
   }
 }
 
+// ── payload & detection ───────────────────────────────────────────────────────
+
+// Returns file-level {src, dest} mappings (absolute paths) for ALL distributable
+// catalog assets, applying TOOLKIT_INTERNAL_ASSETS exclusions.
+// This is the single authoritative source used by the installer (copy plan),
+// resolver, doctor, and list-assets so that ALL four agree on exactly what a valid
+// installation contains. effectiveRoot must be the .claude/ runtime directory.
+function buildPayloadFileMappings(effectiveRoot) {
+  const { getAssetCategories } = require('../lib/asset-catalog');
+  const mappings = [];
+  for (const cat of getAssetCategories()) {
+    const srcDir      = path.join(packageRoot, cat.sourceDir);
+    if (!fs.existsSync(srcDir)) continue;
+    const internalItems = TOOLKIT_INTERNAL_ASSETS[cat.name];
+    const catSubDir   = cat.runtimeDir.replace(/^\.claude\//, '');
+    const destCatDir  = path.join(effectiveRoot, catSubDir);
+    let entries;
+    try { entries = fs.readdirSync(srcDir); } catch (_) { continue; }
+    for (const item of entries) {
+      if (internalItems && internalItems.has(item)) continue;
+      const itemSrc = path.join(srcDir, item);
+      let stat;
+      try { stat = fs.statSync(itemSrc); } catch (_) { continue; }
+      if (stat.isDirectory()) {
+        try {
+          for (const f of walkDir(itemSrc)) {
+            const rel = path.relative(itemSrc, f);
+            mappings.push({ src: f, dest: path.join(destCatDir, item, rel) });
+          }
+        } catch (_) { /* ignore */ }
+      } else {
+        mappings.push({ src: itemSrc, dest: path.join(destCatDir, item) });
+      }
+    }
+  }
+  return mappings;
+}
+
+// Returns the Set of absolute runtime dest-paths derived from buildPayloadFileMappings.
+// Used by resolver, doctor, and list-assets for completeness checks.
+function buildExpectedPayload(effectiveRoot) {
+  return new Set(buildPayloadFileMappings(effectiveRoot).map(m => path.resolve(m.dest)));
+}
+
+// ── validateRuntimeRelativePath ───────────────────────────────────────────────
+// Single source of truth for runtime-path safety and canonicalization. Used by
+// BOTH resolveClaudeRuntimeAsset() (lenient: normalizes and accepts) and
+// validateManifestFilesField() (strict: rejects any non-canonical form). The
+// two callers format their own diagnostics, but traversal, absolute/drive paths,
+// null bytes, confinement, and the canonical computation live here only.
+//
+// A path is safe when it is a non-empty string with no surrounding whitespace,
+// no null byte, is neither a Unix/Windows absolute path nor drive-relative
+// (e.g. 'C:foo'), and contains no '..' traversal segment.
+// Its canonical form uses '/' as the sole separator with no '.'/empty segments,
+// no double separators, and no trailing slash.
+//
+// options:
+//   root             — absolute installation root; when given, the returned
+//                      `resolved` is confined within it. NOTE: after the
+//                      absolute/drive/traversal rejections above, a surviving
+//                      value can never escape root, so the 'escapes-root' branch
+//                      is unreachable defence in depth (retained against future
+//                      OS/symlink normalization surprises).
+//   requireCanonical — when true, a value that is not already canonical is an
+//                      error (code 'non-canonical'); the manifest validator uses
+//                      this so doctor flags incoherent manifests instead of
+//                      silently normalizing them.
+//
+// Returns on success: { ok: true, canonical, resolved, canonicalDiffers }
+// Returns on failure: { ok: false, code, reason, canonical? }
+function validateRuntimeRelativePath(value, options) {
+  const opts = options || {};
+  const fail = (code, reason, extra) => Object.assign({ ok: false, code, reason }, extra);
+
+  if (typeof value !== 'string') {
+    const found = value === null ? 'null' : value === undefined ? 'undefined' : typeof value;
+    return fail('not-string', `must be a non-empty string (found ${found})`);
+  }
+  if (value.length === 0) {
+    return fail('empty', 'must be a non-empty string (found empty string)');
+  }
+  if (value.includes('\0')) {
+    return fail('null-byte', 'must not contain null bytes');
+  }
+  if (value.trim().length === 0) {
+    return fail('whitespace-only', 'must not be a whitespace-only string');
+  }
+  if (value !== value.trim()) {
+    return fail('surrounding-whitespace', 'must not have leading or trailing whitespace');
+  }
+  // Normalize separators BEFORE the absolute-path checks. Otherwise a rooted
+  // Windows path ('\Windows\x.md') or a UNC path ('\\server\share\x.md') would
+  // slip past a raw startsWith('/') test and be reinterpreted as relative once
+  // the backslashes were converted. Per the Tech Spec: normalize '\' → '/' first,
+  // then reject anything that begins with '/'.
+  const unified = value.replace(/\\/g, '/');
+  if (unified.startsWith('/')) {
+    // Covers Unix absolute ('/etc/passwd'), rooted Windows ('\Windows\x.md' → '/…'),
+    // and UNC ('\\server\share' → '//server/share', or already-'/'-form '//server').
+    return fail('absolute-unix', 'must be relative (got Unix absolute path)');
+  }
+  if (/^[A-Za-z]:\//.test(unified)) {
+    return fail('absolute-windows', 'must be relative (got Windows absolute path)');
+  }
+  if (/^[A-Za-z]:/.test(unified)) {
+    return fail('drive-relative', 'must be relative (got Windows drive-relative path)');
+  }
+  if (unified.split('/').includes('..')) {
+    return fail('traversal', 'must not contain path traversal (..)');
+  }
+  // Canonical form: forward slashes, no '.'/empty segments, no double separators,
+  // no trailing slash. '..' is already rejected above, so it cannot survive here.
+  const canonical = unified.split('/').filter(s => s !== '' && s !== '.').join('/');
+  if (canonical.length === 0) {
+    return fail('empty-after-canonical', 'must resolve to a non-empty canonical path');
+  }
+  let resolved = null;
+  if (opts.root !== undefined && opts.root !== null) {
+    const rootResolved = path.resolve(opts.root);
+    resolved = path.resolve(rootResolved, canonical);
+    if (resolved !== rootResolved && !resolved.startsWith(rootResolved + path.sep)) {
+      return fail('escapes-root', 'escapes the installation root', { canonical });
+    }
+  }
+  const canonicalDiffers = value !== canonical;
+  if (opts.requireCanonical && canonicalDiffers) {
+    return fail('non-canonical', `is not canonical; expected '${canonical}'`, { canonical });
+  }
+  return { ok: true, canonical, resolved, canonicalDiffers };
+}
+
+// Validate the shape of a manifest 'files' field for the doctor's schema check.
+// Returns an array of human-readable error strings; an empty array means valid.
+// A valid 'files' field is an array whose every element is a canonical,
+// destination-relative path (forward slashes only, no '.'/'..'/empty segments,
+// no trailing slash) confined to destRoot and free of null bytes. Non-canonical
+// entries are reported — never silently normalized — so doctor requires the
+// installer to regenerate an incoherent manifest.
+// destRoot is the installation destination (parent of .claude) paths resolve against.
+function validateManifestFilesField(files, destRoot) {
+  const errors = [];
+  if (!Array.isArray(files)) {
+    errors.push(`'files' must be an array (found ${files === null ? 'null' : typeof files})`);
+    return errors;
+  }
+  const rootResolved = path.resolve(destRoot);
+  files.forEach((entry, i) => {
+    const check = validateRuntimeRelativePath(entry, { root: rootResolved, requireCanonical: true });
+    if (check.ok) return;
+    // Format the diagnostic inline — this is the only caller, so no shared helper.
+    // The entry is echoed (when a string) so operators can spot the culprit.
+    const shown = typeof entry === 'string' ? ` ('${entry}')` : '';
+    let msg;
+    switch (check.code) {
+      case 'traversal':
+        msg = `'files[${i}]' must not contain '..' segments (path traversal)${shown}`;
+        break;
+      case 'non-canonical':
+        msg = `'files[${i}]' is not canonical; expected '${check.canonical}'${shown}`;
+        break;
+      case 'escapes-root':
+        msg = `'files[${i}]' escapes the installation root${shown}`;
+        break;
+      default:
+        msg = `'files[${i}]' ${check.reason}${shown}`;
+    }
+    errors.push(msg);
+  });
+  return errors;
+}
+
+// Shared presence-detection helpers — used by resolver, doctor, and list-assets.
+// condC: at least one catalog category directory inside claudeDir has files.
+function hasToolkitPayloadFiles(claudeDir) {
+  const { getAssetCategories } = require('../lib/asset-catalog');
+  for (const cat of getAssetCategories()) {
+    const catDir = path.join(claudeDir, cat.runtimeDir.replace(/^\.claude\//, ''));
+    if (!fs.existsSync(catDir)) continue;
+    try { if (fs.statSync(catDir).isDirectory() && walkDir(catDir).length > 0) return true; }
+    catch (_) { /* ignore unreadable dirs */ }
+  }
+  return false;
+}
+
+// A toolkit installation is PRESENT at claudeDir when any of:
+//   condA: .ai-toolkit-manifest.json exists (content may be corrupt)
+//   condB: .ai-toolkit-version exists
+//   condC: at least one catalog category dir contains one or more files
+// settings.json / settings.local.json alone do NOT satisfy any condition.
+function isToolkitInstalled(claudeDir) {
+  if (fs.existsSync(path.join(claudeDir, '.ai-toolkit-manifest.json'))) return true;
+  if (fs.existsSync(path.join(claudeDir, '.ai-toolkit-version')))       return true;
+  return hasToolkitPayloadFiles(claudeDir);
+}
+
+// ── resolveClaudeRuntimeAsset ─────────────────────────────────────────────────
+
+// INFRA-TASK-BE-02 (FTR-015):
+// Resolve a runtime asset path using a six-phase algorithm:
+//   Phase 0: Input validation (no filesystem access)
+//   Phase A: Presence detection — local vs global installation
+//   Phase B: Mode decision — local-only | global-only | both (error) | none (error)
+//   Phase C: Metadata warnings — manifest, version stamp; emit to stderr; never abort
+//   Phase D: Catalog membership + completeness check
+//   Phase E: Confinement check + return absolute path
+//
+// Parameters:
+//   relativePath (string): path relative to .claude/, e.g. 'agents/agent-name.md'
+//   options (object): { projectDir, home }
+//     projectDir — target project directory (defaults to process.cwd())
+//     home       — override for os.homedir() to enable test isolation
+//
+// Returns: absolute path string
+// Throws: Error with diagnostics on validation failure, ambiguity, or incompleteness
+function resolveClaudeRuntimeAsset(relativePath, options) {
+  const os = require('os');
+  const { getAssetCategories } = require('../lib/asset-catalog');
+
+  const opts = options || {};
+  const effectiveHome       = opts.home       !== undefined ? opts.home       : os.homedir();
+  const effectiveProjectDir = opts.projectDir !== undefined ? opts.projectDir : process.cwd();
+
+  // ── Phase 0: Input validation (no filesystem access) ──────────────────────
+  // Delegate all path-safety + canonicalization to the shared primitive. The
+  // resolver is lenient (requireCanonical omitted): it normalizes backslashes,
+  // '.'/empty segments, and trailing slashes into the canonical form and
+  // proceeds, but still rejects null bytes, absolute/drive paths, and traversal.
+  const inputCheck = validateRuntimeRelativePath(relativePath);
+  if (!inputCheck.ok) {
+    throw new Error(`relativePath ${inputCheck.reason}`);
+  }
+  relativePath = inputCheck.canonical;
+
+  // ── Runtime root definitions ───────────────────────────────────────────────
+  const localRuntimeRoot  = path.join(effectiveProjectDir, '.claude');
+  const globalRuntimeRoot = path.join(effectiveHome, '.claude');
+
+  // ── Phase A: Presence detection ────────────────────────────────────────────
+  const localPresent  = isToolkitInstalled(localRuntimeRoot);
+  const globalPresent = isToolkitInstalled(globalRuntimeRoot);
+
+  // ── Phase B: Mode decision ─────────────────────────────────────────────────
+  if (!localPresent && !globalPresent) {
+    throw new Error(
+      "No toolkit installation found. Run 'npm run toolkit:dev-install-global' to install globally, or the installer in your project."
+    );
+  }
+  if (localPresent && globalPresent) {
+    throw new Error(
+      `Ambiguous: toolkit installations detected at both ${localRuntimeRoot} and ` +
+      `${globalRuntimeRoot}. The error is raised even if one installation has corrupt ` +
+      'metadata — presence is established regardless of metadata validity.'
+    );
+  }
+
+  const effectiveRoot = localPresent ? localRuntimeRoot : globalRuntimeRoot;
+  const effectiveMode = localPresent ? 'local' : 'global';
+
+  // Confinement lives in the shared primitive: re-validate the (already canonical)
+  // relativePath against the now-known installation root and reuse its resolved
+  // absolute path everywhere below, instead of re-implementing path.resolve +
+  // startsWith here.
+  const rootedCheck = validateRuntimeRelativePath(relativePath, { root: effectiveRoot });
+  if (!rootedCheck.ok) {
+    throw new Error('Resolved path escapes installation root (confinement violation)');
+  }
+  const absoluteRequested = rootedCheck.resolved;
+
+  // ── Phase C: Metadata warnings (emit to stderr; never abort) ──────────────
+  const manifestPath = path.join(effectiveRoot, '.ai-toolkit-manifest.json');
+  let manifest = null;
+  let manifestSchemaValid = false;
+
+  if (!fs.existsSync(manifestPath)) {
+    process.stderr.write('Warning: No manifest found; installation may be manual or manifest was lost\n');
+  } else {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (_) {
+      process.stderr.write(`Warning: Manifest is corrupt (invalid JSON) at ${manifestPath}\n`);
+    }
+    if (parsed !== null) {
+      const required      = ['version', 'installedAt', 'installationMode', 'files'];
+      const missingFields = required.filter(f => parsed[f] === undefined);
+      if (missingFields.length > 0) {
+        process.stderr.write(`Warning: Manifest schema invalid: missing fields ${missingFields.join(', ')}\n`);
+      } else {
+        manifestSchemaValid = true;
+        manifest = parsed;
+        if (parsed.installationMode !== effectiveMode) {
+          process.stderr.write(
+            `Warning: Manifest installationMode='${parsed.installationMode}' mismatches effective mode '${effectiveMode}'\n`
+          );
+        }
+      }
+    }
+  }
+
+  const versionStampPath = path.join(effectiveRoot, '.ai-toolkit-version');
+  if (!fs.existsSync(versionStampPath)) {
+    process.stderr.write(`Warning: No version stamp at ${versionStampPath}\n`);
+  } else {
+    const stampVersion    = fs.readFileSync(versionStampPath, 'utf8').trim();
+    const resolverVersion = require('../package.json').version;
+    if (stampVersion !== resolverVersion) {
+      process.stderr.write(
+        `Warning: Version mismatch: installed=${stampVersion}, resolver=${resolverVersion}; ` +
+        'run toolkit:dev-install-global to update\n'
+      );
+    }
+  }
+
+  // ── Phase D: Catalog membership + completeness check ──────────────────────
+  // Use the shared distributable payload function so the resolver checks exactly
+  // the same files that the installer writes (TOOLKIT_INTERNAL_ASSETS excluded).
+  const expectedPayload = buildExpectedPayload(effectiveRoot);
+
+  // Step 6e: warn about stale manifest entries (in manifest but no longer in catalog)
+  if (manifestSchemaValid && manifest && Array.isArray(manifest.files)) {
+    const parentDir = path.join(effectiveRoot, '..');
+    const stale     = manifest.files.filter(f => !expectedPayload.has(path.resolve(path.join(parentDir, f))));
+    if (stale.length > 0) {
+      process.stderr.write(
+        `Warning: Manifest has ${stale.length} stale entries not in current catalog: ${stale.join(', ')}\n`
+      );
+    }
+  }
+
+  // Step 8a: catalog membership — requested asset must be in expectedPayload
+  if (!expectedPayload.has(absoluteRequested)) {
+    throw new Error(
+      `Requested asset '${relativePath}' is not a registered catalog asset (mode: ${effectiveMode}). ` +
+      'Only toolkit-installed catalog assets may be resolved; arbitrary files under .claude/ are ' +
+      'not resolvable via this function.'
+    );
+  }
+
+  // Step 9: warn about expected assets absent from manifest (metadata-staleness; disk is authoritative)
+  if (manifestSchemaValid && manifest && Array.isArray(manifest.files)) {
+    const parentDir      = path.join(effectiveRoot, '..');
+    const manifestAbsSet = new Set(
+      manifest.files.map(f => path.resolve(path.join(parentDir, f)))
+    );
+    for (const f of expectedPayload) {
+      if (!manifestAbsSet.has(f)) {
+        process.stderr.write(`Warning: Expected asset missing from manifest: ${f}\n`);
+      }
+    }
+  }
+
+  // Step 10: disk completeness — every expected catalog asset must exist on disk;
+  // a stale manifest cannot suppress this error — disk truth is the only authority.
+  const missingFiles = [...expectedPayload].filter(f => !fs.existsSync(f));
+  if (missingFiles.length > 0) {
+    throw new Error(
+      `Installation incomplete (${effectiveMode}). Missing files:\n  ${missingFiles.join('\n  ')}\n` +
+      'Run the installer.'
+    );
+  }
+
+  // ── Phase E: Return path ───────────────────────────────────────────────────
+  // Confinement was already enforced by the shared primitive above; absoluteRequested
+  // is its confined, resolved absolute path (effectiveRoot already ends at .claude/).
+  const absolutePath = absoluteRequested;
+
+  // Step 12: final existence check
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Asset not found at ${absolutePath} (mode: ${effectiveMode})`);
+  }
+
+  // Step 13: return
+  return absolutePath;
+}
+
+// ── runDoctorResolution ───────────────────────────────────────────────────────
+
+// US-07-TASK-BE-01 (FTR-015):
+// Human-readable diagnostics of runtime installation mode, asset resolution,
+// and potential conflicts. Read-only — never modifies or deletes any file.
+//
+// Parameters (via options object):
+//   projectDir (string): target project directory (defaults to process.cwd())
+//   home       (string): override for os.homedir() to enable test isolation
+//
+// Output: writes to stdout; always exits 0 (reports, does not fail).
+function runDoctorResolution(options) {
+  const os = require('os');
+  const { getAssetCategories } = require('../lib/asset-catalog');
+
+  const opts              = options || {};
+  const effectiveHome     = opts.home       !== undefined ? path.resolve(opts.home)       : os.homedir();
+  const effectiveProject  = opts.projectDir !== undefined ? path.resolve(opts.projectDir) : process.cwd();
+
+  const categories        = getAssetCategories();
+  const localRuntimeRoot  = path.join(effectiveProject, '.claude');
+  const globalRuntimeRoot = path.join(effectiveHome,    '.claude');
+
+  // ── Internal helpers ────────────────────────────────────────────────────────
+
+  function catRelDir(cat) {
+    return cat.runtimeDir.replace(/^\.claude\//, '');
+  }
+
+  function countCategoryFiles(runtimeRoot, cat) {
+    const catDir = path.join(runtimeRoot, catRelDir(cat));
+    if (!fs.existsSync(catDir)) return 0;
+    try { return walkDir(catDir).length; } catch (_) { return 0; }
+  }
+
+  function readVersionStamp(runtimeRoot) {
+    const vFile = path.join(runtimeRoot, '.ai-toolkit-version');
+    if (!fs.existsSync(vFile)) return null;
+    try { return fs.readFileSync(vFile, 'utf8').trim(); } catch (_) { return null; }
+  }
+
+  // Returns { status: 'present'|'missing'|'corrupt', data: parsed|null, path: string }
+  function readManifestInfo(runtimeRoot) {
+    const manifestPath = path.join(runtimeRoot, '.ai-toolkit-manifest.json');
+    if (!fs.existsSync(manifestPath)) return { status: 'missing', data: null, path: manifestPath };
+    let raw;
+    try { raw = fs.readFileSync(manifestPath, 'utf8'); } catch (_) {
+      return { status: 'missing', data: null, path: manifestPath };
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return { status: 'present', data: parsed, path: manifestPath };
+    } catch (_) {
+      return { status: 'corrupt', data: null, path: manifestPath };
+    }
+  }
+
+  // Return category files present under runtimeRoot that are NOT in manifest.files.
+  // Only meaningful when manifestData exists with a files array; returns [] otherwise.
+  function findResiduals(runtimeRoot, manifestData) {
+    if (!manifestData || !Array.isArray(manifestData.files)) return [];
+    // Defensive: a malformed manifest may contain non-string entries; ignore them
+    // here so doctor still produces a read-only report (the schema check flags them).
+    const tracked = new Set(
+      manifestData.files.filter(f => typeof f === 'string').map(f => f.replace(/\\/g, '/'))
+    );
+    const residuals = [];
+    const parentDir = path.dirname(runtimeRoot); // e.g. /proj (parent of .claude)
+    for (const cat of categories) {
+      const catDir = path.join(runtimeRoot, catRelDir(cat));
+      if (!fs.existsSync(catDir)) continue;
+      try {
+        for (const f of walkDir(catDir)) {
+          const rel = path.relative(parentDir, f).replace(/\\/g, '/');
+          if (!tracked.has(rel)) residuals.push(rel);
+        }
+      } catch (_) { /* ignore */ }
+    }
+    return residuals;
+  }
+
+  // ── Detect installations ────────────────────────────────────────────────────
+  const localPresent  = isToolkitInstalled(localRuntimeRoot);
+  const globalPresent = isToolkitInstalled(globalRuntimeRoot);
+
+  let mode, modeStatus;
+  if      (localPresent && globalPresent) { mode = 'both';        modeStatus = 'AMBIGUOUS';    }
+  else if (localPresent)                  { mode = 'local-only';  modeStatus = 'VALID';         }
+  else if (globalPresent)                 { mode = 'global-only'; modeStatus = 'VALID';         }
+  else                                    { mode = 'none';        modeStatus = 'NOT INSTALLED'; }
+
+  const presentRoots = [];
+  if (localPresent)  presentRoots.push({ label: 'Local',  root: localRuntimeRoot  });
+  if (globalPresent) presentRoots.push({ label: 'Global', root: globalRuntimeRoot });
+
+  // ── Output helpers ──────────────────────────────────────────────────────────
+  const L     = (line = '') => console.log(line);
+  const H     = (title)    => { L(bold(title)); L(divider('─', 68)); };
+  const tick  = clr('green',  '✔');
+  const cross = clr('red',    '✖');
+  const warnS = clr('yellow', '⚠');
+
+  // ── Header ──────────────────────────────────────────────────────────────────
+  L('');
+  L(clr('cyan', '╔══════════════════════════════════════════════════════════════════════╗'));
+  L(clr('cyan', '║') + bold(clr('white', '          Claude Runtime Resolution Diagnostics                      ')) + clr('cyan', '║'));
+  L(clr('cyan', '╚══════════════════════════════════════════════════════════════════════╝'));
+  L('');
+
+  // ── Toolkit Source ──────────────────────────────────────────────────────────
+  H('Toolkit Source');
+  L(`  Repository root:  ${dim(packageRoot)}`);
+  L(`  Source directory: ${dim(path.join(packageRoot, 'src', 'claude'))}`);
+  L('');
+
+  // ── Installation Detection ──────────────────────────────────────────────────
+  H('Installation Detection');
+  L(`  Local runtime present:  ${localPresent  ? `${tick}  ${dim(localRuntimeRoot)}`  : `${cross}  ${dim('not found')}`}`);
+  L(`  Global runtime present: ${globalPresent ? `${tick}  ${dim(globalRuntimeRoot)}` : `${cross}  ${dim('not found')}`}`);
+  L('');
+
+  // ── Effective Runtime Mode ──────────────────────────────────────────────────
+  H('Effective Runtime Mode');
+  const modeColors   = { 'local-only': 'green', 'global-only': 'green', 'both': 'yellow', 'none': 'red' };
+  const statusColors = { 'VALID': 'green', 'AMBIGUOUS': 'yellow', 'NOT INSTALLED': 'red' };
+  L(`  Mode:   ${clr(modeColors[mode],     mode)}`);
+  L(`  Status: ${clr(statusColors[modeStatus] || 'gray', modeStatus)}`);
+  L('');
+
+  // ── Runtime Inventory ───────────────────────────────────────────────────────
+  for (const { label, root } of presentRoots) {
+    H(`Runtime Inventory (${label})`);
+    for (const cat of categories) {
+      const count = countCategoryFiles(root, cat);
+      const name  = (cat.name.charAt(0).toUpperCase() + cat.name.slice(1)).padEnd(12);
+      L(`  ${name} ${clr(count > 0 ? 'cyan' : 'gray', String(count).padStart(3))} file${count !== 1 ? 's' : ' '}`);
+    }
+    L('');
+  }
+
+  // ── Version Stamps ──────────────────────────────────────────────────────────
+  H('Version Stamps');
+  L(`  Toolkit source version:  ${clr('cyan', TOOLKIT_VERSION)}  ${dim('(from package.json)')}`);
+  if (localPresent) {
+    const lv = readVersionStamp(localRuntimeRoot);
+    const lvDisplay = lv || dim('not found');
+    const lvColor   = lv === TOOLKIT_VERSION ? 'green' : lv ? 'yellow' : 'gray';
+    L(`  Local installed version:  ${lv ? clr(lvColor, lv) : lvDisplay}  ${dim('(from .claude/.ai-toolkit-version)')}`);
+  }
+  if (globalPresent) {
+    const gv = readVersionStamp(globalRuntimeRoot);
+    const gvDisplay = gv || dim('not found');
+    const gvColor   = gv === TOOLKIT_VERSION ? 'green' : gv ? 'yellow' : 'gray';
+    L(`  Global installed version: ${gv ? clr(gvColor, gv) : gvDisplay}  ${dim('(from ~/.claude/.ai-toolkit-version)')}`);
+  }
+  if (localPresent && globalPresent) {
+    const lv = readVersionStamp(localRuntimeRoot);
+    const gv = readVersionStamp(globalRuntimeRoot);
+    const match = lv !== null && gv !== null && lv === gv;
+    L(`  Match: ${match ? tick : `${cross}  ${clr('yellow', `local=${lv || '?'}, global=${gv || '?'}`)}`}`);
+  }
+  L('');
+
+  // ── Duplicate Files (only when both installations present) ──────────────────
+  if (mode === 'both') {
+    H('Duplicate Files (local vs global)');
+    const dupes = [];
+    for (const cat of categories) {
+      const relDir       = catRelDir(cat);
+      const localCatDir  = path.join(localRuntimeRoot,  relDir);
+      const globalCatDir = path.join(globalRuntimeRoot, relDir);
+      if (!fs.existsSync(localCatDir) || !fs.existsSync(globalCatDir)) continue;
+      try {
+        const localFiles = walkDir(localCatDir).map(f => path.relative(localCatDir, f).replace(/\\/g, '/'));
+        const globalSet  = new Set(walkDir(globalCatDir).map(f => path.relative(globalCatDir, f).replace(/\\/g, '/')));
+        for (const f of localFiles) {
+          if (!globalSet.has(f)) continue;
+          const lp   = path.join(localCatDir,  f);
+          const gp   = path.join(globalCatDir, f);
+          const same = fileHash(lp) === fileHash(gp);
+          dupes.push({ relPath: `${relDir}/${f}`, same });
+        }
+      } catch (_) { /* ignore */ }
+    }
+    if (dupes.length === 0) {
+      L(`  ${dim('(no files appear in both installations)')}`);
+    } else {
+      for (const d of dupes) {
+        L(`  ${dim(d.relPath)}: ${d.same ? `${tick} content matches` : `${cross} content differs`}`);
+      }
+    }
+    L('');
+  }
+
+  // ── Manifest Consistency ────────────────────────────────────────────────────
+  H('Manifest Consistency');
+  if (presentRoots.length === 0) {
+    L(`  ${dim('(no installation to check)')}`);
+  } else {
+    for (const { label, root } of presentRoots) {
+      const mInfo        = readManifestInfo(root);
+      const mSymbol      = { present: tick, missing: warnS, corrupt: cross }[mInfo.status];
+      const mStatusColor = { present: 'green', missing: 'yellow', corrupt: 'red' }[mInfo.status];
+      L(`  ${bold(label)} manifest:`);
+      L(`    File:   ${dim(mInfo.path)}`);
+      L(`    Status: ${mSymbol}  ${clr(mStatusColor, mInfo.status)}`);
+      if (mInfo.status === 'present' && mInfo.data) {
+        const fCount = Array.isArray(mInfo.data.files) ? mInfo.data.files.length : '?';
+        L(`    Files:  ${fCount}`);
+        if (mInfo.data.version)          L(`    Version:           ${mInfo.data.version}`);
+        if (mInfo.data.installationMode) L(`    Installation mode: ${mInfo.data.installationMode}`);
+      }
+    }
+  }
+  L('');
+
+  // ── Residual .claude/ Assets ────────────────────────────────────────────────
+  H('Residual .claude/ Assets');
+  if (presentRoots.length === 0) {
+    L(`  ${dim('(no installation to check)')}`);
+  } else {
+    for (const { label, root } of presentRoots) {
+      const mInfo = readManifestInfo(root);
+      if (mInfo.status !== 'present') {
+        L(`  ${label}: ${warnS}  ${dim('cannot check residuals — manifest missing or corrupt')}`);
+      } else {
+        const residuals = findResiduals(root, mInfo.data);
+        if (residuals.length === 0) {
+          L(`  ${label}: ${tick}  ${clr('green', 'CLEAN')}  ${dim('(all category files tracked in manifest)')}`);
+        } else {
+          L(`  ${label}: ${warnS}  ${clr('yellow', 'WARNING')}  — ${residuals.length} untracked file(s):`);
+          for (const r of residuals.slice(0, 10)) L(`    ${dim(r)}`);
+          if (residuals.length > 10) L(`    ${dim(`... and ${residuals.length - 10} more`)}`);
+        }
+      }
+    }
+  }
+  L('');
+
+  // ── Disk Completeness ─────────────────────────────────────────────────────────
+  H('Disk Completeness');
+  let diskIncomplete = false;
+  let missingRuntimeFiles = [];
+
+  if (mode === 'local-only' || mode === 'global-only') {
+    const singleRoot = mode === 'local-only' ? localRuntimeRoot : globalRuntimeRoot;
+    const expected   = buildExpectedPayload(singleRoot);
+    missingRuntimeFiles = [...expected].filter(f => !fs.existsSync(f));
+    diskIncomplete = missingRuntimeFiles.length > 0;
+  }
+
+  if (mode !== 'local-only' && mode !== 'global-only') {
+    L(`  ${dim('(check runs only for single-installation mode)')}`);
+  } else if (!diskIncomplete) {
+    L(`  ${tick}  ${clr('green', 'COMPLETE')}  ${dim('all catalog files present on disk')}`);
+  } else {
+    L(`  ${cross}  ${clr('red', 'INCOMPLETE')}  — ${missingRuntimeFiles.length} required file(s) missing:`);
+    for (const f of missingRuntimeFiles.slice(0, 10)) {
+      L(`    ${clr('red', '✖')} ${dim(f)}`);
+    }
+    if (missingRuntimeFiles.length > 10) L(`    ${dim(`... and ${missingRuntimeFiles.length - 10} more`)}`);
+  }
+  L('');
+
+  // ── Action Items ────────────────────────────────────────────────────────────
+  H('Action Items');
+  const actions = [];
+  let manifestSchemaProblematic = false;
+  let manifestModeInconsistent  = false;
+  let manifestFilesIncomplete   = false;
+
+  if (mode === 'both') {
+    actions.push(`${warnS}  Choose one: delete local or global installation to resolve ambiguity`);
+  }
+  if (mode === 'none') {
+    actions.push(`${cross}  No installation found. Run 'npm run toolkit:dev-install-global' or the local installer`);
+  }
+  if (mode === 'local-only' || mode === 'global-only') {
+    const effectiveRoot  = mode === 'local-only' ? localRuntimeRoot : globalRuntimeRoot;
+    const detectedMode   = mode === 'local-only' ? 'local' : 'global';
+    const iv = readVersionStamp(effectiveRoot);
+    if (iv && iv !== TOOLKIT_VERSION) {
+      actions.push(`${warnS}  Version mismatch: run 'npm run toolkit:dev-install-global' to update`);
+    }
+    const mInfo = readManifestInfo(effectiveRoot);
+    if (mInfo.status === 'corrupt') {
+      manifestSchemaProblematic = true;
+      actions.push(`${cross}  Manifest schema invalid: file is corrupt (invalid JSON)`);
+    } else if (mInfo.status === 'missing') {
+      manifestSchemaProblematic = true;
+      actions.push(`${warnS}  Manifest is ${mInfo.status}. Run the installer to regenerate.`);
+    } else if (mInfo.status === 'present' && mInfo.data) {
+      // Check required manifest fields (including installationMode).
+      const required = ['version', 'installedAt', 'installationMode', 'files'];
+      const missingFields = required.filter(f => mInfo.data[f] === undefined);
+      if (missingFields.length > 0) {
+        manifestSchemaProblematic = true;
+        for (const f of missingFields) {
+          actions.push(`${cross}  Manifest schema invalid: missing required field '${f}'`);
+        }
+        actions.push(`${warnS}  Run the installer to regenerate the manifest with all required fields.`);
+      } else {
+        const parentDir = path.join(effectiveRoot, '..');
+        // installationMode must match the detected installation mode.
+        if (mInfo.data.installationMode !== detectedMode) {
+          manifestModeInconsistent = true;
+          actions.push(
+            `${cross}  Manifest installationMode='${mInfo.data.installationMode}' does not match ` +
+            `detected mode '${detectedMode}' — run the installer to repair`
+          );
+        }
+        // manifest.files must be a well-formed array of relative, in-bounds paths.
+        const filesErrors = validateManifestFilesField(mInfo.data.files, parentDir);
+        if (filesErrors.length > 0) {
+          manifestSchemaProblematic = true;
+          for (const e of filesErrors.slice(0, 5)) {
+            actions.push(`${cross}  Manifest schema invalid: ${e}`);
+          }
+          if (filesErrors.length > 5) {
+            actions.push(`${cross}  ... and ${filesErrors.length - 5} more manifest 'files' error(s)`);
+          }
+          actions.push(`${warnS}  Run the installer to regenerate the manifest with a valid 'files' list.`);
+        } else {
+          // files is a valid array — it must cover all expected catalog assets.
+          const expected       = buildExpectedPayload(effectiveRoot);
+          const manifestAbsSet = new Set(
+            mInfo.data.files.map(f => path.resolve(path.join(parentDir, f)))
+          );
+          const missingFromManifest = [...expected].filter(f => !manifestAbsSet.has(f));
+          if (missingFromManifest.length > 0) {
+            manifestFilesIncomplete = true;
+            actions.push(
+              `${cross}  manifest.files is missing ${missingFromManifest.length} expected catalog asset(s) — run the installer`
+            );
+            for (const f of missingFromManifest.slice(0, 3)) {
+              actions.push(`       ${dim(path.basename(f))}`);
+            }
+            if (missingFromManifest.length > 3) {
+              actions.push(`       ${dim(`... and ${missingFromManifest.length - 3} more`)}`);
+            }
+          }
+        }
+      }
+    }
+  }
+  if (diskIncomplete) {
+    const display = missingRuntimeFiles.slice(0, 5);
+    for (const f of display) {
+      actions.push(`${cross}  Missing required file: ${dim(path.basename(f))} — run the installer`);
+    }
+    if (missingRuntimeFiles.length > 5) {
+      actions.push(`${cross}  ... and ${missingRuntimeFiles.length - 5} more missing file(s) — run the installer`);
+    }
+  }
+
+  if (actions.length === 0) {
+    L(`  ${tick}  ${clr('green', 'runtime ready for pipelines')}`);
+  } else {
+    for (const a of actions) L(`  • ${a}`);
+  }
+  L('');
+
+  // ── Summary ─────────────────────────────────────────────────────────────────
+  H('Summary');
+  // READY requires: single installation, valid manifest schema, consistent installationMode,
+  // manifest.files covering all expected assets, and complete disk payload.
+  const overallOk = (mode === 'local-only' || mode === 'global-only')
+    && !manifestSchemaProblematic
+    && !manifestModeInconsistent
+    && !manifestFilesIncomplete
+    && !diskIncomplete;
+  const overallStatus = overallOk ? 'READY' : 'PROBLEMATIC';
+  L(`  Status: ${clr(overallOk ? 'green' : 'red', overallStatus)}`);
+  let recommendation;
+  if (mode === 'none') {
+    recommendation = "Run 'npm run toolkit:dev-install-global' to install globally, or use the local installer.";
+  } else if (mode === 'both') {
+    recommendation = 'Remove one installation to resolve ambiguity before running pipelines.';
+  } else if (manifestSchemaProblematic || manifestModeInconsistent || manifestFilesIncomplete) {
+    recommendation = 'Run the installer to repair the manifest before running pipelines.';
+  } else if (diskIncomplete) {
+    recommendation = 'Run the installer to complete the installation before running pipelines.';
+  } else {
+    recommendation = `Installation is operational in ${mode} mode.`;
+  }
+  L(`  Recommendation: ${dim(recommendation)}`);
+  L('');
+  L(clr('gray', '═'.repeat(72)));
+  L('');
+}
+
+// ── validatePurityGuard ───────────────────────────────────────────────────────
+
+// US-05-TASK-BE-03 (FTR-015):
+// Rejects any *.test.js files or blocked directory segments under sourceDir.
+// Called by the installer before copying and by the prepack lifecycle hook.
+//
+// Blocked file patterns: *.test.js
+// Blocked directory names: tests, fixtures, mocks, helpers
+//
+// Returns an array of violation strings (empty = clean).
+// Never modifies the filesystem.
+const PURITY_BLOCKED_DIRS  = new Set(['tests', 'fixtures', 'mocks', 'helpers']);
+const PURITY_BLOCKED_EXTS  = ['.test.js'];
+
+function validatePurityGuard(sourceDir) {
+  const violations = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    let entries;
+    try { entries = fs.readdirSync(dir); } catch (_) { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry);
+      let stat;
+      try { stat = fs.statSync(full); } catch (_) { continue; }
+      if (stat.isDirectory()) {
+        if (PURITY_BLOCKED_DIRS.has(entry)) {
+          violations.push(`Blocked directory: ${full}`);
+        } else {
+          walk(full);
+        }
+      } else {
+        if (PURITY_BLOCKED_EXTS.some(ext => entry.endsWith(ext))) {
+          violations.push(`Blocked file: ${full}`);
+        }
+      }
+    }
+  }
+
+  walk(sourceDir);
+  return violations;
+}
+
+// validate-purity CLI command entry point.
+// Scans sourceDir (defaults to src/claude/) for test or fixture contamination.
+// Exit 0 = clean. Exit 1 = violations found. Violations written to stderr.
+function runValidatePurity(sourceDir) {
+  const effectiveDir = sourceDir
+    ? path.resolve(sourceDir)
+    : path.join(packageRoot, 'src', 'claude');
+
+  const violations = validatePurityGuard(effectiveDir);
+  if (violations.length === 0) {
+    process.stdout.write(`Purity guard: PASS — no test files or blocked dirs under ${effectiveDir}\n`);
+    process.exit(0);
+  } else {
+    process.stderr.write(`Purity guard: FAIL — ${violations.length} violation(s) under ${effectiveDir}:\n`);
+    for (const v of violations) process.stderr.write(`  ${v}\n`);
+    process.exit(1);
+  }
+}
+
+// ── distributable asset mapping ───────────────────────────────────────────────
+
+// Assets that are toolkit-internal and must NEVER be distributed to consumer
+// projects. Keyed by category name; value is a Set of item names to skip.
+// See AGENTS.md hard constraints.
+const TOOLKIT_INTERNAL_ASSETS = {
+  agents: new Set(['install-toolkit.md']),
+  skills: new Set(['install-toolkit']),
+};
+
+// ── verifyInstall ─────────────────────────────────────────────────────────────
+
+// Checks that the version stamp in <home>/.claude/.ai-toolkit-version matches
+// package.json. Called as the final step of toolkit:dev-install-global.
+// Exit 0 = versions match. Exit 1 = stamp missing, unreadable, or wrong version.
+function runVerifyInstall(options) {
+  const os = require('os');
+  const opts          = options || {};
+  const effectiveHome = opts.home !== undefined ? path.resolve(opts.home) : os.homedir();
+  const versionFile   = path.join(effectiveHome, '.claude', VERSION_FILE);
+
+  if (!fs.existsSync(versionFile)) {
+    process.stderr.write(`Error: verify-install FAILED — no version stamp at ${versionFile}\n`);
+    process.exit(1);
+  }
+
+  let stamp;
+  try {
+    stamp = fs.readFileSync(versionFile, 'utf8').trim();
+  } catch (err) {
+    process.stderr.write(`Error: verify-install FAILED — cannot read ${versionFile}: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (!stamp) {
+    process.stderr.write(`Error: verify-install FAILED — version stamp is empty at ${versionFile}\n`);
+    process.exit(1);
+  }
+
+  if (stamp !== TOOLKIT_VERSION) {
+    process.stderr.write(
+      `Error: verify-install FAILED — version mismatch\n` +
+      `  installed: ${stamp}\n` +
+      `  expected:  ${TOOLKIT_VERSION}\n` +
+      `Run 'npm run toolkit:dev-install-global' to update.\n`
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(`verify-install: PASS — version ${stamp} matches package.json\n`);
+  process.exit(0);
+}
+
 // ── entry points ──────────────────────────────────────────────────────────────
 
-async function installLocal(targetDir, force) {
+async function installLocal(targetDir, force, dryRun = false) {
   banner();
   targetDir = path.resolve(process.cwd(), targetDir || '.');
   console.log(`  ${clr('cyan', '▸')}  Target: ${bold(targetDir)}\n`);
-  await checkVersion(targetDir, force);
+  if (!dryRun) await checkVersion(targetDir, force);
+  // Purity guard (UC-05 / BR-16 / AC-29): abort if source contains test files or blocked dirs.
+  const srcClaudeDir = path.join(packageRoot, 'src', 'claude');
+  const purityViolations = validatePurityGuard(srcClaudeDir);
+  if (purityViolations.length > 0) {
+    process.stderr.write(`Purity guard: FAIL — ${purityViolations.length} violation(s):\n`);
+    for (const v of purityViolations) process.stderr.write(`  ${v}\n`);
+    process.exit(1);
+  }
+  // Build copy plan from the single canonical source (buildPayloadFileMappings) so
+  // installer, resolver, doctor, and list-assets all use the same distributable set.
   const mappings = [
-    { src: path.join(packageRoot, '.claude'),   dest: path.join(targetDir, '.claude') },
+    ...buildPayloadFileMappings(path.join(targetDir, '.claude')),
     { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
     { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
   ];
-  await runInstall(`local project`, mappings, force, targetDir);
+  await runInstall(`local project`, mappings, force, targetDir, dryRun, 'local');
+  if (dryRun) return;
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
   checkSpawnDepth(targetDir);
@@ -667,24 +1588,32 @@ async function installLocal(targetDir, force) {
   console.log();
 }
 
-async function installGlobal(force) {
+async function installGlobal(force, dryRun = false, homeOverride = undefined) {
   banner();
   try {
-    const homedir = require('os').homedir();
+    const homedir = homeOverride !== undefined ? path.resolve(homeOverride) : require('os').homedir();
     const target  = path.join(homedir, '.claude');
     console.log(`  ${clr('cyan', '▸')}  Target: ${bold(target)}  ${clr('gray', '(global Claude folder)')}\n`);
-    await checkVersion(target, force);
+    // destRoot is homedir so helpers (manifest, version stamp, trash) resolve to
+    // ~/.claude/... rather than ~/.claude/.claude/... (FIX: global install root path)
+    if (!dryRun) await checkVersion(homedir, force);
+    // Purity guard (UC-05 / BR-16 / AC-29): abort if source contains test files or blocked dirs.
+    const srcClaudeDir = path.join(packageRoot, 'src', 'claude');
+    const purityViolations = validatePurityGuard(srcClaudeDir);
+    if (purityViolations.length > 0) {
+      process.stderr.write(`Purity guard: FAIL — ${purityViolations.length} violation(s):\n`);
+      for (const v of purityViolations) process.stderr.write(`  ${v}\n`);
+      process.exit(1);
+    }
+    // Build copy plan from the single canonical source (buildPayloadFileMappings).
     const mappings = [
-      { src: path.join(packageRoot, '.claude', 'agents'),    dest: path.join(target, 'agents') },
-      { src: path.join(packageRoot, '.claude', 'skills'),    dest: path.join(target, 'skills') },
-      { src: path.join(packageRoot, '.claude', 'commands'),  dest: path.join(target, 'commands') },
-      { src: path.join(packageRoot, '.claude', 'workflows'), dest: path.join(target, 'workflows') },
-      { src: path.join(packageRoot, '.claude', 'scripts'),   dest: path.join(target, 'scripts') },
-      { src: path.join(packageRoot, 'docs'),                 dest: path.join(target, 'docs') },
-      { src: path.join(packageRoot, 'CLAUDE.global.md'),    dest: path.join(target, 'CLAUDE.md') },
+      ...buildPayloadFileMappings(target),
+      { src: path.join(packageRoot, 'docs'),             dest: path.join(target, 'docs') },
+      { src: path.join(packageRoot, 'CLAUDE.global.md'), dest: path.join(target, 'CLAUDE.md') },
     ];
-    await runInstall('global Claude folder', mappings, force, target);
-    writeInstalledVersion(target);
+    await runInstall('global Claude folder', mappings, force, homedir, dryRun, 'global');
+    if (dryRun) return;
+    writeInstalledVersion(homedir);
     console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
     checkSpawnDepth(homedir);
     console.log(divider());
@@ -705,22 +1634,38 @@ function help() {
   console.log(`    ${clr('cyan', 'ai-toolkit')} ${clr('yellow', '--local <dir>')}       Install into target directory`);
   console.log(`    ${clr('cyan', 'ai-toolkit')} ${clr('yellow', '--global')}             Install into ~/.claude (global)`);
   console.log(`    ${clr('gray',  '                     --force')}       Overwrite all files without prompting`);
+  console.log(`    ${clr('gray',  '                     --dry-run')}     Preview what would change — no files written`);
   console.log();
 }
 
 async function main() {
-  const argv  = process.argv.slice(2);
-  const force = argv.includes('--force');
+  const argv   = process.argv.slice(2);
+  const force  = argv.includes('--force');
+  const dryRun = argv.includes('--dry-run');
 
-  if (argv.length === 0 || (argv.length === 1 && argv[0] === '--force')) {
-    await installLocal('.', force);
+  if (argv.length === 0 || argv.every(a => a === '--force' || a === '--dry-run')) {
+    await installLocal('.', force, dryRun);
     return;
   }
 
   if (argv[0] === '--local') {
-    await installLocal(argv[1] || '.', force);
+    await installLocal(argv[1] || '.', force, dryRun);
   } else if (argv[0] === '--global') {
-    await installGlobal(force);
+    const homeIdx = argv.indexOf('--home');
+    const homeOverride = homeIdx !== -1 ? argv[homeIdx + 1] : undefined;
+    await installGlobal(force, dryRun, homeOverride);
+  } else if (argv[0] === 'install') {
+    // Subcommand aliases: `install --project <dir>` ≡ `--local <dir>`
+    //                     `install --global`         ≡ `--global`
+    const sub = argv[1];
+    if (sub === '--project') {
+      await installLocal(argv[2] || '.', force, dryRun);
+    } else if (sub === '--global') {
+      await installGlobal(force, dryRun);
+    } else {
+      // No sub-flag: install into current directory (same as bare invocation)
+      await installLocal(sub && !sub.startsWith('-') ? sub : '.', force, dryRun);
+    }
   } else if (argv[0] === 'help' || argv[0] === '--help') {
     help();
   } else if (argv[0] === 'merge-allowlist') {
@@ -759,8 +1704,166 @@ async function main() {
       console.error(`Error: ${err.message}`);
       process.exit(1);
     }
+  } else if (argv[0] === 'verify-install') {
+    const remaining = argv.slice(1);
+    const homeIdx   = remaining.indexOf('--home');
+    const home      = homeIdx !== -1 ? remaining[homeIdx + 1] : undefined;
+    runVerifyInstall({ home });
+  } else if (argv[0] === 'doctor' && argv[1] === 'resolution') {
+    const remaining  = argv.slice(2);
+    const projectIdx = remaining.indexOf('--project');
+    const homeIdx    = remaining.indexOf('--home');
+    const projectDir = projectIdx !== -1 ? remaining[projectIdx + 1] : process.cwd();
+    const home       = homeIdx    !== -1 ? remaining[homeIdx    + 1] : undefined;
+    runDoctorResolution({ projectDir, home });
+    process.exit(0);
+  } else if (argv[0] === 'validate-purity') {
+    runValidatePurity(argv[1]);
+  } else if (argv[0] === 'resolve-asset') {
+    // resolve-asset <relativePath> [--project <dir>] [--home <dir>]
+    // Three-tier model: Tier 1 = exit 0 + stdout=path + stderr="";
+    //   Tier 2 = exit 0 + stdout=path + stderr=warnings (emitted by resolver);
+    //   Tier 3 = exit 1 + stdout="" + stderr=error.
+    const remaining = argv.slice(1);
+    let relativePath = null;
+    let projectDir   = process.cwd();
+    let home;
+    for (let i = 0; i < remaining.length; i++) {
+      if      (remaining[i] === '--project' && remaining[i + 1]) { projectDir = remaining[++i]; }
+      else if (remaining[i] === '--home'    && remaining[i + 1]) { home       = remaining[++i]; }
+      else if (!remaining[i].startsWith('-'))                     { relativePath = remaining[i]; }
+    }
+    if (!relativePath) {
+      process.stderr.write('Error: resolve-asset requires a relative path argument\n');
+      process.exit(1);
+    }
+    try {
+      const resolved = resolveClaudeRuntimeAsset(relativePath, { projectDir, home });
+      process.stdout.write(resolved + '\n');
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      process.exit(1);
+    }
+  } else if (argv[0] === 'run-asset') {
+    // run-asset <relativePath> [--project <dir>] [--home <dir>] [-- ...scriptArgs]
+    // Security constraints: scripts category only; .js extension only; spawnSync shell:false.
+    const remaining   = argv.slice(1);
+    const dashDashIdx = remaining.indexOf('--');
+    const scriptArgs  = dashDashIdx !== -1 ? remaining.slice(dashDashIdx + 1) : [];
+    const beforeDash  = dashDashIdx !== -1 ? remaining.slice(0, dashDashIdx) : remaining;
+    let relativePath  = null;
+    let projectDir    = process.cwd();
+    let home;
+    for (let i = 0; i < beforeDash.length; i++) {
+      if      (beforeDash[i] === '--project' && beforeDash[i + 1]) { projectDir = beforeDash[++i]; }
+      else if (beforeDash[i] === '--home'    && beforeDash[i + 1]) { home       = beforeDash[++i]; }
+      else if (!beforeDash[i].startsWith('-'))                      { relativePath = beforeDash[i]; }
+    }
+    if (!relativePath) {
+      process.stderr.write('Error: run-asset requires a relative path argument\n');
+      process.exit(1);
+    }
+    // Security: only the scripts category is executable
+    if (!relativePath.startsWith('scripts/')) {
+      process.stderr.write(`Error: run-asset is restricted to the scripts category (got: ${relativePath})\n`);
+      process.exit(1);
+    }
+    // Security: .js extension only
+    if (!relativePath.endsWith('.js')) {
+      process.stderr.write(`Error: run-asset only executes .js files (got: ${relativePath})\n`);
+      process.exit(1);
+    }
+    try {
+      const scriptPath = resolveClaudeRuntimeAsset(relativePath, { projectDir, home });
+      const { spawnSync } = require('child_process');
+      const result = spawnSync(process.execPath, [scriptPath, ...scriptArgs], {
+        stdio: 'inherit',
+        shell: false,
+      });
+      if (result.error) {
+        process.stderr.write(`Error spawning script: ${result.error.message}\n`);
+        process.exit(1);
+      }
+      process.exit(result.status || 0);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      process.exit(1);
+    }
+  } else if (argv[0] === 'list-assets') {
+    // list-assets --project <dir> --category <name> [--format json|plain] [--home <dir>]
+    // Both --project and --category are MANDATORY (Tech Spec contract).
+    // Returns exclusively assets from the distributable payload (buildExpectedPayload).
+    // Foreign/user-created files under .claude/ are never returned.
+    // Exit 0 + result for installed single-mode; exit 1 for no-install or mixed install.
+    const { getAssetCategories, getCategoryByName } = require('../lib/asset-catalog');
+    const os         = require('os');
+    const remaining  = argv.slice(1);
+    let category     = null;
+    let format       = 'json';
+    let projectDir   = null;
+    let home;
+    for (let i = 0; i < remaining.length; i++) {
+      if      (remaining[i] === '--category' && remaining[i + 1]) { category   = remaining[++i]; }
+      else if (remaining[i] === '--format'   && remaining[i + 1]) { format     = remaining[++i]; }
+      else if (remaining[i] === '--project'  && remaining[i + 1]) { projectDir = remaining[++i]; }
+      else if (remaining[i] === '--home'     && remaining[i + 1]) { home       = remaining[++i]; }
+    }
+    // Mandatory parameter contract (Tier 3: exit 1, stdout empty, diagnostic on stderr).
+    if (!projectDir) {
+      process.stderr.write('Error: list-assets requires --project <dir>\n');
+      process.exit(1);
+    }
+    if (!category) {
+      process.stderr.write('Error: list-assets requires --category <name>\n');
+      process.exit(1);
+    }
+    const cat = getCategoryByName(category);
+    if (!cat) {
+      const valid = getAssetCategories().map(c => c.name).join(', ');
+      process.stderr.write(`Error: unknown category '${category}'. Valid: ${valid}\n`);
+      process.exit(1);
+    }
+    // Shared 3-condition presence detection (same as resolver and doctor).
+    const effectiveHome    = home       ? path.resolve(home)       : os.homedir();
+    const effectiveProject = path.resolve(projectDir);
+    const localClaude      = path.join(effectiveProject, '.claude');
+    const globalClaude     = path.join(effectiveHome,    '.claude');
+
+    const localPresent  = isToolkitInstalled(localClaude);
+    const globalPresent = isToolkitInstalled(globalClaude);
+
+    if (localPresent && globalPresent) {
+      process.stderr.write(
+        'Error: mixed installation — toolkit is present in both local (.claude/) and global ' +
+        `(${globalClaude}) locations. Remove one before listing assets.\n`
+      );
+      process.exit(1);
+    }
+
+    // No installation → Tier 3 error (exit 1, stdout empty, diagnostic on stderr).
+    if (!localPresent && !globalPresent) {
+      process.stderr.write('Error: no toolkit installation found. Install with --local or --global.\n');
+      process.exit(1);
+    }
+    const runtimeRoot = localPresent ? localClaude : globalClaude;
+
+    // Return only catalog-defined assets (no foreign files) for the requested
+    // category, and only files that actually exist on disk.
+    const allExpected = [...buildExpectedPayload(runtimeRoot)].sort();
+    const catDir      = path.resolve(path.join(runtimeRoot, cat.name));
+    const results = allExpected
+      .filter(f => f.startsWith(catDir + path.sep) || f.startsWith(catDir + '/'))
+      .filter(f => fs.existsSync(f));
+
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+    } else {
+      for (const r of results) process.stdout.write(r + '\n');
+    }
+    process.exit(0);
   } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
-    await installLocal(argv[0], force);
+    await installLocal(argv[0], force, dryRun);
   } else {
     help();
     process.exit(1);
@@ -780,10 +1883,10 @@ if (require.main === module) {
     expandMappings,
     categorize,
     readInstalledVersion,
-    NEVER_COPY,
     readManifest,
     computeOrphans,
     moveToTrash,
+    trashTimestamp,
     writeManifest,
     CANONICAL_ALLOW,
     CANONICAL_ASK,
@@ -797,5 +1900,16 @@ if (require.main === module) {
     updateGitignore,
     appendLedgerEntry,
     updateLedgerEntry,
+    resolveClaudeRuntimeAsset,
+    runDoctorResolution,
+    validatePurityGuard,
+    TOOLKIT_INTERNAL_ASSETS,
+    buildPayloadFileMappings,
+    buildExpectedPayload,
+    validateRuntimeRelativePath,
+    validateManifestFilesField,
+    hasToolkitPayloadFiles,
+    isToolkitInstalled,
+    runVerifyInstall,
   };
 }