@friedbotstudio/create-baseline 0.5.0 → 0.6.0

package/src/cli/tui/upgrade.js

@@ -1,9 +1,12 @@
-// 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';
@@ -12,19 +15,26 @@ 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');
@@ -43,26 +53,27 @@ 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('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;
@@ -71,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) {
@@ -83,17 +163,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 +212,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));
 }

package/src/cli/upgrade-tiers.js

@@ -0,0 +1,234 @@
+// Domain — tier dispatch + BASE-content recovery + semantic-merge staging.
+// Consumed by src/cli/merge.js's customized-file branch. See
+// docs/specs/upgrade-flow-rework.md §Behavior #2/#3/#4/#5/#6.
+
+import { mkdir, mkdtemp, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+
+export class NoBaseError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'NoBaseError';
+    this.kind = opts.kind ?? 'unknown';
+    this.rel = opts.rel ?? null;
+    if (opts.cause) this.cause = opts.cause;
+  }
+}
+
+export async function resolveBase(rel, baseline_version, target, opts = {}) {
+  const { oldManifest = null, pack = null } = opts;
+  const expectedSha = readExpectedSha(oldManifest, rel);
+  const cached = await readCacheIfPresent(target, rel);
+  if (cached) {
+    if (expectedSha && sha256(cached) === expectedSha) return cached;
+    if (expectedSha) {
+      throw new NoBaseError(`cache sha mismatch for ${rel}`, { kind: 'cache_sha_mismatch', rel });
+    }
+    return cached;
+  }
+  if (!baseline_version) {
+    throw new NoBaseError(`legacy manifest; cannot recover BASE for ${rel}`, { kind: 'legacy_manifest', rel });
+  }
+  const fetched = await fetchFromNpm(rel, baseline_version, pack);
+  if (expectedSha && sha256(fetched) !== expectedSha) {
+    throw new NoBaseError(`npm tarball sha mismatch for ${rel}`, { kind: 'npm_sha_mismatch', rel });
+  }
+  await writeCacheThrough(target, rel, fetched);
+  return fetched;
+}
+
+export async function findPendingStage(target) {
+  const stageRoot = join(target, '.claude/state/upgrade');
+  if (!existsSync(stageRoot)) return null;
+  const stages = await listSubdirs(stageRoot);
+  for (const ts of stages) {
+    const manifestPath = join(stageRoot, ts, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    const pending = await readPendingFiles(manifestPath);
+    if (pending.length > 0) return { stage_ts: ts, files: pending };
+  }
+  return null;
+}
+
+export async function dispatchByTier(rel, tier, ctx) {
+  if (tier === 'BINARY_PROMPT') {
+    return { kind: 'SKIP_CUSTOMIZED', path: rel, reason: 'tier BINARY_PROMPT: user prompt deferred' };
+  }
+  if (tier === 'MECHANICAL') return runMechanicalMerge(rel, ctx);
+  if (tier === 'SEMANTIC') return runSemanticStage(rel, ctx);
+  throw new Error(`unknown tier: ${tier}`);
+}
+
+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 });
+  await writeStageArtifact(stageDir, `${rel}.baseline-base`, baseBuf);
+  await writeStageArtifact(stageDir, `${rel}.baseline-incoming`, incomingBuf);
+  await appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, localBuf);
+}
+
+// --- foundation helpers ---
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+function readExpectedSha(oldManifest, rel) {
+  const entry = oldManifest?.files?.[rel];
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && typeof entry.sha256 === 'string') return entry.sha256;
+  return null;
+}
+
+async function readCacheIfPresent(target, rel) {
+  const cachePath = join(target, '.claude/.baseline-prior', rel);
+  if (!existsSync(cachePath)) return null;
+  return await readFile(cachePath);
+}
+
+async function writeCacheThrough(target, rel, bytes) {
+  const cachePath = join(target, '.claude/.baseline-prior', rel);
+  await mkdir(dirname(cachePath), { recursive: true });
+  await writeFile(cachePath, bytes);
+}
+
+async function fetchFromNpm(rel, baseline_version, packOverride) {
+  const packFn = packOverride ?? defaultPack;
+  const spec = `@friedbotstudio/create-baseline@${baseline_version}`;
+  let result;
+  try {
+    result = await packFn(spec);
+  } catch (err) {
+    throw new NoBaseError(`npm fetch failed for ${rel}: ${err.message}`, {
+      kind: 'npm_fetch_failed', rel, cause: err,
+    });
+  }
+  const bytes = await extractFromPackResult(result, rel);
+  if (!bytes) {
+    throw new NoBaseError(`npm tarball missing ${rel}`, { kind: 'npm_missing_file', rel });
+  }
+  return bytes;
+}
+
+async function defaultPack(spec) {
+  const mod = await import('libnpmpack');
+  const fn = mod.default ?? mod.pack ?? mod;
+  return fn(spec);
+}
+
+async function extractFromPackResult(result, rel) {
+  if (result instanceof Map) return result.get(rel) ?? null;
+  if (Buffer.isBuffer(result) || result instanceof Uint8Array) {
+    return extractFromTarball(Buffer.from(result), rel);
+  }
+  throw new Error(`unsupported pack result type: ${typeof result}`);
+}
+
+async function extractFromTarball(tarballBytes, rel) {
+  const tmp = await mkdtemp(join(tmpdir(), 'baseline-prior-extract-'));
+  const tmpRoot = resolve(tmp) + sep;
+  const result = spawnSync('tar', ['-xz', '-C', tmp, '-f', '-'], { input: tarballBytes });
+  if (result.status !== 0) {
+    throw new Error(`tar extract failed: ${(result.stderr || '').toString()}`);
+  }
+  const candidate = join(tmp, 'package', rel);
+  // Defense in depth: although bsdtar (macOS default) and GNU tar both refuse
+  // absolute paths and `..` components by default when extracting, validate
+  // the candidate resolves under tmp before reading. Refuses to follow a
+  // malicious tarball that somehow planted bytes outside the extraction root.
+  const resolved = resolve(candidate);
+  if (!resolved.startsWith(tmpRoot)) {
+    throw new NoBaseError(`tarball entry escapes extraction root: ${rel}`, { kind: 'tarball_path_traversal', rel });
+  }
+  if (!existsSync(resolved)) return null;
+  return await readFile(resolved);
+}
+
+async function listSubdirs(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+
+async function readPendingFiles(manifestPath) {
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    return (manifest.files || []).filter((f) => f.status === 'PENDING').map((f) => f.rel);
+  } catch {
+    return [];
+  }
+}
+
+// --- domain helpers ---
+
+async function runMechanicalMerge(rel, ctx) {
+  const base = await resolveBase(rel, ctx.baseline_version, ctx.target, {
+    oldManifest: ctx.oldManifest, pack: ctx.pack,
+  });
+  const remote = await readFile(join(ctx.templateDir, rel));
+  const localPath = join(ctx.target, rel);
+  const tmpBase = join(tmpdir(), `merge-base-${randomUUID()}`);
+  const tmpRemote = join(tmpdir(), `merge-remote-${randomUUID()}`);
+  await writeFile(tmpBase, base);
+  await writeFile(tmpRemote, remote);
+  const result = spawnSync('git', ['merge-file', '--diff3', localPath, tmpBase, tmpRemote], { encoding: 'utf8' });
+  await unlink(tmpBase).catch(() => {});
+  await unlink(tmpRemote).catch(() => {});
+  if (result.status === 0) {
+    return { kind: 'MECHANICAL_MERGE_CLEAN', path: rel, reason: 'git merge-file clean' };
+  }
+  if (typeof result.status === 'number' && result.status > 0 && result.status < 128) {
+    return { kind: 'MECHANICAL_MERGE_CONFLICTED', path: rel, hunks: result.status, reason: `${result.status} conflict hunk(s)` };
+  }
+  throw new Error(`git merge-file failed for ${rel}: status=${result.status} stderr=${(result.stderr || '').toString()}`);
+}
+
+async function runSemanticStage(rel, ctx) {
+  const base = await resolveBase(rel, ctx.baseline_version, ctx.target, {
+    oldManifest: ctx.oldManifest, pack: ctx.pack,
+  });
+  const remote = await readFile(join(ctx.templateDir, rel));
+  const local = await readFile(join(ctx.target, rel));
+  await writeStage(ctx, rel, base, remote, local);
+  return { kind: 'SEMANTIC_MERGE_STAGED', path: rel, reason: 'staged for /upgrade-project' };
+}
+
+async function writeStageArtifact(stageDir, rel, bytes) {
+  const dst = join(stageDir, rel);
+  await mkdir(dirname(dst), { recursive: true });
+  await writeFile(dst, bytes);
+}
+
+async function appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, localBuf) {
+  const manifestPath = join(stageDir, 'manifest.json');
+  const manifest = existsSync(manifestPath)
+    ? JSON.parse(await readFile(manifestPath, 'utf8'))
+    : newStageManifest(ctx);
+  manifest.files.push({
+    rel,
+    base_sha256: sha256(baseBuf),
+    incoming_sha256: sha256(incomingBuf),
+    local_sha256: sha256(localBuf),
+    status: 'PENDING',
+  });
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+function newStageManifest(ctx) {
+  return {
+    stage_version: 1,
+    slug: ctx.slug ?? 'upgrade',
+    created_at: new Date().toISOString(),
+    baseline_version_from: ctx.oldManifest?.baseline_version ?? 'unknown',
+    baseline_version_to: ctx.baseline_version ?? 'unknown',
+    files: [],
+  };
+}
+
+function stageTimestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}

package/src/seed.template.md

@@ -11,7 +11,7 @@
 
 **Mandatory binding language.** Each numbered section (§) below specifies a binding requirement for the baseline. Implementations SHALL conform; `CLAUDE.md` Articles SHALL reference the corresponding §; project amendments (per `CLAUDE.md` Art. X) SHALL NOT contradict any § here.
 
-The baseline turns soft engineering rules (no unauthorized commits, no stubs, no mocks of internal code, no self-approved specs) into structural guarantees enforced by write-boundary hooks. Eleven workflow phases plus one stripped-down chore track (skips TDD; runs verify + archive mandatorily, simplify/integrate/document conditionally), seventeen write/run-boundary guards plus four lifecycle hooks plus one input-boundary hook (twenty-two hook scripts total — twenty `.sh` + two `.mjs` after the JS-port pilot), thirty-seven skills, one subagent, and four consent gates. Decisions live in main context; the lone subagent (`swarm-worker`) executes pre-decided recipes in parallel worktrees during `/swarm-dispatch`. Every artifact is archived; every third-party API is looked up against live docs. Project memory accumulates across sessions in `.claude/memory/` — auto-extracted by a Stop hook, curated in main context via `/memory-flush`, self-healing via re-verification.
+The baseline turns soft engineering rules (no unauthorized commits, no stubs, no mocks of internal code, no self-approved specs) into structural guarantees enforced by write-boundary hooks. Eleven workflow phases plus one stripped-down chore track (skips TDD; runs verify + archive mandatorily, simplify/integrate/document conditionally), seventeen write/run-boundary guards plus four lifecycle hooks plus one input-boundary hook (twenty-two hook scripts total — twenty `.sh` + two `.mjs` after the JS-port pilot), thirty-eight skills, one subagent, and four consent gates. Decisions live in main context; the lone subagent (`swarm-worker`) executes pre-decided recipes in parallel worktrees during `/swarm-dispatch`. Every artifact is archived; every third-party API is looked up against live docs. Project memory accumulates across sessions in `.claude/memory/` — auto-extracted by a Stop hook, curated in main context via `/memory-flush`, self-healing via re-verification.
 
 ---
 
@@ -110,7 +110,7 @@ Applies to every language. Mappings for TSX, Node, Python, Go, Rust ship inside
 │   │   └── lib/common.sh       # shared helpers
 │   ├── agents/                 # 1 subagent: swarm-worker (rendered from src/agents/swarm-worker.template.md)
 │   ├── commands/               # 5 consent/bootstrap gates (user-only — structurally)
-│   ├── skills/                 # 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1)
+│   ├── skills/                 # 38 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) + maintenance (1)
 │   ├── memory/                 # project memory: 7 canonical files + _pending.md (gitignored body) + README.md
 │   └── state/                  # runtime: workflow.json, approvals, swarm plans, verdicts, logs
 ├── src/                        # pristine ship-time templates (overlay source for `npx @friedbotstudio/create-baseline`)
@@ -181,7 +181,7 @@ The baseline ships exactly one subagent. The architectural reason: subagents los
 
 **Automated re-rendering by `/init-project`.** Step 6.4 re-renders `swarm-worker.md` from the template, driven by the recommender's `additions.swarm_worker_skills`. The recommender does **not** propose new subagent types — only stack-skill additions for the existing worker. Specialization happens via skills loaded into the worker's context, not via parallel agent personas; new decision-making roles belong in skills, which run in main context.
 
-### §4.3 Skills (37)
+### §4.3 Skills (38)
 
 Each at `.claude/skills/<name>/SKILL.md`, frontmatter `name` + `description`, plus optional `template.md` (artifact skills) or helper scripts.
 
@@ -516,7 +516,7 @@ Seed-level requirement: no stale workflow artifacts in the working tree after co
 
 **Step 4:** Write `src/agents/swarm-worker.template.md` (canonical-body store, per §4.2) — the only subagent template. Then render `.claude/agents/swarm-worker.md` from it with default tokens. The template carries four tokens — `{{NAME}}`, `{{DESCRIPTION}}`, `{{SKILLS}}`, `{{ROLE_LINE}}`. Default `SKILLS` is the YAML list block `  - scenario\n  - implement` (the worker's two mandatory sub-skills). Render-parity holds at this stage. `/init-project` later re-renders the worker with stack-aware tokens when the recommender flags stack-specific skills to preload via `additions.swarm_worker_skills`.
 
-**Step 5:** Write `.claude/skills/` for the 37 skills (§4.3) — 29 workflow/worker/orchestration/memory/alt-track skills you author (the +1 over 28 is the `changelog` Phase 11.5 skill) plus 7 shared globals plus 1 audit skill. The breakdown: artifact drafting (4) + workflow phases (10) + phase workers (5: `scenario`, `implement`, `verify`, `prose`, `design-ui`) + spec helpers (4: `spec-lint`, `spec-render`, `spec-diagram-review`, `spec-traceability-review`) + orchestration (3: `harness`, `swarm-plan`, `swarm-dispatch`) + memory (1: `memory-flush`) + shared globals (7: `claude-automation-recommender`, `code-structure`, `humanizer`, `documentation`, `technical-tutorials`, `copywriting`, `impeccable`) + drift defender (1: `audit-baseline`) + alternate tracks (1: `chore`). The vendored `claude-automation-recommender` (Apache 2.0, from `claude-code-setup`), the writing/quality globals, and the design global ship unchanged with their licenses intact. Artifact skills (intake, brd, spec, rca) each ship a `template.md`. Helper scripts: swarm-plan gets `validate.sh`, swarm-dispatch gets `swarm_merge.sh`, spec-render gets `render.sh`, spec-lint gets `lint.sh`, archive gets `archive.sh`, audit-baseline gets `audit.sh`. All helper scripts `chmod +x`.
+**Step 5:** Write `.claude/skills/` for the 38 skills (§4.3) — 29 workflow/worker/orchestration/memory/alt-track skills you author (the +1 over 28 is the `changelog` Phase 11.5 skill) plus 7 shared globals plus 1 audit skill plus 1 maintenance skill. The breakdown: artifact drafting (4) + workflow phases (10) + phase workers (5: `scenario`, `implement`, `verify`, `prose`, `design-ui`) + spec helpers (4: `spec-lint`, `spec-render`, `spec-diagram-review`, `spec-traceability-review`) + orchestration (3: `harness`, `swarm-plan`, `swarm-dispatch`) + memory (1: `memory-flush`) + shared globals (7: `claude-automation-recommender`, `code-structure`, `humanizer`, `documentation`, `technical-tutorials`, `copywriting`, `impeccable`) + drift defender (1: `audit-baseline`) + alternate tracks (1: `chore`) + maintenance (1: `upgrade-project`). The vendored `claude-automation-recommender` (Apache 2.0, from `claude-code-setup`), the writing/quality globals, and the design global ship unchanged with their licenses intact. Artifact skills (intake, brd, spec, rca) each ship a `template.md`. Helper scripts: swarm-plan gets `validate.sh`, swarm-dispatch gets `swarm_merge.sh`, spec-render gets `render.sh`, spec-lint gets `lint.sh`, archive gets `archive.sh`, audit-baseline gets `audit.sh`. All helper scripts `chmod +x`.
 
 **Step 6:** Write `.claude/commands/*.md` for the 4 gates (§4.4). All carry `disable-model-invocation: true` as belt-and-braces; structural user-only is enforced by their directory.