@friedbotstudio/create-baseline 0.2.1 → 0.4.0

package/src/CLAUDE.template.md

@@ -40,11 +40,11 @@ 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."
-4. **Memory check.** The `memory_session_start` hook injects a memory index into your additional context. If it reports `K candidates pending in _pending.md` with `K > 0`, you SHALL invoke `/memory-flush` before any workflow phase work — keeps canonical memory fresh for downstream skills.
+4. **Memory check.** The `memory_session_start` hook injects a memory index into your additional context. The hook emits a **debt-mode nag** only when `_pending.md` has unflushed candidates AND no active workflow on disk (i.e., `.claude/state/workflow.json` is absent) — those candidates are debt from a prior workflow that didn't end-flush. During an active workflow, **Phase 10.6** (memory-flush, between archive and grant-commit) handles flushing automatically; the session-start nag stays silent. You SHALL run `/memory-flush` when the debt-mode nag fires, before starting new work.
 5. **Git-repo check.** Run `git rev-parse --is-inside-work-tree 2>/dev/null` at the project root. If non-zero (not a git repo), surface this once per session and tell the user that gate C and the `commit` phase will be auto-excepted; the workflow ends after `/archive`. This is a sanctioned operating mode — Article IV phase 11 and Article VII are git-conditional.
 6. Once per session is sufficient. You SHALL NOT repeat the greeting on every prompt.
 
@@ -68,6 +68,7 @@ The 11-phase workflow is the only sanctioned path from request to commit. Phase
 | 9 | Integrate | `/integrate` | binding verify verdict |
 | 10 | Document | `/document` | docs |
 | 10.5 | Archive | `/archive` | bundle at `docs/archive/<date>/<slug>/` |
+| 10.6 | Memory flush | `/memory-flush` | curated canonical memory + reset `_pending.md` |
 | 11 | **Grant commit** (gate C) + commit | user runs **`/grant-commit`**, then `/commit` (skill) | commit |
 
 **Mandatory rules:**
@@ -77,7 +78,7 @@ The 11-phase workflow is the only sanctioned path from request to commit. Phase
 - The only mechanism to bypass a phase is the `exceptions` array in `.claude/state/workflow.json`, written by `/triage`.
 - **Phase 6c and Phase 11 are git-conditional.** On a project where `git rev-parse --is-inside-work-tree` exits non-zero (no `.git/`, not inside a work tree), `/triage` SHALL auto-add `swarm-plan`, `approve-swarm`, `swarm-dispatch`, `grant-commit`, and `commit` to `exceptions`. Phase 6 routes to solo `/tdd` unconditionally; the workflow ends after `/archive`. Worktree isolation (the swarm contract's physical safety mechanism) requires git; `swarm.isolation: "shared"` is a sanctioned configuration knob for git projects that opt out of worktrees but does NOT restore the cross-task write isolation the swarm-worker assumes — it is unsafe as a non-git fallback, especially when `swarm.exempt_path_prefixes` covers baseline-internal paths (e.g. `.claude/`). Persistence outside git is the user's responsibility. See Article VII for the matching rule on git operations.
 - The three consent gates (A, B, C) are **commands**, not skills. They are structurally un-invokable by Claude. You SHALL NOT self-approve.
-- **How the gates are structurally enforced.** Each consent command (`/approve-spec`, `/approve-swarm`, `/grant-commit`) is a slash command typed by the user. The `consent_gate_grant` UserPromptSubmit hook (Art. VIII) parses the user's prompt **before Claude is invoked** and writes a short-lived consent marker at `.claude/state/.<gate>_grant`. The corresponding PreToolUse approval guard (`spec_approval_guard`, `swarm_approval_guard`, `git_commit_guard`) then allows Claude's slash-command-body write of the approval token only when the marker is present, fresh (≤ `consent.gate_marker_ttl_seconds`, default 120), and slug-matched; the marker is single-use and deleted on the allowed write. Slug derivation is centralized in `lib/common.sh → canonical_slug` (strip directory prefix + trailing `.md`) so the marker and the expected slug always agree, whether the user typed a bare slug, a filename, or a full path. The same guards block Claude from writing the marker file itself via Write/Edit/MultiEdit. Claude cannot reach the UserPromptSubmit code path, so it cannot forge consent.
+- **How the gates are structurally enforced.** Each consent command (`/approve-spec`, `/approve-swarm`, `/grant-commit`, `/grant-push`) is a slash command typed by the user. The `consent_gate_grant` UserPromptSubmit hook (Art. VIII) parses the user's prompt **before Claude is invoked** and writes a short-lived consent marker at `.claude/state/.<gate>_grant`. The corresponding PreToolUse approval guard (`spec_approval_guard`, `swarm_approval_guard`, `git_commit_guard`) then allows Claude's slash-command-body write of the approval token only when the marker is present, fresh (≤ `consent.gate_marker_ttl_seconds`, default 120), and slug-matched; the marker is single-use and deleted on the allowed write. `/grant-push` is **not** a workflow-phase gate — it is a Bash-time consent for push to a protected branch (see Article VII). Slug derivation is centralized in `lib/common.sh → canonical_slug` (strip directory prefix + trailing `.md`) so the marker and the expected slug always agree, whether the user typed a bare slug, a filename, or a full path. The same guards block Claude from writing the marker file itself via Write/Edit/MultiEdit. Claude cannot reach the UserPromptSubmit code path, so it cannot forge consent.
 - **Out-of-band**: `/rca` produces an incident postmortem at `docs/rca/<slug>.md`. It is not a workflow phase and often precedes a bugfix intake.
 
 **Entry points** (`/triage` writes `workflow.json` with `entry_phase` and `exceptions`):
@@ -105,7 +106,7 @@ When `/harness` is invoked, you SHALL:
 
 **The safety net.** The `harness_continuation` Stop hook (Article VIII) re-fires `Skill(harness)` only when the loop exited mid-flow — i.e., on-disk state is `{state: "continue"}` with the marker present, and `stop_hook_active` is absent on the Stop payload. In normal operation (loop runs to gate/failure/done), the hook sees `state != continue` or marker absent and stays silent. The hook is a defense-in-depth signal, not the primary driver: a healthy `Skill(harness)` invocation never depends on it. The hook is also bounded to one block per turn by Claude Code's `stop_hook_active` semantics, so it cannot itself drive multi-phase chaining.
 
-**Resume after yield.** The user runs the consent command (which writes the gate marker via `consent_gate_grant`), then `/harness` again. The next invocation re-enters preflight, finds the gate token on disk, marks the gate task `completed`, and re-enters the loop.
+**Resume after yield (auto).** After yielding at a consent gate, the harness skill writes `state: yielded` and removes `.harness_active`. The user runs the consent slash command in their next prompt; `consent_gate_grant` writes the gate marker (outside Claude's tool boundary), the command body writes the consent token, and the `harness_continuation` Stop hook detects fresh consent (rung 4: `workflow.json` present + `state=yielded` + a consent-token mtime newer than `harness_state`). The hook emits `{decision:"block"}`, and `Skill(harness)` is re-invoked in the same turn. The next invocation re-enters preflight, finds the gate token on disk, marks the gate task `completed`, and re-enters the loop. The user does not type `/harness` to resume.
 
 **Task discipline (autonomous progression).** `/triage` seeds a `TaskCreate`-backed checklist covering every non-excepted phase plus consent-gate placeholders (the placeholders carry `metadata.needs_user: true`). Inside the loop you SHALL: (a) call `TaskList` first; if empty, re-seed from `workflow.json → completed + exceptions + entry_phase` using the canonical templates in `triage`'s SKILL.md; (b) `TaskUpdate` the next pending non-blocked task to `in_progress` before invoking its phase skill; (c) `TaskUpdate` to `completed` only after the phase skill returns success; (d) when the next pending task carries `needs_user: true`, EXIT LOOP with YIELD — never invoke a skill for that task. The TaskList is session-bound; `workflow.json → completed` is the durable truth, and re-seeding always reconciles to it.
 
@@ -157,21 +158,25 @@ The following bind every code change.
 
 **Applicability.** Article VII applies only when the project is a git repository (`git rev-parse --is-inside-work-tree` exits 0 at the project root). On a non-git project, this Article is vacuously satisfied: you SHALL NOT attempt any git operation, gate C and the `commit` phase are auto-excepted at triage time (Art. IV), and the workflow ends after `/archive`. The rules below bind only inside the git-repository case.
 
-You SHALL run `git add <named paths>` and `git commit` only when **both** hold:
+**Branch-aware consent policy.** Consent enforcement for `git commit` and `git push` is driven by two `project.json` knobs:
 
-1. The user has explicitly asked for a commit in their current request; **and**
-2. A fresh `commit_consent` token exists at `.claude/state/commit_consent` (5-minute TTL, written by `/grant-commit`).
+- `git.protected_branches` — glob list. `null` (default) means every branch is protected. Set e.g. `["main", "release/*"]` to limit consent enforcement to those branches.
+- `git.branch_pattern` — regex. `null` (default) means no naming check. Set e.g. `"^(feat|fix|chore|docs)/[a-z0-9-]+$"` to require conformant branch names on commit.
 
-`git_commit_guard` (Art. VIII) enforces both conditions.
+On a **protected branch**, commits require a fresh `commit_consent` token (written by `/grant-commit`, 5-min TTL) and pushes require a fresh `push_consent` token (written by `/grant-push`, 5-min TTL) — both gated by the user having explicitly asked for the operation in their current request. On a non-protected branch, commits and pushes proceed without consent. `git_commit_guard` (Art. VIII) is the enforcer.
 
-You SHALL NEVER, unless the user names the exact operation in their current request:
+**Detached HEAD.** When the current branch resolves to the literal string `HEAD` (detached state), the guard denies both commit and push with an explicit message. Check out a named branch before attempting either — branch-aware policy needs a named branch to evaluate `git.protected_branches` and `git.branch_pattern`.
 
-- `git push`, `git push --force`, `--force-with-lease`
-- `git commit --amend` — always create a new commit
-- `--no-verify`, `--no-gpg-sign`, or any flag that skips hooks/signing
-- `git reset --hard`, `git clean -f`, `git checkout --`, `git branch -D`
-- `git config`, `git rebase -i`, `git add -i`
-- `git add -A`, `git add .` — name the paths
+**Hard-blocks regardless of consent, branch, or user request.** These operations rewrite history, skip safety, or sweep paths; `git_commit_guard`'s `FORBIDDEN_RE` blocks them flat-out:
+
+- `git commit --amend` — always create a new commit.
+- `--no-verify`, `--no-gpg-sign`, or any flag that skips hooks/signing.
+- `git reset --hard`, `git clean -f`, `git checkout --`, `git branch -D`.
+- `git config` changes.
+- `git rebase -i`, `git add -i` (interactive).
+- `git add -A`, `git add .` — name the paths.
+
+`git push` is no longer in this set — it is governed by the branch-aware policy above. `git push --force` and `--force-with-lease` are still forbidden unless the user names the exact operation in their current request, AND additionally subject to the branch-aware policy (force-push to a protected branch requires fresh `push_consent` plus the user-named carve-out).
 
 ## Article VIII — Hooks (the enforcement layer)
 
@@ -181,7 +186,7 @@ The 22 hooks in `.claude/hooks/` are the structural enforcement of this constitu
 |---|---|---|---|
 | `setup_guard` | PreToolUse / Edit\|Write\|MultiEdit | Art. III | Advisory reminder when `configured: false` (rate-limited 10 min). Does **not** block. |
 | `destructive_cmd_guard` | PreToolUse / Bash | Art. VII | Hard-block catastrophic commands; ask risky |
-| `git_commit_guard` | PreToolUse / Bash + Edit\|Write\|MultiEdit | Art. IV gate C, Art. VII | Bash: require fresh consent for `git commit`; hard-block forbidden flags. Write: gate writes to `.claude/state/commit_consent` and the `.commit_consent_grant` marker |
+| `git_commit_guard` | PreToolUse / Bash + Edit\|Write\|MultiEdit | Art. IV gate C, Art. VII | Bash: enforce branch-aware policy — `git commit` on a protected branch requires fresh `commit_consent`; `git push` on a protected branch requires fresh `push_consent`; both proceed without consent on non-protected branches; off-`branch_pattern` branches deny commits; detached HEAD denies both. Hard-block remaining forbidden flags (--amend, --no-verify, reset --hard, etc.). Write: gate writes to `.claude/state/{commit,push}_consent` and the matching `.{commit,push}_consent_grant` markers. |
 | `env_guard` | PreToolUse / Edit\|Write\|MultiEdit\|NotebookEdit | Art. VII | Block writes to `.env*` (allows `.env.example`) |
 | `spec_approval_guard` | PreToolUse / Edit\|Write\|MultiEdit | Art. IV gate A | Validate fresh `.spec_approval_grant` marker before allowing approval-token writes; block self-approval inside spec markdown; block direct writes to the marker |
 | `swarm_approval_guard` | PreToolUse / Edit\|Write\|MultiEdit | Art. IV gate B | Validate fresh `.swarm_approval_grant` marker before allowing swarm-approval writes; block direct writes to the marker |
@@ -200,13 +205,13 @@ The 22 hooks in `.claude/hooks/` are the structural enforcement of this constitu
 | `memory_stop` | Stop | Art. IX | Auto-extract memory candidates each turn-end |
 | `harness_continuation` | Stop | Art. V | Three-rung gate: (1) `stop_hook_active` absent on payload; (2) `.claude/state/.harness_active` exists (session-scoped marker created by the harness skill on `continue`, deleted on `yielded`/`done`, cleaned by `memory_session_start.sh` on session boundary); (3) `harness_state.state == "continue"`. When all three pass, emits `{"decision":"block","reason":"…invoke Skill(harness)…"}`. Sanity rail: marker-slug-vs-`workflow.json`-slug mismatch logs WARN to `harness_continuation.log` without changing the decision. Silent on any rung fail. Never writes consent markers. |
 | `memory_pre_compact` | PreCompact | Art. IX | Capture resume snapshot before context compaction |
-| `consent_gate_grant` | UserPromptSubmit | Art. IV gates A/B/C | Detect `/approve-spec`/`/approve-swarm`/`/grant-commit` in user input and write the gate-specific consent marker — runs OUTSIDE Claude's tool boundary so Claude cannot forge it |
+| `consent_gate_grant` | UserPromptSubmit | Art. IV gates A/B/C, Art. VII | Detect `/approve-spec`/`/approve-swarm`/`/grant-commit`/`/grant-push` in user input and write the gate-specific consent marker — runs OUTSIDE Claude's tool boundary so Claude cannot forge it |
 
 ## Article IX — Project memory
 
 The memory system at `.claude/memory/` accumulates project facts across sessions. You SHALL:
 
-1. Treat the six canonical files (`landmarks.md`, `libraries.md`, `decisions.md`, `landmines.md`, `conventions.md`, `pending-questions.md`) as long-term project memory. Each entry has a stable key per the schema in `.claude/memory/README.md`.
+1. Treat the seven canonical files (`landmarks.md`, `libraries.md`, `decisions.md`, `landmines.md`, `conventions.md`, `pending-questions.md`, `backlog.md`) as long-term project memory. Each entry has a stable key per the schema in `.claude/memory/README.md`.
 2. **Re-verify before citing.** Every skill that cites a memory entry SHALL re-verify it (file exists, symbol still at named line, library version still pinned). Failed verification → you SHALL correct or delete the entry in the same run before proceeding.
 3. Treat `_pending.md` as the auto-extraction inbox (written by `memory_stop`). Promote candidates to canonical files only via `/memory-flush`. You SHALL NOT write directly into canonical memory files outside the natural byproduct of phase skills.
 4. Treat `_resume.md` as the cross-session continuity snapshot (refreshed every turn-end and before compaction). It is **session memory**, not project memory.
@@ -257,7 +262,7 @@ Every UI design task that originates inside a workflow phase SHALL route through
 | A spec whose `write_set` intersects `project.json → tdd.ui_globs` SHALL declare a populated `## Design calls` section, one row per design surface. | `spec_design_calls_guard` (Art. VIII) at the Write boundary; `/spec-lint` at preflight. |
 | `/tdd` Step 6 SHALL invoke `Skill(design-ui, task_brief)` once per `## Design calls` row before Step 7 (verify). | `tdd` skill SOP. |
 | `design-ui` SHALL NOT write product code. Its only writes are the state file at `.claude/state/design/<slug>.json`, snapshots under `docs/design/<slug>.*.md`, and memory candidates. The product-code writes happen inside `impeccable` invocations. | `design-ui` SKILL.md. |
-| `design-ui` SHALL classify incoming intents at Stage 0 (design / development / copy). A misrouted intent returns `final_state: "not_a_design_task"` with a pointer to the correct lane and writes no code. | `design-ui` Stage 0 + `references/design-vs-development.md`. |
+| `design-ui` SHALL classify incoming intents at Stage 0 (design / development / copy). A misrouted intent returns one of two terminal states: `final_state: "not_a_design_task"` (single-lane misroute) with `correct_lane`, OR `final_state: "mixed_brief"` (multi-lane misroute) with a structured `lane_split` array. Neither writes code. | `design-ui` Stage 0 + `references/design-vs-development.md`. |
 | Iteration cap: `audit → polish` loops SHALL terminate after 3 iterations with `final_state: "needs_human"` if P0 ≥ 1 or P1 > 0 persist. P0 issues block (do not loop). | `design-ui` SKILL.md + `references/orchestration.md`. |
 | Multi-step impeccable recipes SHALL ask the user before proceeding. Single-step recipes SHALL auto-execute. | `references/intent-table.md` `mode` column. |
 
@@ -287,12 +292,12 @@ 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/commands/` | 4 consent/bootstrap gates: `approve-spec`, `approve-swarm`, `grant-commit`, `init-project` |
-| `.claude/memory/` | 6 canonical knowledge files + `_pending.md` (staging) + `_resume.md` (continuity snapshot) + `README.md` |
+| `.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`. |
 | `.claude/settings.json` | hook wiring + permissions |
-| `.claude/state/` | runtime: `workflow.json`, `commit_consent`, `spec_approvals/`, `swarm_approvals/`, `swarm/`, `harness/<slug>.log`, `last_test_result` |
+| `.claude/state/` | runtime: `workflow.json`, `commit_consent`, `push_consent`, `spec_approvals/`, `swarm_approvals/`, `swarm/`, `harness/<slug>.log`, `last_test_result` |
 | `.mcp.json` | three baseline MCP servers: `context7`, `plantuml`, `playwright` |
 | `src/` | pristine ship-time templates for every file `/init-project` modifies (overlay source for `npx @friedbotstudio/create-baseline`) |
 | `docs/init/seed.md` | genesis prompt — governing specification of the baseline |
@@ -317,8 +322,14 @@ Cryptographic supply-chain attestation, signed lock files, and per-skill aggrega
 **Memory (1)**:
 - `memory-flush`
 
-**Shared globals (7)** — vendored / globally available:
-- `claude-automation-recommender` (Apache 2.0, vendored), `code-structure` (mandatory on all code), `humanizer`, `documentation`, `technical-tutorials`, `copywriting`, `impeccable`
+**Shared globals (7)** — one written for this baseline, six vendored from external sources with their upstream licenses preserved in `LICENSE` + `NOTICE` alongside each skill:
+- `claude-automation-recommender` — vendored from Anthropic's `claude-code-setup` plugin, Apache 2.0.
+- `code-structure` — written for this baseline (Friedbot Studio). Mandatory on every code-generation step.
+- `humanizer` — vendored from [`blader/humanizer`](https://github.com/blader/humanizer), MIT.
+- `documentation` — vendored from Anthropic's `claude-code-setup` plugin, Apache 2.0.
+- `technical-tutorials` — vendored from [`jonathimer/devmarketing-skills`](https://github.com/jonathimer/devmarketing-skills), MIT.
+- `copywriting` — vendored from [`coreyhaines31/marketingskills`](https://github.com/coreyhaines31/marketingskills), MIT.
+- `impeccable` — vendored from [`pbakaus/impeccable`](https://github.com/pbakaus/impeccable), Apache 2.0.
 
 **Audit (1)**:
 - `audit-baseline` — drift check between this constitution + seed.md and the implementation

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,79 @@
+// 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';
+
+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();
+  prompts.intro(`create-baseline v${version}`);
+
+  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';
+  }
+}

package/src/cli/tui/meta.js

@@ -0,0 +1,30 @@
+// Domain — branded renderers for the meta commands (--help, --version).
+// In a TTY, a brand banner frames the canonical body; in non-TTY the body is
+// emitted unchanged so that piped consumers (`$(cli --version)`, `cli --help |
+// grep ...`) keep working byte-clean.
+
+import { accent, muted, rule } from './tokens.js';
+
+export function renderHelp(helpText, version) {
+  if (!process.stdout.isTTY) {
+    process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+    return;
+  }
+  const banner = [
+    '',
+    `  ${accent('Baseline CLI')}  ${muted(`v${version}`)}`,
+    `  ${muted('@friedbotstudio/create-baseline')}`,
+    `  ${rule('─'.repeat(48))}`,
+    '',
+  ].join('\n');
+  process.stdout.write(banner + '\n');
+  process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+}
+
+export function renderVersion(version) {
+  if (!process.stdout.isTTY) {
+    process.stdout.write(`${version}\n`);
+    return;
+  }
+  process.stdout.write(`${accent('baseline')} ${muted('v')}${version}\n`);
+}

package/src/cli/tui/tokens.js

@@ -0,0 +1,38 @@
+// Foundation — ANSI brand-color helpers for the TUI presentation layer.
+// Translates Friedbot Studio's oklch tokens (site-src/assets/site.css :root) to
+// 24-bit truecolor escape sequences. Respects NO_COLOR (https://no-color.org)
+// and skips emission when stdout is not a TTY.
+
+const NO_COLOR = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '';
+
+// oklch -> approximate sRGB hex used in the rendered docs site:
+//   --accent       oklch(55.8% 0.187 41.5) ~ #c2410c   (orange-700)
+//   --accent-light oklch(70.3% 0.187 41.5) ~ #ea6a25   (orange-500)
+//   --muted        oklch(45% 0.026 257)    ~ #6b7280
+//   --cli-success  oklch(70% 0.15 145)     ~ #4ade80
+//   --warn         oklch(58% 0.13 60)      ~ #d97706
+//   --mac-red      oklch(70% 0.21 24)      ~ #ef4444
+//   --rule         oklch(89% 0.013 257)    ~ #d1d5db
+const RGB = {
+  accent: [194, 65, 12],
+  accentLight: [234, 106, 37],
+  muted: [107, 114, 128],
+  success: [74, 222, 128],
+  warn: [217, 119, 6],
+  error: [239, 68, 68],
+  rule: [209, 213, 219],
+};
+
+function paint(rgb, text) {
+  if (NO_COLOR || !process.stdout.isTTY) return text;
+  const [r, g, b] = rgb;
+  return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+}
+
+export const accent = (text) => paint(RGB.accent, text);
+export const accentLight = (text) => paint(RGB.accentLight, text);
+export const muted = (text) => paint(RGB.muted, text);
+export const success = (text) => paint(RGB.success, text);
+export const warn = (text) => paint(RGB.warn, text);
+export const error = (text) => paint(RGB.error, text);
+export const rule = (text) => paint(RGB.rule, text);

package/src/cli/tui/upgrade.js

@@ -0,0 +1,100 @@
+// Domain — branded upgrade flow with interactive per-file conflict resolution.
+// 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
+
+import * as clackModule from '@clack/prompts';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { threeWayMerge, ACTION_KINDS } from '../merge.js';
+import { loadManifest, buildManifestFromDir } from '../manifest.js';
+
+const SUCCESS = 0;
+const ERR_ABORT = 1;
+const ERR_NO_MANIFEST = 2;
+const ERR_DIVERGENCE = 3;
+
+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: 'abort', label: 'Abort', hint: 'exit without changes' },
+];
+
+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');
+  }
+  if (!opts.templateDir) {
+    throw new Error('tui.upgrade.run requires opts.templateDir');
+  }
+
+  const manifestPath = join(target, '.claude/.baseline-manifest.json');
+  if (!existsSync(manifestPath)) {
+    prompts.log.error(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
+    return ERR_NO_MANIFEST;
+  }
+
+  prompts.intro('create-baseline upgrade');
+
+  const { oldManifest, newManifest } = await loadManifests(opts.templateDir, manifestPath);
+  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);
+  }
+
+  if (opts.dryRun) {
+    for (const action of dryReport.actions) {
+      prompts.log.info(`${action.kind.padEnd(24)} ${action.path}`);
+    }
+    prompts.outro('Dry run complete; no changes written.');
+    return SUCCESS;
+  }
+
+  const onSkipCustomized = (rel) => choices.get(rel) ?? 'keep-mine';
+  const finalReport = await threeWayMerge(opts.templateDir, target, oldManifest, newManifest, { onSkipCustomized });
+
+  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;
+}
+
+function isApplied(kind) {
+  return (
+    kind === ACTION_KINDS.ADD ||
+    kind === ACTION_KINDS.OVERWRITE ||
+    kind === ACTION_KINDS.PRUNE ||
+    kind === ACTION_KINDS.SPECIAL_MERGE ||
+    kind === ACTION_KINDS.NEVER_TOUCH_ADD
+  );
+}
+
+async function loadManifests(templateDir, manifestPath) {
+  const oldManifest = await loadManifest(manifestPath);
+  const tplFiles = await listShippedFiles(templateDir);
+  const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  return { oldManifest, newManifest };
+}
+
+async function listShippedFiles(root, base = root, acc = []) {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) await listShippedFiles(full, base, acc);
+    else if (entry.isFile()) acc.push(relative(base, full).split(sep).join('/'));
+  }
+  return acc;
+}

package/src/memory/backlog.template.md

@@ -0,0 +1,12 @@
+---
+owners: [/memory-flush]
+category: future-work intent
+size-cap: 500
+key: <slug>-<4char-hash>
+verifies-against: none
+stale-exempt: true
+---
+
+# Backlog
+
+(populated by /memory-flush from auto-extracted candidates)

package/src/project.template.json

@@ -185,7 +185,12 @@
   },
   "consent": {
     "commit_ttl_seconds": 300,
-    "gate_marker_ttl_seconds": 120
+    "gate_marker_ttl_seconds": 120,
+    "push_ttl_seconds": 300
+  },
+  "git": {
+    "protected_branches": null,
+    "branch_pattern": null
   },
   "swarm": {
     "max_parallel": 4,