@friedbotstudio/create-baseline 0.7.0 → 0.8.0

package/README.md

@@ -95,7 +95,7 @@ npx @friedbotstudio/create-baseline ./your-project
 npx @friedbotstudio/create-baseline ./your-project --force
 
 # Upgrade an existing install against a newer baseline version.
-# In a TTY, each tier-1 customised file becomes a keep-mine / take-theirs / abort
+# In a TTY, each tier-1 customised file prompts: keep-mine / take-theirs / merge / abort
 # prompt; tier-2 files auto-merge via `git merge-file --diff3`; tier-3 files
 # stage for the /upgrade-project Claude Code skill to reconcile. In CI / piped
 # stdout, every per-file action is reported with a user-facing label:

package/bin/cli.js

@@ -33,7 +33,9 @@ Upgrade:
   Replaces the prior --merge flag. Reads <target>/.claude/.baseline-manifest.json
   and runs a three-tier merge against the shipped template:
     - tier 1 (binary prompt): customized files prompt "Keep your version / Use
-      new baseline / Show diff" in TTY mode (exit 3 on any skipped).
+      new baseline / Merge / Abort" in TTY mode. "Merge" stages incoming bytes
+      under .claude/state/upgrade/<ts>/ for /upgrade-project to reconcile in
+      Claude Code (exit 5); "Keep your version" exits 3 on any skipped.
     - tier 2 (mechanical): files routed through git merge-file --diff3 with
       BASE recovered from .claude/.baseline-prior/ cache or npm fallback;
       clean merges land silently, conflicts surface with markers (exit 4).

package/obj/template/.claude/hooks/memory_session_start.sh

@@ -189,6 +189,30 @@ if pending_count > 0 and not active_workflow:
         'run `/memory-flush` to clear before starting new work.'
     )
 
+# Pending upgrade stages (tier1-merge-option AC-004 + AC-008). Scans
+# .claude/state/upgrade/*/manifest.json for entries with status: PENDING.
+# Fires regardless of active_workflow (design pick 2C): stages are stable
+# infrastructure debt, distinct from memory-candidate debt above.
+upgrade_pending = 0
+upgrade_root = root / '.claude/state/upgrade'
+if upgrade_root.is_dir():
+    for stage_manifest in upgrade_root.glob('*/manifest.json'):
+        try:
+            with open(stage_manifest) as f:
+                stage = json.load(f)
+        except Exception:
+            continue
+        for entry in stage.get('files', []):
+            if entry.get('status') == 'PENDING':
+                upgrade_pending += 1
+
+if upgrade_pending > 0:
+    noun = 'file' if upgrade_pending == 1 else 'files'
+    lines.append(
+        f'**{upgrade_pending} {noun} staged for /upgrade-project to reconcile** — '
+        'run `/upgrade-project` when ready.'
+    )
+
 lines.append('')
 lines.append(
     'Files are read on demand by the relevant skill (scout reads landmarks, research reads libraries, etc.). '

package/obj/template/.claude/manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest_version": 3,
-  "generated_at": "2026-05-21T16:49:56.519Z",
+  "generated_at": "2026-05-22T13:30:10.925Z",
   "files": {
     ".claude/agents/swarm-worker.md": {
       "sha256": "1735a220f268c9765cb22e0567b728803f2edd7776cbde51dd017a9f062ae41f",
@@ -83,7 +83,7 @@
       "tier": "MECHANICAL"
     },
     ".claude/hooks/memory_session_start.sh": {
-      "sha256": "76625781d6cec1dc0d069926adad65c30010b07b1c0e24a2ac441c2981d2ecb5",
+      "sha256": "ec03026919c3cfeb0bdb8e46d8ace19b23d93b5b21f1ebdb4f579e9c52293ac9",
       "tier": "MECHANICAL"
     },
     ".claude/hooks/memory_stop.sh": {
@@ -823,7 +823,7 @@
       "tier": "MECHANICAL"
     },
     ".claude/skills/upgrade-project/SKILL.md": {
-      "sha256": "15e7cc2bd2ad8a271854352a7aa6ce8afc864747657af0be1ec90d392a8ee648",
+      "sha256": "a8d31370b626bb2c5fb733cf3b1e210f66ade1de84007ad0b3a46e31d115687a",
       "tier": "MECHANICAL"
     },
     ".claude/skills/verify/SKILL.md": {
@@ -889,5 +889,5 @@
       "verify": "baseline"
     }
   },
-  "build_id": "gha-26240106828"
+  "build_id": "gha-26290648827"
 }

package/obj/template/.claude/skills/upgrade-project/SKILL.md

@@ -31,7 +31,7 @@ For each stage directory under `.claude/state/upgrade/`:
     "files": [
       {
         "rel": "docs/init/seed.md",
-        "base_sha256": "<hex>",
+        "base_sha256": "<hex>" | null,
         "incoming_sha256": "<hex>",
         "local_sha256": "<hex>",
         "status": "PENDING"
@@ -39,24 +39,35 @@ For each stage directory under `.claude/state/upgrade/`:
     ]
   }
   ```
-- For each entry in `files`, three artifacts are present:
-  - `<rel>.baseline-base` — the **BASE** content (the file as it was when the user last installed the baseline).
-  - `<rel>.baseline-incoming` — the **INCOMING** content (the file as it ships in the new baseline; INCOMING and REMOTE are the same thing).
+  `base_sha256` is the **per-entry classification discriminator**: a 64-hex string means the CLI staged a recoverable BASE (three-way reconciliation); the JSON value `null` means BASE was unrecoverable when the user picked Merge on the tier-1 prompt (two-way reconciliation). See [tier1-merge-option spec](../../../docs/specs/tier1-merge-option.md) §Design pick 1A.
+- For each entry, the staged artifacts are:
+  - `<rel>.baseline-incoming` — the **INCOMING** content. Always present.
+  - `<rel>.baseline-base` — the **BASE** content. Present iff `base_sha256` is a string; **absent** for BASE-less entries.
   - The LOCAL file remains at its real path inside the target tree (untouched by the CLI).
 
 ## Procedure
 
 1. **Discover the stage.** Read `.claude/state/upgrade/` and pick the most-recent stage directory whose manifest has at least one file with `status: PENDING` or `status: NEEDS_USER_INPUT`. If no such stage exists, tell the user "No pending stage to reconcile" and exit.
-2. **Per file**, in the order they appear in the stage manifest:
+2. **Per-entry classification** (binding). For each entry in the stage manifest, in declared order:
+   - If `entry.base_sha256` is a 64-hex string → **three-way reconciliation** (existing path; BASE was recoverable).
+   - If `entry.base_sha256` is `null` → **two-way reconciliation** (new path; BASE was unrecoverable when the user picked Merge on tier-1; the zero-drift renumbering rule does not apply because there is no BASE anchor to shift against).
+   - Any other value → apply the `NEEDS_USER_INPUT` fallback with reason `malformed-base-sha256`.
+3. **Three-way reconciliation** (BASE recoverable):
    - Read BASE, INCOMING, and LOCAL.
    - Reason about the three-way delta. Identify what changed between BASE → INCOMING (the upstream edit), what changed between BASE → LOCAL (the user edit), and where they conflict.
    - If both edits are textually non-overlapping, the CLI would have routed the file to tier 2 (mechanical merge). The fact that the file is in tier 3 means structural reconciliation is needed — most commonly: both sides inserted content at the same structural anchor (a new section, a new numbered article, a new TOC entry).
    - Apply the **zero-drift renumbering rule** below.
    - Write the reconciled bytes to the LOCAL path.
    - Update the stage manifest entry's `status` to `RECONCILED`.
-3. **Finalize the stage.** When every entry's status is `RECONCILED`, delete the stage directory (`rm -rf .claude/state/upgrade/<ts>/`). Report per-file status to the user.
+4. **Two-way reconciliation** (BASE-less; tier-1 Merge):
+   - Read INCOMING and LOCAL. Do NOT attempt to read `<rel>.baseline-base` — it is absent by construction.
+   - Reason about the two-way diff: which lines/sections in INCOMING are new bytes that should land in LOCAL, and which lines/sections in LOCAL are user-authored content that should be preserved.
+   - The **zero-drift renumbering rule does NOT apply** to two-way reconciliation — there is no BASE anchor to shift against, so "shift, never fold" cannot be evaluated. When LOCAL and INCOMING both add structural entries at the same anchor and you cannot determine which is user content vs baseline content without the BASE, apply the `NEEDS_USER_INPUT` fallback.
+   - Write the reconciled bytes to the LOCAL path.
+   - Update the stage manifest entry's `status` to `RECONCILED`.
+5. **Finalize the stage.** When every entry's status is `RECONCILED`, delete the stage directory (`rm -rf .claude/state/upgrade/<ts>/`). Report per-file status to the user.
 
-## The zero-drift renumbering rule (binding)
+## The zero-drift renumbering rule (binding for three-way only)
 
 When BASE → INCOMING adds a new structural entry (a new Article, a new section, a new numbered item) at position N, and BASE → LOCAL added the user's own entry at the same position N, you SHALL renumber the user's entry to the **next available** slot (N+1) — you SHALL **never fold** the user's entry into an existing baseline section.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friedbotstudio/create-baseline",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Node CLI scaffolder that materializes the Claude Code baseline (hooks, skills, commands, MCP servers, governance docs) into a target project, with branded interactive install / upgrade / doctor flows. Run via `npx @friedbotstudio/create-baseline <target>`.",
   "type": "module",
   "bin": {

package/src/cli/merge.js

@@ -1,10 +1,10 @@
-import { cp, mkdir, unlink } from 'node:fs/promises';
+import { cp, mkdir, readFile, unlink } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 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';
+import { dispatchByTier, NoBaseError, canRecoverBase, writeStageBaseless } from './upgrade-tiers.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
@@ -176,23 +176,33 @@ async function dispatchCustomized({ rel, newEntry, tierCtx, dryRun, onSkipCustom
       return await dispatchByTier(rel, tier, tierCtx);
     } catch (err) {
       if (err instanceof NoBaseError) {
-        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err });
+        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx, err });
       }
       throw err;
     }
   }
-  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath });
+  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx });
 }
 
-async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err = null }) {
+async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx, 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' };
   }
+  if (choice === 'merge') {
+    if (!dryRun) await stageBaselessMerge({ rel, tplPath, tgtPath, tierCtx });
+    return { kind: ACTION_KINDS.SEMANTIC_MERGE_STAGED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); staged for two-way merge` : 'tier-1 customized; staged for two-way merge' };
+  }
   return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); preserved` : 'target customized since last install' };
 }
 
+async function stageBaselessMerge({ rel, tplPath, tgtPath, tierCtx }) {
+  const incomingBuf = await readFile(tplPath);
+  const localBuf = await readFile(tgtPath);
+  await writeStageBaseless(tierCtx, rel, incomingBuf, localBuf);
+}
+
 function computeExitCode(actions) {
   let code = 0;
   for (const a of actions) {

package/src/cli/tui/upgrade.js

@@ -2,7 +2,9 @@
 // Plan/apply split:
 //   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)
+//   3. prompt the user once per tier-1 conflict: Keep your version / Use new
+//      baseline / Merge / Abort. The Merge pick stages incoming bytes for
+//      /upgrade-project to reconcile (tier1-merge-option spec).
 //   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
@@ -16,7 +18,6 @@ import { threeWayMerge, ACTION_KINDS, ACTION_LABELS, ACTION_LABEL_WIDTH } from '
 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;
@@ -29,12 +30,10 @@ const ERR_SEMANTIC_STAGED = 5;
 const CHOICE_OPTIONS = [
   { 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: 'merge', label: 'Merge', hint: 'stage incoming bytes for /upgrade-project to reconcile' },
   { 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');
@@ -65,7 +64,7 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   const conflicts = dryReport.actions.filter((a) => a.kind === ACTION_KINDS.SKIP_CUSTOMIZED);
 
   const choices = new Map();
-  const aborted = await collectUserChoices(prompts, conflicts, opts.templateDir, target, choices);
+  const aborted = await collectUserChoices(prompts, conflicts, choices);
   if (aborted) {
     prompts.cancel('Upgrade aborted; tree unchanged.');
     return ERR_ABORT;
@@ -95,7 +94,7 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   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.`);
+    prompts.log.info(`${stagedCount} file(s) staged. Open Claude Code and run /upgrade-project to reconcile.`);
   }
 
   const applied = finalReport.actions.filter((a) => isApplied(a.kind)).length;
@@ -121,38 +120,22 @@ function isLegacyManifest(m) {
   return typeof m.baseline_version !== 'string';
 }
 
-async function collectUserChoices(prompts, conflicts, templateDir, target, choices) {
+async function collectUserChoices(prompts, conflicts, choices) {
   for (const conflict of conflicts) {
-    const choice = await pickForFile(prompts, conflict.path, templateDir, target);
+    const choice = await pickForFile(prompts, conflict.path);
     if (choice === 'abort') return true;
-    if (choice !== null) choices.set(conflict.path, choice);
+    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}`);
+async function pickForFile(prompts, rel) {
+  const choice = await prompts.select({
+    message: `${rel} has been customized — choose:`,
+    options: CHOICE_OPTIONS,
+  });
+  if (prompts.isCancel(choice)) return 'abort';
+  return choice;
 }
 
 function isReportableAction(kind) {

package/src/cli/upgrade-tiers.js

@@ -86,14 +86,30 @@ export async function dispatchByTier(rel, tier, ctx) {
 }
 
 export async function writeStage(ctx, rel, baseBuf, incomingBuf, localBuf) {
-  if (!ctx.stageRunTs) ctx.stageRunTs = stageTimestamp();
-  const stageDir = join(ctx.target, '.claude/state/upgrade', ctx.stageRunTs);
-  await mkdir(stageDir, { recursive: true });
+  const stageDir = await ensureStageDir(ctx);
   await writeStageArtifact(stageDir, `${rel}.baseline-base`, baseBuf);
   await writeStageArtifact(stageDir, `${rel}.baseline-incoming`, incomingBuf);
   await appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, localBuf);
 }
 
+// BASE-less stage writer used by the tier-1 Merge pick (see
+// docs/specs/tier1-merge-option.md §Behavior #2 + design pick 1A). Unlike
+// writeStage, no BASE artifact is written and the manifest entry carries
+// base_sha256: null — the discriminator /upgrade-project reads to route to
+// two-way reconciliation.
+export async function writeStageBaseless(ctx, rel, incomingBuf, localBuf) {
+  const stageDir = await ensureStageDir(ctx);
+  await writeStageArtifact(stageDir, `${rel}.baseline-incoming`, incomingBuf);
+  await appendToStageManifest(stageDir, ctx, rel, null, incomingBuf, localBuf);
+}
+
+async function ensureStageDir(ctx) {
+  if (!ctx.stageRunTs) ctx.stageRunTs = stageTimestamp();
+  const stageDir = join(ctx.target, '.claude/state/upgrade', ctx.stageRunTs);
+  await mkdir(stageDir, { recursive: true });
+  return stageDir;
+}
+
 // --- foundation helpers ---
 
 function sha256(buf) {
@@ -232,7 +248,7 @@ async function appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, l
     : newStageManifest(ctx);
   manifest.files.push({
     rel,
-    base_sha256: sha256(baseBuf),
+    base_sha256: baseBuf === null ? null : sha256(baseBuf),
     incoming_sha256: sha256(incomingBuf),
     local_sha256: sha256(localBuf),
     status: 'PENDING',

package/src/cli/diff-render.js

@@ -1,54 +0,0 @@
-// Foundation — line-level unified-diff renderer used by the upgrade TUI's
-// "Show diff" prompt. Pure function; no IO, no side effects.
-
-const ANSI_RED = '\x1b[31m';
-const ANSI_GREEN = '\x1b[32m';
-const ANSI_RESET = '\x1b[0m';
-
-export function renderUnifiedDiff(localText, incomingText, opts = {}) {
-  const colorize = opts.colorize === true;
-  const ops = diffLines(splitLines(localText), splitLines(incomingText));
-  return ops.map((op) => renderOp(op, colorize)).join('\n');
-}
-
-function splitLines(text) {
-  return String(text).split('\n');
-}
-
-function renderOp(op, colorize) {
-  if (op.kind === 'context') return ' ' + op.line;
-  const marker = op.kind === 'remove' ? '-' : '+';
-  if (!colorize) return marker + op.line;
-  const color = op.kind === 'remove' ? ANSI_RED : ANSI_GREEN;
-  return color + marker + op.line + ANSI_RESET;
-}
-
-function diffLines(a, b) {
-  const m = a.length;
-  const n = b.length;
-  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      if (a[i - 1] === b[j - 1]) dp[i][j] = dp[i - 1][j - 1] + 1;
-      else dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
-    }
-  }
-  const ops = [];
-  let i = m;
-  let j = n;
-  while (i > 0 && j > 0) {
-    if (a[i - 1] === b[j - 1]) {
-      ops.push({ kind: 'context', line: a[i - 1] });
-      i--; j--;
-    } else if (dp[i - 1][j] >= dp[i][j - 1]) {
-      ops.push({ kind: 'remove', line: a[i - 1] });
-      i--;
-    } else {
-      ops.push({ kind: 'add', line: b[j - 1] });
-      j--;
-    }
-  }
-  while (i > 0) { ops.push({ kind: 'remove', line: a[i - 1] }); i--; }
-  while (j > 0) { ops.push({ kind: 'add', line: b[j - 1] }); j--; }
-  return ops.reverse();
-}