@friedbotstudio/create-baseline 0.3.0 → 0.4.0

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

@@ -0,0 +1,49 @@
+// Conventional-commit type → keepachangelog 1.0.0 section.
+//
+// Default mapping (overridable per-commit in the actuator):
+//   feat       → Added
+//   fix        → Fixed
+//   perf       → Changed
+//   refactor   → Changed
+//   docs       → (no entry; release-time CHANGELOG ignores)
+//   style      → (no entry)
+//   test       → (no entry)
+//   build      → (no entry)
+//   ci         → (no entry)
+//   chore      → (no entry)
+//   revert     → Removed
+// Breaking suffix (`feat!:` or `BREAKING CHANGE:` body) → forces Changed
+// section regardless of base type AND sets breaking: true on the entry.
+
+const TYPE_TO_SECTION = Object.freeze({
+  feat: 'Added',
+  fix: 'Fixed',
+  perf: 'Changed',
+  refactor: 'Changed',
+  revert: 'Removed',
+});
+
+const SKIP_TYPES = new Set(['docs', 'style', 'test', 'build', 'ci', 'chore']);
+
+export function classify(commit) {
+  if (!commit || typeof commit !== 'object') return null;
+  const type = (commit.type || '').toLowerCase();
+  const breaking = Boolean(commit.breaking);
+  if (SKIP_TYPES.has(type) && !breaking) return null;
+  if (breaking) {
+    return { section: 'Changed', breaking: true };
+  }
+  const section = TYPE_TO_SECTION[type];
+  if (!section) return null;
+  return { section, breaking: false };
+}
+
+// All six keepachangelog 1.0.0 sections, in canonical order.
+export const KEEPACHANGELOG_SECTIONS = Object.freeze([
+  'Added',
+  'Changed',
+  'Deprecated',
+  'Removed',
+  'Fixed',
+  'Security',
+]);

package/obj/template/.claude/skills/changelog/state-writer.mjs

@@ -0,0 +1,19 @@
+// Idempotent writer for .claude/state/changelog/<slug>.json.
+//
+// Re-invocation on the same (slug, source_commit_sha) re-writes the file with
+// identical content except for generated_at / unreleased_inserted_at, which
+// always advance. The state object's body content (excluding those two
+// timestamps) is byte-equal between invocations — letting the
+// idempotent-reentry test compare via JSON.dumps on a clone with those keys
+// popped.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export async function writeState(projectRoot, slug, state) {
+  const dir = join(projectRoot, '.claude/state/changelog');
+  const path = join(dir, `${slug}.json`);
+  await mkdir(dir, { recursive: true });
+  await writeFile(path, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  return path;
+}

package/obj/template/.claude/skills/changelog/tests/consent-expired_test.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Fixture-based integration test for AC-010: when commit_consent token is
+# stale (older than consent.commit_ttl_seconds, default 300s), the changelog
+# skill exits non-zero with "consent expired" stderr, does NOT modify
+# CHANGELOG.md, and does NOT write the state file.
+#
+# Pre-implement RED state: actuator does not exist; test fails on missing file.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+ACTUATOR="$REPO_ROOT/.claude/skills/changelog/changelog.mjs"
+
+PASS=0; FAIL=0; FAILED=()
+
+fail() { echo "  FAIL: $*"; return 1; }
+
+# Seed a tempdir with a stale commit_consent (epoch = now - 310s).
+seed_stale_consent_project() {
+  local proj="$1" slug="$2"
+  mkdir -p "$proj/.claude/state"
+  cd "$proj"
+  git init -q
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  git commit --allow-empty -q -m "chore: initial"
+  git tag v0.1.0
+  echo "stale test" > thing.txt
+  git add thing.txt
+  git commit -q -m "feat: stale consent path"
+  # Stale token: epoch in the past, beyond 300s default TTL.
+  local stale_epoch; stale_epoch=$(( $(date +%s) - 310 ))
+  echo "$stale_epoch" > "$proj/.claude/state/commit_consent"
+  echo "stale" >> "$proj/.claude/state/commit_consent"
+  cat > "$proj/.claude/state/workflow.json" <<EOF
+{
+  "request": "consent-expired test",
+  "slug": "$slug",
+  "entry_phase": "intake",
+  "exceptions": [],
+  "completed": ["intake","scout","research","spec","approve-spec","tdd","simplify","security","integrate","document","archive","memory-flush"],
+  "source_backlog_keys": [],
+  "created_at": 1700000000,
+  "updated_at": 1700000000
+}
+EOF
+  cat > "$proj/CHANGELOG.md" <<'EOF'
+# Changelog
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial release
+EOF
+  cat > "$proj/.releaserc.json" <<'EOF'
+{
+  "branches": ["main"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "angular" }]
+  ]
+}
+EOF
+}
+
+run() {
+  local name="$1"
+  echo "RUN  $name"
+  if "$name"; then
+    PASS=$((PASS+1)); echo "PASS $name"
+  else
+    FAIL=$((FAIL+1)); FAILED+=("$name"); echo "FAIL $name"
+  fi
+}
+
+# --- AC-010 -------------------------------------------------------------------
+
+test_when_commit_consent_token_stale_then_changelog_exits_with_consent_expired() {
+  local proj; proj="$(mktemp -d)"; trap "rm -rf $proj" RETURN
+  seed_stale_consent_project "$proj" "stale-consent"
+  if [ ! -f "$ACTUATOR" ]; then
+    fail "AC-010 actuator not yet at $ACTUATOR — expected pre-implement RED state"
+    return 1
+  fi
+  local changelog_before; changelog_before="$(sha256sum "$proj/CHANGELOG.md" | awk '{print $1}')"
+  local out; local err
+  # Capture stdout, stderr, and exit code. NO `|| true` after the assignment —
+  # set -uo pipefail is active (no `-e`), so a non-zero exit from the assigned
+  # command propagates to $? without aborting the test. Adding `|| true` here
+  # would clobber $? to 0 and silently break the exit-code assertion below.
+  out="$(node "$ACTUATOR" --slug stale-consent --project-root "$proj" 2>/tmp/changelog-stderr.$$)"
+  local ec=$?
+  err="$(cat /tmp/changelog-stderr.$$)"
+  if [ "$ec" -eq 0 ]; then
+    fail "AC-010 actuator must exit non-zero on stale consent; exit was 0"
+    return 1
+  fi
+  # stderr must mention "consent expired" (case-insensitive match).
+  if ! printf '%s' "$err" | grep -qiE 'consent.*expired|expired.*consent'; then
+    fail "AC-010 stderr must match /consent.*expired/i; got: $err"
+    return 1
+  fi
+  # CHANGELOG.md unchanged.
+  local changelog_after; changelog_after="$(sha256sum "$proj/CHANGELOG.md" | awk '{print $1}')"
+  if [ "$changelog_before" != "$changelog_after" ]; then
+    fail "AC-010 CHANGELOG.md was modified despite stale consent"
+    return 1
+  fi
+  # State file NOT created.
+  if [ -f "$proj/.claude/state/changelog/stale-consent.json" ]; then
+    fail "AC-010 state file must NOT be written on stale consent"
+    return 1
+  fi
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_commit_consent_token_stale_then_changelog_exits_with_consent_expired
+
+echo "----"
+echo "Passed: $PASS  Failed: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed tests:"
+  for t in "${FAILED[@]}"; do echo "  - $t"; done
+fi
+exit $((FAIL > 0))

package/obj/template/.claude/skills/changelog/tests/golden-path_test.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Fixture-based integration tests for the changelog skill's golden-path
+# behavior. Covers AC-001, AC-002, AC-008 from
+# docs/specs/changelog-skill-and-responsive-svgs.md.
+#
+# Until .claude/skills/changelog/changelog.mjs exists, every test fails RED
+# (correct TDD state).
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+ACTUATOR="$REPO_ROOT/.claude/skills/changelog/changelog.mjs"
+
+PASS=0; FAIL=0; FAILED=()
+
+fail() { echo "  FAIL: $*"; return 1; }
+
+assert_file_contains() {
+  local path="$1" needle="$2" msg="$3"
+  if grep -qF "$needle" "$path" 2>/dev/null; then return 0; fi
+  fail "$msg :: file $path missing: $needle"
+}
+
+assert_file_matches() {
+  local path="$1" pattern="$2" msg="$3"
+  if grep -qE "$pattern" "$path" 2>/dev/null; then return 0; fi
+  fail "$msg :: file $path missing pattern: $pattern"
+}
+
+today() { date -u +%Y-%m-%d; }
+
+# Build a tempdir project with .git, one feat: commit, fresh commit_consent,
+# and workflow.json with phases up through memory-flush completed.
+seed_golden_path_project() {
+  local proj="$1" slug="$2"
+  mkdir -p "$proj/.claude/state"
+  cd "$proj"
+  git init -q >/dev/null 2>&1
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  # Seed an existing-tracked CHANGELOG.md BEFORE the feat commit so that when
+  # the actuator appends to it, git status reports M (modified) rather than ??
+  # (untracked). This matches the realistic workflow shape: any real project
+  # has a tracked CHANGELOG.md, the actuator modifies it, /commit stages the
+  # modification.
+  cat > "$proj/CHANGELOG.md" <<'EOF'
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial release
+EOF
+  git add CHANGELOG.md
+  git commit -q -m "chore: initial"
+  git tag v0.1.0
+  echo "added thing" > thing.txt
+  git add thing.txt
+  git commit -q -m "feat(skill): add the thing"
+  # Fresh commit_consent (epoch now).
+  date +%s > "$proj/.claude/state/commit_consent"
+  echo "test consent" >> "$proj/.claude/state/commit_consent"
+  # workflow.json with all phases up through memory-flush completed.
+  cat > "$proj/.claude/state/workflow.json" <<EOF
+{
+  "request": "golden-path test",
+  "slug": "$slug",
+  "entry_phase": "intake",
+  "exceptions": [],
+  "completed": ["intake","scout","research","spec","approve-spec","tdd","simplify","security","integrate","document","archive","memory-flush"],
+  "source_backlog_keys": [],
+  "created_at": 1700000000,
+  "updated_at": 1700000000
+}
+EOF
+  # Minimal .releaserc.json so semantic-release can analyze.
+  cat > "$proj/.releaserc.json" <<'EOF'
+{
+  "branches": ["main"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "angular" }]
+  ]
+}
+EOF
+}
+
+run() {
+  local name="$1"
+  echo "RUN  $name"
+  if "$name"; then
+    PASS=$((PASS+1)); echo "PASS $name"
+  else
+    FAIL=$((FAIL+1)); FAILED+=("$name"); echo "FAIL $name"
+  fi
+}
+
+# --- AC-001 -------------------------------------------------------------------
+
+test_when_grant_commit_token_fresh_then_changelog_writes_unreleased_section() {
+  local proj; proj="$(mktemp -d)"; trap "rm -rf $proj" RETURN
+  seed_golden_path_project "$proj" "golden-path"
+  if [ ! -f "$ACTUATOR" ]; then
+    fail "AC-001 actuator not yet at $ACTUATOR — expected pre-implement RED state"
+    return 1
+  fi
+  node "$ACTUATOR" --slug golden-path --project-root "$proj" \
+    > /tmp/changelog-stdout.$$ 2> /tmp/changelog-stderr.$$ \
+    || { fail "AC-001 actuator exited non-zero; stderr: $(cat /tmp/changelog-stderr.$$)"; return 1; }
+  assert_file_contains "$proj/CHANGELOG.md" "## [Unreleased]" "AC-001 Unreleased heading missing" || return 1
+  # At least one keepachangelog category subheading under Unreleased.
+  assert_file_matches "$proj/CHANGELOG.md" '^### (Added|Changed|Deprecated|Removed|Fixed|Security)' \
+    "AC-001 no keepachangelog category subheading in CHANGELOG.md" || return 1
+  # State file written.
+  [ -f "$proj/.claude/state/changelog/golden-path.json" ] \
+    || { fail "AC-001 .claude/state/changelog/golden-path.json not written"; return 1; }
+  # State file is valid JSON with expected shape.
+  python3 -c "
+import json, sys
+with open('$proj/.claude/state/changelog/golden-path.json') as f:
+    data = json.load(f)
+required = {'slug', 'source_commit_sha', 'entries', 'generated_at'}
+missing = required - set(data.keys())
+if missing:
+    sys.exit(f'state file missing keys: {missing}')
+if data['slug'] != 'golden-path':
+    sys.exit(f'slug mismatch: {data[\"slug\"]}')
+if not isinstance(data['entries'], list):
+    sys.exit('entries must be a list')
+" || { fail "AC-001 state file shape invalid"; return 1; }
+}
+
+# --- AC-002 -------------------------------------------------------------------
+
+test_when_changelog_completed_then_commit_includes_changelog_md_in_stage_list() {
+  local proj; proj="$(mktemp -d)"; trap "rm -rf $proj" RETURN
+  seed_golden_path_project "$proj" "stage-list"
+  if [ ! -f "$ACTUATOR" ]; then
+    fail "AC-002 actuator not yet at $ACTUATOR — expected pre-implement RED state"
+    return 1
+  fi
+  cd "$proj"
+  node "$ACTUATOR" --slug stage-list --project-root "$proj" >/dev/null 2>&1 \
+    || { fail "AC-002 actuator exited non-zero"; return 1; }
+  # CHANGELOG.md must now be modified in the working tree (the change the skill made).
+  local diff_status; diff_status="$(cd "$proj" && git status --porcelain CHANGELOG.md)"
+  if [ -z "$diff_status" ]; then
+    fail "AC-002 CHANGELOG.md must show modification in git status after changelog skill runs"
+    return 1
+  fi
+  # Confirm M flag (modified) on the file.
+  printf '%s' "$diff_status" | grep -qE '^\s*M\s+CHANGELOG\.md' \
+    || { fail "AC-002 CHANGELOG.md not marked Modified in git status; got: $diff_status"; return 1; }
+}
+
+# --- AC-008 -------------------------------------------------------------------
+
+test_when_workflow_completed_then_changelog_appended_before_commit() {
+  # Static: the commit SKILL.md prereq line names "changelog" as a required
+  # entry in workflow.json → completed. The harness ordering text lists
+  # changelog immediately before commit. This test reads the LIVE SKILL.md
+  # files (which the implement worker edits) and asserts on their content.
+  local commit_skill="$REPO_ROOT/.claude/skills/commit/SKILL.md"
+  local harness_skill="$REPO_ROOT/.claude/skills/harness/SKILL.md"
+  [ -f "$commit_skill" ] || { fail "AC-008 commit/SKILL.md missing"; return 1; }
+  [ -f "$harness_skill" ] || { fail "AC-008 harness/SKILL.md missing"; return 1; }
+  # commit SKILL.md prereq line must mention changelog.
+  assert_file_matches "$commit_skill" 'archive.*memory-flush.*changelog|changelog.*archive.*memory-flush|memory-flush.*changelog' \
+    "AC-008 commit/SKILL.md prereq must include changelog alongside archive and memory-flush" \
+    || return 1
+  # harness ordering text mentions changelog between grant-commit and commit.
+  assert_file_matches "$harness_skill" '/grant-commit.*changelog.*commit|grant-commit → changelog → commit' \
+    "AC-008 harness/SKILL.md ordering must mention changelog between /grant-commit and commit" \
+    || return 1
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_grant_commit_token_fresh_then_changelog_writes_unreleased_section
+run test_when_changelog_completed_then_commit_includes_changelog_md_in_stage_list
+run test_when_workflow_completed_then_changelog_appended_before_commit
+
+echo "----"
+echo "Passed: $PASS  Failed: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed tests:"
+  for t in "${FAILED[@]}"; do echo "  - $t"; done
+fi
+exit $((FAIL > 0))

package/obj/template/.claude/skills/changelog/tests/idempotent-reentry_test.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Regression test for the idempotency invariant: invoking the changelog
+# actuator twice on the same slug + same commit SHA SHALL NOT duplicate
+# entries under ## [Unreleased]; the state file mtime advances but content
+# (excluding generated_at) is byte-equal.
+#
+# Pre-implement RED: actuator does not exist; test fails on missing file.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+ACTUATOR="$REPO_ROOT/.claude/skills/changelog/changelog.mjs"
+
+PASS=0; FAIL=0; FAILED=()
+
+fail() { echo "  FAIL: $*"; return 1; }
+
+# Identical setup to golden-path_test.sh; replicated here so each test file
+# stays independently runnable.
+seed_idem_project() {
+  local proj="$1" slug="$2"
+  mkdir -p "$proj/.claude/state"
+  cd "$proj"
+  git init -q
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  git commit --allow-empty -q -m "chore: initial"
+  git tag v0.1.0
+  echo "thing" > thing.txt
+  git add thing.txt
+  git commit -q -m "feat: add the thing"
+  date +%s > "$proj/.claude/state/commit_consent"
+  echo "fresh" >> "$proj/.claude/state/commit_consent"
+  cat > "$proj/.claude/state/workflow.json" <<EOF
+{
+  "request": "idempotent re-entry test",
+  "slug": "$slug",
+  "entry_phase": "intake",
+  "exceptions": [],
+  "completed": ["intake","scout","research","spec","approve-spec","tdd","simplify","security","integrate","document","archive","memory-flush"],
+  "source_backlog_keys": [],
+  "created_at": 1700000000,
+  "updated_at": 1700000000
+}
+EOF
+  cat > "$proj/CHANGELOG.md" <<'EOF'
+# Changelog
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial release
+EOF
+  cat > "$proj/.releaserc.json" <<'EOF'
+{
+  "branches": ["main"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "angular" }]
+  ]
+}
+EOF
+}
+
+run() {
+  local name="$1"
+  echo "RUN  $name"
+  if "$name"; then
+    PASS=$((PASS+1)); echo "PASS $name"
+  else
+    FAIL=$((FAIL+1)); FAILED+=("$name"); echo "FAIL $name"
+  fi
+}
+
+# --- regression: idempotency -------------------------------------------------
+
+test_when_invoked_twice_then_no_duplicate_unreleased_entries() {
+  local proj; proj="$(mktemp -d)"; trap "rm -rf $proj" RETURN
+  seed_idem_project "$proj" "idem-test"
+  if [ ! -f "$ACTUATOR" ]; then
+    fail "actuator not yet at $ACTUATOR — expected pre-implement RED state"
+    return 1
+  fi
+  # First invocation.
+  node "$ACTUATOR" --slug idem-test --project-root "$proj" >/dev/null 2>&1 \
+    || { fail "first invocation exited non-zero"; return 1; }
+  local hash1; hash1="$(sha256sum "$proj/CHANGELOG.md" | awk '{print $1}')"
+  local state1; state1="$(cat "$proj/.claude/state/changelog/idem-test.json")"
+  # Sleep 1s so generated_at advances detectably.
+  sleep 1
+  # Second invocation (same slug, same git HEAD).
+  node "$ACTUATOR" --slug idem-test --project-root "$proj" >/dev/null 2>&1 \
+    || { fail "second invocation exited non-zero"; return 1; }
+  local hash2; hash2="$(sha256sum "$proj/CHANGELOG.md" | awk '{print $1}')"
+  if [ "$hash1" != "$hash2" ]; then
+    fail "CHANGELOG.md changed on re-entry; hash1=$hash1 hash2=$hash2"
+    return 1
+  fi
+  # State file: contents excluding generated_at and unreleased_inserted_at MUST be byte-equal.
+  python3 - "$proj/.claude/state/changelog/idem-test.json" "$state1" <<'PY' || { fail "state file content drifted on re-entry"; return 1; }
+import json, sys
+new = json.load(open(sys.argv[1]))
+old = json.loads(sys.argv[2])
+for k in ('generated_at', 'unreleased_inserted_at'):
+    new.pop(k, None); old.pop(k, None)
+if json.dumps(new, sort_keys=True) != json.dumps(old, sort_keys=True):
+    sys.exit(f'state diverged: new={new!r} old={old!r}')
+PY
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_invoked_twice_then_no_duplicate_unreleased_entries
+
+echo "----"
+echo "Passed: $PASS  Failed: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed tests:"
+  for t in "${FAILED[@]}"; do echo "  - $t"; done
+fi
+exit $((FAIL > 0))

package/obj/template/.claude/skills/changelog/tests/keepachangelog-unreleased-preserved_test.mjs

@@ -0,0 +1,149 @@
+// Integration test for AC-013: @semantic-release/changelog 6.0.3 SHALL
+// preserve the "## [Unreleased]" heading at the top of CHANGELOG.md when it
+// prepends a new versioned release block during the prepare step.
+//
+// Resolves the verification gap flagged in the spec: context7 did not
+// document this seam, so this test answers the question empirically.
+//
+// Pre-implement RED note: this test imports @semantic-release/changelog
+// (installed as a devDep at package.json:48) and the production actuator at
+// .claude/skills/changelog/unreleased-writer.mjs. Until the actuator exists,
+// the test errors on the import — the correct TDD failure mode.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const FIXTURE_CHANGELOG = `# Changelog
+
+## [Unreleased]
+
+### Added
+- A draft entry the local changelog skill inserted
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial release
+`;
+
+async function setupFixture() {
+  const dir = await mkdtemp(join(tmpdir(), 'changelog-fixture-'));
+  await writeFile(join(dir, 'CHANGELOG.md'), FIXTURE_CHANGELOG, 'utf8');
+  return dir;
+}
+
+async function cleanup(dir) {
+  await rm(dir, { recursive: true, force: true });
+}
+
+// Load the plugin. The plugin exports `verifyConditions` and `prepare` as
+// named exports (ESM) or as properties on a CommonJS default (legacy). Try
+// the modern shape first and fall back.
+async function loadPlugin() {
+  try {
+    const mod = await import('@semantic-release/changelog');
+    if (typeof mod.prepare === 'function') return mod;
+    if (mod.default && typeof mod.default.prepare === 'function') return mod.default;
+    throw new Error('@semantic-release/changelog does not expose a prepare function in the expected shape');
+  } catch (err) {
+    throw new Error(`failed to load @semantic-release/changelog: ${err.message}`);
+  }
+}
+
+// A no-op logger that satisfies semantic-release's expected shape.
+const noopLogger = {
+  log: () => {},
+  warn: () => {},
+  error: () => {},
+  success: () => {},
+};
+
+test('AC-013: @semantic-release/changelog prepare leaves ## [Unreleased] in file but displaces it (motivates the fallback hook)', async () => {
+  // Empirical documentation test: confirms two facts about
+  // @semantic-release/changelog 6.0.3 prepare-step behavior:
+  //   (1) it does NOT delete the ## [Unreleased] heading — the heading
+  //       survives in the file body, so a fallback can find it.
+  //   (2) it does NOT preserve top-of-file position — the plugin prepends
+  //       `nextRelease.notes` ABOVE the existing # Changelog + ## [Unreleased]
+  //       headings, displacing them downward.
+  // Together (1) + (2) motivate the second test in this file, which exercises
+  // the unreleased-writer.mjs `reinsertUnreleasedHeading` fallback that lifts
+  // the heading back to canonical top position.
+  const dir = await setupFixture();
+  try {
+    const plugin = await loadPlugin();
+    const context = {
+      cwd: dir,
+      env: { ...process.env },
+      branch: { name: 'main' },
+      lastRelease: { version: '0.1.0', gitTag: 'v0.1.0' },
+      nextRelease: {
+        type: 'minor',
+        version: '0.2.0',
+        gitTag: 'v0.2.0',
+        // Full release-notes payload as semantic-release's
+        // release-notes-generator would produce upstream of the changelog
+        // plugin: version heading + body.
+        notes: '## [0.2.0] - 2026-05-18\n\n### Added\n\n- A new feature shipped by the release pipeline',
+      },
+      logger: noopLogger,
+    };
+    await plugin.prepare({ changelogFile: 'CHANGELOG.md' }, context);
+    const after = await readFile(join(dir, 'CHANGELOG.md'), 'utf8');
+    // Fact (1): ## [Unreleased] heading survives somewhere in the file.
+    assert.ok(
+      after.includes('## [Unreleased]'),
+      `## [Unreleased] heading must survive in file (plugin must not delete it); got:\n${after}`,
+    );
+    // Fact (1, cont.): the new versioned block is in the file.
+    assert.ok(
+      after.includes('0.2.0'),
+      `CHANGELOG.md must contain new release version 0.2.0 after prepare; got:\n${after}`,
+    );
+    // Fact (2): the plugin prepends ABOVE the existing headings, so the
+    // 0.2.0 block ends up BEFORE the ## [Unreleased] heading. This is the
+    // exact behavior that motivates the fallback hook.
+    const unreleasedIdx = after.indexOf('## [Unreleased]');
+    const newReleaseIdx = after.indexOf('## [0.2.0]');
+    assert.ok(
+      newReleaseIdx >= 0 && unreleasedIdx > newReleaseIdx,
+      `plugin behavior contract: 0.2.0 block prepended ABOVE ## [Unreleased]; ` +
+        `expected 0.2.0@N < unreleased@M; got 0.2.0@${newReleaseIdx}, unreleased@${unreleasedIdx}; full:\n${after}`,
+    );
+  } finally {
+    await cleanup(dir);
+  }
+});
+
+test('AC-013 fallback: when prepare destroys Unreleased, our re-insertion path exists', async () => {
+  // If the plugin DOES strip the heading, our post-prepare hook re-inserts it.
+  // The hook is at .claude/skills/changelog/unreleased-writer.mjs and exports
+  // a reinsertUnreleasedHeading(changelogPath) function. Until implement
+  // lands, this import errors — the correct RED state.
+  const { reinsertUnreleasedHeading } = await import(
+    new URL('../unreleased-writer.mjs', import.meta.url).href
+  );
+  const dir = await setupFixture();
+  try {
+    // Synthesize the "plugin destroyed Unreleased" state by removing it.
+    const broken = FIXTURE_CHANGELOG.replace(/## \[Unreleased\][\s\S]*?(?=## \[)/, '');
+    await writeFile(join(dir, 'CHANGELOG.md'), broken, 'utf8');
+    await reinsertUnreleasedHeading(join(dir, 'CHANGELOG.md'));
+    const after = await readFile(join(dir, 'CHANGELOG.md'), 'utf8');
+    assert.ok(
+      after.includes('## [Unreleased]'),
+      `reinsertUnreleasedHeading must restore the ## [Unreleased] heading; got:\n${after}`,
+    );
+    // The Unreleased heading must be the FIRST ## heading in the file.
+    const firstH2 = after.match(/^## .+$/m);
+    assert.ok(
+      firstH2 && firstH2[0].includes('[Unreleased]'),
+      `first ## heading must be [Unreleased]; got: ${firstH2 ? firstH2[0] : '(none)'}`,
+    );
+  } finally {
+    await cleanup(dir);
+  }
+});