@friedbotstudio/create-baseline 0.3.0 → 0.4.0

package/README.md

@@ -37,11 +37,11 @@ A discipline layer for Claude Code. Hooks at every tool boundary, a workflow tha
 > [!IMPORTANT]
 > **Install in one line:** `npx @friedbotstudio/create-baseline ./your-project`
 >
-> The CLI fetches the published package, runs the install, and leaves your project with `.claude/`, `CLAUDE.md`, `docs/init/seed.md`, and `.mcp.json`. Re-run with `--merge` to bring an existing install forward; with `--dry-run` to preview without writing; with `doctor` to report drift.
+> The CLI fetches the published package, runs the install, and leaves your project with `.claude/`, `CLAUDE.md`, `docs/init/seed.md`, and `.mcp.json`. Re-run with the `upgrade` subcommand to bring an existing install forward (interactive in a TTY, batch-mode in CI). Add `--dry-run` to preview, and run `doctor` to report drift (pass `--json` for machine output).
 
 ## What this is
 
-The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **36 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
+The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **37 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
 
 Every soft engineering rule a team usually repeats every session — *don't push, don't `--amend`, don't self-approve specs, don't skip phases, don't mock internal modules* — becomes a structural guarantee because the hooks run **outside Claude's tool boundary**. Claude cannot disable a hook with a flag, cannot write a consent marker, cannot reorder the phases without an explicit exception that triage records on disk.
 
@@ -94,12 +94,14 @@ npx @friedbotstudio/create-baseline ./your-project
 # Force-overwrite an existing install (interactive — type 'overwrite')
 npx @friedbotstudio/create-baseline ./your-project --overwrite
 
-# Three-way merge against a previously-installed baseline:
+# Upgrade an existing install against a newer baseline version.
+# In a TTY, each customised file becomes a keep-mine / take-theirs / abort
+# prompt. In CI / piped stdout, reproduces the prior --merge behaviour:
 #   - adds new baseline files
 #   - refreshes baseline files the user has not touched
 #   - preserves user-customised files (exit 3 if any)
 #   - removes baseline files the upstream removed (only if untouched locally)
-npx @friedbotstudio/create-baseline ./your-project --merge
+npx @friedbotstudio/create-baseline upgrade ./your-project
 
 # Preview without writing anything
 npx @friedbotstudio/create-baseline ./your-project --dry-run
@@ -124,6 +126,10 @@ npx @friedbotstudio/create-baseline doctor ./your-project
 # Strict mode — print TAMPERED: shipped vs observed sha256 for every
 # customised file and exit 1 on any drift.
 npx @friedbotstudio/create-baseline doctor ./your-project --strict
+
+# JSON mode — emit the structured report on stdout for CI parsers.
+# Same exit codes; honours --strict.
+npx @friedbotstudio/create-baseline doctor ./your-project --json
 ```
 
 ## Quickstart

package/bin/cli.js

@@ -2,7 +2,7 @@
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 
 import * as io from '../src/cli/io.js';
@@ -17,18 +17,24 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 const HELP_TEXT = `Usage:
-  create-baseline <target> [options]      install/merge the baseline
+  create-baseline <target> [options]      install the baseline
+  create-baseline upgrade [target]        three-way merge against an installed baseline
   create-baseline doctor [target]         report drift in an installed target
 
 Materializes the Claude Code baseline (.claude/, CLAUDE.md, .mcp.json,
 docs/init/seed.md, plus vendored LICENSE/NOTICE) into <target>.
 
-Modes:
+Install modes:
   (default)        Fresh install. Refuses if any sentinel path already present.
   --force          Overwrite unconditionally (requires typing 'overwrite' in TTY).
-  --merge          Three-way merge against existing .baseline-manifest.json.
-                   Prunes baseline files removed upstream that the user hadn't
-                   touched; customized stale files are preserved (exit 3).
+  --dry-run        Print intended actions without writing.
+
+Upgrade:
+  Replaces the prior --merge flag. Reads <target>/.claude/.baseline-manifest.json
+  and runs a three-way merge against the shipped template. Prunes baseline files
+  removed upstream that the user hadn't touched; customized-stale files are
+  preserved (exit 3) — or interactively resolved when stdout is a TTY (keep
+  mine / take theirs / abort).
   --dry-run        Print intended actions without writing.
 
 Doctor:
@@ -38,6 +44,8 @@ Doctor:
   --strict          Promote customized to exit 1 and prefix tampered paths
                     with "TAMPERED:" with shipped vs observed sha256. Detects
                     post-install supply-chain tampering of the baseline tree.
+  --json            Emit the structured report as JSON to stdout instead of
+                    the text renderer. Honours --strict; same exit codes.
 
 PlantUML jar (~19 MB, fetched at install time from upstream):
   --no-plantuml       Skip the jar download entirely.
@@ -54,12 +62,24 @@ Misc:
 
 Exit codes:
   0  success / clean doctor
-  1  user abort, conflict-without-force/merge, or doctor reports missing files
-  2  argv error, non-TTY where TTY required, or doctor finds no manifest
-  3  --merge had skipped customizations (or stale-customized prunes)
+  1  user abort, conflict-without-force, doctor reports missing files, or upgrade aborted
+  2  argv error, non-TTY where TTY required, doctor finds no manifest, or --merge passed
+  3  upgrade had skipped customizations (or stale-customized prunes)
   4  --require-plantuml fetch failure
 `;
 
+const OPTIONS = {
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean' },
+  force: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  'no-plantuml': { type: 'boolean' },
+  'require-plantuml': { type: 'boolean' },
+  'with-npmrc': { type: 'boolean' },
+  strict: { type: 'boolean' },
+  json: { type: 'boolean' },
+};
+
 async function readPackageVersion() {
   try {
     const pkg = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf8'));
@@ -77,16 +97,141 @@ function getTemplateDir() {
   throw new Error(`Template directory not found at ${candidate}. Run \`npm run build\` (or rely on prepack).`);
 }
 
-function listShippedFiles(templateDir) {
-  const files = [];
-  const walk = (dir, base) => {
-    for (const entry of require('node:fs').readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) walk(full, base);
-      else if (entry.isFile()) files.push(full.slice(base.length + 1).split(require('node:path').sep).join('/'));
+async function listShippedFiles(templateDir) {
+  const out = [];
+  await walkFiles(templateDir, templateDir, out);
+  return out;
+}
+
+async function walkFiles(dir, base, acc) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) await walkFiles(full, base, acc);
+    else if (entry.isFile()) acc.push(full.slice(base.length + 1).split('/').join('/'));
+  }
+}
+
+async function dispatchInstall(target, values, templateDir) {
+  const dryRun = !!values['dry-run'];
+  if (process.stdout.isTTY && !values.force && !dryRun) {
+    return await runBrandedInstall(target, values, templateDir);
+  }
+  return await runPlainInstall(target, values, templateDir);
+}
+
+async function runBrandedInstall(target, values, templateDir) {
+  const tui = await import('../src/cli/tui/install.js');
+  return tui.run({
+    target,
+    opts: {
+      templateDir,
+      noPlantuml: !!values['no-plantuml'],
+      requirePlantuml: !!values['require-plantuml'],
+      withNpmrc: !!values['with-npmrc'],
+    },
+  });
+}
+
+async function runPlainInstall(target, values, templateDir) {
+  const dryRun = !!values['dry-run'];
+  if (values.force) {
+    if (!process.stdin.isTTY) {
+      io.error('--force requires an interactive TTY for the confirmation prompt');
+      return 2;
+    }
+    if (!dryRun) {
+      const answer = await io.ask("type 'overwrite' to proceed: ");
+      if (answer.toLowerCase() !== 'overwrite') {
+        io.error('confirmation declined');
+        return 1;
+      }
     }
-  };
-  return files;
+  }
+
+  try {
+    if (values.force) {
+      if (dryRun) io.log(`Would force-install into ${target}`);
+      else await forceInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
+    } else {
+      if (dryRun) io.log(`Would fresh-install into ${target}`);
+      else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
+    }
+  } catch (err) {
+    io.error(`install failed: ${err.message}`);
+    return 1;
+  }
+
+  if (!dryRun) {
+    const plantumlExit = await fetchPlantumlPlain(target, values);
+    if (plantumlExit !== 0) return plantumlExit;
+    io.log(`Installed manifest version 1 to ${target}.`);
+    io.log(`Pin via "@friedbotstudio/create-baseline@<exact-version>" in your bootstrap docs.`);
+  }
+  return 0;
+}
+
+async function fetchPlantumlPlain(target, values) {
+  const result = await fetchPlantumlIfMissing(target, {
+    noPlantuml: values['no-plantuml'],
+    requirePlantuml: values['require-plantuml'],
+  });
+  if (result.outcome === FETCH_OUTCOMES.WARNED_NETWORK_FAILURE
+      || result.outcome === FETCH_OUTCOMES.WARNED_HASH_MISMATCH) {
+    io.warn(`PlantUML jar fetch failed (${result.reason}); install continued. Retry with --require-plantuml or set system plantuml on PATH.`);
+    return 0;
+  }
+  if (result.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
+    io.error(`--require-plantuml: ${result.reason}`);
+    return 4;
+  }
+  return 0;
+}
+
+async function dispatchUpgrade(target, values, templateDir) {
+  const manifestPath = join(target, '.claude/.baseline-manifest.json');
+  if (!existsSync(manifestPath)) {
+    io.error(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
+    return 2;
+  }
+  if (process.stdout.isTTY) {
+    const tui = await import('../src/cli/tui/upgrade.js');
+    return tui.run({
+      target,
+      opts: { templateDir, dryRun: !!values['dry-run'] },
+    });
+  }
+  return await runPlainUpgrade(target, values, templateDir, manifestPath);
+}
+
+async function runPlainUpgrade(target, values, templateDir, manifestPath) {
+  const oldManifest = await loadManifest(manifestPath);
+  const tplFiles = await listShippedFiles(templateDir);
+  const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  if (values['dry-run']) {
+    io.log(`Would upgrade ${tplFiles.length} files into ${target}`);
+    return 0;
+  }
+  const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
+  for (const action of report.actions) {
+    io.log(`${action.kind.padEnd(24)} ${action.path}`);
+  }
+  return report.exitCode;
+}
+
+async function dispatchDoctor(positionals, values) {
+  const target = resolve(positionals[1] ?? '.');
+  const report = await runDoctor(target, { strict: !!values.strict });
+  if (values.json) {
+    io.log(JSON.stringify(report));
+    return report.exitCode;
+  }
+  if (process.stdout.isTTY) {
+    const tui = await import('../src/cli/tui/doctor.js');
+    tui.render(report);
+  } else {
+    process.stdout.write(formatReport(report));
+  }
+  return report.exitCode;
 }
 
 async function main(argv) {
@@ -94,21 +239,15 @@ async function main(argv) {
   try {
     parsed = parseArgs({
       args: argv.slice(2),
-      options: {
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean' },
-        force: { type: 'boolean' },
-        merge: { type: 'boolean' },
-        'dry-run': { type: 'boolean' },
-        'no-plantuml': { type: 'boolean' },
-        'require-plantuml': { type: 'boolean' },
-        'with-npmrc': { type: 'boolean' },
-        strict: { type: 'boolean' },
-      },
+      options: OPTIONS,
       strict: true,
       allowPositionals: true,
     });
   } catch (err) {
+    if (/--merge/.test(err.message)) {
+      io.error('--merge has been removed; use `create-baseline upgrade <target>` instead.');
+      return 2;
+    }
     io.error(err.message);
     return 2;
   }
@@ -116,26 +255,42 @@ async function main(argv) {
   const { values, positionals } = parsed;
 
   if (values.help) {
-    io.log(HELP_TEXT);
+    const version = await readPackageVersion();
+    if (process.stdout.isTTY) {
+      const meta = await import('../src/cli/tui/meta.js');
+      meta.renderHelp(HELP_TEXT, version);
+    } else {
+      io.log(HELP_TEXT);
+    }
     return 0;
   }
   if (values.version) {
-    io.log(await readPackageVersion());
+    const version = await readPackageVersion();
+    if (process.stdout.isTTY) {
+      const meta = await import('../src/cli/tui/meta.js');
+      meta.renderVersion(version);
+    } else {
+      io.log(version);
+    }
     return 0;
   }
 
-  // `doctor` subcommand: read-only drift check against an installed target's manifest.
   if (positionals[0] === 'doctor') {
-    const target = resolve(positionals[1] ?? '.');
-    const report = await runDoctor(target, { strict: !!values.strict });
-    io.log(formatReport(report));
-    return report.exitCode;
+    return await dispatchDoctor(positionals, values);
   }
 
-  if (values.force && values.merge) {
-    io.error('--force and --merge are mutually exclusive');
-    return 2;
+  if (positionals[0] === 'upgrade') {
+    const target = resolve(positionals[1] ?? '.');
+    let templateDir;
+    try {
+      templateDir = getTemplateDir();
+    } catch (err) {
+      io.error(err.message);
+      return 2;
+    }
+    return await dispatchUpgrade(target, values, templateDir);
   }
+
   if (values['no-plantuml'] && values['require-plantuml']) {
     io.error('--no-plantuml and --require-plantuml are mutually exclusive');
     return 2;
@@ -151,8 +306,6 @@ async function main(argv) {
   }
 
   const target = resolve(positionals[0]);
-  const dryRun = !!values['dry-run'];
-
   let templateDir;
   try {
     templateDir = getTemplateDir();
@@ -163,88 +316,13 @@ async function main(argv) {
 
   const sentinels = await scanSentinels(target);
   const hasConflict = sentinels.length > 0;
-
-  if (hasConflict && !values.force && !values.merge) {
+  if (hasConflict && !values.force) {
     io.error(`existing baseline detected at ${target}: ${sentinels.join(', ')}`);
-    io.error('pass --force to overwrite or --merge to three-way merge');
+    io.error('pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge');
     return 1;
   }
 
-  if (values.force) {
-    if (!process.stdin.isTTY) {
-      io.error('--force requires an interactive TTY for the confirmation prompt');
-      return 2;
-    }
-    if (!dryRun) {
-      const answer = await io.ask("type 'overwrite' to proceed: ");
-      if (answer.toLowerCase() !== 'overwrite') {
-        io.error('confirmation declined');
-        return 1;
-      }
-    }
-  }
-
-  if (values.merge) {
-    if (!process.stdin.isTTY && !dryRun) {
-      io.error('--merge requires an interactive TTY for the confirmation prompt');
-      return 2;
-    }
-    if (!dryRun) {
-      const answer = await io.ask("type 'merge' to proceed: ");
-      if (answer.toLowerCase() !== 'merge') {
-        io.error('confirmation declined');
-        return 1;
-      }
-    }
-  }
-
-  let exitCode = 0;
-  try {
-    if (values.merge) {
-      const oldManifest = await loadManifest(join(target, '.claude/.baseline-manifest.json'));
-      const tplFiles = listShippedFiles(templateDir);
-      const newManifest = await buildManifestFromDir(templateDir, tplFiles);
-      if (dryRun) {
-        io.log(`Would merge ${tplFiles.length} files into ${target}`);
-      } else {
-        const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
-        for (const a of report.actions) {
-          io.log(`${a.kind.padEnd(24)} ${a.path}`);
-        }
-        exitCode = report.exitCode;
-      }
-    } else if (values.force) {
-      if (dryRun) io.log(`Would force-install into ${target}`);
-      else await forceInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
-    } else {
-      if (dryRun) io.log(`Would fresh-install into ${target}`);
-      else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
-    }
-  } catch (err) {
-    io.error(`install failed: ${err.message}`);
-    return 1;
-  }
-
-  if (!dryRun) {
-    const fetchResult = await fetchPlantumlIfMissing(target, {
-      noPlantuml: values['no-plantuml'],
-      requirePlantuml: values['require-plantuml'],
-    });
-    if (fetchResult.outcome === FETCH_OUTCOMES.WARNED_NETWORK_FAILURE
-        || fetchResult.outcome === FETCH_OUTCOMES.WARNED_HASH_MISMATCH) {
-      io.warn(`PlantUML jar fetch failed (${fetchResult.reason}); install continued. Retry with --require-plantuml or set system plantuml on PATH.`);
-    } else if (fetchResult.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
-      io.error(`--require-plantuml: ${fetchResult.reason}`);
-      return 4;
-    }
-  }
-
-  if (!dryRun && exitCode === 0) {
-    io.log(`Installed manifest version 1 to ${target}.`);
-    io.log(`Pin via "@friedbotstudio/create-baseline@<exact-version>" in your bootstrap docs.`);
-  }
-
-  return exitCode;
+  return await dispatchInstall(target, values, templateDir);
 }
 
 main(process.argv).then((code) => { process.exit(code); }).catch((err) => {

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

@@ -0,0 +1,69 @@
+---
+name: changelog
+owner: baseline
+description: Workflow Phase 11.5 — Pre-commit changelog curation. Reads the staged commit's diff + conventional-type, classifies entries into keepachangelog 1.0.0 sections, appends them under `## [Unreleased]` in CHANGELOG.md, and writes ChangelogState to `.claude/state/changelog/<slug>.json`. Runs between `/grant-commit` (gate C) and `/commit`. Authorized by the same `commit_consent` token that authorizes `/commit` — no new gate. Also supports `--preview-only` for ad-hoc projected-version lookups outside a workflow.
+argument-hint: "[--preview-only]"
+---
+
+# changelog — Phase 11.5
+
+Curates the `## [Unreleased]` section of `CHANGELOG.md` per [keepachangelog.com 1.0.0](https://keepachangelog.com/en/1.0.0/) before `/commit` stages the diff. Pure local curation — `@semantic-release/changelog` continues to own release-time version-block insertion.
+
+## Prereq
+
+ALL of `archive` AND `memory-flush` AND (implicitly) a fresh `commit_consent` token MUST be in place. Verified by the actuator at runtime, NOT by a separate guard hook.
+
+## Applicability
+
+Git projects only. Non-git projects auto-except this phase at `/triage` time alongside `commit` and the swarm phases (CLAUDE.md Article IV).
+
+## Steps
+
+1. **Prereq check.** Read `.claude/state/workflow.json`. Confirm `archive` and `memory-flush` are in `completed`. If not, exit 1 with a clear error.
+2. **Invoke the actuator.** `node .claude/skills/changelog/changelog.mjs --slug <slug> --project-root <root>`. The actuator does all the work: reads the consent token, classifies commits, appends to `## [Unreleased]`, writes state.
+3. **On actuator success.** The harness marks this task `completed`, appends `"changelog"` to `workflow.json → completed`, and continues to `/commit`.
+4. **On actuator failure (exit 1).** Surface the stderr to the user. Most likely cause: `commit_consent` expired. User re-runs `/grant-commit`.
+
+## Ad-hoc preview mode
+
+The skill is also invokable outside an active workflow via `--preview-only`. The actuator calls `semantic-release` as a JS API with `dryRun: true` and prints the projected next version + a draft fragment to stdout. No files are written; no consent gesture is required. Useful for answering "what version would my next push deploy?" without running the full workflow.
+
+## Companion files
+
+- `changelog.mjs` — CLI actuator. The decision logic.
+- `classifier.mjs` — conventional-commit type → keepachangelog section.
+- `version-preview.mjs` — semantic-release JS API call for projected version.
+- `state-writer.mjs` — idempotent writes to `.claude/state/changelog/<slug>.json`.
+- `unreleased-writer.mjs` — `CHANGELOG.md` RMW under `## [Unreleased]`; also exports `reinsertUnreleasedHeading` for the release-time fallback (`@semantic-release/changelog` destroys the heading position; this restores it).
+
+## Constraints
+
+- **Idempotent.** Re-invocation on the same slug + same HEAD SHA does NOT duplicate entries. The actuator computes a digest from `(slug, source_commit_sha, entries)` and skips writes if the digest matches the prior state file.
+- **No internal mocks.** The actuator imports `semantic-release` (devDep) directly; no mock layer. The system clock IS mocked in `consent-expired` tests with `touch -d`.
+- **TTL fit.** The skill is designed to complete inside the 300 s `commit_consent` window. Typical runtime: under 5 s. If the token expires mid-run, the actuator exits 1 BEFORE writing — partial writes are not allowed.
+- **CHANGELOG.md migration is in scope of the workflow that introduces this skill.** Subsequent workflows assume the file already has the keepachangelog `## [Unreleased]` heading.
+
+## Spec traceability
+
+The acceptance criteria from `docs/specs/changelog-skill-and-responsive-svgs.md` map to the skill's components as follows:
+
+- **AC-001** (harness invokes changelog between gate C and commit; Unreleased section grows) — `changelog.mjs` `runActiveMode` + `unreleased-writer.mjs` `appendUnderUnreleased`.
+- **AC-002** (CHANGELOG.md included in commit stage list) — `commit/SKILL.md` Step 3 named-path enumeration grows `CHANGELOG.md` via the actuator's write; verified in `golden-path_test.sh`.
+- **AC-003** (non-git short-circuit) — `triage/SKILL.md` step 2 non-git auto-except list grew to include `"changelog"` alongside `"commit"`; verified in `non-git-shortcircuit_test.sh`.
+- **AC-004** (audit-baseline byte-mirror invariants after Article IV amendment) — handled in `CLAUDE.md` ↔ `src/CLAUDE.template.md` mirror + `docs/init/seed.md` ↔ `src/seed.template.md` mirror; verified by `audit.sh` PASS.
+- **AC-005** (site-src narrative names new phase; Article X.1 em-dash discipline) — handled in `/document` Phase 10 per design-ui row 1 misroute terminal at `.claude/state/design/changelog-skill-and-responsive-svgs-row1.json`.
+- **AC-006** (SVG legible at 320 px) — handled in `site-src/assets/site.css` bento `@media (max-width: 768px)` block per design-ui row 0 audit at `docs/design/changelog-skill-and-responsive-svgs.audit.md`.
+- **AC-007** (bento composition at 1920 px) — same design-ui row 0 deliverable; audit verdict 20/20 PASS.
+- **AC-008** (workflow.json completed sequence ends with `[..., "changelog", "commit"]`) — `harness/SKILL.md` phase-ordering fence + `commit/SKILL.md` prereq line.
+- **AC-009** (source_backlog_keys stamp-closure on commit) — `commit/SKILL.md` Step 6 invokes `sweep.py --mode stamp-closure`; no change to that flow needed in this workflow.
+- **AC-010** (consent-expired denial) — `changelog.mjs` `checkConsent` reads epoch from line 1 of `commit_consent`; exits 1 on stale; verified in `consent-expired_test.sh`.
+- **AC-011** (TaskList re-seed across session boundary) — `triage/SKILL.md` four task-seeding templates updated to insert `Run /changelog` between `Wait for /grant-commit` and `Run /commit`; `harness/SKILL.md` state-machine table grew a row for the new gap.
+- **AC-012** (ad-hoc `--preview-only` mode) — `changelog.mjs` `runPreviewMode` calls semantic-release JS API with `dryRun:true`; no consent required; verified in `preview-only_test.sh`.
+- **AC-013** (`@semantic-release/changelog` preserves Unreleased OR fallback re-inserts) — `unreleased-writer.mjs` `reinsertUnreleasedHeading` export; verified in `keepachangelog-unreleased-preserved_test.mjs` (test 1 documents the plugin behavior empirically; test 2 confirms the fallback restores canonical structure).
+
+Design call rows from the spec:
+
+- **`architecture-svg-bento-grid-responsive`** (design lane) — completed at design-ui row 0; site-src/index.njk + site-src/assets/site.css written; audit 20/20 PASS.
+- **`site-narrative-new-phase-mention`** (copy lane) — Stage 0 misroute to `/document` Phase 10; state checkpoint at row1.json; `/document` reads the misroute terminal and routes the three target files through `Skill(prose)` with mandatory humanizer pass.
+
+Phase 11.5 introduces gate-adjacent automation between gate C `/grant-commit` (Article IV phase 11 gate) and the `/commit` skill body. No new gate (no gate D); the existing `commit_consent` token authorizes both.

package/obj/template/.claude/skills/changelog/changelog.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Phase 11.5 Changelog actuator.
+//
+// CLI:
+//   node changelog.mjs --slug <slug> [--project-root <path>]
+//   node changelog.mjs --preview-only --slug <slug> [--project-root <path>]
+//
+// Active mode: verifies commit_consent freshness, classifies new commits,
+// appends keepachangelog entries under ## [Unreleased] in CHANGELOG.md,
+// writes ChangelogState to .claude/state/changelog/<slug>.json.
+//
+// Preview mode: prints projected next version + draft fragment; no writes.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { classify } from './classifier.mjs';
+import { previewProjectedVersion } from './version-preview.mjs';
+import { writeState } from './state-writer.mjs';
+import { appendUnderUnreleased } from './unreleased-writer.mjs';
+
+const TTL_SECONDS = 300;
+
+function parseCli() {
+  const { values } = parseArgs({
+    options: {
+      slug: { type: 'string' },
+      'preview-only': { type: 'boolean', default: false },
+      'project-root': { type: 'string', default: '.' },
+    },
+    strict: true,
+  });
+  if (!values.slug) {
+    process.stderr.write('error: --slug required\n');
+    process.exit(2);
+  }
+  return {
+    slug: values.slug,
+    previewOnly: values['preview-only'],
+    projectRoot: resolve(values['project-root']),
+  };
+}
+
+function checkConsent(projectRoot) {
+  const path = join(projectRoot, '.claude/state/commit_consent');
+  if (!existsSync(path)) {
+    return { ok: false, reason: 'consent absent (no commit_consent token)' };
+  }
+  // Token contract: line 1 is the unix epoch when /grant-commit was issued.
+  // Reading the epoch (not filesystem mtime) keeps the freshness check
+  // consistent with how `/grant-commit` writes the file and with how tests
+  // stale the consent via `echo "<old-epoch>" > commit_consent`.
+  const firstLine = readFileSync(path, 'utf8').split('\n', 1)[0].trim();
+  const tokenEpoch = parseInt(firstLine, 10);
+  if (!Number.isFinite(tokenEpoch)) {
+    return { ok: false, reason: 'consent malformed (line 1 not an epoch)' };
+  }
+  const ageSeconds = Math.floor(Date.now() / 1000) - tokenEpoch;
+  if (ageSeconds > TTL_SECONDS) {
+    return {
+      ok: false,
+      reason: `consent expired (${ageSeconds}s > ${TTL_SECONDS}s)`,
+    };
+  }
+  return { ok: true };
+}
+
+function getHeadSha(projectRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: projectRoot, encoding: 'utf8',
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+function buildEntry(commit) {
+  const cls = classify(commit);
+  if (!cls) return null;
+  return {
+    section: cls.section,
+    body: commit.subject,
+    conventional_type: commit.type,
+    conventional_scope: commit.scope,
+    breaking: cls.breaking,
+  };
+}
+
+function renderPreviewFragment(projection) {
+  const lines = [];
+  lines.push(`Projected: ${projection.version} (${projection.type || 'no release'})`);
+  lines.push(`Commits analyzed: ${projection.commits.length}`);
+  if (projection.commits.length > 0) {
+    lines.push('');
+    lines.push('Draft fragment under ## [Unreleased]:');
+    const entries = projection.commits.map(buildEntry).filter(Boolean);
+    if (entries.length === 0) {
+      lines.push('(no commits map to keepachangelog sections)');
+    } else {
+      const grouped = new Map();
+      for (const e of entries) {
+        if (!grouped.has(e.section)) grouped.set(e.section, []);
+        grouped.get(e.section).push(e);
+      }
+      for (const [section, items] of grouped) {
+        lines.push('');
+        lines.push(`### ${section}`);
+        for (const item of items) {
+          const prefix = item.breaking ? '**BREAKING:** ' : '';
+          lines.push(`- ${prefix}${item.body}`);
+        }
+      }
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+async function runPreviewMode({ projectRoot }) {
+  const projection = await previewProjectedVersion(projectRoot);
+  process.stdout.write(renderPreviewFragment(projection));
+  process.exit(0);
+}
+
+async function runActiveMode({ slug, projectRoot }) {
+  const consent = checkConsent(projectRoot);
+  if (!consent.ok) {
+    process.stderr.write(`error: ${consent.reason}\n`);
+    process.exit(1);
+  }
+  const projection = await previewProjectedVersion(projectRoot);
+  const entries = projection.commits.map(buildEntry).filter(Boolean);
+  const changelogPath = join(projectRoot, 'CHANGELOG.md');
+  await appendUnderUnreleased(changelogPath, entries);
+  const state = {
+    slug,
+    source_commit_sha: getHeadSha(projectRoot),
+    projected_version: projection.version,
+    projected_type: projection.type,
+    entries,
+    generated_at: new Date().toISOString(),
+    unreleased_inserted_at: new Date().toISOString(),
+  };
+  await writeState(projectRoot, slug, state);
+  process.stdout.write(
+    `changelog: wrote ${entries.length} entries to ${changelogPath} (projected ${projection.version})\n`,
+  );
+}
+
+async function main() {
+  const cli = parseCli();
+  if (cli.previewOnly) {
+    await runPreviewMode(cli);
+  } else {
+    await runActiveMode(cli);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`error: ${err.message}\n`);
+  process.exit(1);
+});