@friedbotstudio/create-baseline 0.4.0 → 0.6.0

package/src/cli/merge.js

@@ -4,6 +4,7 @@ import { hashFile, saveManifest } from './manifest.js';
 import { deepMergeMcpServers } from './mcp.js';
 import { NEVER_TOUCH, SPECIAL_MERGE } from './install.js';
 import { pathExists } from './util.js';
+import { dispatchByTier, NoBaseError } from './upgrade-tiers.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
@@ -15,6 +16,9 @@ export const ACTION_KINDS = Object.freeze({
   NEVER_TOUCH_PRESERVE: 'NEVER_TOUCH_PRESERVE',
   NEVER_TOUCH_ADD: 'NEVER_TOUCH_ADD',
   SPECIAL_MERGE: 'SPECIAL_MERGE',
+  MECHANICAL_MERGE_CLEAN: 'MECHANICAL_MERGE_CLEAN',
+  MECHANICAL_MERGE_CONFLICTED: 'MECHANICAL_MERGE_CONFLICTED',
+  SEMANTIC_MERGE_STAGED: 'SEMANTIC_MERGE_STAGED',
 });
 
 async function copyFile(src, dst) {
@@ -22,13 +26,40 @@ async function copyFile(src, dst) {
   await cp(src, dst, { force: true });
 }
 
+function readShaFromEntry(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && typeof entry.sha256 === 'string') return entry.sha256;
+  return null;
+}
+
+function readTierFromEntry(entry) {
+  if (entry && typeof entry === 'object' && typeof entry.tier === 'string') return entry.tier;
+  // Bare-sha entries (legacy shipped manifest_version: 2 OR installed-manifest
+  // round-trips without tier overlay) fall back to BINARY_PROMPT — the safe
+  // default that preserves today's two-way prompt behavior. New shipped
+  // manifests (v3+) carry `{sha256, tier}` per file and exercise the full
+  // three-tier flow.
+  return 'BINARY_PROMPT';
+}
+
 export async function threeWayMerge(templateDir, target, oldManifest, newManifest, opts = {}) {
-  const { dryRun = false, onSkipCustomized = null } = opts;
+  const { dryRun = false, onSkipCustomized = null, pack = null } = opts;
   const actions = [];
   const oldFiles = oldManifest?.files ?? {};
   const newFiles = newManifest?.files ?? {};
+  const baseline_version = oldManifest?.baseline_version;
   const allPaths = new Set([...Object.keys(oldFiles), ...Object.keys(newFiles)]);
 
+  const tierCtx = {
+    target,
+    templateDir,
+    oldManifest,
+    newManifest,
+    baseline_version,
+    pack,
+    stageRunTs: null,
+  };
+
   for (const rel of allPaths) {
     const tplPath = join(templateDir, rel);
     const tgtPath = join(target, rel);
@@ -51,8 +82,10 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
       continue;
     }
 
-    const newHash = newFiles[rel];
-    const oldHash = oldFiles[rel];
+    const newEntry = newFiles[rel];
+    const oldEntry = oldFiles[rel];
+    const newHash = readShaFromEntry(newEntry);
+    const oldHash = readShaFromEntry(oldEntry);
     const targetExists = await pathExists(tgtPath);
     const tgtHash = targetExists ? await hashFile(tgtPath) : null;
 
@@ -74,13 +107,10 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     }
 
     if (newHash && tgtHash && tgtHash !== oldHash) {
-      const choice = onSkipCustomized ? await onSkipCustomized(rel) : 'keep-mine';
-      if (choice === 'take-theirs') {
-        if (!dryRun) await copyFile(tplPath, tgtPath);
-        actions.push({ kind: ACTION_KINDS.OVERWRITE, path: rel, reason: 'customized file; user chose take-theirs' });
-      } else {
-        actions.push({ kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: 'target customized since last install' });
-      }
+      const action = await dispatchCustomized({
+        rel, newEntry, tierCtx, dryRun, onSkipCustomized, tplPath, tgtPath,
+      });
+      actions.push(action);
       continue;
     }
 
@@ -106,7 +136,44 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     await saveManifest(join(target, '.claude/.baseline-manifest.json'), newManifest);
   }
 
-  const skipKinds = [ACTION_KINDS.SKIP_CUSTOMIZED, ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED];
-  const exitCode = actions.some((a) => skipKinds.includes(a.kind)) ? 3 : 0;
-  return { actions, exitCode };
+  return { actions, exitCode: computeExitCode(actions) };
+}
+
+async function dispatchCustomized({ rel, newEntry, tierCtx, dryRun, onSkipCustomized, tplPath, tgtPath }) {
+  const tier = readTierFromEntry(newEntry);
+  if (tier === 'MECHANICAL' || tier === 'SEMANTIC') {
+    if (dryRun) {
+      return { kind: tier === 'MECHANICAL' ? ACTION_KINDS.MECHANICAL_MERGE_CLEAN : ACTION_KINDS.SEMANTIC_MERGE_STAGED, path: rel, reason: 'dry-run: tier dispatch deferred' };
+    }
+    try {
+      return await dispatchByTier(rel, tier, tierCtx);
+    } catch (err) {
+      if (err instanceof NoBaseError) {
+        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err });
+      }
+      throw err;
+    }
+  }
+  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath });
+}
+
+async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err = null }) {
+  const choice = onSkipCustomized ? await onSkipCustomized(rel) : 'keep-mine';
+  if (choice === 'take-theirs') {
+    if (!dryRun) await copyFile(tplPath, tgtPath);
+    return { kind: ACTION_KINDS.OVERWRITE, path: rel, reason: err ? `BASE recovery failed (${err.kind}); user chose take-theirs` : 'customized file; user chose take-theirs' };
+  }
+  return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); preserved` : 'target customized since last install' };
+}
+
+function computeExitCode(actions) {
+  let code = 0;
+  for (const a of actions) {
+    if (a.kind === ACTION_KINDS.SEMANTIC_MERGE_STAGED) code = Math.max(code, 5);
+    else if (a.kind === ACTION_KINDS.MECHANICAL_MERGE_CONFLICTED) code = Math.max(code, 4);
+    else if (a.kind === ACTION_KINDS.SKIP_CUSTOMIZED || a.kind === ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED) {
+      code = Math.max(code, 3);
+    }
+  }
+  return code;
 }

package/src/cli/tui/install.js

@@ -6,6 +6,7 @@ import * as clackModule from '@clack/prompts';
 import { readFile } from 'node:fs/promises';
 import { freshInstall, forceInstall } from '../install.js';
 import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../plantuml.js';
+import { renderBrandStrip } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_INSTALL_FAILED = 1;
@@ -20,7 +21,8 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   }
 
   const version = await readPackageVersion();
-  prompts.intro(`create-baseline v${version}`);
+  process.stdout.write(renderBrandStrip({ version, subtitle: 'install' }));
+  prompts.intro('create-baseline');
 
   const spinner = prompts.spinner();
   spinner.start('Copying baseline files');

package/src/cli/tui/meta.js

@@ -1,24 +1,30 @@
-// Domain — branded renderers for the meta commands (--help, --version).
-// In a TTY, a brand banner frames the canonical body; in non-TTY the body is
-// emitted unchanged so that piped consumers (`$(cli --version)`, `cli --help |
-// grep ...`) keep working byte-clean.
+// Domain — branded renderers for the meta commands (--help, --version) and
+// for usage-class errors. In a TTY, the splash marquee (wordmark + brand
+// strip from splash.js) frames the canonical body; in non-TTY the body is
+// emitted unchanged so that piped consumers (`$(cli --version)`,
+// `cli --help | grep ...`) keep working byte-clean.
 
-import { accent, muted, rule } from './tokens.js';
+import { accent, muted, rule, error as errorPaint } from './tokens.js';
+import {
+  renderSplash,
+  renderBrandStrip,
+  renderVersionMarquee,
+  wordmarkFits,
+} from './splash.js';
 
-export function renderHelp(helpText, version) {
-  if (!process.stdout.isTTY) {
-    process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+const DISCOVER_URL = 'https://baseline.friedbotstudio.com/';
+
+export function renderHelp(helpText, _version) {
+  const body = helpText.endsWith('\n') ? helpText : helpText + '\n';
+  if (!process.stdout.isTTY || !wordmarkFits()) {
+    process.stdout.write(body);
     return;
   }
-  const banner = [
-    '',
-    `  ${accent('Baseline CLI')}  ${muted(`v${version}`)}`,
-    `  ${muted('@friedbotstudio/create-baseline')}`,
-    `  ${rule('─'.repeat(48))}`,
-    '',
-  ].join('\n');
-  process.stdout.write(banner + '\n');
-  process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+  process.stdout.write(renderSplash({
+    tryLine: 'npx @friedbotstudio/create-baseline ./my-project',
+    discoverUrl: DISCOVER_URL,
+  }));
+  process.stdout.write(body);
 }
 
 export function renderVersion(version) {
@@ -26,5 +32,32 @@ export function renderVersion(version) {
     process.stdout.write(`${version}\n`);
     return;
   }
-  process.stdout.write(`${accent('baseline')} ${muted('v')}${version}\n`);
+  if (wordmarkFits()) {
+    process.stdout.write(renderVersionMarquee(version));
+    return;
+  }
+  process.stdout.write(renderBrandStrip({ version }));
+}
+
+// Usage errors always print to stderr (so a `cli ... 2>/dev/null` pipeline
+// can still consume stdout cleanly). In a TTY we wrap the message and the
+// HELP_TEXT body in the same brand banner used by --help, with the error
+// label painted in --mac-red. In non-TTY we emit a plain `Error: <msg>`
+// line followed by the canonical help body — same body, no ANSI.
+export function renderUsageError(msg, helpText, version) {
+  const body = helpText.endsWith('\n') ? helpText : helpText + '\n';
+  if (!process.stderr.isTTY) {
+    process.stderr.write(`Error: ${msg}\n`);
+    process.stderr.write(body);
+    return;
+  }
+  const banner = [
+    '',
+    `  ${errorPaint('Error')}  ${msg}`,
+    `  ${muted(`@friedbotstudio/create-baseline v${version}`)}`,
+    `  ${rule('─'.repeat(48))}`,
+    '',
+  ].join('\n');
+  process.stderr.write(banner + '\n');
+  process.stderr.write(body);
 }

package/src/cli/tui/splash.js

@@ -0,0 +1,111 @@
+// Domain — branded splash surfaces for the CLI. Renders a chunky pixel-art
+// "BASELINE" wordmark in three bands of FBS orange (bevel: shadow / mid /
+// highlight / mid / shadow) so the marquee surfaces (--help, --version,
+// no-arg landing) share a single visual identity. Slimmer brand strip is
+// reused by install / upgrade intros and inside the usage-error renderer.
+//
+// All renderers degrade cleanly when stdout is not a TTY or NO_COLOR is set
+// (paintRGB short-circuits to plain text). When the terminal is narrower
+// than the wordmark, callers should fall through to the plain banner via
+// `wordmarkFits(width)` instead of letting the glyphs wrap.
+
+import { paintRGB, PALETTE, accent, muted } from './tokens.js';
+
+// ANSI-Shadow style block-letter wordmark for "BASELINE". 5 rows × ~60 cols.
+// Kept as raw strings (not paint-wrapped) so renderWordmark can apply a
+// per-row shade. Trailing spaces matter — they're part of the glyph shape.
+const WORDMARK = [
+  '██████   █████  ███████ ███████ ██      ██ ███    ██ ███████',
+  '██   ██ ██   ██ ██      ██      ██      ██ ████   ██ ██     ',
+  '██████  ███████ ███████ █████   ██      ██ ██ ██  ██ █████  ',
+  '██   ██ ██   ██      ██ ██      ██      ██ ██  ██ ██ ██     ',
+  '██████  ██   ██ ███████ ███████ ███████ ██ ██   ████ ███████',
+];
+
+// Outline trace — mirrors the bottom row of the wordmark using the upper
+// one-eighth block (▔) so it visually kisses the base of every letter,
+// producing the subtle "letters are sitting on a baseline" shadow from
+// the skills.sh reference. Painted in accentShadow so it reads as a
+// trace, not a fifth band of the letter body.
+const WORDMARK_OUTLINE = WORDMARK[4].replace(/█/g, '▔');
+
+// Bevel banding: dim → mid → bright → mid → dim. Produces the chiseled
+// pixel-art look of the skills.sh reference (substituting FBS oranges for
+// the reference's grayscale palette).
+const SHADES = [
+  PALETTE.accentShadow,
+  PALETTE.accent,
+  PALETTE.accentLight,
+  PALETTE.accent,
+  PALETTE.accentShadow,
+];
+
+const WORDMARK_WIDTH = Math.max(...WORDMARK.map((row) => row.length));
+
+export const SPLASH_COMMANDS = Object.freeze([
+  ['$ npx @friedbotstudio/create-baseline <target>', 'Install the baseline'],
+  ['$ npx @friedbotstudio/create-baseline upgrade',  'Three-way merge upgrade'],
+  ['$ npx @friedbotstudio/create-baseline doctor',   'Drift report'],
+]);
+
+// `process.stdout.columns` is 0 (not undefined) under `script(1)` and some
+// CI ptys; treat any falsy value as "unknown, assume wide enough" so the
+// marquee renders rather than silently degrading to the plain banner.
+export function wordmarkFits(columns) {
+  const cols = columns ?? process.stdout.columns;
+  if (!cols) return true;
+  return cols >= WORDMARK_WIDTH;
+}
+
+export function renderWordmark() {
+  const bands = WORDMARK.map((row, i) => paintRGB(SHADES[i], row));
+  bands.push(paintRGB(PALETTE.accentShadow, WORDMARK_OUTLINE));
+  return bands.join('\n');
+}
+
+// Full marquee splash. Used by --help in TTY and the no-arg landing. The
+// version is intentionally NOT rendered here — `--version` already surfaces
+// it via renderVersionMarquee, and embedding it in the splash would force
+// docs-site screenshots to re-render every release.
+export function renderSplash({ tagline, tryLine, discoverUrl } = {}) {
+  const lines = [
+    '',
+    `${muted('▲')} ${muted('~/')} ${muted('npx @friedbotstudio/create-baseline@latest')}`,
+    '',
+    renderWordmark(),
+    '',
+    muted(tagline ?? 'The Claude Code baseline — hooks, skills, MCP, governance.'),
+    '',
+  ];
+  for (const [cmd, desc] of SPLASH_COMMANDS) {
+    const left = `  ${cmd}`;
+    lines.push(`${left.padEnd(54)}${muted(desc)}`);
+  }
+  if (tryLine) {
+    lines.push('');
+    lines.push(`${muted('try:')} ${tryLine}`);
+  }
+  if (discoverUrl) {
+    lines.push('');
+    lines.push(`${muted('Discover more at')} ${discoverUrl}`);
+  }
+  lines.push('');
+  lines.push(`${muted('▲')} ${muted('~/')}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Slim two-line brand strip. Used by install / upgrade intros, --version,
+// and the top of the usage-error renderer. Cheap and width-safe (~32 cols).
+export function renderBrandStrip({ version, subtitle } = {}) {
+  const left = `${accent('▲ BASELINE')}`;
+  const right = version ? `  ${muted(`v${version}`)}` : '';
+  const sub = subtitle ? `\n  ${muted(subtitle)}` : '';
+  return ['', `${left}${right}${sub}`, ''].join('\n');
+}
+
+// --version flourish: the wordmark + a version line. Wider than the strip;
+// callers should fall back to renderBrandStrip when the terminal is narrow.
+export function renderVersionMarquee(version) {
+  return ['', renderWordmark(), '', `  ${muted(`v${version}`)}`, ''].join('\n');
+}

package/src/cli/tui/tokens.js

@@ -6,6 +6,7 @@
 const NO_COLOR = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '';
 
 // oklch -> approximate sRGB hex used in the rendered docs site:
+//   --accent-shadow oklch(35% 0.15 41.5)   ~ #7a2907   (dark band of the wordmark bevel)
 //   --accent       oklch(55.8% 0.187 41.5) ~ #c2410c   (orange-700)
 //   --accent-light oklch(70.3% 0.187 41.5) ~ #ea6a25   (orange-500)
 //   --muted        oklch(45% 0.026 257)    ~ #6b7280
@@ -14,6 +15,7 @@ const NO_COLOR = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !==
 //   --mac-red      oklch(70% 0.21 24)      ~ #ef4444
 //   --rule         oklch(89% 0.013 257)    ~ #d1d5db
 const RGB = {
+  accentShadow: [122, 41, 7],
   accent: [194, 65, 12],
   accentLight: [234, 106, 37],
   muted: [107, 114, 128],
@@ -23,16 +25,21 @@ const RGB = {
   rule: [209, 213, 219],
 };
 
-function paint(rgb, text) {
+// Exposed for the splash wordmark, which paints individual rows in their own
+// shade. All other UI tokens funnel through the named helpers below.
+export function paintRGB(rgb, text) {
   if (NO_COLOR || !process.stdout.isTTY) return text;
   const [r, g, b] = rgb;
   return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
 }
 
-export const accent = (text) => paint(RGB.accent, text);
-export const accentLight = (text) => paint(RGB.accentLight, text);
-export const muted = (text) => paint(RGB.muted, text);
-export const success = (text) => paint(RGB.success, text);
-export const warn = (text) => paint(RGB.warn, text);
-export const error = (text) => paint(RGB.error, text);
-export const rule = (text) => paint(RGB.rule, text);
+export const PALETTE = Object.freeze(RGB);
+
+export const accentShadow = (text) => paintRGB(RGB.accentShadow, text);
+export const accent = (text) => paintRGB(RGB.accent, text);
+export const accentLight = (text) => paintRGB(RGB.accentLight, text);
+export const muted = (text) => paintRGB(RGB.muted, text);
+export const success = (text) => paintRGB(RGB.success, text);
+export const warn = (text) => paintRGB(RGB.warn, text);
+export const error = (text) => paintRGB(RGB.error, text);
+export const rule = (text) => paintRGB(RGB.rule, text);

package/src/cli/tui/upgrade.js

@@ -1,28 +1,40 @@
-// Domain — branded upgrade flow with interactive per-file conflict resolution.
+// Domain — branded upgrade flow with three-tier merge orchestration.
 // Plan/apply split:
-//   1. dry-run threeWayMerge → enumerate SKIP_CUSTOMIZED conflicts
-//   2. prompt the user once per conflict
-//   3. on cancel/abort: bail before any write
-//   4. on resolve: real threeWayMerge with onSkipCustomized backed by the Map
+//   1. detect pending semantic-merge stage (idempotency short-circuit, AC-007)
+//   2. dry-run threeWayMerge → enumerate SKIP_CUSTOMIZED conflicts (tier-1 only)
+//   3. prompt the user once per tier-1 conflict (with Show-diff loop, cap-at-2)
+//   4. on cancel/abort: bail before any write
+//   5. on resolve: real threeWayMerge with onSkipCustomized backed by the Map.
+// Tier-2 MECHANICAL and tier-3 SEMANTIC files are NOT prompted — they're
+// dispatched by the merge engine via upgrade-tiers.dispatchByTier.
 
 import * as clackModule from '@clack/prompts';
 import { existsSync } from 'node:fs';
-import { readdir } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { threeWayMerge, ACTION_KINDS } from '../merge.js';
 import { loadManifest, buildManifestFromDir } from '../manifest.js';
+import { COPY_EXCLUDE } from '../install.js';
+import { findPendingStage } from '../upgrade-tiers.js';
+import { renderUnifiedDiff } from '../diff-render.js';
+import { renderBrandStrip } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_ABORT = 1;
 const ERR_NO_MANIFEST = 2;
 const ERR_DIVERGENCE = 3;
+const ERR_MECHANICAL_CONFLICTED = 4;
+const ERR_SEMANTIC_STAGED = 5;
 
 const CHOICE_OPTIONS = [
-  { value: 'keep-mine', label: 'Keep mine', hint: 'preserve target file as-is' },
-  { value: 'take-theirs', label: 'Take theirs', hint: 'overwrite with new baseline' },
+  { value: 'keep-mine', label: 'Keep your version', hint: 'preserve target file as-is' },
+  { value: 'take-theirs', label: 'Use new baseline', hint: 'overwrite with new template' },
+  { value: 'show-diff', label: 'Show diff', hint: 'render local vs incoming and re-prompt' },
   { value: 'abort', label: 'Abort', hint: 'exit without changes' },
 ];
 
+const SHOW_DIFF_CONSECUTIVE_CAP = 2;
+
 export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   if (!target || typeof target !== 'string') {
     throw new Error('tui.upgrade.run requires a non-empty string target');
@@ -37,28 +49,31 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
     return ERR_NO_MANIFEST;
   }
 
+  const version = await readPackageVersion();
+  process.stdout.write(renderBrandStrip({ version, subtitle: 'upgrade' }));
   prompts.intro('create-baseline upgrade');
 
+  const pending = await findPendingStage(target);
+  if (pending) return reportPendingStage(prompts, pending);
+
   const { oldManifest, newManifest } = await loadManifests(opts.templateDir, manifestPath);
+  if (isLegacyManifest(oldManifest)) {
+    prompts.log.warn('legacy manifest_version: 1 detected; BASE-content recovery unavailable. Tier-2 / tier-3 files will fall back to the binary prompt.');
+  }
+
   const dryReport = await threeWayMerge(opts.templateDir, target, oldManifest, newManifest, { dryRun: true });
   const conflicts = dryReport.actions.filter((a) => a.kind === ACTION_KINDS.SKIP_CUSTOMIZED);
 
   const choices = new Map();
-  for (const conflict of conflicts) {
-    const choice = await prompts.select({
-      message: `${conflict.path} has been customized — choose:`,
-      options: CHOICE_OPTIONS,
-    });
-    if (prompts.isCancel(choice) || choice === 'abort') {
-      prompts.cancel('Upgrade aborted; tree unchanged.');
-      return ERR_ABORT;
-    }
-    choices.set(conflict.path, choice);
+  const aborted = await collectUserChoices(prompts, conflicts, opts.templateDir, target, choices);
+  if (aborted) {
+    prompts.cancel('Upgrade aborted; tree unchanged.');
+    return ERR_ABORT;
   }
 
   if (opts.dryRun) {
     for (const action of dryReport.actions) {
-      prompts.log.info(`${action.kind.padEnd(24)} ${action.path}`);
+      prompts.log.info(`${action.kind.padEnd(28)} ${action.path}`);
     }
     prompts.outro('Dry run complete; no changes written.');
     return SUCCESS;
@@ -67,10 +82,79 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   const onSkipCustomized = (rel) => choices.get(rel) ?? 'keep-mine';
   const finalReport = await threeWayMerge(opts.templateDir, target, oldManifest, newManifest, { onSkipCustomized });
 
+  for (const action of finalReport.actions) {
+    if (isReportableAction(action.kind)) {
+      prompts.log.info(`${action.kind.padEnd(28)} ${action.path}`);
+    }
+    if (action.kind === ACTION_KINDS.MECHANICAL_MERGE_CONFLICTED) {
+      prompts.log.warn(`Merged with conflicts — resolve in ${action.path}`);
+    }
+  }
+
+  const stagedCount = finalReport.actions.filter((a) => a.kind === ACTION_KINDS.SEMANTIC_MERGE_STAGED).length;
+  if (stagedCount > 0) {
+    prompts.log.info(`${stagedCount} file(s) need semantic merge. Open Claude Code and run /upgrade-project to reconcile.`);
+  }
+
   const applied = finalReport.actions.filter((a) => isApplied(a.kind)).length;
   const skipped = finalReport.actions.filter((a) => a.kind === ACTION_KINDS.SKIP_CUSTOMIZED).length;
   prompts.outro(`Applied ${applied}; ${skipped} skipped.`);
-  return finalReport.exitCode === 3 ? ERR_DIVERGENCE : SUCCESS;
+  return mapExitCode(finalReport.exitCode);
+}
+
+function reportPendingStage(prompts, pending) {
+  const fileLines = pending.files.map((f) => `  - ${f}`).join('\n');
+  prompts.log.warn(`Pending semantic-merge stage at ${pending.stage_ts}.\n${pending.files.length} file(s) awaiting reconciliation:\n${fileLines}\nOpen Claude Code and run /upgrade-project to reconcile.`);
+  prompts.outro('No new work; existing stage pending.');
+  return ERR_SEMANTIC_STAGED;
+}
+
+function isLegacyManifest(m) {
+  if (!m) return false;
+  if (m.manifest_version === 1) return true;
+  return typeof m.baseline_version !== 'string';
+}
+
+async function collectUserChoices(prompts, conflicts, templateDir, target, choices) {
+  for (const conflict of conflicts) {
+    const choice = await pickForFile(prompts, conflict.path, templateDir, target);
+    if (choice === 'abort') return true;
+    if (choice !== null) choices.set(conflict.path, choice);
+  }
+  return false;
+}
+
+async function pickForFile(prompts, rel, templateDir, target) {
+  let consecutiveShowDiff = 0;
+  while (true) {
+    const choice = await prompts.select({
+      message: `${rel} has been customized — choose:`,
+      options: CHOICE_OPTIONS,
+    });
+    if (prompts.isCancel(choice)) return 'abort';
+    if (choice !== 'show-diff') return choice;
+    await renderConflictDiff(prompts, rel, templateDir, target);
+    consecutiveShowDiff++;
+    if (consecutiveShowDiff >= SHOW_DIFF_CONSECUTIVE_CAP) {
+      prompts.log.info(`Show-diff picked ${SHOW_DIFF_CONSECUTIVE_CAP} times for ${rel}; falling through (keeping your version). Re-run if you want to choose differently.`);
+      return null;
+    }
+  }
+}
+
+async function renderConflictDiff(prompts, rel, templateDir, target) {
+  const localBytes = await readFile(join(target, rel), 'utf8');
+  const incomingBytes = await readFile(join(templateDir, rel), 'utf8');
+  const diff = renderUnifiedDiff(localBytes, incomingBytes, { colorize: process.stdout.isTTY === true });
+  prompts.log.info(`Diff for ${rel} (local → incoming):\n${diff}`);
+}
+
+function isReportableAction(kind) {
+  return (
+    kind === ACTION_KINDS.MECHANICAL_MERGE_CLEAN ||
+    kind === ACTION_KINDS.MECHANICAL_MERGE_CONFLICTED ||
+    kind === ACTION_KINDS.SEMANTIC_MERGE_STAGED
+  );
 }
 
 function isApplied(kind) {
@@ -79,22 +163,54 @@ function isApplied(kind) {
     kind === ACTION_KINDS.OVERWRITE ||
     kind === ACTION_KINDS.PRUNE ||
     kind === ACTION_KINDS.SPECIAL_MERGE ||
-    kind === ACTION_KINDS.NEVER_TOUCH_ADD
+    kind === ACTION_KINDS.NEVER_TOUCH_ADD ||
+    kind === ACTION_KINDS.MECHANICAL_MERGE_CLEAN
   );
 }
 
+function mapExitCode(mergeExit) {
+  if (mergeExit === 5) return ERR_SEMANTIC_STAGED;
+  if (mergeExit === 4) return ERR_MECHANICAL_CONFLICTED;
+  if (mergeExit === 3) return ERR_DIVERGENCE;
+  return SUCCESS;
+}
+
 async function loadManifests(templateDir, manifestPath) {
   const oldManifest = await loadManifest(manifestPath);
   const tplFiles = await listShippedFiles(templateDir);
   const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  await overlayShippedTiers(templateDir, newManifest);
   return { oldManifest, newManifest };
 }
 
+async function overlayShippedTiers(templateDir, newManifest) {
+  const shippedPath = join(templateDir, '.claude/manifest.json');
+  if (!existsSync(shippedPath)) return;
+  const shipped = JSON.parse(await readFile(shippedPath, 'utf8'));
+  if (!shipped?.files) return;
+  for (const rel of Object.keys(newManifest.files)) {
+    const shippedEntry = shipped.files[rel];
+    if (shippedEntry && typeof shippedEntry === 'object' && typeof shippedEntry.tier === 'string') {
+      newManifest.files[rel] = { sha256: newManifest.files[rel], tier: shippedEntry.tier };
+    }
+  }
+}
+
+async function readPackageVersion() {
+  try {
+    const url = new URL('../../../package.json', import.meta.url);
+    const pkg = JSON.parse(await readFile(url, 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 async function listShippedFiles(root, base = root, acc = []) {
   for (const entry of await readdir(root, { withFileTypes: true })) {
     const full = join(root, entry.name);
     if (entry.isDirectory()) await listShippedFiles(full, base, acc);
     else if (entry.isFile()) acc.push(relative(base, full).split(sep).join('/'));
   }
-  return acc;
+  return acc.filter((p) => !COPY_EXCLUDE.includes(p));
 }