@friedbotstudio/create-baseline 0.8.1 → 0.8.2

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

@@ -1,6 +1,6 @@
 {
   "manifest_version": 3,
-  "generated_at": "2026-05-22T15:13:25.707Z",
+  "generated_at": "2026-05-22T21:02:04.729Z",
   "files": {
     ".claude/agents/swarm-worker.md": {
       "sha256": "1735a220f268c9765cb22e0567b728803f2edd7776cbde51dd017a9f062ae41f",
@@ -168,11 +168,11 @@
     },
     ".claude/memory/_pending.md": {
       "sha256": "ae6407956aadd998c17ad5ad7150dbb21ccf49cc3375efe25b2d2ffb61c0a92a",
-      "tier": "MECHANICAL"
+      "tier": "NEVER_TOUCH"
     },
     ".claude/memory/_resume.md": {
       "sha256": "7ef4da663edc2ea35d19167f776e94b3f925072e9d8388841c42c5c6b81fc2f5",
-      "tier": "MECHANICAL"
+      "tier": "NEVER_TOUCH"
     },
     ".claude/memory/backlog.md": {
       "sha256": "4e124b7ecee5aa0918fd6d9a3bb232a68c7feff6fcf916b8562ed6513715db71",
@@ -227,7 +227,7 @@
       "tier": "MECHANICAL"
     },
     ".claude/skills/audit-baseline/audit.sh": {
-      "sha256": "68011b46a05473237b9d1ce3d6c9c6d760b460e3416a749b2738504fbde6ab4f",
+      "sha256": "77c0f083f108cba4b5d3b049936323e189ebe5f434f0559888647ed3df97995f",
       "tier": "MECHANICAL"
     },
     ".claude/skills/audit-baseline/tests/fixtures/_pending_opener_only.md": {
@@ -823,7 +823,7 @@
       "tier": "MECHANICAL"
     },
     ".claude/skills/upgrade-project/SKILL.md": {
-      "sha256": "a8d31370b626bb2c5fb733cf3b1e210f66ade1de84007ad0b3a46e31d115687a",
+      "sha256": "f444667925baa4e4f054c7e23dfea5a0578077192cd3b7bc0838627e95387293",
       "tier": "MECHANICAL"
     },
     ".claude/skills/verify/SKILL.md": {
@@ -889,5 +889,5 @@
       "verify": "baseline"
     }
   },
-  "build_id": "gha-26295896640"
+  "build_id": "gha-26311755762"
 }

package/obj/template/.claude/skills/audit-baseline/audit.sh

@@ -781,7 +781,13 @@ docs_to_check = [
 for doc in docs_to_check:
     text = read_text(doc)
     if not text:
-        add(f"{doc} count claims", "WARN", "file not present")
+        # README.md is not shipped to consumer projects by the create-baseline
+        # CLI (only CLAUDE.md + docs/init/seed.md land at the consumer root).
+        # Its absence is the consumer-install case, not drift — silently skip.
+        # CLAUDE.md and seed.md are required baseline shipfiles; missing means
+        # real drift, so keep the WARN.
+        if doc != "README.md":
+            add(f"{doc} count claims", "WARN", "file not present")
         continue
 
     headline_drift = []   # confirmed stale headline claims

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

@@ -65,7 +65,20 @@ For each stage directory under `.claude/state/upgrade/`:
    - 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.
+5. **Record the reconciliation marker.** For every entry whose status just transitioned to `RECONCILED` (NOT `NEEDS_USER_INPUT`, NOT skipped under `--dry-run`), invoke the marker writer so the next `create-baseline upgrade` knows the user has already reviewed this file against the current template hash. From the skill terminal:
+
+   ```
+   node -e "import('./src/cli/reconciliation-marker.js').then(m => m.recordReconciliation('<target>', '<rel>', '<baseline_version_to>', '<incoming_sha256>'))"
+   ```
+
+   - `<target>` is the project root the skill is operating in (usually `.`).
+   - `<rel>` is the entry's `rel` field from the stage manifest.
+   - `<baseline_version_to>` is the stage manifest's top-level field of the same name.
+   - `<incoming_sha256>` is the entry's `incoming_sha256` field (the template hash this reconciliation was reviewed against).
+
+   The writer creates / updates `<target>/.claude/.baseline-reconciliations.json` atomically (write-then-rename). On filesystem error it throws `MarkerWriteError` — surface the error to the user but do NOT roll back the reconciled LOCAL bytes (LOCAL is already on disk and is the user-visible outcome). Marker is best-effort: the user can re-run `/upgrade-project` to re-record if the write was lost. See `docs/specs/upgrade-no-replay-prompts.md §Behavior #4` for the contract.
+
+6. **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 for three-way only)
 
@@ -93,6 +106,7 @@ When invoked with `args=dry-run` (e.g., `/upgrade-project dry-run`):
 - DO NOT modify any LOCAL file.
 - DO NOT update the stage manifest (statuses stay PENDING / NEEDS_USER_INPUT).
 - DO NOT delete the stage directory.
+- DO NOT call `recordReconciliation` — the marker would record a reconciliation the user never actually applied, causing the next upgrade to silently skip a file that still has unreviewed upstream changes. Dry-run is for preview only; the marker write happens exclusively on the real apply path.
 - Tell the user: "Dry-run complete. Re-run without `dry-run` to apply."
 
 Dry-run mode is for building trust in early use. After the first few successful reconciliations, the user typically stops dry-running.
@@ -111,7 +125,7 @@ Use this fallback sparingly. The rework's whole point is that LLM judgment excee
 ## Constraints
 
 - **Validate `rel` before writing.** Before writing reconciled bytes to LOCAL, you SHALL verify that the resolved absolute path of `<target>/<rel>` is a descendant of `target`. A `rel` value that escapes the target tree (`../`, absolute path, symlink-resolved escape) SHALL be rejected as a `NEEDS_USER_INPUT` fallback with the reason `path-traversal-rejected`. The CLI's stage writer never produces escaping `rel` values, so this catches only tampered stage manifests from a local attacker with `.claude/state/` write access — defense in depth.
-- **No write outside the stage directory and the LOCAL path.** You SHALL NOT touch `.claude/.baseline-prior/`, the installed `.baseline-manifest.json`, or any other CLI state.
+- **No write outside the stage directory, the LOCAL path, and the reconciliation marker.** You SHALL NOT touch `.claude/.baseline-prior/`, the installed `.baseline-manifest.json`, or any other CLI state. The single narrow exception is `.claude/.baseline-reconciliations.json`, written via the `recordReconciliation` foundation module per Procedure step 5 (post-RECONCILED, not in `--dry-run`). The marker write goes through that module's atomic write-then-rename so partial writes cannot corrupt the file.
 - **No partial writes per file.** The reconciled LOCAL must be the complete final content. If you cannot produce a complete reconciliation, use the NEEDS_USER_INPUT fallback and leave LOCAL unmodified.
 - **Honor Article XI of CLAUDE.md.** This skill only touches files explicitly staged by the CLI — which, by construction, are baseline-owned. User-added files at colliding paths are never staged.
 - **No commits.** Reconciled files land on the working tree; the user inspects via `git diff` and commits when satisfied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friedbotstudio/create-baseline",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "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/doctor.js

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { hashFile, loadManifest } from './manifest.js';
+import { MARKER_PATH_REL } from './reconciliation-marker.js';
 import { pathExists } from './util.js';
 
 const MANIFEST_REL = '.claude/.baseline-manifest.json';
@@ -84,12 +85,15 @@ export async function runDoctor(target, options = {}) {
   }
 
   // ADDED — files under .claude/ that aren't in the manifest. Excludes the
-  // manifest itself (it's written by the CLI post-install and is not self-referential).
+  // manifest itself (it's written by the CLI post-install and is not self-referential)
+  // and the reconciliation marker (per-target user state written by
+  // /upgrade-project; see docs/specs/upgrade-no-replay-prompts.md §Behavior #6).
   const added = [];
   const onDisk = await listFilesUnder(join(target, ADDED_SCAN_PREFIX));
   for (const rel of onDisk) {
     const full = `${ADDED_SCAN_PREFIX}/${rel}`;
     if (full === MANIFEST_REL) continue;
+    if (full === MARKER_PATH_REL) continue;
     if (!(full in manifest.files)) added.push(full);
   }
 

package/src/cli/install.js

@@ -14,6 +14,13 @@ export const NEVER_TOUCH = Object.freeze([
   '.claude/project.json',
   '.claude/workflows.jsonl',
   '.claude/schemas/workflow-track.v1.json',
+  // Runtime-state files: bodies are gitignored and overwritten every
+  // conversation turn by memory_stop.sh / memory_pre_compact.sh / /memory-flush.
+  // Their on-disk hash will essentially never match the shipped template hash,
+  // so any merge-time prompt is a structural false positive. Preserve silently.
+  // See docs/specs/upgrade-no-replay-prompts.md §Behavior #1.
+  '.claude/memory/_pending.md',
+  '.claude/memory/_resume.md',
 ]);
 export const SPECIAL_MERGE = Object.freeze(['.mcp.json']);
 // The shipped manifest now lives at `.claude/manifest.json` (inside the

package/src/cli/merge.js

@@ -5,11 +5,13 @@ import { deepMergeMcpServers } from './mcp.js';
 import { NEVER_TOUCH, SPECIAL_MERGE } from './install.js';
 import { pathExists } from './util.js';
 import { dispatchByTier, NoBaseError, canRecoverBase, writeStageBaseless } from './upgrade-tiers.js';
+import { readMarker, matchesReconciledHash } from './reconciliation-marker.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
   OVERWRITE: 'OVERWRITE',
   NOOP: 'NOOP',
+  MARKER_MATCHED: 'MARKER_MATCHED',
   SKIP_CUSTOMIZED: 'SKIP_CUSTOMIZED',
   PRUNE: 'PRUNE',
   PRUNE_SKIPPED_CUSTOMIZED: 'PRUNE_SKIPPED_CUSTOMIZED',
@@ -28,6 +30,7 @@ export const ACTION_LABELS = Object.freeze({
   ADD: 'add',
   OVERWRITE: 'update',
   NOOP: 'unchanged',
+  MARKER_MATCHED: 'already reconciled',
   SKIP_CUSTOMIZED: 'kept yours',
   PRUNE: 'removed (upstream)',
   PRUNE_SKIPPED_CUSTOMIZED: 'kept yours (upstream removed)',
@@ -69,6 +72,7 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
   const newFiles = newManifest?.files ?? {};
   const baseline_version = oldManifest?.baseline_version;
   const allPaths = new Set([...Object.keys(oldFiles), ...Object.keys(newFiles)]);
+  const marker = await readMarker(target);
 
   const tierCtx = {
     target,
@@ -127,6 +131,14 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     }
 
     if (newHash && tgtHash && tgtHash !== oldHash) {
+      if (matchesReconciledHash(marker, rel, newHash)) {
+        actions.push({
+          kind: ACTION_KINDS.MARKER_MATCHED,
+          path: rel,
+          reason: 'marker records reconciliation against this template hash; no re-stage',
+        });
+        continue;
+      }
       const action = await dispatchCustomized({
         rel, newEntry, tierCtx, dryRun, onSkipCustomized, tplPath, tgtPath,
       });

package/src/cli/reconciliation-marker.js

@@ -0,0 +1,108 @@
+// Foundation — per-target reconciliation marker for create-baseline upgrade.
+//
+// Records which template hash each customized file was reconciled against by
+// `/upgrade-project`, so subsequent `create-baseline upgrade` runs can skip
+// files the user has already reviewed. The marker lives at
+// <target>/.claude/.baseline-reconciliations.json (gitignore-by-default; see
+// docs/specs/upgrade-no-replay-prompts.md non-goal on consumer .gitignore).
+//
+// Consumed by: src/cli/merge.js (marker-consult branch in threeWayMerge).
+// Written by: /upgrade-project skill via the Bash interop the skill describes
+//   in its Procedure section (post-RECONCILED step).
+// Doctor: src/cli/doctor.js excludes this path from its `added` scan.
+
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const MARKER_REL = '.claude/.baseline-reconciliations.json';
+const SCHEMA_VERSION = 1;
+
+export class MarkerWriteError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'MarkerWriteError';
+    if (opts.cause) this.cause = opts.cause;
+  }
+}
+
+export async function readMarker(target) {
+  const path = join(target, MARKER_REL);
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    process.stderr.write(`reconciliation-marker: cannot read ${MARKER_REL}: ${err.message}\n`);
+    return null;
+  }
+  return parseMarker(text);
+}
+
+export async function recordReconciliation(target, rel, baseline_version, template_sha) {
+  const path = join(target, MARKER_REL);
+  const existing = (await readMarker(target)) ?? newMarker();
+  existing.reconciliations[rel] = {
+    baseline_version,
+    reconciled_against_template_sha: template_sha,
+    reconciled_at: new Date().toISOString(),
+  };
+  await atomicWriteJson(path, existing);
+}
+
+export function matchesReconciledHash(marker, rel, template_sha) {
+  if (!marker || !marker.reconciliations) return false;
+  const entry = marker.reconciliations[rel];
+  if (!entry) return false;
+  return entry.reconciled_against_template_sha === template_sha;
+}
+
+export const MARKER_PATH_REL = MARKER_REL;
+
+function newMarker() {
+  return { schema_version: SCHEMA_VERSION, reconciliations: {} };
+}
+
+function parseMarker(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    process.stderr.write(
+      `reconciliation-marker: malformed ${MARKER_REL} (invalid JSON): ${err.message}\n` +
+      `  To reset, delete the file: rm ${MARKER_REL}\n`,
+    );
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || typeof parsed.reconciliations !== 'object') {
+    process.stderr.write(
+      `reconciliation-marker: malformed ${MARKER_REL} (missing reconciliations object)\n` +
+      `  To reset, delete the file: rm ${MARKER_REL}\n`,
+    );
+    return null;
+  }
+  if (parsed.schema_version !== SCHEMA_VERSION) {
+    process.stderr.write(
+      `reconciliation-marker: unsupported schema_version=${parsed.schema_version} in ${MARKER_REL} ` +
+      `(this CLI understands schema_version=${SCHEMA_VERSION}); ignoring marker.\n` +
+      `  Either upgrade create-baseline, or delete the file: rm ${MARKER_REL}\n`,
+    );
+    return null;
+  }
+  return parsed;
+}
+
+async function atomicWriteJson(path, obj) {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  const body = JSON.stringify(obj, null, 2) + '\n';
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(tmp, body);
+    await rename(tmp, path);
+  } catch (err) {
+    throw new MarkerWriteError(
+      `cannot write ${MARKER_REL}: ${err.message}`,
+      { cause: err },
+    );
+  }
+}

package/src/cli/tui/doctor.js

@@ -4,8 +4,9 @@
 // formatReport — this renderer is only invoked when stdout is a TTY.
 
 import { accent, muted, success, warn, error, accentLight } from './tokens.js';
+import { renderHeader } from './splash.js';
 
-function brandHeader(target, manifestInfo) {
+function targetAndManifestLines(target, manifestInfo) {
   const lines = [accent('Baseline doctor')];
   if (target) lines.push(muted(`target:   ${target}`));
   if (manifestInfo) lines.push(muted(`manifest: ${manifestInfo}`));
@@ -13,13 +14,14 @@ function brandHeader(target, manifestInfo) {
 }
 
 export function render(report) {
+  process.stdout.write(renderHeader({ subtitle: 'doctor' }));
   if (report.error) {
-    const headerLines = brandHeader(report.target);
+    const headerLines = targetAndManifestLines(report.target);
     process.stdout.write(headerLines.join('\n') + '\n\n');
     process.stdout.write(`${error('doctor:')} ${report.error}\n`);
     return;
   }
-  const lines = brandHeader(report.target, `version ${report.manifestVersion}, installed ${report.generatedAt}`);
+  const lines = targetAndManifestLines(report.target, `version ${report.manifestVersion}, installed ${report.generatedAt}`);
   lines.push('');
   lines.push(`  ${success('matched')}:    ${report.matched.length}`);
   lines.push(`  ${accentLight('customized')}: ${report.customized.length}`);

package/src/cli/tui/install.js

@@ -6,7 +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';
+import { renderHeader } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_INSTALL_FAILED = 1;
@@ -21,7 +21,7 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   }
 
   const version = await readPackageVersion();
-  process.stdout.write(renderBrandStrip({ version, subtitle: 'install' }));
+  process.stdout.write(renderHeader({ version, subtitle: 'install' }));
   prompts.intro('create-baseline');
 
   const spinner = prompts.spinner();

package/src/cli/tui/splash.js

@@ -1,12 +1,16 @@
 // 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.
+// highlight / mid / shadow) so every command (--help, --version, no-arg
+// landing, install, upgrade, doctor) shares a single visual identity.
+// Install / upgrade / doctor use `renderHeader` (wordmark + tagline);
+// --version uses `renderVersionMarquee`; --help and the no-arg landing use
+// the full `renderSplash`; `renderBrandStrip` is the slim header reserved
+// for the usage-error renderer and as `renderHeader`'s narrow-terminal
+// fallback.
 //
 // 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
+// than the wordmark, callers fall through to the slim brand strip via
 // `wordmarkFits(width)` instead of letting the glyphs wrap.
 
 import { paintRGB, PALETTE, accent, muted } from './tokens.js';
@@ -95,8 +99,32 @@ export function renderSplash({ tagline, tryLine, discoverUrl } = {}) {
   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).
+// Wordmark + tagline header. Used by install / upgrade / doctor command
+// intros so every command shares the same branded surface as the no-arg
+// landing. Width-gated: when the terminal is narrower than the wordmark,
+// falls back to the slim brand strip so the header never wraps into
+// unreadable glyphs.
+export function renderHeader({ subtitle, version, columns } = {}) {
+  if (!wordmarkFits(columns)) return renderBrandStrip({ version, subtitle });
+  const lines = [
+    '',
+    `${muted('▲')} ${muted('~/')} ${muted('npx @friedbotstudio/create-baseline@latest')}`,
+    '',
+    renderWordmark(),
+    '',
+    muted('The Claude Code baseline — hooks, skills, MCP, governance.'),
+  ];
+  if (subtitle) {
+    lines.push('');
+    lines.push(muted(subtitle));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Slim two-line brand strip. Used by --version and the top of the
+// usage-error renderer (and as renderHeader's narrow-terminal fallback).
+// Cheap and width-safe (~32 cols).
 export function renderBrandStrip({ version, subtitle } = {}) {
   const left = `${accent('▲ BASELINE')}`;
   const right = version ? `  ${muted(`v${version}`)}` : '';

package/src/cli/tui/upgrade.js

@@ -18,7 +18,7 @@ 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 { renderBrandStrip } from './splash.js';
+import { renderHeader } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_ABORT = 1;
@@ -49,7 +49,7 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   }
 
   const version = await readPackageVersion();
-  process.stdout.write(renderBrandStrip({ version, subtitle: 'upgrade' }));
+  process.stdout.write(renderHeader({ version, subtitle: 'upgrade' }));
   prompts.intro('create-baseline upgrade');
 
   const pending = await findPendingStage(target);
@@ -57,7 +57,7 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   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.");
+    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. After you finish, run `/upgrade-project` in Claude Code on any staged files — the reconciliations are recorded so future upgrades silently skip files you've already reviewed against the current baseline.");
   }
 
   const dryReport = await threeWayMerge(opts.templateDir, target, oldManifest, newManifest, { dryRun: true });