@friedbotstudio/create-baseline 0.3.0 → 0.5.0

package/obj/template/.claude/skills/changelog/version-preview.mjs

@@ -0,0 +1,124 @@
+// Projected-version preview via semantic-release JS API.
+//
+// Returns { version, type, commits } where commits is the analyzer's list
+// of conventional-parsed commits between the last release tag and HEAD.
+
+import { execFileSync } from 'node:child_process';
+
+// Parse conventional-commit subject lines: type(scope)?: subject  +  breaking-suffix.
+function parseConventional(subject) {
+  const match = subject.match(/^([a-z]+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/i);
+  if (!match) return { type: 'unknown', scope: null, breaking: false, subject };
+  return {
+    type: match[1].toLowerCase(),
+    scope: match[2] || null,
+    breaking: Boolean(match[3]),
+    subject: match[4],
+  };
+}
+
+// List commits between the latest tag and HEAD via plain git (no semantic-release
+// dep needed for the commit list itself; semantic-release is only used for the
+// projected version computation).
+function listCommitsSinceLastTag(cwd) {
+  let lastTag;
+  try {
+    lastTag = execFileSync('git', ['describe', '--tags', '--abbrev=0'], {
+      cwd, encoding: 'utf8',
+    }).trim();
+  } catch {
+    lastTag = null;
+  }
+  const range = lastTag ? `${lastTag}..HEAD` : 'HEAD';
+  let raw;
+  try {
+    raw = execFileSync('git', ['log', range, '--format=%H%x09%s%x09%b%x00'], {
+      cwd, encoding: 'utf8',
+    });
+  } catch {
+    return [];
+  }
+  return raw.split('\0').filter(Boolean).map((entry) => {
+    const [sha, subject, body] = entry.split('\t');
+    const parsed = parseConventional(subject || '');
+    const breakingBody = /^BREAKING CHANGE:/m.test(body || '');
+    return {
+      sha,
+      subject: parsed.subject,
+      body: (body || '').trim(),
+      type: parsed.type,
+      scope: parsed.scope,
+      breaking: parsed.breaking || breakingBody,
+    };
+  });
+}
+
+// Use semantic-release's JS API to compute the next version.
+async function semanticReleaseDryRun(cwd) {
+  const mod = await import('semantic-release');
+  const semanticRelease = mod.default || mod;
+  const noopWritable = { write: () => true, end: () => {} };
+  const result = await semanticRelease(
+    {
+      dryRun: true,
+      ci: false,
+      branches: ['main', 'master'],
+    },
+    {
+      cwd,
+      env: { ...process.env },
+      stdout: noopWritable,
+      stderr: noopWritable,
+    },
+  );
+  if (result && result.nextRelease) {
+    return { version: result.nextRelease.version, type: result.nextRelease.type };
+  }
+  return { version: null, type: null };
+}
+
+// Fallback: derive a projection locally if semantic-release rejects the run
+// (e.g., no .releaserc.json, no remote, no commits since last tag).
+function localProjection(cwd, commits) {
+  let lastTag;
+  try {
+    lastTag = execFileSync('git', ['describe', '--tags', '--abbrev=0'], {
+      cwd, encoding: 'utf8',
+    }).trim();
+  } catch {
+    lastTag = 'v0.0.0';
+  }
+  const baseSemver = lastTag.replace(/^v/, '');
+  const baseParts = baseSemver.split('.').map((s) => parseInt(s, 10) || 0);
+  let bumpType = null;
+  for (const commit of commits) {
+    if (commit.breaking) { bumpType = bumpType === 'major' ? 'major' : 'minor'; continue; }
+    if (commit.type === 'feat') { bumpType = bumpType === 'major' ? 'major' : (bumpType === 'minor' ? 'minor' : 'minor'); continue; }
+    if (commit.type === 'fix' || commit.type === 'perf' || commit.type === 'refactor') {
+      if (!bumpType) bumpType = 'patch';
+    }
+  }
+  if (!bumpType) return { version: baseSemver, type: null };
+  const [maj, min, pat] = baseParts;
+  if (bumpType === 'major') return { version: `${maj + 1}.0.0`, type: 'major' };
+  if (bumpType === 'minor') return { version: `${maj}.${min + 1}.0`, type: 'minor' };
+  return { version: `${maj}.${min}.${pat + 1}`, type: 'patch' };
+}
+
+export async function previewProjectedVersion(cwd) {
+  const commits = listCommitsSinceLastTag(cwd);
+  let projection;
+  try {
+    projection = await semanticReleaseDryRun(cwd);
+    if (!projection.version) {
+      projection = localProjection(cwd, commits);
+    }
+  } catch {
+    projection = localProjection(cwd, commits);
+  }
+  return {
+    version: projection.version || '0.0.0',
+    type: projection.type,
+    commits,
+  };
+}

package/obj/template/.claude/skills/commit/SKILL.md

@@ -5,7 +5,7 @@ description: Workflow Phase 11 — Commit Preparation and Execution. Stages and
 argument-hint: "[optional commit message; otherwise drafted from the spec/intake]"
 ---
 
-Prereq: BOTH `archive` AND `memory-flush` in `completed` (Phase 10.5 moved slug artifacts to `docs/archive/<date>/<slug>/`; Phase 10.6 curated `_pending.md` and applied canonical memory writes) AND a valid consent token at `.claude/state/commit_consent` (the Git Commit Guard hook enforces this independently). On any workflow where `memory-flush` is in `exceptions` (rare), this skill SHALL refuse to proceed unless that exception is explicit in `workflow.json`.
+Prereq: ALL of `archive` AND `memory-flush` AND `changelog` in `completed` (Phase 10.5 archives slug artifacts; Phase 10.6 curates `_pending.md`; Phase 11.5 appends keepachangelog entries under `## [Unreleased]` in `CHANGELOG.md`) AND a valid consent token at `.claude/state/commit_consent` (the Git Commit Guard hook enforces this independently). On any workflow where `memory-flush` or `changelog` is in `exceptions` (e.g. non-git projects auto-except both), this skill SHALL refuse to proceed unless those exceptions are explicit in `workflow.json`.
 
 **Applicability.** This skill applies only when the project is a git repository. Non-git projects auto-except `commit` at `/triage` time (CLAUDE.md Article IV); the workflow ends after `/archive`.
 

package/obj/template/.claude/skills/harness/SKILL.md

@@ -106,7 +106,7 @@ The phases the harness loops through, in order:
 ```
 intake → scout → research → spec → /approve-spec → tdd → simplify →
 security → integrate → document → archive → memory-flush →
-/grant-commit → commit
+/grant-commit → changelog → commit
 ```
 
 - Phases listed in `workflow.json → exceptions` are skipped.
@@ -158,6 +158,8 @@ On each `/harness` invocation, read `workflow.json` and decide whether to enter
 | `completed` contains `spec` **and** approval token present, but `tdd`/`swarm-dispatch` not in `completed` | Enter loop; decide swarm-vs-solo at first iteration; invoke the next phase |
 | `completed` contains `swarm-plan` but no `swarm_approvals/<slug>.approval` | Enter loop; loop exits with `state: yielded` (approve-swarm gate) |
 | `completed` contains `archive` but no `commit_consent` (git project) | Enter loop; loop exits with `state: yielded` (grant-commit gate) |
+| `completed` contains `grant-commit` consent (token fresh) but no `changelog` | Enter loop; invoke `Skill(changelog)` (Phase 11.5); on success continue to commit |
+| `completed` contains `changelog` but no commit yet (git project) | Enter loop; invoke `Skill(commit)` (Phase 11) |
 | Phase skill returned an error this invocation | Loop exits with phase-failure reason; user investigates |
 
 ## Constraints

package/obj/template/.claude/skills/triage/SKILL.md

@@ -17,7 +17,7 @@ Triage the user's request and set up `.claude/state/workflow.json` so downstream
 # Steps
 
 1. Restate the request back to the user in 1-2 sentences, and name the entry phase you've chosen and why.
-2. **Git-repo detection (mandatory).** Run `git rev-parse --is-inside-work-tree 2>/dev/null` at the project root. If the exit status is non-zero, the project is not a git repository: gate C / `commit` are inapplicable AND the swarm path is unavailable because worktree isolation (the swarm contract's physical safety mechanism) requires git (CLAUDE.md Article IV "Phase 6c and Phase 11 are git-conditional", Article VII). Append `"swarm-plan"`, `"approve-swarm"`, `"swarm-dispatch"`, `"grant-commit"`, and `"commit"` to the exceptions array you'll write in step 4. Tell the user: "Non-git project detected — `swarm-plan`, `approve-swarm`, `swarm-dispatch`, `grant-commit`, and `commit` auto-excepted. Phase 6 routes to solo `/tdd`. Workflow ends after `/archive`. Persistence outside git is your responsibility."
+2. **Git-repo detection (mandatory).** Run `git rev-parse --is-inside-work-tree 2>/dev/null` at the project root. If the exit status is non-zero, the project is not a git repository: gate C / `commit` are inapplicable AND the swarm path is unavailable because worktree isolation (the swarm contract's physical safety mechanism) requires git (CLAUDE.md Article IV "Phase 6c and Phase 11 are git-conditional", Article VII). Append `"swarm-plan"`, `"approve-swarm"`, `"swarm-dispatch"`, `"grant-commit"`, `"changelog"`, and `"commit"` to the exceptions array you'll write in step 4. `"changelog"` is auto-excepted alongside `"commit"` because Phase 11.5 is a pre-commit curator with no purpose outside a commit-bearing workflow. Tell the user: "Non-git project detected — `swarm-plan`, `approve-swarm`, `swarm-dispatch`, `grant-commit`, `changelog`, and `commit` auto-excepted. Phase 6 routes to solo `/tdd`. Workflow ends after `/archive`. Persistence outside git is your responsibility."
 3. If the user has not confirmed yet, ask: "Entry phase = <X>. Exceptions = <Y>. Proceed? (or tell me a different entry)"
 4. On confirmation, write `.claude/state/workflow.json`:
    ```json
@@ -36,18 +36,19 @@ Triage the user's request and set up `.claude/state/workflow.json` so downstream
    The `source_backlog_keys` field is optional. When the user's request explicitly names one or more backlog entries this workflow picks up (the common framing is a `Source:` line listing backlog keys), populate the array with those keys. `/commit` (Phase 11) reads this field and invokes `sweep.py --mode stamp-closure` after the commit lands, stamping each named entry with `status: picked-up` + `superseded-at: <today>` so the next `/memory-flush` Step 0a auto-closes them. Absent / empty array → `/commit` skips the stamp step entirely (backward-compatible for any workflow that pre-dates the field). `/triage` does NOT auto-detect backlog keys from free-form prose — the user populates the field (or names them in the triage prompt and you populate it during step 4).
 5. **Seed the workflow tasklist.** Use the `TaskCreate` tool to register one task per non-excepted phase plus each applicable consent gate. The tasks are the running checklist that `/harness` (or any direct phase invocation) reads to decide the next action; consent-gate tasks block the workflow until the user runs the corresponding command. **When `grant-commit` and `commit` are in exceptions (non-git project), do NOT seed those two tasks** — the workflow ends after `/archive`. Use these canonical templates:
 
-   **For `chore` track** (single phase + memory-flush + commit gate):
+   **For `chore` track** (single phase + memory-flush + changelog + commit gate):
    - `Run /chore for <slug>` — activeForm: "Running chore", metadata: `{"phase": "chore"}`
    - `Run /memory-flush for <slug>` — activeForm: "Running memory-flush", metadata: `{"phase": "memory-flush"}`, addBlockedBy previous
    - `Wait for /grant-commit` — metadata: `{"phase": "grant-commit", "needs_user": true}`, addBlockedBy previous
+   - `Run /changelog for <slug>` — activeForm: "Running changelog", metadata: `{"phase": "changelog"}`, addBlockedBy previous
    - `Run /commit for <slug>` — activeForm: "Running commit", metadata: `{"phase": "commit"}`, addBlockedBy previous
 
    **For `tdd`-entry quickfix track** (skip intake/scout/research/spec/review):
-   - `Run /tdd`, `Run /simplify`, `Run /security` (only if not in exceptions), `Run /integrate`, `Run /document`, `Run /archive`, `Run /memory-flush`, `Wait for /grant-commit` (`needs_user`), `Run /commit` — each with `addBlockedBy` set to the previous task's id.
+   - `Run /tdd`, `Run /simplify`, `Run /security` (only if not in exceptions), `Run /integrate`, `Run /document`, `Run /archive`, `Run /memory-flush`, `Wait for /grant-commit` (`needs_user`), `Run /changelog`, `Run /commit` — each with `addBlockedBy` set to the previous task's id.
 
-   **For `spec`-entry track** (skip upstream): start from `Run /spec`, then `Wait for /approve-spec <path>` (`needs_user`), then continue per the full track.
+   **For `spec`-entry track** (skip upstream): `Run /spec`, `Wait for /approve-spec <path>` (`needs_user`), `Run /tdd`, `Run /simplify`, `Run /security` (unless excepted), `Run /integrate`, `Run /document`, `Run /archive`, `Run /memory-flush`, `Wait for /grant-commit` (`needs_user`), `Run /changelog`, `Run /commit` — each with `addBlockedBy` set to the previous task's id.
 
-   **For `intake`-entry full track**: `Run /intake`, `Run /brd` (only if stakeholder-heavy), `Run /scout`, `Run /research`, `Run /spec`, `Wait for /approve-spec <path>` (`needs_user`), `Run /tdd` OR (`Run /swarm-plan`, `Wait for /approve-swarm <slug>` (`needs_user`), `Run /swarm-dispatch`), `Run /simplify`, `Run /security` (unless excepted), `Run /integrate`, `Run /document`, `Run /archive`, `Run /memory-flush`, `Wait for /grant-commit` (`needs_user`), `Run /commit`. **On non-git projects the swarm branch SHALL NOT be seeded** — only `Run /tdd` goes in the list, regardless of expected component count. Swarm-vs-solo is a Phase-6 main-context decision (per CLAUDE.md Article V) only on git projects; non-git workflows resolve to solo at triage time because `swarm-plan`, `approve-swarm`, and `swarm-dispatch` are already in `exceptions`.
+   **For `intake`-entry full track**: `Run /intake`, `Run /brd` (only if stakeholder-heavy), `Run /scout`, `Run /research`, `Run /spec`, `Wait for /approve-spec <path>` (`needs_user`), `Run /tdd` OR (`Run /swarm-plan`, `Wait for /approve-swarm <slug>` (`needs_user`), `Run /swarm-dispatch`), `Run /simplify`, `Run /security` (unless excepted), `Run /integrate`, `Run /document`, `Run /archive`, `Run /memory-flush`, `Wait for /grant-commit` (`needs_user`), `Run /changelog`, `Run /commit`. **On non-git projects the swarm branch SHALL NOT be seeded** — only `Run /tdd` goes in the list, regardless of expected component count. Swarm-vs-solo is a Phase-6 main-context decision (per CLAUDE.md Article V) only on git projects; non-git workflows resolve to solo at triage time because `swarm-plan`, `approve-swarm`, and `swarm-dispatch` are already in `exceptions`. On non-git projects `changelog` is also auto-excepted alongside `commit` (Phase 11.5 only has purpose with a downstream commit).
 
    For every task: `subject` is imperative ("Run /scout for <slug>" / "Wait for /approve-spec <path>"); `description` names the phase + the slug; `metadata.phase` carries the phase name; consent-gate tasks set `metadata.needs_user: true`. Wire `addBlockedBy` so each task blocks until its predecessor completes — this surfaces the workflow's true dependency graph and prevents `/harness` from racing past a gate.
 

package/obj/template/CLAUDE.md

@@ -40,7 +40,7 @@ On every new session, before any work, you SHALL:
 
 1. **Read** `.claude/project.json` and check the `configured` field.
 2. **If `configured: false`** — `/init-project` has not run. The repository is in a sanctioned operating state called **project-agnostic mode**: hooks are active but `test_runner` and `lint_runner` run in guide mode and nothing is tailored to the user's stack. You SHALL greet the user with this exact framing:
-   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 36 skills). It's in **project-agnostic mode** — `test_runner` and `lint_runner` are in guide mode and nothing is tailored to your stack. Run **`/init-project`** to scout the codebase, run the recommender, and generate a config. Skip it if you want baseline-only behavior, but you'll miss stack-specific tailoring."
+   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 37 skills). It's in **project-agnostic mode** — `test_runner` and `lint_runner` are in guide mode and nothing is tailored to your stack. Run **`/init-project`** to scout the codebase, run the recommender, and generate a config. Skip it if you want baseline-only behavior, but you'll miss stack-specific tailoring."
    You SHALL then proceed with whatever the user asks. Project-agnostic mode is **allowed** — the user is not required to run `/init-project` to use the baseline. The `setup_guard` hook surfaces a one-shot reminder on Write/Edit/MultiEdit (rate-limited to 10 minutes); it does **not** block writes. Other guards (commit, env, spec-approval, verify-pass, track, swarm-boundary) remain hard regardless of `configured` state.
 3. **If `configured: true`** — read `docs/init/seed.md` §16 if present so you know what was added. Tell the user:
    > "Configured for `<stack>`. Run `/triage \"<request>\"` to start a workflow, or `/harness` for the full pipeline."
@@ -272,13 +272,13 @@ The vendored `impeccable` skill stays untouched (Article IX). `design-ui` is the
 
 ## Article XI — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on install. The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest straight to `<target>/.claude/manifest.json` (same path inside the `.claude/` subtree, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install as a runtime sha256 table of the target's actual on-disk contents (used by `doctor` and `upgrade`). The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` from the shipped `.claude/manifest.json` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
 
 You SHALL:
 
 1. **Declare baseline ownership only.** A SKILL.md that ships in the baseline SHALL declare `owner: baseline` in its frontmatter directly after `name:`. Authoring a user/third-party skill does NOT require any `owner:` annotation — absence is the default. Explicit `owner: user` is permitted but never required. The only frontmatter-related FAIL the audit emits is `invalid owner=<value>` (a present-but-malformed `owner:` field, e.g. typo). Missing-`owner:` is silently skipped.
-2. **Trust the manifest.** The shipped `obj/template/manifest.json` (mirrored to `<target>/.claude/.baseline-manifest.json` on install) is the canonical record of baseline-owned skills and their content hashes. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
-3. **Re-derive on drift.** The audit re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
+2. **Trust the manifest.** The shipped manifest at `obj/template/.claude/manifest.json` (delivered to `<target>/.claude/manifest.json` by the recursive install copy) is the canonical record of baseline-owned skills and their content hashes. The runtime `<target>/.claude/.baseline-manifest.json` written by the CLI post-install is a separate file that captures the target's actual on-disk hashes for `doctor`/`upgrade` — do not conflate the two. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
+3. **Re-derive on drift.** The audit reads the manifest from `<root>/.claude/manifest.json` (consumer projects) with a fallback to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo). It re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
 4. **Preserve constitutional citation.** This Article XI SHALL remain in CLAUDE.md AND in `src/CLAUDE.template.md` (byte-equal mirror). The genesis §17 in `docs/init/seed.md` SHALL remain present, with `src/seed.template.md` mirroring it. The audit verifies both citations and reports `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation` on absence.
 5. **Out-of-scope skills don't break the audit.** Any skill on disk that doesn't declare `owner: baseline` is out-of-scope: excluded from the baseline count, the names-match check, and the hash-drift check. Installing the baseline into a project that already has its own skills is zero-friction — no per-file annotation required. Maintenance of those skills is the user's responsibility.
 
@@ -292,7 +292,7 @@ Cryptographic supply-chain attestation, signed lock files, and per-skill aggrega
 |---|---|
 | `.claude/hooks/` | 22 hook scripts (17 write/run-boundary + 4 lifecycle + 1 input-boundary). Bash + python3, no jq. |
 | `.claude/agents/` | 1 baseline subagent: `swarm-worker` (rendered from `src/agents/swarm-worker.template.md`) |
-| `.claude/skills/` | 36 skills: artifact (4) + phases (10) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
+| `.claude/skills/` | 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
 | `.claude/commands/` | 5 consent/bootstrap gates: `approve-spec`, `approve-swarm`, `grant-commit`, `grant-push`, `init-project` |
 | `.claude/memory/` | 7 canonical knowledge files + `_pending.md` (staging) + `_resume.md` (continuity snapshot) + `README.md` |
 | `.claude/project.json` | per-project config (test/lint cmd, TDD globs, destructive patterns, swarm config, additions). Populated by `/init-project`. |

package/obj/template/docs/init/seed.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-six 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-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.
 
 ---
 
@@ -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/                 # 36 skills: artifact (4) + phases (10) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1)
+│   ├── skills/                 # 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (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 (36)
+### §4.3 Skills (37)
 
 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 36 skills (§4.3) — 28 workflow/worker/orchestration/memory/alt-track skills you author 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 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 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.
 
@@ -591,9 +591,9 @@ Until `/init-project` runs, this section stays empty. Once populated, every fiel
 
 ## §17 — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on `freshInstall`/`forceInstall`/`merge`.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest into the consumer target at `<target>/.claude/manifest.json` (same in-tree path, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install on `freshInstall`/`forceInstall`/`merge` — that file is the runtime snapshot of the target's actual on-disk hashes, consumed by `doctor` and `upgrade`. The two files coexist by design: the shipped manifest is frozen at release time and carries `owners.skills`; the runtime manifest is generated at install time and is hash-only.
 
-The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
+The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). It reads the manifest from `<root>/.claude/manifest.json` first (consumer projects) and falls back to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo where `npm run build` writes the manifest). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
 
 The audit also verifies constitutional citation: CLAUDE.md SHALL contain the literal string "Article XI" and a reference to the manifest, and `docs/init/seed.md` SHALL contain "§17" and a manifest reference. Missing citations trigger FAIL with `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation`.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friedbotstudio/create-baseline",
-  "version": "0.3.0",
-  "description": "Zero-dependency Node CLI scaffolder that materializes the Claude Code baseline (hooks, skills, commands, MCP servers, governance docs) into a target project. Run via `npx @friedbotstudio/create-baseline <target>`.",
+  "version": "0.5.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": {
     "create-baseline": "bin/cli.js"
@@ -43,6 +43,9 @@
     "email": "hello@friedbotstudio.com"
   },
   "homepage": "https://baseline.friedbotstudio.com",
+  "dependencies": {
+    "@clack/prompts": "1.4.0"
+  },
   "devDependencies": {
     "@11ty/eleventy": "3.1.5",
     "@semantic-release/changelog": "6.0.3",

package/src/CLAUDE.template.md

@@ -40,7 +40,7 @@ On every new session, before any work, you SHALL:
 
 1. **Read** `.claude/project.json` and check the `configured` field.
 2. **If `configured: false`** — `/init-project` has not run. The repository is in a sanctioned operating state called **project-agnostic mode**: hooks are active but `test_runner` and `lint_runner` run in guide mode and nothing is tailored to the user's stack. You SHALL greet the user with this exact framing:
-   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 36 skills). It's in **project-agnostic mode** — `test_runner` and `lint_runner` are in guide mode and nothing is tailored to your stack. Run **`/init-project`** to scout the codebase, run the recommender, and generate a config. Skip it if you want baseline-only behavior, but you'll miss stack-specific tailoring."
+   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 37 skills). It's in **project-agnostic mode** — `test_runner` and `lint_runner` are in guide mode and nothing is tailored to your stack. Run **`/init-project`** to scout the codebase, run the recommender, and generate a config. Skip it if you want baseline-only behavior, but you'll miss stack-specific tailoring."
    You SHALL then proceed with whatever the user asks. Project-agnostic mode is **allowed** — the user is not required to run `/init-project` to use the baseline. The `setup_guard` hook surfaces a one-shot reminder on Write/Edit/MultiEdit (rate-limited to 10 minutes); it does **not** block writes. Other guards (commit, env, spec-approval, verify-pass, track, swarm-boundary) remain hard regardless of `configured` state.
 3. **If `configured: true`** — read `docs/init/seed.md` §16 if present so you know what was added. Tell the user:
    > "Configured for `<stack>`. Run `/triage \"<request>\"` to start a workflow, or `/harness` for the full pipeline."
@@ -272,13 +272,13 @@ The vendored `impeccable` skill stays untouched (Article IX). `design-ui` is the
 
 ## Article XI — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on install. The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest straight to `<target>/.claude/manifest.json` (same path inside the `.claude/` subtree, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install as a runtime sha256 table of the target's actual on-disk contents (used by `doctor` and `upgrade`). The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` from the shipped `.claude/manifest.json` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
 
 You SHALL:
 
 1. **Declare baseline ownership only.** A SKILL.md that ships in the baseline SHALL declare `owner: baseline` in its frontmatter directly after `name:`. Authoring a user/third-party skill does NOT require any `owner:` annotation — absence is the default. Explicit `owner: user` is permitted but never required. The only frontmatter-related FAIL the audit emits is `invalid owner=<value>` (a present-but-malformed `owner:` field, e.g. typo). Missing-`owner:` is silently skipped.
-2. **Trust the manifest.** The shipped `obj/template/manifest.json` (mirrored to `<target>/.claude/.baseline-manifest.json` on install) is the canonical record of baseline-owned skills and their content hashes. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
-3. **Re-derive on drift.** The audit re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
+2. **Trust the manifest.** The shipped manifest at `obj/template/.claude/manifest.json` (delivered to `<target>/.claude/manifest.json` by the recursive install copy) is the canonical record of baseline-owned skills and their content hashes. The runtime `<target>/.claude/.baseline-manifest.json` written by the CLI post-install is a separate file that captures the target's actual on-disk hashes for `doctor`/`upgrade` — do not conflate the two. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
+3. **Re-derive on drift.** The audit reads the manifest from `<root>/.claude/manifest.json` (consumer projects) with a fallback to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo). It re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
 4. **Preserve constitutional citation.** This Article XI SHALL remain in CLAUDE.md AND in `src/CLAUDE.template.md` (byte-equal mirror). The genesis §17 in `docs/init/seed.md` SHALL remain present, with `src/seed.template.md` mirroring it. The audit verifies both citations and reports `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation` on absence.
 5. **Out-of-scope skills don't break the audit.** Any skill on disk that doesn't declare `owner: baseline` is out-of-scope: excluded from the baseline count, the names-match check, and the hash-drift check. Installing the baseline into a project that already has its own skills is zero-friction — no per-file annotation required. Maintenance of those skills is the user's responsibility.
 
@@ -292,7 +292,7 @@ Cryptographic supply-chain attestation, signed lock files, and per-skill aggrega
 |---|---|
 | `.claude/hooks/` | 22 hook scripts (17 write/run-boundary + 4 lifecycle + 1 input-boundary). Bash + python3, no jq. |
 | `.claude/agents/` | 1 baseline subagent: `swarm-worker` (rendered from `src/agents/swarm-worker.template.md`) |
-| `.claude/skills/` | 36 skills: artifact (4) + phases (10) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
+| `.claude/skills/` | 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
 | `.claude/commands/` | 5 consent/bootstrap gates: `approve-spec`, `approve-swarm`, `grant-commit`, `grant-push`, `init-project` |
 | `.claude/memory/` | 7 canonical knowledge files + `_pending.md` (staging) + `_resume.md` (continuity snapshot) + `README.md` |
 | `.claude/project.json` | per-project config (test/lint cmd, TDD globs, destructive patterns, swarm config, additions). Populated by `/init-project`. |

package/src/cli/install.js

@@ -12,15 +12,13 @@ const NPMRC_TEMPLATE_PATH = join(PACKAGE_ROOT, 'src/.npmrc.template');
 
 export const NEVER_TOUCH = Object.freeze(['.claude/project.json']);
 export const SPECIAL_MERGE = Object.freeze(['.mcp.json']);
-// Files present in the shipped template that must NOT be cp'd to target. These
-// are reference artifacts the CLI consults from templateDir (or that ship for
-// inspection-time provenance), never materialized at consumer project root.
-// `manifest.json`: the shipped sha256 table. The CLI's runtime manifest lives
-// at `target/.claude/.baseline-manifest.json` (written by writeBaselineManifest);
-// `target/manifest.json` would be a confusing duplicate. Keep the file in the
-// published tarball so anyone inspecting `node_modules/<pkg>/obj/template/` can
-// see what shipped, but exclude it from the fresh/force install copy.
-export const COPY_EXCLUDE = Object.freeze(['manifest.json']);
+// The shipped manifest now lives at `.claude/manifest.json` (inside the
+// template's .claude/ subtree), so the recursive cp drops it at the correct
+// consumer path without any special-case filtering. The consumer-side audit
+// (`.claude/skills/audit-baseline/audit.sh`) reads it from there for
+// hash-drift detection. COPY_EXCLUDE stays as a list (currently empty) so
+// future never-copy artifacts can be added without API churn at the callers.
+export const COPY_EXCLUDE = Object.freeze([]);
 
 async function listFiles(root, base = root, acc = []) {
   for (const entry of await readdir(root, { withFileTypes: true })) {

package/src/cli/merge.js

@@ -22,7 +22,8 @@ async function copyFile(src, dst) {
   await cp(src, dst, { force: true });
 }
 
-export async function threeWayMerge(templateDir, target, oldManifest, newManifest) {
+export async function threeWayMerge(templateDir, target, oldManifest, newManifest, opts = {}) {
+  const { dryRun = false, onSkipCustomized = null } = opts;
   const actions = [];
   const oldFiles = oldManifest?.files ?? {};
   const newFiles = newManifest?.files ?? {};
@@ -36,7 +37,7 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
       if (await pathExists(tgtPath)) {
         actions.push({ kind: ACTION_KINDS.NEVER_TOUCH_PRESERVE, path: rel, reason: 'NEVER_TOUCH path present in target' });
       } else if (rel in newFiles) {
-        await copyFile(tplPath, tgtPath);
+        if (!dryRun) await copyFile(tplPath, tgtPath);
         actions.push({ kind: ACTION_KINDS.NEVER_TOUCH_ADD, path: rel, reason: 'NEVER_TOUCH path absent; written from template' });
       }
       continue;
@@ -44,7 +45,7 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
 
     if (SPECIAL_MERGE.includes(rel)) {
       if (rel in newFiles && await pathExists(tplPath)) {
-        await deepMergeMcpServers(tplPath, tgtPath);
+        if (!dryRun) await deepMergeMcpServers(tplPath, tgtPath);
         actions.push({ kind: ACTION_KINDS.SPECIAL_MERGE, path: rel, reason: 'additive deep-merge applied' });
       }
       continue;
@@ -56,7 +57,7 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     const tgtHash = targetExists ? await hashFile(tgtPath) : null;
 
     if (!targetExists && newHash) {
-      await copyFile(tplPath, tgtPath);
+      if (!dryRun) await copyFile(tplPath, tgtPath);
       actions.push({ kind: ACTION_KINDS.ADD, path: rel, reason: 'new in template; not present in target' });
       continue;
     }
@@ -67,13 +68,19 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     }
 
     if (newHash && oldHash && tgtHash === oldHash) {
-      await copyFile(tplPath, tgtPath);
+      if (!dryRun) await copyFile(tplPath, tgtPath);
       actions.push({ kind: ACTION_KINDS.OVERWRITE, path: rel, reason: 'target untouched since last install; updated' });
       continue;
     }
 
     if (newHash && tgtHash && tgtHash !== oldHash) {
-      actions.push({ kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: 'target customized since last install' });
+      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' });
+      }
       continue;
     }
 
@@ -84,10 +91,8 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
       //     prune. Otherwise the user accumulates stale baseline files forever.
       //   - target customized (tgtHash != oldHash) → preserve to avoid
       //     destroying user work; report drift via exit 3.
-      // Pruning only runs when --merge already applies; there is no separate
-      // flag (decision recorded in README).
       if (targetExists && tgtHash === oldHash) {
-        await unlink(tgtPath);
+        if (!dryRun) await unlink(tgtPath);
         actions.push({ kind: ACTION_KINDS.PRUNE, path: rel, reason: 'removed from new template; target was untouched — deleted' });
       } else if (targetExists) {
         actions.push({ kind: ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED, path: rel, reason: 'removed from new template; target customized — preserved' });
@@ -96,7 +101,7 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     }
   }
 
-  if (newManifest) {
+  if (newManifest && !dryRun) {
     await mkdir(join(target, '.claude'), { recursive: true });
     await saveManifest(join(target, '.claude/.baseline-manifest.json'), newManifest);
   }

package/src/cli/tui/doctor.js

@@ -0,0 +1,56 @@
+// Domain — branded sectioned doctor report. Consumes the structured
+// DoctorReport from src/cli/doctor.js (unchanged) and writes a colorized,
+// sectioned rendering to stdout. The non-TTY plain path stays on doctor.js's
+// formatReport — this renderer is only invoked when stdout is a TTY.
+
+import { accent, muted, success, warn, error, accentLight } from './tokens.js';
+
+function brandHeader(target, manifestInfo) {
+  const lines = [accent('Baseline doctor')];
+  if (target) lines.push(muted(`target:   ${target}`));
+  if (manifestInfo) lines.push(muted(`manifest: ${manifestInfo}`));
+  return lines;
+}
+
+export function render(report) {
+  if (report.error) {
+    const headerLines = brandHeader(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}`);
+  lines.push('');
+  lines.push(`  ${success('matched')}:    ${report.matched.length}`);
+  lines.push(`  ${accentLight('customized')}: ${report.customized.length}`);
+  lines.push(`  ${error('missing')}:    ${report.missing.length}`);
+  lines.push(`  ${warn('added')}:      ${report.added.length}`);
+
+  if (report.missing.length > 0) {
+    lines.push('');
+    lines.push(error('Missing (deleted from disk; exit 1):'));
+    for (const p of report.missing) lines.push(`  - ${p}`);
+  }
+  if (report.customized.length > 0) {
+    lines.push('');
+    const header = report.strict
+      ? accentLight('Customized (strict mode → exit 1):')
+      : accentLight('Customized (informational):');
+    lines.push(header);
+    if (Array.isArray(report.tampered) && report.tampered.length > 0) {
+      for (const entry of report.tampered) {
+        lines.push(`  ${warn('TAMPERED')}: ${entry.path}`);
+        lines.push(`    shipped=${muted(entry.shipped)}  observed=${muted(entry.observed)}`);
+      }
+    } else {
+      for (const p of report.customized) lines.push(`  - ${p}`);
+    }
+  }
+  if (report.added.length > 0) {
+    lines.push('');
+    lines.push(warn('Added under .claude/ since install (likely /init-project; informational):'));
+    for (const p of report.added) lines.push(`  - ${p}`);
+  }
+
+  process.stdout.write(lines.join('\n') + '\n');
+}

package/src/cli/tui/install.js

@@ -0,0 +1,81 @@
+// Domain — branded install flow. Composes the pure-data install + plantuml
+// foundations behind a clack-style presentation seam. The `prompts` parameter
+// defaults to @clack/prompts but is injected in tests.
+
+import * as clackModule from '@clack/prompts';
+import { readFile } from 'node:fs/promises';
+import { freshInstall, forceInstall } from '../install.js';
+import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../plantuml.js';
+import { renderBrandStrip } from './splash.js';
+
+const SUCCESS = 0;
+const ERR_INSTALL_FAILED = 1;
+const ERR_PLANTUML_REQUIRED = 4;
+
+export async function run({ target, opts = {}, prompts = clackModule } = {}) {
+  if (!target || typeof target !== 'string') {
+    throw new Error('tui.install.run requires a non-empty string target');
+  }
+  if (!opts.templateDir) {
+    throw new Error('tui.install.run requires opts.templateDir');
+  }
+
+  const version = await readPackageVersion();
+  process.stdout.write(renderBrandStrip({ version, subtitle: 'install' }));
+  prompts.intro('create-baseline');
+
+  const spinner = prompts.spinner();
+  spinner.start('Copying baseline files');
+
+  try {
+    await copyTemplate(target, opts);
+  } catch (err) {
+    spinner.error('Install failed');
+    prompts.outro(err.message);
+    return ERR_INSTALL_FAILED;
+  }
+
+  const plantumlExit = await fetchPlantumlBranded(target, opts, prompts, spinner);
+  if (plantumlExit !== SUCCESS) return plantumlExit;
+
+  spinner.stop('Baseline installed');
+  prompts.outro(`Installed at ${target}`);
+  return SUCCESS;
+}
+
+async function copyTemplate(target, opts) {
+  const installOpts = { withNpmrc: !!opts.withNpmrc };
+  if (opts.force) await forceInstall(opts.templateDir, target, installOpts);
+  else await freshInstall(opts.templateDir, target, installOpts);
+}
+
+async function fetchPlantumlBranded(target, opts, prompts, spinner) {
+  if (opts.noPlantuml) return SUCCESS;
+  spinner.message('Fetching PlantUML jar');
+  const result = await fetchPlantumlIfMissing(target, {
+    noPlantuml: opts.noPlantuml,
+    requirePlantuml: opts.requirePlantuml,
+  });
+  if (result.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
+    spinner.error('PlantUML required but unavailable');
+    prompts.outro(result.reason);
+    return ERR_PLANTUML_REQUIRED;
+  }
+  if (
+    result.outcome === FETCH_OUTCOMES.WARNED_NETWORK_FAILURE ||
+    result.outcome === FETCH_OUTCOMES.WARNED_HASH_MISMATCH
+  ) {
+    prompts.log.warn(`PlantUML jar: ${result.reason} — install continued`);
+  }
+  return SUCCESS;
+}
+
+async function readPackageVersion() {
+  try {
+    const url = new URL('../../../package.json', import.meta.url);
+    const pkg = JSON.parse(await readFile(url, 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}