@friedbotstudio/create-baseline 0.3.0 → 0.5.0

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);
+});

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))