@friedbotstudio/create-baseline 0.3.0 → 0.5.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);
+  }
+});

package/obj/template/.claude/skills/changelog/tests/non-git-shortcircuit_test.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Fixture-based test for AC-003: when a project is not a git repository,
+# /triage SHALL auto-except changelog alongside commit and the swarm-* phases,
+# AND no Run /changelog task SHALL be seeded.
+#
+# Static-analysis test: reads the LIVE .claude/skills/triage/SKILL.md content
+# (which the implement worker edits) and asserts on its content. Until the
+# implement worker updates triage SKILL.md, this test fails RED.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+TRIAGE_SKILL="$REPO_ROOT/.claude/skills/triage/SKILL.md"
+
+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"
+}
+
+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-003 — static-analysis on triage SKILL.md -----------------------------
+
+test_when_triage_skill_md_describes_nongit_then_changelog_in_exceptions_list() {
+  [ -f "$TRIAGE_SKILL" ] || { fail "AC-003 triage/SKILL.md missing"; return 1; }
+  # The non-git auto-except list MUST mention 'changelog' alongside the
+  # existing 'swarm-plan', 'approve-swarm', 'swarm-dispatch', 'grant-commit',
+  # 'commit' entries. The exact phrasing may vary; assert presence of the
+  # changelog token within reasonable proximity of the other tokens.
+  if ! grep -qE '"swarm-plan".*"swarm-dispatch".*"commit"' "$TRIAGE_SKILL"; then
+    fail "AC-003 baseline non-git auto-except list not found in triage SKILL.md"
+    return 1
+  fi
+  assert_file_contains "$TRIAGE_SKILL" '"changelog"' \
+    "AC-003 triage SKILL.md non-git auto-except list must include \"changelog\"" \
+    || return 1
+}
+
+test_when_triage_task_templates_include_changelog_row_between_grant_commit_and_commit() {
+  [ -f "$TRIAGE_SKILL" ] || { fail "AC-003 triage/SKILL.md missing"; return 1; }
+  # Each non-chore template (tdd-entry, spec-entry, intake-entry) AND the
+  # chore template SHOULD include a Run /changelog task row between
+  # "Wait for /grant-commit" and "Run /commit". The exact prose varies but the
+  # ordering must hold.
+  # Strategy: extract the prose between "Wait for /grant-commit" and "Run /commit"
+  # blocks and require "changelog" to appear within that slice.
+  if ! python3 - "$TRIAGE_SKILL" <<'PY'
+import re, sys
+path = sys.argv[1]
+text = open(path).read()
+# Find every occurrence of "Wait for /grant-commit" followed by content up to "Run /commit"
+matches = list(re.finditer(
+    r'Wait for /grant-commit[\s\S]*?Run /commit', text))
+if not matches:
+    sys.exit('no "Wait for /grant-commit" → "Run /commit" sequence found in triage SKILL.md')
+# Every such slice must mention "changelog".
+missing = [i for i, m in enumerate(matches) if 'changelog' not in m.group(0).lower()]
+if missing:
+    sys.exit(f'{len(missing)} task-seeding slice(s) missing changelog: indices {missing}')
+PY
+  then
+    fail "AC-003 triage SKILL.md task-seeding templates must include changelog between grant-commit and commit"
+    return 1
+  fi
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_triage_skill_md_describes_nongit_then_changelog_in_exceptions_list
+run test_when_triage_task_templates_include_changelog_row_between_grant_commit_and_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/preview-only_test.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Fixture-based integration test for AC-012: the changelog actuator's
+# --preview-only mode prints projected next semver + draft fragment to stdout,
+# requires no commit_consent gesture, and writes no files.
+#
+# 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; }
+
+# Build a tempdir project WITHOUT commit_consent (preview must work without it).
+seed_preview_project() {
+  local proj="$1"
+  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 "preview" > thing.txt
+  git add thing.txt
+  git commit -q -m "feat: preview path"
+  # NO commit_consent file.
+  # NO workflow.json — preview must not require one.
+  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-012 -------------------------------------------------------------------
+
+test_when_preview_only_flag_then_stdout_projection_no_writes() {
+  local proj; proj="$(mktemp -d)"; trap "rm -rf $proj" RETURN
+  seed_preview_project "$proj"
+  if [ ! -f "$ACTUATOR" ]; then
+    fail "AC-012 actuator not yet at $ACTUATOR — expected pre-implement RED state"
+    return 1
+  fi
+  local out
+  out="$(node "$ACTUATOR" --preview-only --slug demo --project-root "$proj" 2>/tmp/preview-stderr.$$)"
+  local ec=$?
+  if [ "$ec" -ne 0 ]; then
+    fail "AC-012 preview-only must exit 0; got $ec; stderr: $(cat /tmp/preview-stderr.$$)"
+    return 1
+  fi
+  # stdout matches Projected: <semver>.
+  if ! printf '%s' "$out" | grep -qE 'Projected:\s*[0-9]+\.[0-9]+\.[0-9]+'; then
+    fail "AC-012 stdout must contain Projected: <semver>; got: $out"
+    return 1
+  fi
+  # No state file written.
+  if [ -f "$proj/.claude/state/changelog/demo.json" ]; then
+    fail "AC-012 preview-only must NOT write state file"
+    return 1
+  fi
+  # CHANGELOG.md is either absent (we never created one) or unchanged.
+  if [ -f "$proj/CHANGELOG.md" ]; then
+    fail "AC-012 preview-only must NOT create CHANGELOG.md when absent"
+    return 1
+  fi
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_preview_only_flag_then_stdout_projection_no_writes
+
+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/run.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Aggregate test runner for .claude/skills/changelog/.
+# Invokes each sibling *_test.sh AND any *_test.mjs (node --test) and exits
+# non-zero if any fail.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+FAIL=0
+
+for t in "$HERE"/*_test.sh; do
+  [ -f "$t" ] || continue
+  echo "=== $(basename "$t") ==="
+  bash "$t" || FAIL=$((FAIL+1))
+done
+
+for t in "$HERE"/*_test.mjs; do
+  [ -f "$t" ] || continue
+  echo "=== $(basename "$t") ==="
+  node --test "$t" || FAIL=$((FAIL+1))
+done
+
+if [ "$FAIL" -gt 0 ]; then
+  echo "changelog/tests: $FAIL suite(s) failed"
+  exit 1
+fi
+echo "changelog/tests: all suites passed"
+exit 0

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

@@ -0,0 +1,155 @@
+// CHANGELOG.md curation under ## [Unreleased].
+//
+// Two exports:
+//   appendUnderUnreleased(changelogPath, entries) — per-commit RMW.
+//   reinsertUnreleasedHeading(changelogPath)       — AC-013 fallback for the
+//     case where @semantic-release/changelog has prepended versioned notes
+//     above the `# Changelog` and `## [Unreleased]` headings. Restores the
+//     canonical order: `# Changelog\n\n## [Unreleased]\n\n<rest>`.
+//
+// File shape we maintain (keepachangelog 1.0.0):
+//
+//   # Changelog
+//
+//   ## [Unreleased]
+//
+//   ### Added
+//   - <entry>
+//
+//   ### Fixed
+//   - <entry>
+//
+//   ## [0.1.0] - 2026-01-01
+//
+//   ...
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+const UNRELEASED_HEADING = '## [Unreleased]';
+const CHANGELOG_HEADING = '# Changelog';
+
+const CATEGORY_ORDER = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'];
+
+function groupBySection(entries) {
+  const map = new Map();
+  for (const entry of entries) {
+    if (!map.has(entry.section)) map.set(entry.section, []);
+    map.get(entry.section).push(entry);
+  }
+  return map;
+}
+
+function renderUnreleasedBody(entries) {
+  if (entries.length === 0) return '';
+  const grouped = groupBySection(entries);
+  const lines = [];
+  for (const section of CATEGORY_ORDER) {
+    const items = grouped.get(section);
+    if (!items || items.length === 0) continue;
+    lines.push('');
+    lines.push(`### ${section}`);
+    lines.push('');
+    for (const item of items) {
+      const prefix = item.breaking ? '**BREAKING:** ' : '';
+      lines.push(`- ${prefix}${item.body}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// Split text into { preamble, unreleasedBody, rest } where preamble is
+// everything up to and including the `## [Unreleased]` line, unreleasedBody
+// is the content between that and the next `##` heading, and rest is from
+// the next `##` heading onward.
+function splitAroundUnreleased(text) {
+  const unreleasedIdx = text.indexOf(UNRELEASED_HEADING);
+  if (unreleasedIdx < 0) return null;
+  const afterHeading = text.indexOf('\n', unreleasedIdx);
+  const headingEnd = afterHeading < 0 ? text.length : afterHeading + 1;
+  // Find the next `## ` heading after the Unreleased heading.
+  const restMatch = text.slice(headingEnd).match(/\n## [^\n]+\n/);
+  const restOffset = restMatch ? headingEnd + restMatch.index + 1 : text.length;
+  return {
+    preamble: text.slice(0, headingEnd),
+    unreleasedBody: text.slice(headingEnd, restOffset),
+    rest: text.slice(restOffset),
+  };
+}
+
+function defaultChangelogText() {
+  return `# Changelog\n\n## [Unreleased]\n\n`;
+}
+
+export async function appendUnderUnreleased(changelogPath, entries) {
+  let text;
+  if (existsSync(changelogPath)) {
+    text = await readFile(changelogPath, 'utf8');
+  } else {
+    text = defaultChangelogText();
+  }
+  if (!text.includes(CHANGELOG_HEADING)) {
+    text = `${CHANGELOG_HEADING}\n\n${text}`;
+  }
+  if (!text.includes(UNRELEASED_HEADING)) {
+    text = text.replace(
+      new RegExp(`(${CHANGELOG_HEADING}\\n)`, ''),
+      `$1\n${UNRELEASED_HEADING}\n\n`,
+    );
+  }
+  const parts = splitAroundUnreleased(text);
+  if (!parts) {
+    // Defensive: should be unreachable after the insertions above.
+    throw new Error(`could not locate ${UNRELEASED_HEADING} in ${changelogPath}`);
+  }
+  const body = renderUnreleasedBody(entries);
+  const merged = `${parts.preamble}${body}\n${parts.rest.startsWith('\n') ? parts.rest : '\n' + parts.rest}`;
+  await writeFile(changelogPath, merged, 'utf8');
+}
+
+export async function reinsertUnreleasedHeading(changelogPath) {
+  const text = await readFile(changelogPath, 'utf8');
+  // If the first `##` heading in the file is already `## [Unreleased]`, the
+  // file is structurally correct; do nothing.
+  const firstH2 = text.match(/^## .+$/m);
+  if (firstH2 && firstH2[0].includes('[Unreleased]')) {
+    return;
+  }
+  // Otherwise: find the existing Unreleased heading (which may sit deeper in
+  // the file because @semantic-release/changelog prepended notes above it)
+  // and lift it to the canonical top position.
+  const lines = text.split('\n');
+  // Identify the Unreleased section's start and the next `##` start.
+  let unreleasedStart = -1;
+  let unreleasedEnd = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (unreleasedStart < 0 && lines[i] === UNRELEASED_HEADING) {
+      unreleasedStart = i;
+      continue;
+    }
+    if (unreleasedStart >= 0 && /^## /.test(lines[i])) {
+      unreleasedEnd = i;
+      break;
+    }
+  }
+  if (unreleasedStart < 0) {
+    // No Unreleased heading anywhere; insert a fresh one at the top.
+    const top = `${CHANGELOG_HEADING}\n\n${UNRELEASED_HEADING}\n\n`;
+    await writeFile(changelogPath, top + text, 'utf8');
+    return;
+  }
+  if (unreleasedEnd < 0) unreleasedEnd = lines.length;
+  const unreleasedBlock = lines.slice(unreleasedStart, unreleasedEnd);
+  const without = lines.slice(0, unreleasedStart).concat(lines.slice(unreleasedEnd));
+  // Strip any leading blank lines from the without-block so the result starts
+  // with the `# Changelog` heading (we'll insert one if absent).
+  const withoutText = without.join('\n');
+  const head = withoutText.startsWith(CHANGELOG_HEADING)
+    ? withoutText
+    : `${CHANGELOG_HEADING}\n\n${withoutText.replace(/^\n+/, '')}`;
+  const restored = head.replace(
+    new RegExp(`^(${CHANGELOG_HEADING})\\n\\n?`),
+    `$1\n\n${unreleasedBlock.join('\n')}\n\n`,
+  );
+  await writeFile(changelogPath, restored, 'utf8');
+}