@ionivetech/mugiwara 0.6.0 → 0.6.2

package/scripts/mission-report.sh

@@ -2,6 +2,9 @@
 # scripts/mission-report.sh — generate aggregate mission report from state.json
 # + per-mission wave artifacts. Usage: mission-report.sh <mission>
 # Output: .mugiwara/reports/YYYY-MM-DD-<mission>.md — one-file summary of all waves.
+# Enriched: mission header, token budget (WARN/STOP flag), tasks (state or plan
+# doc fallback), gate/quality excerpt from 06-closure.md, evidence file list.
+# Every section degrades to n/a when state.json or results/ artifacts are absent.
 set -u
 
 MISSION="${1:-}"
@@ -17,8 +20,6 @@ RESULTS_DIR="$MUGIWARA_DIR/results/$MISSION"
 REVIEW_DIR="$MUGIWARA_DIR/review"
 ISSUES_DIR="$MUGIWARA_DIR/issues"
 
-[ -f "$STATE_FILE" ] || { echo "mission-report: $STATE_FILE not found" >&2; exit 1; }
-
 export STATE_FILE REPORT_DIR RESULTS_DIR REVIEW_DIR ISSUES_DIR MISSION
 node << 'NODE'
 const fs = require('fs');
@@ -29,33 +30,49 @@ const reportDir = process.env.REPORT_DIR || ".mugiwara/reports";
 const resultsDir = process.env.RESULTS_DIR || ".mugiwara/results/unknown";
 const reviewDir = process.env.REVIEW_DIR || ".mugiwara/review";
 const issuesDir = process.env.ISSUES_DIR || ".mugiwara/issues";
+const mugiDir = path.dirname(stateFile);
 const mission = process.env.MISSION || "unknown";
 
-if (!fs.existsSync(stateFile)) {
-  console.error("mission-report: " + stateFile + " not found");
-  process.exit(1);
+fs.mkdirSync(reportDir, { recursive: true });
+
+// state.json is optional — degrade gracefully, never hard-exit
+let s = null;
+if (fs.existsSync(stateFile)) {
+  try {
+    s = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch (e) {
+    console.error("mission-report: warning: " + stateFile + " unreadable — degraded report");
+  }
+} else {
+  console.error("mission-report: warning: " + stateFile + " not found — degraded report");
 }
 
-fs.mkdirSync(reportDir, { recursive: true });
-const s = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+const val = (obj, key, dflt) => {
+  if (!s || !obj) return dflt;
+  const v = obj[key];
+  return (v === undefined || v === null || v === "") ? dflt : v;
+};
 
 const now = new Date().toISOString().slice(0, 10);
 const reportFile = path.join(reportDir, now + "-" + mission + ".md");
-const lane = s.lane || "unknown";
-const mode = s.mode || "guided";
-const actor = s.actor || "unknown";
-const branch = s.branch || "unknown";
-const wave = s.wave || 0;
-const filesTouched = s.files_touched || 0;
-const locDelta = s.loc_delta || 0;
-const sensitive = s.sensitive_paths || [];
-const tasks = s.tasks || {};
-const blockers = s.blockers_open || 0;
-const healCycle = s.heal_cycle || 1;
-const tokens = s.tokens_est || 0;
-const budget = s.budget || 0;
-const evidence = s.evidence || [];
-const updated = s.updated_at || new Date().toISOString();
+const lane = val(s, 'lane', 'n/a');
+const laneReason = val(s, 'lane_reason', 'n/a');
+const mode = val(s, 'mode', 'n/a');
+const actor = val(s, 'actor', 'n/a');
+const branch = val(s, 'branch', 'n/a');
+const wave = val(s, 'wave', 'n/a');
+const filesTouched = val(s, 'files_touched', 0);
+const locDelta = val(s, 'loc_delta', 0);
+const sensitive = s ? (s.sensitive_paths || []) : [];
+const tasks = s ? (s.tasks || {}) : {};
+const blockers = val(s, 'blockers_open', 0);
+const healCycle = val(s, 'heal_cycle', 1);
+const tokens = Number(val(s, 'tokens_est', 0)) || 0;
+const tokensSource = val(s, 'tokens_source', 'n/a');
+const budget = Number(val(s, 'budget', 0)) || 0;
+const budgetStatus = val(s, 'budget_status', 'n/a');
+const evidence = s ? (s.evidence || []) : [];
+const updated = val(s, 'updated_at', now);
 
 // --- wave artifact scan: results/<mission>/NN-*.md with verdict sniffing ---
 const WAVE_LABEL = {
@@ -117,26 +134,133 @@ if (fs.existsSync(issuesDir)) {
   }
 }
 
+// --- tasks: state.json counts, plan-doc fallback (savepoint-style counting) ---
+function findPlan(mDir, m) {
+  const plansDir = path.join(mDir, 'plans');
+  if (!fs.existsSync(plansDir)) return null;
+  const direct = path.join(plansDir, m + '.md');
+  if (fs.existsSync(direct)) return direct;
+  const matches = fs.readdirSync(plansDir).filter(f => f.endsWith('-' + m + '.md'));
+  return matches.length ? path.join(plansDir, matches.sort()[0]) : null;
+}
+
+let tasksDone = tasks.done || 0;
+let tasksTotal = tasks.total || 0;
+let tasksSource = "state.json";
+if (tasksTotal === 0) {
+  const plan = findPlan(mugiDir, mission);
+  if (plan) {
+    const lines = fs.readFileSync(plan, 'utf8').split(/\r?\n/);
+    const done = lines.filter(l => l.includes('[x]')).length;
+    const total = done + lines.filter(l => l.includes('[ ]')).length;
+    if (total > 0) {
+      tasksDone = done;
+      tasksTotal = total;
+      tasksSource = "plan doc";
+    }
+  }
+}
+if (tasksDone === 0 && tasksTotal === 0) { tasksDone = 'n/a'; tasksTotal = 'n/a'; }
+
+// --- token budget flag: WARN/STOP line when status is not ok ---
+let budgetFlag = "";
+if (budgetStatus === "warn" || budgetStatus === "stop") {
+  const warnAt = Math.floor(budget * 3 / 2);
+  const stopAt = budget * 3;
+  if (budgetStatus === "stop") {
+    budgetFlag = "🛑 STOP: tokens " + tokens.toLocaleString() + " ≥ 3× budget " + budget.toLocaleString() + " (stop at " + stopAt.toLocaleString() + ") — halt; escalate to Luffy";
+  } else {
+    budgetFlag = "⚠ WARN: tokens " + tokens.toLocaleString() + " ≥ 1.5× budget " + budget.toLocaleString() + " (warn at " + warnAt.toLocaleString() + ") — checkpoint before continuing";
+  }
+}
+
+// --- gate/quality excerpt: headings + body from 06-closure.md, as-is ---
+function sectionExcerpt(file, heading) {
+  if (!fs.existsSync(file)) return null;
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  let collecting = false;
+  let content = 0;
+  const out = [];
+  for (const l of lines) {
+    if (/^##\s/.test(l)) {
+      if (collecting) break;
+      if (l.trim() === heading) { collecting = true; out.push(l); continue; }
+    } else if (collecting) {
+      if (l.trim()) {
+        out.push(l);
+        content++;
+        if (content >= 20) break; // cap excerpt
+      }
+    }
+  }
+  return collecting ? out : null;
+}
+
+const closureFile = path.join(resultsDir, "06-closure.md");
+const gateSec = sectionExcerpt(closureFile, "## Gate verdicts");
+const testsSec = sectionExcerpt(closureFile, "## Tests");
+
+// --- evidence file list: all .md artifacts in results/<mission>/ ---
+let evidenceFiles = [];
+if (fs.existsSync(resultsDir)) {
+  evidenceFiles = fs.readdirSync(resultsDir).filter(f => f.endsWith('.md')).sort();
+}
+
+// --- assemble report ---
 let report = "# Mission: " + mission + " . " + now + "\n\n";
-report += "**Lane** " + lane + " . **Mode** " + mode + " . **Actor** " + actor + " . **Branch** " + branch + "\n\n";
+
+report += "## Mission header\n\n| Field | Value |\n|-------|-------|\n";
+report += "| Mission | " + mission + " |\n";
+report += "| Branch | " + branch + " |\n";
+report += "| Lane | " + lane + " |\n";
+report += "| Lane reason | " + laneReason + " |\n";
+report += "| Mode | " + mode + " |\n";
+report += "| Wave | " + wave + " |\n";
+report += "| Actor | " + actor + " |\n\n";
+
+report += "## Token budget\n\n| Field | Value |\n|-------|-------|\n";
+report += "| Tokens (est) | " + tokens.toLocaleString() + " |\n";
+report += "| Tokens source | " + tokensSource + " |\n";
+report += "| Budget | " + budget.toLocaleString() + " |\n";
+report += "| Budget status | " + budgetStatus + " |\n";
+if (budgetFlag) report += "\n" + budgetFlag;
+report += "\n\n";
+
+report += "## Tasks\n\n| Field | Value |\n|-------|-------|\n";
+report += "| Done | " + tasksDone + " |\n";
+report += "| Total | " + tasksTotal + " |\n";
+report += "| Source | " + tasksSource + " |\n\n";
 
 report += "## What changed\n\n";
 report += filesTouched + " files, +" + locDelta + " LOC";
 if (sensitive.length) report += "\nSensitive paths: " + sensitive.join(", ");
+report += "\n\n";
 
-report += "\n\n## Waves\n\n| Wave | Artifact | Verdict |\n|------|----------|---------|";
+report += "## Waves\n\n| Wave | Artifact | Verdict |\n|------|----------|---------|";
 if (waveRows.length) {
   for (const r of waveRows) report += "\n| " + r.label + " | `" + r.file + "` | " + r.verdict + " |";
 } else {
   report += "\n| (no wave artifacts found in `" + resultsDir + "`) | | |";
 }
+report += "\n\n";
+
+report += "## Gate & quality\n\n";
+if (gateSec) report += gateSec.join("\n") + "\n";
+if (testsSec) report += (gateSec ? "\n" : "") + testsSec.join("\n") + "\n";
+if (!gateSec && !testsSec) report += "n/a\n";
+report += "\n";
 
-report += "\n\n## Review & blockers\n\n";
+report += "## Evidence files\n\n";
+report += evidenceFiles.length ? evidenceFiles.map(f => "- " + f).join("\n") : "n/a";
+report += "\n\n";
+
+report += "## Review & blockers\n\n";
 report += "Review + security files: " + (reviewFiles.length ? reviewFiles.join(", ") : "none") + "\n";
 report += "Findings: " + reviewFindings + "\n";
 report += "Blocker ledger rows: " + issueRows.length + (issueRows.length ? "\n" + issueRows.map(r => "- " + r).join("\n") : "");
+report += "\n\n";
 
-report += "\n\n## State\n\n| Field | Value |\n|-------|-------|\n";
+report += "## State\n\n| Field | Value |\n|-------|-------|\n";
 report += "| Wave | " + wave + " |\n";
 report += "| Tasks | " + (tasks.done || 0) + "/" + (tasks.total || 0) + " done |\n";
 report += "| Blockers open | " + blockers + " |\n";
@@ -144,9 +268,8 @@ report += "| Heal cycles | " + healCycle + " |\n";
 report += "| Tokens used | " + tokens.toLocaleString() + " / " + budget.toLocaleString() + " |\n\n";
 
 report += "## Evidence\n\n";
-for (const e of evidence) report += "- " + e + "\n";
-
-report += "\n## Updated\n\n" + updated + "\n";
+report += evidence.length ? evidence.map(e => "- " + e).join("\n") : "n/a";
+report += "\n\n## Updated\n\n" + updated + "\n";
 
 fs.writeFileSync(reportFile, report);
 console.log("\u2713 mission report: " + reportFile);

package/scripts/onboard.ts

@@ -7,7 +7,6 @@ import { createInterface } from "node:readline";
 const root = join(import.meta.dirname, "..");
 const mugiwaraDir = join(root, ".mugiwara");
 const configPath = join(mugiwaraDir, "config");
-const onboardPath = join(mugiwaraDir, "onboard.json");
 
 function ask(rl: import("node:readline").Interface, prompt: string): Promise<string> {
   return new Promise((resolve) => {
@@ -38,7 +37,7 @@ async function main() {
   if (process.argv.includes("--help") || process.argv.includes("-h")) {
     console.log("Usage: bun scripts/onboard.ts");
     console.log("Runs the Mugiwara onboarding wizard (10 fixed questions).");
-    console.log("Writes .mugiwara/config and .mugiwara/onboard.json.");
+    console.log("Writes .mugiwara/config.");
     process.exit(0);
   }
 
@@ -64,10 +63,6 @@ async function main() {
       console.log("");
     }
 
-    const answers: Record<string, unknown> = {
-      started_at: new Date().toISOString(),
-    };
-
     // ---- Phase 1: Project Context ----
     console.log("── Phase 1: Project Context ──");
     console.log("");
@@ -80,7 +75,6 @@ async function main() {
       "Backend service / API",
       "Other",
     ]);
-    answers.project_type = q1;
     console.log("");
 
     const q2 = await pick(rl, "Q2 — Primary language:\n  [1] TypeScript\n  [2] JavaScript\n  [3] Python\n  [4] Go\n  [5] Rust\n  [6] Java\n  [7] Other\n  > ", [
@@ -92,7 +86,6 @@ async function main() {
       "Java",
       "Other",
     ]);
-    answers.primary_language = q2;
     console.log("");
 
     const q3 = await pick(rl, "Q3 — Team size:\n  [1] Solo\n  [2] 2–5\n  [3] 6–15\n  [4] 16+\n  > ", [
@@ -101,7 +94,6 @@ async function main() {
       "6–15",
       "16+",
     ]);
-    answers.team_size = q3;
     console.log("");
 
     const q4 = await pick(rl, "Q4 — Git workflow:\n  [1] Trunk-based (feature/{type}-{issue}-{slug})\n  [2] GitFlow (feature/{slug})\n  [3] GitHub Flow (feat/{slug})\n  [4] Other (feature/{slug})\n  > ", [
@@ -110,7 +102,6 @@ async function main() {
       "github-flow",
       "other",
     ]);
-    answers.git_workflow = q4;
     console.log("");
 
     const q5 = await pick(rl, "Q5 — CI/CD platform:\n  [1] GitHub Actions\n  [2] GitLab CI\n  [3] CircleCI\n  [4] Jenkins\n  [5] None / manual\n  [6] Other\n  > ", [
@@ -121,7 +112,6 @@ async function main() {
       "None / manual",
       "Other",
     ]);
-    answers.ci_cd = q5;
     console.log("");
 
     // ---- Phase 2: Mugiwara Preferences ----
@@ -133,27 +123,20 @@ async function main() {
       "semi",
       "auto",
     ]);
-    answers.autonomy_mode = q6;
-    console.log("");
-
-    const q7 = await ask(rl, "Q7 — Agents to enable (comma-separated or 'all'):\n  Available: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing\n  Default: all\n  > ");
-    answers.enabled_agents = q7 || "all";
     console.log("");
 
-    const q8a = await pick(rl, "Q8a — Code review depth:\n  [1] full — breaking-change map, five-axis review, ≤3 cycles\n  [2] standard — five-axis review, 1 cycle\n  [3] quick — diff-only, no caller-map\n  > ", [
+    const q8a = await pick(rl, "Q7 — Code review depth:\n  [1] full — breaking-change map, five-axis review, ≤3 cycles\n  [2] standard — five-axis review, 1 cycle\n  [3] quick — diff-only, no caller-map\n  > ", [
       "full",
       "standard",
       "quick",
     ]);
-    answers.review_depth = q8a;
     console.log("");
 
-    const q8b = await pick(rl, "Q8b — Quality check depth:\n  [1] full — format, lint, typecheck, test, build\n  [2] standard — lint, typecheck, test\n  [3] quick — test only\n  > ", [
+    const q8b = await pick(rl, "Q8 — Quality check depth:\n  [1] full — format, lint, typecheck, test, build\n  [2] standard — lint, typecheck, test\n  [3] quick — test only\n  > ", [
       "full",
       "standard",
       "quick",
     ]);
-    answers.quality_depth = q8b;
     console.log("");
 
     console.log("Q9 — Test coverage threshold:");
@@ -180,9 +163,6 @@ async function main() {
       coverageNew = 0;
       coverageModified = 0;
     }
-    answers.coverage_threshold = q9;
-    answers.coverage_new = coverageNew;
-    answers.coverage_modified = coverageModified;
     console.log("");
 
     const q10 = await pick(rl, "Q10 — Commit style:\n  [1] Conventional Commits (feat:, fix:, chore:, docs:)\n  [2] Semantic (type(scope): message)\n  [3] Free-form\n  > ", [
@@ -190,8 +170,6 @@ async function main() {
       "semantic",
       "free-form",
     ]);
-    answers.commit_style = q10;
-    answers.completed_at = new Date().toISOString();
     console.log("");
 
     // ---- Branch name format ----
@@ -230,11 +208,9 @@ async function main() {
       commit,
       review_depth: reviewDepth,
       quality_depth: qualityDepth,
-      enabled_agents: answers.enabled_agents,
     };
 
     writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-    writeFileSync(onboardPath, JSON.stringify(answers, null, 2) + "\n");
 
     // ---- Summary ----
     const qLabels: Record<string, Record<number, string>> = {
@@ -275,14 +251,12 @@ async function main() {
     console.log("  Git workflow:     ", qLabels.git_workflow[q4]);
     console.log("  CI/CD:            ", qLabels.ci_cd[q5]);
     console.log("  Autonomy mode:    ", qLabels.autonomy_mode[q6]);
-    console.log("  Enabled agents:   ", answers.enabled_agents);
     console.log("  Review depth:     ", qLabels.review_depth[q8a]);
     console.log("  Quality depth:    ", qLabels.quality_depth[q8b]);
     console.log("  Coverage:         ", q9 === 3 ? `${coverageNew}/${coverageModified}` : qLabels.coverage_threshold[q9]);
     console.log("  Commit style:     ", qLabels.commit_style[q10]);
     console.log("");
     console.log(`  Config written:   ${configPath}`);
-    console.log(`  Audit trail:      ${onboardPath}`);
     console.log("");
   } finally {
     rl.close();

package/scripts/release-notes.ts

@@ -1,94 +1,171 @@
 #!/usr/bin/env bun
 // scripts/release-notes.ts — generates a detailed GitHub Release description
 // from git history between the previous tag and HEAD. Pulls the full commit
-// message (subject + body), groups by conventional-commit type, flags breaking
-// changes, and lists the affected scopes. No gh dependency.
+// message (subject + body), groups by conventional-commit scope (feature area)
+// in first-appearance order, falls back to type for unscoped commits, flags
+// breaking changes, and lists the affected scopes. No gh dependency.
 //
 //   bun scripts/release-notes.ts                 notes since the last tag → stdout
 //   bun scripts/release-notes.ts --since v0.3.0   notes from that tag → stdout
 import { execFileSync } from 'node:child_process';
 
-const args = process.argv;
-const sinceIdx = args.indexOf('--since');
-let since = sinceIdx !== -1 ? args[sinceIdx + 1] : null;
-
-if (!since) {
-  // The release workflow tags HEAD BEFORE generating notes, so the newest tag
-  // is the release tag itself. The "since" boundary must be the tag BEFORE it,
-  // otherwise range = "<release>..HEAD" is empty and the notes come out blank.
-  // With only one tag (first release), there is no previous tag — show all.
-  const tags = execFileSync('git', ['tag', '--sort=-version:refname'], { encoding: 'utf8' })
-    .split(/\r?\n/).filter(Boolean);
-  since = tags.length >= 2 ? tags[1] : null;
-}
-
-const range = since ? `${since}..HEAD` : '';
-const raw = execFileSync('git', ['log', '--pretty=%H%n%s%n%n%b%n__END__', ...(range ? [range] : [])], { encoding: 'utf8' });
-const commits = raw
-  .split('__END__\n')
-  .map(c => c.trim())
-  .filter(Boolean)
-  .map(c => {
-    const [sha, subject, ...rest] = c.split('\n');
-    return { sha: sha.slice(0, 7), subject: subject ?? '', body: rest.join('\n').trim() };
-  });
-
-const groups: Record<string, { label: string; items: string[] }> = {
-  feat: { label: 'New', items: [] },
-  fix: { label: 'Fixed', items: [] },
-  refactor: { label: 'Refactored', items: [] },
-  perf: { label: 'Performance', items: [] },
-  docs: { label: 'Docs', items: [] },
-  chore: { label: 'Housekeeping', items: [] },
-  test: { label: 'Housekeeping', items: [] },
-  ci: { label: 'Housekeeping', items: [] },
+// human label for a conventional-commit type: section fallback + per-bullet tag
+const TYPE_LABEL: Record<string, string> = {
+  feat: 'New',
+  fix: 'Fixed',
+  refactor: 'Refactored',
+  perf: 'Performance',
+  docs: 'Docs',
+  chore: 'Housekeeping',
+  test: 'Housekeeping',
+  ci: 'Housekeeping',
 };
 
-const order = ['feat', 'fix', 'refactor', 'perf', 'docs', 'chore'];
+const TYPE_ORDER = ['feat', 'fix', 'refactor', 'perf', 'docs', 'chore'];
 
 // strip signature trailers (Co-authored-by, Signed-off-by, review notes)
 const TRAILER = /^(Co-authored-by|Signed-off-by|Reviewed-by|Helped-by|Reported-by|Tested-by|Acked-by):/i;
 
-for (const commit of commits) {
-  const m = /^(\w+)(?:\((.*?)\))?!?: (.*)/.exec(commit.subject);
-  const type = m ? m[1] : 'chore';
-  const scope = m?.[2] || '';
-  const text = m ? m[3] : commit.subject;
-  const breaking = Boolean(m?.[0]?.includes('!')) || /^BREAKING CHANGE:/m.test(commit.body);
-
-  const title = text.charAt(0).toUpperCase() + text.slice(1);
-  const scopeTag = scope ? ` \`${scope}\`` : '';
-  const breakingTag = breaking ? ' ⚠️ **BREAKING**' : '';
-
-  const bodyLines = commit.body
-    .split(/\r?\n/)
-    .map(l => l.trim())
-    .filter(l => l && !TRAILER.test(l) && l !== '---')
-    // the release-version marker commit repeats the subject as body — drop it
-    .filter(l => l !== text);
-
-  let entry = `- ${title}${scopeTag}${breakingTag} \`${commit.sha}\``;
-  if (bodyLines.length) {
-    entry += '\n' + bodyLines.map(l => `  - ${l}`).join('\n');
-  }
-  const g = groups[type] ?? groups.chore;
-  g.items.push(entry);
+// capitalize the first letter of each word; split on non-alphanumerics
+// (opencode → Opencode, release-notes → Release Notes)
+const titleCase = (s: string) =>
+  s
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+
+export interface ReleaseCommit {
+  sha: string;
+  subject: string;
+  body: string;
 }
 
-const lines: string[] = [];
-for (const t of order) {
-  const g = groups[t];
-  if (!g.items.length) continue;
-  lines.push(`## ${g.label}`);
-  lines.push('');
-  for (const item of g.items) lines.push(item);
-  lines.push('');
+/**
+ * Group parsed commits into per-scope sections (first-appearance order) with a
+ * type-fallback for unscoped commits. Returns the rendered markdown body and
+ * the change count. Pure — no git access, deterministic. Exported so tests
+ * exercise the grouping without invoking git.
+ */
+export function buildNotes(commits: ReleaseCommit[]): { count: number; markdown: string } {
+  // scoped (feature-area) sections, keyed by lowercased scope, first-appearance order
+  const scoped = new Map<string, { label: string; items: string[] }>();
+  const scopedOrder: string[] = [];
+  // unscoped fallback sections by type, rendered in canonical type order
+  const byType = new Map<string, { label: string; items: string[] }>();
+  for (const t of TYPE_ORDER) byType.set(t, { label: TYPE_LABEL[t], items: [] });
+
+  for (const commit of commits) {
+    const m = /^(\w+)(?:\((.*?)\))?(!)?: (.*)/.exec(commit.subject);
+    const type = m ? m[1] : 'chore';
+    const scope = m?.[2] || '';
+    const text = m ? m[4] : commit.subject;
+    // the conventional-commits `!` breaking marker sits between scope and
+    // colon; capture it positionally so `fix: handle a! in parser` is NOT
+    // flagged breaking (a bare `!` anywhere in the subject would be)
+    const breaking = m?.[3] === '!' || /^BREAKING CHANGE:/m.test(commit.body);
+
+    const title = text.charAt(0).toUpperCase() + text.slice(1);
+    const breakingTag = breaking ? ' ⚠️ **BREAKING**' : '';
+
+    const bodyLines = commit.body
+      .split(/\r?\n/)
+      .map(l => l.trim())
+      .filter(l => l && !TRAILER.test(l) && l !== '---')
+      // the release-version marker commit repeats the subject as body — drop it
+      .filter(l => l !== text);
+
+    const typeLabel = TYPE_LABEL[type] ?? 'Housekeeping';
+    const base = `${title}${breakingTag} \`${commit.sha}\``;
+    const bodyBlock = bodyLines.length ? '\n' + bodyLines.map(l => `  - ${l}`).join('\n') : '';
+
+    if (scope) {
+      const key = scope.toLowerCase();
+      let g = scoped.get(key);
+      if (!g) {
+        g = { label: titleCase(scope), items: [] };
+        scoped.set(key, g);
+        scopedOrder.push(key);
+      }
+      // scoped (feature-area) sections: the type label adds information because
+      // the heading names the area, not the type
+      g.items.push(`- **${typeLabel}** ${base}${bodyBlock}`);
+    } else {
+      // type-fallback sections: the heading already names the type, so a
+      // per-bullet label would be redundant (R5a)
+      (byType.get(type) ?? byType.get('chore')!).items.push(`- ${base}${bodyBlock}`);
+    }
+  }
+
+  // Render into a heading-keyed map (case-insensitive) so a type-fallback
+  // heading that collides with an earlier scoped heading merges into it
+  // instead of emitting a duplicate section (R5b).
+  const sections = new Map<string, { heading: string; items: string[] }>();
+  const order: string[] = [];
+  const addSection = (heading: string, items: string[]) => {
+    const key = heading.toLowerCase();
+    let s = sections.get(key);
+    if (!s) {
+      s = { heading, items: [] };
+      sections.set(key, s);
+      order.push(key);
+    }
+    s.items.push(...items);
+  };
+
+  // scoped (feature-area) sections first, in order of first appearance
+  for (const key of scopedOrder) addSection(scoped.get(key)!.label, scoped.get(key)!.items);
+  // then unscoped type-fallback sections, canonical type order
+  for (const t of TYPE_ORDER) {
+    const g = byType.get(t)!;
+    if (g.items.length) addSection(g.label, g.items);
+  }
+
+  const lines: string[] = [];
+  for (const key of order) {
+    const s = sections.get(key)!;
+    lines.push(`## ${s.heading}`);
+    lines.push('');
+    for (const item of s.items) lines.push(item);
+    lines.push('');
+  }
+
+  const bumpIdx = commits.findIndex(c => /chore: release|chore: bump/.test(c.subject));
+  const body = commits.slice(0, bumpIdx === -1 ? commits.length : bumpIdx);
+  const count = body.length || commits.length;
+
+  return { count, markdown: lines.join('\n').trimEnd() };
 }
 
-const bumpIdx = commits.findIndex(c => /chore: release|chore: bump/.test(c.subject));
-const body = commits.slice(0, bumpIdx === -1 ? commits.length : bumpIdx);
-const count = body.length || commits.length;
+// Guard the CLI path so importing buildNotes in tests does not run git.
+if (import.meta.main) {
+  const args = process.argv;
+  const sinceIdx = args.indexOf('--since');
+  let since = sinceIdx !== -1 ? args[sinceIdx + 1] : null;
+
+  if (!since) {
+    // The release workflow tags HEAD BEFORE generating notes, so the newest tag
+    // is the release tag itself. The "since" boundary must be the tag BEFORE it,
+    // otherwise range = "<release>..HEAD" is empty and the notes come out blank.
+    // With only one tag (first release), there is no previous tag — show all.
+    const tags = execFileSync('git', ['tag', '--sort=-version:refname'], { encoding: 'utf8' })
+      .split(/\r?\n/).filter(Boolean);
+    since = tags.length >= 2 ? tags[1] : null;
+  }
 
-console.log(`**${count} change${count === 1 ? '' : 's'} since ${since ?? 'the start'}.**`);
-console.log('');
-console.log(lines.join('\n').trimEnd());
+  const range = since ? `${since}..HEAD` : '';
+  const raw = execFileSync('git', ['log', '--pretty=%H%n%s%n%n%b%n__END__', ...(range ? [range] : [])], { encoding: 'utf8' });
+  const commits: ReleaseCommit[] = raw
+    .split('__END__\n')
+    .map(c => c.trim())
+    .filter(Boolean)
+    .map(c => {
+      const [sha, subject, ...rest] = c.split('\n');
+      return { sha: sha.slice(0, 7), subject: subject ?? '', body: rest.join('\n').trim() };
+    });
+
+  const { count, markdown } = buildNotes(commits);
+  console.log(`**${count} change${count === 1 ? '' : 's'} since ${since ?? 'the start.'}**`);
+  console.log('');
+  console.log(markdown);
+}