@friedbotstudio/create-baseline 0.2.1 → 0.4.0

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

@@ -19,6 +19,14 @@ results = []  # (name, status, detail)
 def add(name, status, detail=""):
     results.append((name, status, detail))
 
+def is_valid_preamble(text):
+    if not text.startswith("---"):
+        return False, "missing frontmatter"
+    remainder = text[3:]
+    if "\n---\n" in remainder or remainder.endswith("\n---"):
+        return True, ""
+    return False, "malformed frontmatter: missing closing separator"
+
 # ---------- expected canonical sets (mirror seed.md §4) ----------
 EXPECTED_HOOKS = {
     # Write/Bash boundary guards (17)
@@ -65,12 +73,12 @@ def read_skill_owner(slug):
     m = re.search(r'^owner:\s*(\S+)\s*$', fm.group(1), re.MULTILINE)
     return m.group(1) if m else None
 
-EXPECTED_COMMANDS = {"approve-spec", "approve-swarm", "grant-commit", "init-project"}
+EXPECTED_COMMANDS = {"approve-spec", "approve-swarm", "grant-commit", "grant-push", "init-project"}
 
 EXPECTED_MEMORY_FILES = {
-    # Canonical files (six)
+    # Canonical files (seven)
     "landmarks", "libraries", "decisions", "landmines", "conventions",
-    "pending-questions",
+    "pending-questions", "backlog",
     # Auto-extraction inbox (one); body gitignored, file committed
     "_pending",
     # Cross-session continuity snapshot (one); written by memory_stop &
@@ -128,7 +136,7 @@ agents_dir  = root / ".claude/agents"
 skills_dir  = root / ".claude/skills"
 cmds_dir    = root / ".claude/commands"
 
-disk_hooks    = {p.stem for p in hooks_dir.glob("*.sh")} if hooks_dir.exists() else set()
+disk_hooks    = ({p.stem for p in hooks_dir.glob("*.sh")} | {p.stem for p in hooks_dir.glob("*.mjs")}) if hooks_dir.exists() else set()
 disk_agents   = {p.stem for p in agents_dir.glob("*.md")} if agents_dir.exists() else set()
 disk_skills   = {p.name for p in skills_dir.iterdir() if p.is_dir()} if skills_dir.exists() else set()
 disk_commands = {p.stem for p in cmds_dir.glob("*.md")} if cmds_dir.exists() else set()
@@ -171,7 +179,7 @@ skills_claimed  = find_count(
     r"\b(\d+|twenty-(?:four|five|six|seven|eight|nine)|"
     r"thirty|thirty-(?:one|two|three|four|five|six|seven|eight|nine)|forty)\s+skills?\b")
 gates_claimed   = find_count(r"\b(\d+|three)\s+consent\s+gates?\b")
-cmds_claimed    = 4 if re.search(r"three\s+consent\s+gates?\s*\+\s*one\s+bootstrap", seed, re.IGNORECASE) else None
+cmds_claimed    = 5 if re.search(r"four\s+consent\s+gates?\s*\+\s*one\s+bootstrap", seed, re.IGNORECASE) else None
 
 def check_count(label, claimed, actual):
     if claimed is None:
@@ -295,28 +303,29 @@ else:
         add("memory files present", "FAIL", "; ".join(bits))
     else:
         add("memory files present", "PASS", f"{len(disk_memory)} files")
-    # Each canonical file should have frontmatter (--- ... ---) and at least one entry.
+    # Record count is not an audit signal — a freshly-initialized project
+    # legitimately has zero entries in every canonical file (overlaid from
+    # pristine src/memory/<name>.template.md). Entry count is reported
+    # informationally.
     for name in sorted(EXPECTED_MEMORY_FILES):
         p = mem_dir / f"{name}.md"
         if not p.is_file():
             continue
         text = p.read_text(encoding="utf-8", errors="replace")
-        if not text.startswith("---"):
-            add(f"memory shape: {name}.md", "FAIL", "missing frontmatter")
+        ok, reason = is_valid_preamble(text)
+        if not ok:
+            add(f"memory shape: {name}.md", "FAIL", reason)
             continue
-        # _pending body may be empty; canonical must have at least one entry.
         if name == "_pending":
             add(f"memory shape: {name}.md", "PASS", "")
             continue
-        body = text.split("---", 2)[-1] if text.startswith("---") else text
+        body = text.split("---", 2)[-1]
         # Strip fenced code blocks so example "## <stable key>" lines inside
         # ```markdown ... ``` don't count as entries.
         body_no_fence = re.sub(r"(?ms)^```.*?^```\s*$", "", body)
         entry_count = len(re.findall(r'(?m)^##\s+\S', body_no_fence))
-        if entry_count == 0:
-            add(f"memory shape: {name}.md", "FAIL", "no entries (## headings) in body")
-        else:
-            add(f"memory shape: {name}.md", "PASS", f"{entry_count} entries")
+        detail = f"{entry_count} entries" if entry_count > 0 else "empty (preamble-only)"
+        add(f"memory shape: {name}.md", "PASS", detail)
     # README inside memory/ is a structural expectation
     add("memory README", "PASS" if (mem_dir / "README.md").is_file() else "FAIL",
         "" if (mem_dir / "README.md").is_file() else "missing .claude/memory/README.md")
@@ -419,7 +428,7 @@ else:
         try:
             s_text = src_settings.read_text(encoding="utf-8")
             json.loads(s_text)
-            missing_wired = sorted(h for h in EXPECTED_HOOKS if f"{h}.sh" not in s_text)
+            missing_wired = sorted(h for h in EXPECTED_HOOKS if (f"{h}.sh" not in s_text and f"{h}.mjs" not in s_text))
             if missing_wired:
                 head = missing_wired[:3]
                 tail = f" + {len(missing_wired) - 3} more" if len(missing_wired) > 3 else ""
@@ -502,7 +511,7 @@ else:
     except Exception as e:
         add("settings.json parses", "FAIL", str(e))
     for h in sorted(EXPECTED_HOOKS):
-        if f"{h}.sh" in settings_text:
+        if f"{h}.sh" in settings_text or f"{h}.mjs" in settings_text:
             add(f"hook wired: {h}", "PASS", "")
         else:
             add(f"hook wired: {h}", "FAIL", "not in settings.json")
@@ -535,6 +544,9 @@ else:
         ("swarm.enforced_path_prefixes",        ["swarm", "enforced_path_prefixes"]),
         ("consent.commit_ttl_seconds",          ["consent", "commit_ttl_seconds"]),
         ("consent.gate_marker_ttl_seconds",     ["consent", "gate_marker_ttl_seconds"]),
+        ("consent.push_ttl_seconds",            ["consent", "push_ttl_seconds"]),
+        ("git.protected_branches",              ["git", "protected_branches"]),
+        ("git.branch_pattern",                  ["git", "branch_pattern"]),
         ("additions.agents",                    ["additions", "agents"]),
         ("additions.skills",                    ["additions", "skills"]),
         ("additions.hooks",                     ["additions", "hooks"]),

package/obj/template/.claude/skills/audit-baseline/tests/fixtures/_pending_opener_only.md

@@ -0,0 +1,3 @@
+---
+owners: [memory_stop.sh writes; /memory-flush clears]
+category: auto-extracted candidates awaiting curation

package/obj/template/.claude/skills/audit-baseline/tests/fixtures/preamble_full_empty_body.md

@@ -0,0 +1,4 @@
+---
+owners: [test]
+key: full-preamble-no-entries
+---

package/obj/template/.claude/skills/audit-baseline/tests/fixtures/preamble_full_with_entries.md

@@ -0,0 +1,9 @@
+---
+owners: [test]
+key: full-preamble-one-entry
+---
+
+## sample-entry
+
+- role: synthetic test fixture
+- verified-at: HEAD

package/obj/template/.claude/skills/audit-baseline/tests/fixtures/preamble_no_opener.md

@@ -0,0 +1,3 @@
+# Some content without frontmatter
+
+This file has no `---` opener at all.

package/obj/template/.claude/skills/audit-baseline/tests/fixtures/preamble_opener_only.md

@@ -0,0 +1,3 @@
+---
+owners: [test]
+key: opener-only-no-closer

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Fixture-based integration tests for the audit-baseline preamble validator.
+# Covers the strict-preamble tightening in .claude/skills/audit-baseline/audit.sh.
+#
+# Each test builds a synthetic .claude/memory/ tree under a tempdir (with all
+# 9 expected canonical filenames), substitutes one file with a fixture, then
+# runs audit.sh with CLAUDE_PROJECT_DIR pointed at the tempdir and greps the
+# captured output for the "memory shape: <name>.md" line.
+#
+# The audit will exit non-zero in the stub tree because hook/skill/agent
+# counts won't match — that's expected. We only assert on the specific
+# memory-shape line each test cares about.
+#
+# Not wired into project.json -> test.cmd; run manually during /tdd and
+# /integrate alongside .claude/hooks/tests/memory_session_start_test.sh.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+AUDIT="$REPO_ROOT/.claude/skills/audit-baseline/audit.sh"
+FIXTURES="$HERE/fixtures"
+
+PASS=0; FAIL=0; FAILED=()
+
+# --- assertion helpers --------------------------------------------------------
+
+fail() { echo "  FAIL: $*"; return 1; }
+
+# Seed a stub .claude/memory/ tree under $1. The file basename $2 is replaced
+# with the fixture content from $3; the other 8 expected files get a valid
+# synthetic preamble so they don't pollute the audit output we grep against.
+seed_stub_tree() {
+  local root="$1" under_test="$2" fixture_path="$3"
+  mkdir -p "$root/.claude/memory"
+  # README is checked separately by audit.sh; copy the real one so that check
+  # passes and doesn't tangle our grep.
+  cp "$REPO_ROOT/.claude/memory/README.md" "$root/.claude/memory/README.md"
+  local mem_name
+  for mem_name in landmarks libraries decisions landmines conventions \
+                  pending-questions backlog _pending _resume; do
+    if [ "$mem_name" = "$under_test" ]; then
+      cp "$fixture_path" "$root/.claude/memory/${mem_name}.md"
+    else
+      cat > "$root/.claude/memory/${mem_name}.md" <<'EOF'
+---
+owners: [test]
+key: test
+---
+
+# Synthetic valid preamble
+EOF
+    fi
+  done
+}
+
+# Run audit.sh against the stub tree at $1 and print the line matching
+# "memory shape: $2.md" to stdout. Returns 1 if no such line found.
+audit_memory_shape_line() {
+  local root="$1" name="$2"
+  CLAUDE_PROJECT_DIR="$root" bash "$AUDIT" 2>&1 \
+    | grep -E "^memory shape: ${name}\.md[[:space:]]" \
+    | head -1
+}
+
+# Assert that the memory-shape line for $2 in the audit run against $1 has
+# status $3 and a detail matching the extended-regex $4.
+assert_memory_shape() {
+  local root="$1" name="$2" want_status="$3" want_detail_re="$4"
+  local line; line="$(audit_memory_shape_line "$root" "$name")"
+  if [ -z "$line" ]; then
+    fail "no 'memory shape: ${name}.md' line in audit output"
+    return 1
+  fi
+  if ! printf '%s' "$line" | grep -qE "[[:space:]]${want_status}[[:space:]]"; then
+    fail "expected status ${want_status} for ${name}.md; got: ${line}"
+    return 1
+  fi
+  if ! printf '%s' "$line" | grep -qE "${want_detail_re}"; then
+    fail "expected detail matching '${want_detail_re}' for ${name}.md; got: ${line}"
+    return 1
+  fi
+  return 0
+}
+
+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
+}
+
+# --- tests --------------------------------------------------------------------
+
+test_when_memory_file_has_opener_only_then_audit_reports_fail() {
+  local tmp; tmp="$(mktemp -d)"; trap "rm -rf $tmp" RETURN
+  seed_stub_tree "$tmp" "landmarks" "$FIXTURES/preamble_opener_only.md"
+  assert_memory_shape "$tmp" "landmarks" "FAIL" \
+    "malformed frontmatter: missing closing separator"
+}
+
+test_when_memory_file_has_no_opener_then_audit_reports_fail() {
+  local tmp; tmp="$(mktemp -d)"; trap "rm -rf $tmp" RETURN
+  seed_stub_tree "$tmp" "libraries" "$FIXTURES/preamble_no_opener.md"
+  assert_memory_shape "$tmp" "libraries" "FAIL" \
+    "missing frontmatter"
+}
+
+test_when_memory_file_has_valid_full_preamble_no_body_then_audit_reports_pass_preamble_only() {
+  local tmp; tmp="$(mktemp -d)"; trap "rm -rf $tmp" RETURN
+  seed_stub_tree "$tmp" "decisions" "$FIXTURES/preamble_full_empty_body.md"
+  assert_memory_shape "$tmp" "decisions" "PASS" \
+    "empty \\(preamble-only\\)"
+}
+
+test_when_memory_file_has_valid_preamble_with_entries_then_audit_reports_pass_with_count() {
+  local tmp; tmp="$(mktemp -d)"; trap "rm -rf $tmp" RETURN
+  seed_stub_tree "$tmp" "landmines" "$FIXTURES/preamble_full_with_entries.md"
+  assert_memory_shape "$tmp" "landmines" "PASS" \
+    "1 entries"
+}
+
+test_when_pending_file_has_opener_only_then_audit_reports_fail() {
+  local tmp; tmp="$(mktemp -d)"; trap "rm -rf $tmp" RETURN
+  seed_stub_tree "$tmp" "_pending" "$FIXTURES/_pending_opener_only.md"
+  assert_memory_shape "$tmp" "_pending" "FAIL" \
+    "malformed frontmatter: missing closing separator"
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_memory_file_has_opener_only_then_audit_reports_fail
+run test_when_memory_file_has_no_opener_then_audit_reports_fail
+run test_when_memory_file_has_valid_full_preamble_no_body_then_audit_reports_pass_preamble_only
+run test_when_memory_file_has_valid_preamble_with_entries_then_audit_reports_pass_with_count
+run test_when_pending_file_has_opener_only_then_audit_reports_fail
+
+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/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;
+}