@friedbotstudio/create-baseline 0.5.0 → 0.7.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, canRecoverBase } from './upgrade-tiers.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
@@ -15,20 +16,70 @@ 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',
 });
 
+// User-facing labels for each ACTION_KIND. Surfaced in the per-file upgrade
+// report (TTY via `tui/upgrade.js`, non-TTY via `bin/cli.js dispatchUpgrade`).
+// Kept centralized so both paths render identically.
+export const ACTION_LABELS = Object.freeze({
+  ADD: 'add',
+  OVERWRITE: 'update',
+  NOOP: 'unchanged',
+  SKIP_CUSTOMIZED: 'kept yours',
+  PRUNE: 'removed (upstream)',
+  PRUNE_SKIPPED_CUSTOMIZED: 'kept yours (upstream removed)',
+  NEVER_TOUCH_PRESERVE: 'kept yours (never-touch)',
+  NEVER_TOUCH_ADD: 'add (never-touch)',
+  SPECIAL_MERGE: 'merged (.mcp.json deep-merge)',
+  MECHANICAL_MERGE_CLEAN: 'merged cleanly',
+  MECHANICAL_MERGE_CONFLICTED: 'merged with conflicts — resolve manually',
+  SEMANTIC_MERGE_STAGED: 'staged for /upgrade-project',
+});
+
+export const ACTION_LABEL_WIDTH = Math.max(...Object.values(ACTION_LABELS).map((s) => s.length));
+
 async function copyFile(src, dst) {
   await mkdir(dirname(dst), { recursive: true });
   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 +102,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 +127,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 +156,51 @@ 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) {
+      // When BASE recovery would fail (legacy manifest with no cache hit, no
+      // npm fallback), the real run will fall through to the binary prompt.
+      // Surface this file as SKIP_CUSTOMIZED at dry-run time so the TUI
+      // collects a user choice up front instead of silently keep-mine'ing it.
+      if (!canRecoverBase(rel, tierCtx.baseline_version, tierCtx.target)) {
+        return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: 'BASE unrecoverable; will prompt user' };
+      }
+      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/track-tasklist-materializer.js

@@ -0,0 +1,223 @@
+// Foundation — translate a workflows.jsonl Track record into a canonical
+// TaskList shape. Used by triage at workflow-seed time AND by the
+// byte-equivalent-migration tests (compared to golden fixtures).
+//
+// The returned shape is ordinal-positioned (1-indexed `ord`); `blockedBy`
+// references predecessor ordinals (NOT session task_ids). The runtime
+// caller (triage skill body, harness re-seed) translates ordinals to
+// TaskCreate-assigned task_ids at materialization time.
+//
+// Selector nodes resolve to their default alternate (the first alternate
+// with empty preconditions). Sub-track refs read the originating track's
+// `_allTracks` Map (attached by the validator) to find the target track.
+
+export function materializeTaskList(track, { slug, ctx } = {}) {
+  if (!slug) {
+    throw new Error('materializeTaskList requires a slug option (used for <slug> substitution in subjects/activeForms).');
+  }
+  const emitter = createEmitter(slug, track._allTracks ?? new Map(), ctx);
+  emitNodes(track.nodes, emitter);
+  return finalize(emitter);
+}
+
+function createEmitter(slug, allTracks, ctx) {
+  return {
+    slug,
+    allTracks,
+    ctx: ctx ?? null,
+    tasks: [],
+    idToOrd: new Map(),
+  };
+}
+
+function emitNodes(nodes, emitter) {
+  for (const node of nodes) {
+    emitNode(node, emitter);
+  }
+}
+
+function emitNode(node, emitter) {
+  if (node.type === 'selector') {
+    const chosen = evaluateAlternates(node, emitter.ctx);
+    if (!chosen) {
+      throw new Error(
+        `Selector node '${node.id}' has no alternate whose preconditions pass against the provided context. ` +
+        `Either provide a ctx that satisfies one alternate's preconditions, or declare an alternate with empty preconditions (unconditional default).`
+      );
+    }
+    emitAlternate(chosen, node, emitter);
+    return;
+  }
+  if (node.sub_track) {
+    expandSubTrack(node.sub_track, node, emitter);
+    return;
+  }
+  recordTask(node, emitter, []);
+}
+
+function emitAlternate(alternate, parentNode, emitter) {
+  if (alternate.sub_track) {
+    expandSubTrack(alternate.sub_track, parentNode, emitter);
+    return;
+  }
+  if (alternate.skill) {
+    const synthetic = {
+      id: parentNode.id,
+      type: 'task',
+      skill: alternate.skill,
+      depends_on: parentNode.depends_on || [],
+      blocks: parentNode.blocks || [],
+      can_parallel: false,
+      needs_user: false,
+    };
+    recordTask(synthetic, emitter, []);
+    return;
+  }
+  throw new Error(`Alternate on selector '${parentNode.id}' has neither skill nor sub_track.`);
+}
+
+function expandSubTrack(subTrackId, parentNode, emitter) {
+  const sub = emitter.allTracks.get(subTrackId);
+  if (!sub) {
+    throw new Error(`sub_track '${subTrackId}' referenced by node '${parentNode.id}' not found in _allTracks.`);
+  }
+  const parentDepends = parentNode.depends_on || [];
+  const beforeOrd = emitter.tasks.length;
+  for (const subNode of sub.nodes) {
+    const isEntry = !subNode.depends_on || subNode.depends_on.length === 0;
+    const effectiveDepends = isEntry ? parentDepends : subNode.depends_on;
+    recordTask(subNode, emitter, effectiveDepends);
+    if (emitter.tasks.length === beforeOrd + 1) {
+      emitter.idToOrd.set(parentNode.id, emitter.tasks[beforeOrd].ord);
+    }
+  }
+}
+
+function recordTask(node, emitter, effectiveDepends) {
+  const ord = emitter.tasks.length + 1;
+  emitter.idToOrd.set(node.id, ord);
+  emitter.tasks.push({
+    ord,
+    subject: deriveSubject(node, emitter.slug),
+    activeForm: deriveActiveForm(node),
+    metadata: deriveMetadata(node),
+    needs_user: !!node.needs_user,
+    can_parallel: !!node.can_parallel,
+    _dependsOnIds: effectiveDepends.length > 0 ? effectiveDepends : (node.depends_on || []),
+  });
+}
+
+function finalize(emitter) {
+  const out = [];
+  for (const task of emitter.tasks) {
+    const blockedBy = task._dependsOnIds
+      .map((id) => emitter.idToOrd.get(id))
+      .filter((ord) => typeof ord === 'number');
+    out.push({
+      ord: task.ord,
+      subject: task.subject,
+      activeForm: task.activeForm,
+      metadata: task.metadata,
+      needs_user: task.needs_user,
+      can_parallel: task.can_parallel,
+      blockedBy,
+    });
+  }
+  return out;
+}
+
+// evaluateAlternates walks the selector node's alternates in declaration order
+// and returns the first one whose preconditions all pass against ctx. When ctx
+// is null/undefined, only alternates with empty preconditions are eligible
+// (preserves the materialize-time-only default-fallback behavior used by tests
+// that don't pass a ctx — e.g., the byte-equivalent fixture comparison). When
+// ctx is provided, predicates evaluate against its fields:
+//   { isGit: bool, componentCount: int, userOverride: string|null,
+//     completed: string[], knownSkills: Set<string> }
+// Any predicate whose required field is absent in ctx evaluates false.
+function evaluateAlternates(selectorNode, ctx) {
+  const alts = selectorNode.alternates || [];
+  for (const alt of alts) {
+    const preconditions = Array.isArray(alt.preconditions) ? alt.preconditions : [];
+    if (preconditions.every((p) => evaluatePredicate(p, ctx))) {
+      return alt;
+    }
+  }
+  return null;
+}
+
+function evaluatePredicate(pred, ctx) {
+  if (!ctx) return false;
+  switch (pred.name) {
+    case 'requires_git':
+      return ctx.isGit === true;
+    case 'requires_user_override':
+      return typeof ctx.userOverride === 'string' && ctx.userOverride === pred.argument;
+    case 'requires_min_components': {
+      const n = parseInt(pred.argument, 10);
+      return Number.isFinite(n) && typeof ctx.componentCount === 'number' && ctx.componentCount >= n;
+    }
+    case 'requires_phase_completed':
+      return Array.isArray(ctx.completed) && ctx.completed.includes(pred.argument);
+    case 'requires_skill_present':
+      return ctx.knownSkills instanceof Set && ctx.knownSkills.has(pred.argument);
+    default:
+      return false;
+  }
+}
+
+const ACTIVE_FORM_OVERRIDES = Object.freeze({
+  tdd: 'Running TDD',
+  intake: 'Running intake',
+  scout: 'Running scout',
+  research: 'Running research',
+  spec: 'Running spec',
+  simplify: 'Running simplify',
+  security: 'Running security',
+  integrate: 'Running integrate',
+  document: 'Running document',
+  archive: 'Running archive',
+  'memory-flush': 'Running memory-flush',
+  changelog: 'Running changelog',
+  commit: 'Running commit',
+  chore: 'Running chore',
+  'swarm-plan': 'Running swarm-plan',
+  'swarm-dispatch': 'Running swarm-dispatch',
+});
+
+const CONSENT_GATE_SUBJECTS = Object.freeze({
+  'approve-spec': 'Wait for /approve-spec <path>',
+  'grant-commit': 'Wait for /grant-commit',
+  'approve-swarm': 'Wait for /approve-swarm <slug>',
+});
+
+const CONSENT_GATE_ACTIVE_FORMS = Object.freeze({
+  'approve-spec': 'Awaiting spec approval',
+  'grant-commit': 'Awaiting commit consent',
+  'approve-swarm': 'Awaiting swarm approval',
+});
+
+function deriveSubject(node, slug) {
+  if (node.needs_user) {
+    return CONSENT_GATE_SUBJECTS[node.id] ?? `Wait for /${node.id}`;
+  }
+  const skill = node.skill || node.id;
+  return `Run /${skill} for ${slug}`;
+}
+
+function deriveActiveForm(node) {
+  if (node.activeForm) return node.activeForm;
+  if (node.needs_user) {
+    return CONSENT_GATE_ACTIVE_FORMS[node.id] ?? `Awaiting /${node.id}`;
+  }
+  const skill = node.skill || node.id;
+  return ACTIVE_FORM_OVERRIDES[skill] ?? `Running ${skill}`;
+}
+
+function deriveMetadata(node) {
+  const phase = node.metadata?.phase ?? node.skill ?? node.id;
+  if (node.needs_user) {
+    return { phase, needs_user: true };
+  }
+  return { phase };
+}

package/src/cli/tui/upgrade.js

@@ -1,30 +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, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { threeWayMerge, ACTION_KINDS } from '../merge.js';
+import { threeWayMerge, ACTION_KINDS, ACTION_LABELS, ACTION_LABEL_WIDTH } from '../merge.js';
 import { loadManifest, buildManifestFromDir } from '../manifest.js';
 import { COPY_EXCLUDE } from '../install.js';
+import { findPendingStage, formatStageTimestamp } 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');
@@ -43,26 +53,28 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   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("Your previous install predates version-tracked manifests, so this upgrade can't perform automatic three-way merges on customized files. You'll be prompted to keep your version or take the new baseline for each customized file. To enable three-way merges next time, re-install with the latest baseline.");
+  }
+
   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}`);
+      const label = ACTION_LABELS[action.kind] ?? action.kind;
+      prompts.log.info(`${label.padEnd(ACTION_LABEL_WIDTH)}  ${action.path}`);
     }
     prompts.outro('Dry run complete; no changes written.');
     return SUCCESS;
@@ -71,10 +83,84 @@ 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)) {
+      const label = ACTION_LABELS[action.kind] ?? action.kind;
+      prompts.log.info(`${label.padEnd(ACTION_LABEL_WIDTH)}  ${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;
+  prompts.outro(
+    skipped === 0
+      ? `Applied ${applied} update(s).`
+      : `Applied ${applied} update(s); kept your version on ${skipped} customized file(s). Re-run \`create-baseline upgrade\` if you want to revisit those choices.`,
+  );
+  return mapExitCode(finalReport.exitCode);
+}
+
+function reportPendingStage(prompts, pending) {
+  const fileLines = pending.files.map((f) => `  - ${f}`).join('\n');
+  prompts.log.warn(`A previous upgrade staged ${pending.files.length} file(s) for Claude Code review (staged ${formatStageTimestamp(pending.stage_ts)}):\n${fileLines}\nOpen Claude Code and run /upgrade-project to reconcile.`);
+  prompts.outro('No new work; previous staged files still need reconciliation.');
+  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) {
@@ -83,17 +169,39 @@ 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);
@@ -110,10 +218,5 @@ async function listShippedFiles(root, base = root, acc = []) {
     if (entry.isDirectory()) await listShippedFiles(full, base, acc);
     else if (entry.isFile()) acc.push(relative(base, full).split(sep).join('/'));
   }
-  // COPY_EXCLUDE (single source of truth in install.js) now lists no paths —
-  // the shipped manifest moved into `.claude/manifest.json` so the recursive
-  // walk picks it up at the same path the consumer expects. The filter stays
-  // for forward-compat; if a future path needs to be kept out of the merge,
-  // add it to install.js → COPY_EXCLUDE in one place.
   return acc.filter((p) => !COPY_EXCLUDE.includes(p));
 }