@friedbotstudio/create-baseline 0.5.0 → 0.6.0

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

@@ -261,13 +261,16 @@ def check_skill_ownership():
         if not skill_dir.is_dir():
             add(f"skill ownership: {slug}", "FAIL", "baseline skill missing")
             continue
-        for path, expected_hash in files_map.items():
+        for path, entry in files_map.items():
             if not path.startswith(f".claude/skills/{slug}/"):
                 continue
             disk_file = root / path
             if not disk_file.exists():
                 add(f"skill ownership: {slug}", "FAIL", f"baseline skill missing: {path}")
                 continue
+            # Manifest v3+ wraps each entry as {sha256, tier}; v2 ships bare
+            # sha strings. Both shapes are accepted at read time.
+            expected_hash = entry if isinstance(entry, str) else (entry or {}).get("sha256")
             actual = hashlib.sha256(disk_file.read_bytes()).hexdigest()
             if actual != expected_hash:
                 add(f"skill ownership: {slug}", "FAIL", f"hash mismatch at {path}")

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

@@ -0,0 +1,121 @@
+---
+name: upgrade-project
+owner: baseline
+description: Reconcile baseline-versioned files that the `create-baseline upgrade` CLI staged for LLM-assisted semantic merge. Use when the CLI prints "Open Claude Code and run /upgrade-project to reconcile". Reads the stage manifest at `.claude/state/upgrade/<ts>/manifest.json`, reasons through each pending file's three-way delta in main context, writes a reconciled LOCAL, then deletes the stage when every file lands. Supports `--dry-run` (preview the reconciled diff without writing) and a structured "needs-user-input" fallback when the conflict cannot be disambiguated automatically.
+---
+
+# /upgrade-project — semantic-merge reconciliation for baseline files
+
+You are reconciling files that `create-baseline upgrade` decided required **semantic merge** rather than mechanical merge. The CLI has already detected per-file customization, classified each file as tier 3 (SEMANTIC) at build time, and staged the three states (BASE / INCOMING / LOCAL) for you to reason about in main context. This skill is the only sanctioned way to drive that staged state to RECONCILED.
+
+This skill is **maintenance work**, not a workflow phase. It is invoked reactively whenever the upgrade CLI prints the "run /upgrade-project to reconcile" pointer. It does not appear in `.claude/state/workflow.json`, does not require `/triage`, and does not trigger consent gates.
+
+## When to use
+
+- The user just ran `npx @friedbotstudio/create-baseline upgrade <target>` and the CLI exited 5 with a "Pending semantic-merge stage at <ts>" message.
+- The user types `/upgrade-project` or asks "reconcile the staged files".
+- A previous `/upgrade-project` invocation hit a `NEEDS_USER_INPUT` fallback, the user provided direction, and you re-invoke to pick up where you left off.
+
+## Inputs (read from disk)
+
+For each stage directory under `.claude/state/upgrade/`:
+
+- `manifest.json` — the **stage manifest** the CLI wrote. Schema:
+  ```json
+  {
+    "stage_version": 1,
+    "slug": "upgrade-flow-rework",
+    "created_at": "2026-05-20T14:49:00.000Z",
+    "baseline_version_from": "0.4.0",
+    "baseline_version_to": "0.5.0",
+    "files": [
+      {
+        "rel": "docs/init/seed.md",
+        "base_sha256": "<hex>",
+        "incoming_sha256": "<hex>",
+        "local_sha256": "<hex>",
+        "status": "PENDING"
+      }
+    ]
+  }
+  ```
+- For each entry in `files`, three artifacts are present:
+  - `<rel>.baseline-base` — the **BASE** content (the file as it was when the user last installed the baseline).
+  - `<rel>.baseline-incoming` — the **INCOMING** content (the file as it ships in the new baseline; INCOMING and REMOTE are the same thing).
+  - The LOCAL file remains at its real path inside the target tree (untouched by the CLI).
+
+## Procedure
+
+1. **Discover the stage.** Read `.claude/state/upgrade/` and pick the most-recent stage directory whose manifest has at least one file with `status: PENDING` or `status: NEEDS_USER_INPUT`. If no such stage exists, tell the user "No pending stage to reconcile" and exit.
+2. **Per file**, in the order they appear in the stage manifest:
+   - Read BASE, INCOMING, and LOCAL.
+   - Reason about the three-way delta. Identify what changed between BASE → INCOMING (the upstream edit), what changed between BASE → LOCAL (the user edit), and where they conflict.
+   - If both edits are textually non-overlapping, the CLI would have routed the file to tier 2 (mechanical merge). The fact that the file is in tier 3 means structural reconciliation is needed — most commonly: both sides inserted content at the same structural anchor (a new section, a new numbered article, a new TOC entry).
+   - Apply the **zero-drift renumbering rule** below.
+   - Write the reconciled bytes to the LOCAL path.
+   - Update the stage manifest entry's `status` to `RECONCILED`.
+3. **Finalize the stage.** When every entry's status is `RECONCILED`, delete the stage directory (`rm -rf .claude/state/upgrade/<ts>/`). Report per-file status to the user.
+
+## The zero-drift renumbering rule (binding)
+
+When BASE → INCOMING adds a new structural entry (a new Article, a new section, a new numbered item) at position N, and BASE → LOCAL added the user's own entry at the same position N, you SHALL renumber the user's entry to the **next available** slot (N+1) — you SHALL **never fold** the user's entry into an existing baseline section.
+
+Concrete example (the Article-XI reproducer):
+- BASE `seed.md` ends at Article X.
+- LOCAL has added a project-specific `## Article XI (user content)`.
+- INCOMING ships a new baseline `## Article XI (Skill provenance and the baseline manifest)`.
+
+The reconciled `seed.md` SHALL contain:
+- `## Article XI` — the baseline's content (verbatim).
+- `## Article XII` — the user's prior content, renumbered.
+- Every cross-reference in the document that pointed to "Article XI" SHALL be updated to point to either Article XI (when the reference was always to the new baseline content) or Article XII (when the reference was to what was previously Article XI). Surface ambiguous references as `NEEDS_USER_INPUT` per the fallback below.
+
+The reason **shift, never fold**: the next baseline upgrade SHALL produce zero new staging entries for this file. If the user's content were folded into an existing baseline section, the next upgrade would re-detect a customization and re-stage. The renumbering preserves both bodies as independent structural units, so subsequent upgrades see exactly the baseline-owned portion (Articles I–XI) as unchanged.
+
+The same principle applies recursively. If a later baseline ships Article XII and the user's content has been at Article XII since the prior upgrade, shift the user's content to Article XIII. Always shift to the next available slot.
+
+## `--dry-run` mode
+
+When invoked with `args=dry-run` (e.g., `/upgrade-project dry-run`):
+
+- Per file, produce the reconciled bytes in your reasoning, then emit a colorized unified diff (LOCAL vs reconciled) to the skill's terminal output rather than writing.
+- DO NOT modify any LOCAL file.
+- DO NOT update the stage manifest (statuses stay PENDING / NEEDS_USER_INPUT).
+- DO NOT delete the stage directory.
+- Tell the user: "Dry-run complete. Re-run without `dry-run` to apply."
+
+Dry-run mode is for building trust in early use. After the first few successful reconciliations, the user typically stops dry-running.
+
+## Fallback — NEEDS_USER_INPUT
+
+When you genuinely cannot disambiguate intent — the conflict has multiple plausible reconciliations and you cannot pick one without guessing the user's preference — apply the **NEEDS_USER_INPUT** fallback rather than picking arbitrarily:
+
+1. Update the stage manifest entry's `status` to `NEEDS_USER_INPUT`.
+2. Leave BASE, INCOMING, and LOCAL artifacts in place (do NOT delete the stage).
+3. Surface a targeted question to the user that names the file, summarizes the conflict in one sentence, and offers concrete options. Example: "Cannot disambiguate `docs/init/seed.md` Article XI: the baseline's new Article XI heading shares the user's chosen heading text. Should I (a) treat them as the same article and merge bodies, or (b) renumber the user's article to XII?"
+4. Exit clean. The user provides direction in their next prompt. A subsequent `/upgrade-project` invocation re-reads the stage manifest, finds the `NEEDS_USER_INPUT` entry, and re-attempts with the user's direction.
+
+Use this fallback sparingly. The rework's whole point is that LLM judgment exceeds `git merge-file` for structural conflicts; if you punt to NEEDS_USER_INPUT for trivial reconciliations, you defeat the purpose.
+
+## Constraints
+
+- **Validate `rel` before writing.** Before writing reconciled bytes to LOCAL, you SHALL verify that the resolved absolute path of `<target>/<rel>` is a descendant of `target`. A `rel` value that escapes the target tree (`../`, absolute path, symlink-resolved escape) SHALL be rejected as a `NEEDS_USER_INPUT` fallback with the reason `path-traversal-rejected`. The CLI's stage writer never produces escaping `rel` values, so this catches only tampered stage manifests from a local attacker with `.claude/state/` write access — defense in depth.
+- **No write outside the stage directory and the LOCAL path.** You SHALL NOT touch `.claude/.baseline-prior/`, the installed `.baseline-manifest.json`, or any other CLI state.
+- **No partial writes per file.** The reconciled LOCAL must be the complete final content. If you cannot produce a complete reconciliation, use the NEEDS_USER_INPUT fallback and leave LOCAL unmodified.
+- **Honor Article XI of CLAUDE.md.** This skill only touches files explicitly staged by the CLI — which, by construction, are baseline-owned. User-added files at colliding paths are never staged.
+- **No commits.** Reconciled files land on the working tree; the user inspects via `git diff` and commits when satisfied.
+- **No re-fetching from npm.** BASE is already on disk in the stage; no network round-trip needed.
+
+## Output
+
+After running, report per file:
+
+```
+# /upgrade-project — <stage_ts>
+
+- <rel>: RECONCILED (N lines changed)
+- <rel>: NEEDS_USER_INPUT — <one-sentence question>
+- <rel>: SKIPPED (dry-run)
+
+Stage deleted: yes | no (NEEDS_USER_INPUT pending)
+```

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, 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."
+   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 38 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."
@@ -69,7 +69,8 @@ The 11-phase workflow is the only sanctioned path from request to commit. Phase
 | 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 |
+| 11 | **Grant commit** (gate C) + changelog + commit | user runs **`/grant-commit`**, then `/changelog` (skill, sub-step 11.5), then `/commit` (skill) | commit |
+| 11.5 | Changelog (Phase 11 sub-step) | `/changelog` (skill); harness auto-invokes between gate C and `/commit` | `CHANGELOG.md` `## [Unreleased]` section grows + `.claude/state/changelog/<slug>.json` |
 
 **Mandatory rules:**
 
@@ -292,7 +293,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/` | 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
+| `.claude/skills/` | 38 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) + maintenance (1) |
 | `.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`. |
@@ -307,8 +308,8 @@ Cryptographic supply-chain attestation, signed lock files, and per-skill aggrega
 **Artifact drafting (4)** — each ships a `template.md`:
 - `intake` (Phase 1), `brd` (cross-functional pre-spec), `spec` (Phase 4, diagram-driven), `rca` (out-of-band postmortem)
 
-**Workflow phases (10)** — auto-invocable; orchestrator chains them:
-- `triage`, `scout`, `research`, `tdd`, `simplify`, `security`, `integrate`, `document`, `archive`, `commit`
+**Workflow phases (11)** — auto-invocable; orchestrator chains them:
+- `triage`, `scout`, `research`, `tdd`, `simplify`, `security`, `integrate`, `document`, `archive`, `changelog` (Phase 11.5), `commit`
 
 **Phase workers (5)** — execute pre-decided recipes; mandatorily invoke a sub-skill:
 - `scenario`, `implement`, `verify`, `prose`, `design-ui`

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

package/package.json

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

package/src/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, 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."
+   > "This repo has the Claude Code baseline installed (22 hooks, 1 subagent, 38 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."
@@ -69,7 +69,8 @@ The 11-phase workflow is the only sanctioned path from request to commit. Phase
 | 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 |
+| 11 | **Grant commit** (gate C) + changelog + commit | user runs **`/grant-commit`**, then `/changelog` (skill, sub-step 11.5), then `/commit` (skill) | commit |
+| 11.5 | Changelog (Phase 11 sub-step) | `/changelog` (skill); harness auto-invokes between gate C and `/commit` | `CHANGELOG.md` `## [Unreleased]` section grows + `.claude/state/changelog/<slug>.json` |
 
 **Mandatory rules:**
 
@@ -292,7 +293,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/` | 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) |
+| `.claude/skills/` | 38 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) + maintenance (1) |
 | `.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`. |
@@ -307,8 +308,8 @@ Cryptographic supply-chain attestation, signed lock files, and per-skill aggrega
 **Artifact drafting (4)** — each ships a `template.md`:
 - `intake` (Phase 1), `brd` (cross-functional pre-spec), `spec` (Phase 4, diagram-driven), `rca` (out-of-band postmortem)
 
-**Workflow phases (10)** — auto-invocable; orchestrator chains them:
-- `triage`, `scout`, `research`, `tdd`, `simplify`, `security`, `integrate`, `document`, `archive`, `commit`
+**Workflow phases (11)** — auto-invocable; orchestrator chains them:
+- `triage`, `scout`, `research`, `tdd`, `simplify`, `security`, `integrate`, `document`, `archive`, `changelog` (Phase 11.5), `commit`
 
 **Phase workers (5)** — execute pre-decided recipes; mandatorily invoke a sub-skill:
 - `scenario`, `implement`, `verify`, `prose`, `design-ui`

package/src/cli/diff-render.js

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

package/src/cli/install.js

@@ -32,14 +32,43 @@ async function listFiles(root, base = root, acc = []) {
   return acc;
 }
 
+async function readPackageVersion() {
+  try {
+    const pkgPath = join(PACKAGE_ROOT, 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return typeof pkg.version === 'string' && pkg.version.length > 0 ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 async function writeBaselineManifest(target) {
   const files = await listFiles(target);
-  const filtered = files.filter((p) => p !== '.claude/.baseline-manifest.json');
-  const m = await buildManifestFromDir(target, filtered);
+  const filtered = files.filter((p) =>
+    p !== '.claude/.baseline-manifest.json' && !p.startsWith('.claude/.baseline-prior/')
+  );
+  const baseline_version = await readPackageVersion();
+  const m = await buildManifestFromDir(target, filtered, { baseline_version });
   await mkdir(join(target, '.claude'), { recursive: true });
   await saveManifest(join(target, '.claude/.baseline-manifest.json'), m);
 }
 
+async function writeBaselinePriorMirror(templateDir, target) {
+  const priorRoot = join(target, '.claude/.baseline-prior');
+  await mkdir(priorRoot, { recursive: true });
+  await cp(templateDir, priorRoot, {
+    recursive: true,
+    force: true,
+    filter: (src) => {
+      const rel = relative(templateDir, src).split(sep).join('/');
+      if (rel === '') return true;
+      if (COPY_EXCLUDE.includes(rel)) return false;
+      return true;
+    },
+  });
+  await writeFile(join(priorRoot, '.gitignore'), '*\n');
+}
+
 function makeFilter(opts) {
   return (src, _dest) => {
     const rel = relative(opts.templateRoot, src).split(sep).join('/');
@@ -89,6 +118,7 @@ export async function freshInstall(templateDir, target, opts = {}) {
   await cp(templateDir, target, { recursive: true, force: false, filter });
   await applySpecialAndNeverTouch(templateDir, target);
   if (opts.withNpmrc === true) await materializeNpmrc(target);
+  await writeBaselinePriorMirror(templateDir, target);
   await writeBaselineManifest(target);
 }
 
@@ -97,5 +127,6 @@ export async function forceInstall(templateDir, target, opts = {}) {
   await cp(templateDir, target, { recursive: true, force: true, filter });
   await applySpecialAndNeverTouch(templateDir, target);
   if (opts.withNpmrc === true) await materializeNpmrc(target);
+  await writeBaselinePriorMirror(templateDir, target);
   await writeBaselineManifest(target);
 }

package/src/cli/manifest.js

@@ -2,7 +2,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 
-export const MANIFEST_VERSION = 1;
+export const MANIFEST_VERSION = 2;
 
 export async function hashFile(path) {
   const buf = await readFile(path);
@@ -24,15 +24,19 @@ export async function saveManifest(path, m) {
   await writeFile(path, JSON.stringify(m, null, 2) + '\n');
 }
 
-export async function buildManifestFromDir(rootDir, fileList) {
+export async function buildManifestFromDir(rootDir, fileList, opts = {}) {
   const files = {};
   const sorted = [...fileList].sort();
   for (const rel of sorted) {
     files[rel] = await hashFile(join(rootDir, rel));
   }
-  return {
+  const manifest = {
     manifest_version: MANIFEST_VERSION,
     generated_at: new Date().toISOString(),
     files,
   };
+  if (typeof opts.baseline_version === 'string' && opts.baseline_version.length > 0) {
+    manifest.baseline_version = opts.baseline_version;
+  }
+  return manifest;
 }

package/src/cli/merge.js

@@ -4,6 +4,7 @@ import { hashFile, saveManifest } from './manifest.js';
 import { deepMergeMcpServers } from './mcp.js';
 import { NEVER_TOUCH, SPECIAL_MERGE } from './install.js';
 import { pathExists } from './util.js';
+import { dispatchByTier, NoBaseError } from './upgrade-tiers.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
@@ -15,6 +16,9 @@ export const ACTION_KINDS = Object.freeze({
   NEVER_TOUCH_PRESERVE: 'NEVER_TOUCH_PRESERVE',
   NEVER_TOUCH_ADD: 'NEVER_TOUCH_ADD',
   SPECIAL_MERGE: 'SPECIAL_MERGE',
+  MECHANICAL_MERGE_CLEAN: 'MECHANICAL_MERGE_CLEAN',
+  MECHANICAL_MERGE_CONFLICTED: 'MECHANICAL_MERGE_CONFLICTED',
+  SEMANTIC_MERGE_STAGED: 'SEMANTIC_MERGE_STAGED',
 });
 
 async function copyFile(src, dst) {
@@ -22,13 +26,40 @@ async function copyFile(src, dst) {
   await cp(src, dst, { force: true });
 }
 
+function readShaFromEntry(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && typeof entry.sha256 === 'string') return entry.sha256;
+  return null;
+}
+
+function readTierFromEntry(entry) {
+  if (entry && typeof entry === 'object' && typeof entry.tier === 'string') return entry.tier;
+  // Bare-sha entries (legacy shipped manifest_version: 2 OR installed-manifest
+  // round-trips without tier overlay) fall back to BINARY_PROMPT — the safe
+  // default that preserves today's two-way prompt behavior. New shipped
+  // manifests (v3+) carry `{sha256, tier}` per file and exercise the full
+  // three-tier flow.
+  return 'BINARY_PROMPT';
+}
+
 export async function threeWayMerge(templateDir, target, oldManifest, newManifest, opts = {}) {
-  const { dryRun = false, onSkipCustomized = null } = opts;
+  const { dryRun = false, onSkipCustomized = null, pack = null } = opts;
   const actions = [];
   const oldFiles = oldManifest?.files ?? {};
   const newFiles = newManifest?.files ?? {};
+  const baseline_version = oldManifest?.baseline_version;
   const allPaths = new Set([...Object.keys(oldFiles), ...Object.keys(newFiles)]);
 
+  const tierCtx = {
+    target,
+    templateDir,
+    oldManifest,
+    newManifest,
+    baseline_version,
+    pack,
+    stageRunTs: null,
+  };
+
   for (const rel of allPaths) {
     const tplPath = join(templateDir, rel);
     const tgtPath = join(target, rel);
@@ -51,8 +82,10 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
       continue;
     }
 
-    const newHash = newFiles[rel];
-    const oldHash = oldFiles[rel];
+    const newEntry = newFiles[rel];
+    const oldEntry = oldFiles[rel];
+    const newHash = readShaFromEntry(newEntry);
+    const oldHash = readShaFromEntry(oldEntry);
     const targetExists = await pathExists(tgtPath);
     const tgtHash = targetExists ? await hashFile(tgtPath) : null;
 
@@ -74,13 +107,10 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     }
 
     if (newHash && tgtHash && tgtHash !== oldHash) {
-      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' });
-      }
+      const action = await dispatchCustomized({
+        rel, newEntry, tierCtx, dryRun, onSkipCustomized, tplPath, tgtPath,
+      });
+      actions.push(action);
       continue;
     }
 
@@ -106,7 +136,44 @@ export async function threeWayMerge(templateDir, target, oldManifest, newManifes
     await saveManifest(join(target, '.claude/.baseline-manifest.json'), newManifest);
   }
 
-  const skipKinds = [ACTION_KINDS.SKIP_CUSTOMIZED, ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED];
-  const exitCode = actions.some((a) => skipKinds.includes(a.kind)) ? 3 : 0;
-  return { actions, exitCode };
+  return { actions, exitCode: computeExitCode(actions) };
+}
+
+async function dispatchCustomized({ rel, newEntry, tierCtx, dryRun, onSkipCustomized, tplPath, tgtPath }) {
+  const tier = readTierFromEntry(newEntry);
+  if (tier === 'MECHANICAL' || tier === 'SEMANTIC') {
+    if (dryRun) {
+      return { kind: tier === 'MECHANICAL' ? ACTION_KINDS.MECHANICAL_MERGE_CLEAN : ACTION_KINDS.SEMANTIC_MERGE_STAGED, path: rel, reason: 'dry-run: tier dispatch deferred' };
+    }
+    try {
+      return await dispatchByTier(rel, tier, tierCtx);
+    } catch (err) {
+      if (err instanceof NoBaseError) {
+        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err });
+      }
+      throw err;
+    }
+  }
+  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath });
+}
+
+async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err = null }) {
+  const choice = onSkipCustomized ? await onSkipCustomized(rel) : 'keep-mine';
+  if (choice === 'take-theirs') {
+    if (!dryRun) await copyFile(tplPath, tgtPath);
+    return { kind: ACTION_KINDS.OVERWRITE, path: rel, reason: err ? `BASE recovery failed (${err.kind}); user chose take-theirs` : 'customized file; user chose take-theirs' };
+  }
+  return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); preserved` : 'target customized since last install' };
+}
+
+function computeExitCode(actions) {
+  let code = 0;
+  for (const a of actions) {
+    if (a.kind === ACTION_KINDS.SEMANTIC_MERGE_STAGED) code = Math.max(code, 5);
+    else if (a.kind === ACTION_KINDS.MECHANICAL_MERGE_CONFLICTED) code = Math.max(code, 4);
+    else if (a.kind === ACTION_KINDS.SKIP_CUSTOMIZED || a.kind === ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED) {
+      code = Math.max(code, 3);
+    }
+  }
+  return code;
 }