@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/templates/research-outputs/STACK.md.tmpl

@@ -0,0 +1,63 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges stack findings into SUMMARY.md. Needs: technology table with versions and rationale, confidence levels per recommendation.
+  - Planner agent: uses stack decisions for phase planning and dependency ordering. Needs: prescriptive technology choices (not "consider X or Y"), version numbers, package manager.
+  - Dashboard ResearchTab: displays research confidence. Needs: frontmatter confidence field.
+  Breaks if missing: Synthesizer produces SUMMARY with vague stack section; planner makes technology decisions without research backing.
+-->
+# Stack Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Core Stack
+
+| Technology | Version | Purpose | Why Standard |
+|------------|---------|---------|--------------|
+| {technology} | {version} | {purpose} | {rationale} |
+
+## Supporting Tools
+
+| Tool | Version | Purpose | When to Use |
+|------|---------|---------|-------------|
+| {tool} | {version} | {purpose} | {use_case} |
+
+## Package Manager
+
+**Recommended:** {package_manager}
+**Why:** {rationale}
+
+## Deployment Target
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Platform | {platform} | {notes} |
+| Hosting | {hosting} | {notes} |
+| CI/CD | {ci_cd} | {notes} |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|-------------|---------|
+| {our_choice} | {alternative} | {rejection_reason} |
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| {package_a} | {package_b} | {compatibility_notes} |
+
+## Quality Gates
+
+- [ ] All technology recommendations are prescriptive ("Use X") not exploratory ("Consider X or Y")
+- [ ] Every technology entry has a specific version number (not "latest")
+- [ ] Core stack table has at least 3 entries
+- [ ] Alternatives Considered table documents at least 2 rejected alternatives with rationale
+- [ ] Package manager recommendation includes rationale
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/pbr/templates/research-outputs/SUMMARY.md.tmpl

@@ -0,0 +1,98 @@
+<!-- Downstream consumers:
+  - Planner agent (primary consumer): reads SUMMARY.md for all phase planning decisions. Needs: stack recommendation, architecture recommendation, key risks, feature priorities, confidence assessment.
+  - Begin skill: presents synthesis to user for approval before roadmap creation. Needs: executive summary, consolidated recommendations.
+  - Dashboard ResearchTab: displays synthesis with confidence levels. Needs: confidence assessment table, research coverage.
+  Breaks if missing: Planner makes phase decisions without research backing; user approves roadmap without seeing synthesis; dashboard shows empty research card.
+-->
+# Research Synthesis
+
+**Synthesized:** {date}
+**Input documents:** {count}
+**Confidence:** {overall_confidence}
+
+## Executive Summary
+
+{Unified findings across all research dimensions in under 200 words. State: what was researched, key conclusions, primary recommendation, and confidence level.}
+
+## Stack Recommendation
+
+**Recommended stack:** {one_line_summary}
+
+{Key technology choices with rationale, sourced from STACK research.}
+
+- **{technology}:** {version} -- {why_chosen}
+
+## Architecture Recommendation
+
+**Recommended pattern:** {pattern_name}
+
+{Architecture approach with component overview, sourced from ARCHITECTURE research.}
+
+- **{component}:** {responsibility}
+
+## Key Risks
+
+{Top risks from PITFALLS research, ordered by impact.}
+
+1. **{risk}** -- {mitigation}
+2. **{risk}** -- {mitigation}
+3. **{risk}** -- {mitigation}
+
+## Feature Priorities
+
+{Prioritized feature summary from FEATURES research.}
+
+**Must-have:** {must_have_features}
+**Should-have:** {should_have_features}
+**Deferred:** {deferred_features}
+
+## Consolidated Recommendations
+
+{Actionable recommendations that integrate findings across all dimensions.}
+
+1. {recommendation}
+2. {recommendation}
+3. {recommendation}
+
+## Confidence Assessment
+
+| Dimension | Confidence | Gaps |
+|-----------|------------|------|
+| Stack | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Features | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Architecture | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Pitfalls | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+
+**Overall confidence:** {confidence}
+
+## Research Coverage
+
+| Dimension | Status | Notes |
+|-----------|--------|-------|
+| Stack | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Features | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Architecture | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Pitfalls | {COMPLETE/PARTIAL/MISSING} | {notes} |
+
+**Dimensions researched:** {count}/4
+**Gaps requiring attention:** {list_or_none}
+
+## Quality Gates
+
+- [ ] Executive summary is under 200 words
+- [ ] All 4 research dimensions referenced (Stack, Features, Architecture, Pitfalls)
+- [ ] Confidence gaps explicitly listed for each dimension
+- [ ] Recommendations are prescriptive and actionable (not "consider" or "evaluate")
+- [ ] Partial failure handled -- missing dimensions noted, not silently omitted
+- [ ] Sources consolidated from all input documents
+
+## Sources
+
+### Primary (HIGH confidence)
+- {source}
+
+### Secondary (MEDIUM confidence)
+- {source}
+
+### Tertiary (LOW confidence)
+- {source}

package/scripts/build-hooks.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Copy PBR hooks to dist for installation.
+ *
+ * Dynamically discovers all .js files in plugins/pbr/scripts/ and copies them
+ * along with hooks.json and hooks-schema.json to plugins/pbr/dist/.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HOOKS_DIR = path.join(__dirname, '..', 'plugins', 'pbr', 'scripts');
+const DIST_DIR = path.join(__dirname, '..', 'plugins', 'pbr', 'dist');
+
+// Static assets to copy alongside hook scripts
+const STATIC_FILES = [
+  'hooks.json',
+  'hooks-schema.json'
+];
+
+function build() {
+  // Ensure dist directory exists
+  if (!fs.existsSync(DIST_DIR)) {
+    fs.mkdirSync(DIST_DIR, { recursive: true });
+  }
+
+  // Discover all .js files in hooks/
+  const jsFiles = fs.readdirSync(HOOKS_DIR).filter(f => f.endsWith('.js'));
+
+  // Copy all .js hook scripts
+  let copied = 0;
+  for (const file of jsFiles) {
+    const src = path.join(HOOKS_DIR, file);
+    const dest = path.join(DIST_DIR, file);
+
+    console.log(`Copying ${file}...`);
+    fs.copyFileSync(src, dest);
+    console.log(`  → ${dest}`);
+    copied++;
+  }
+
+  // Copy static assets (hooks.json, hooks-schema.json)
+  for (const file of STATIC_FILES) {
+    const src = path.join(HOOKS_DIR, file);
+    const dest = path.join(DIST_DIR, file);
+
+    if (!fs.existsSync(src)) {
+      console.warn(`Warning: ${file} not found, skipping`);
+      continue;
+    }
+
+    console.log(`Copying ${file}...`);
+    fs.copyFileSync(src, dest);
+    console.log(`  → ${dest}`);
+    copied++;
+  }
+
+  console.log(`\nBuild complete. ${copied} files copied.`);
+}
+
+build();

package/scripts/check-ci.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * check-ci.js — Check GitHub Actions CI status and cache for the status line.
+ *
+ * Writes .planning/.ci-status.json with the latest CI run status.
+ * The status line reads this file to show CI pass/fail/pending.
+ *
+ * Usage:
+ *   node scripts/check-ci.js          # Check latest run for current branch
+ *   node scripts/check-ci.js --watch  # Check and exit non-zero on failure
+ *
+ * Requires: gh CLI authenticated with repo access.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+const planningDir = path.join(process.cwd(), '.planning');
+const ciFile = path.join(planningDir, '.ci-status.json');
+
+function main() {
+  const watch = process.argv.includes('--watch');
+
+  // Get current branch
+  let branch;
+  try {
+    branch = cp.execSync('git branch --show-current', {
+      encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (_e) {
+    console.error('check-ci: not in a git repo');
+    process.exit(1);
+  }
+
+  // Get latest CI run via gh CLI
+  let runs;
+  try {
+    const output = cp.execSync(
+      `gh run list --branch ${branch} --limit 1 --json status,conclusion,headBranch,event,createdAt,name,databaseId`,
+      { encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    runs = JSON.parse(output);
+  } catch (e) {
+    // gh CLI not available or not authenticated
+    console.error('check-ci: gh CLI failed —', e.message || 'unknown error');
+    // Write unknown status so status line knows we tried
+    writeStatus({ status: 'unknown', branch, error: 'gh CLI unavailable' });
+    return;
+  }
+
+  if (!runs || runs.length === 0) {
+    console.log(`check-ci: no CI runs found for branch '${branch}'`);
+    writeStatus({ status: 'none', branch });
+    return;
+  }
+
+  const run = runs[0];
+  let status;
+
+  if (run.status === 'completed') {
+    status = run.conclusion === 'success' ? 'pass' : 'fail';
+  } else if (run.status === 'in_progress' || run.status === 'queued') {
+    status = 'pending';
+  } else {
+    status = 'unknown';
+  }
+
+  const result = {
+    status,
+    branch,
+    conclusion: run.conclusion || null,
+    name: run.name || null,
+    runId: run.databaseId || null,
+    createdAt: run.createdAt || null,
+    timestamp: new Date().toISOString()
+  };
+
+  writeStatus(result);
+
+  const icons = { pass: '✓', fail: '✗', pending: '○', unknown: '?', none: '-' };
+  const icon = icons[status] || '?';
+  console.log(`check-ci: ${icon} ${status} — ${run.name || 'CI'} on ${branch}`);
+
+  if (watch && status === 'fail') {
+    process.exit(1);
+  }
+}
+
+function writeStatus(data) {
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+  fs.writeFileSync(ciFile, JSON.stringify(data, null, 2), 'utf8');
+}
+
+main();

package/scripts/clean-changelog.js

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+
+/**
+ * Changelog generator for Plan-Build-Run.
+ *
+ * Generates CHANGELOG.md grouped by component (Hooks, Skills, Agents, CLI, etc.)
+ * instead of flat lists under commit types.
+ *
+ * Features:
+ *   - Groups entries by component scope or keyword detection
+ *   - Strips internal phase-plan scopes (01-01, 03-02) from output
+ *   - Removes TDD markers (RED/GREEN/REFACTOR prefixes)
+ *   - Deduplicates entries that differ only by scope
+ *   - Rebrands GSD references to PBR
+ *   - Drops entries for removed features
+ *
+ * Usage:
+ *   node scripts/clean-changelog.js                    # generate full CHANGELOG.md to stdout
+ *   node scripts/clean-changelog.js --write            # write CHANGELOG.md in place
+ *   node scripts/clean-changelog.js --latest           # show only latest version
+ *   node scripts/clean-changelog.js --post-process     # clean an existing CHANGELOG.md (legacy mode)
+ *
+ * Also exported as cleanChangelog() for programmatic use.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ─── Component Detection ────────────────────────────────────────────────────
+
+// Explicit scope → component mapping (new-style scopes)
+const SCOPE_TO_COMPONENT = {
+  hooks: 'Hooks',
+  skills: 'Skills',
+  agents: 'Agents',
+  cli: 'CLI Tools',
+  dashboard: 'Dashboard',
+  templates: 'Templates',
+  plugin: 'Plugin',
+  config: 'Configuration',
+  ci: 'CI/CD',
+  tests: 'Testing',
+  commands: 'Plugin',
+  refs: 'Documentation',
+  changelog: 'CI/CD',
+  release: 'CI/CD',
+};
+
+// Keyword → component mapping for commits without explicit component scopes
+// Order matters: first match wins. More specific patterns come first.
+const KEYWORD_RULES = [
+  [/\bhook[s]?\b|\bPostToolUse\b|\bPreToolUse\b|\bSessionStart\b|\bdispatch\b|\bhook-logger\b|\bevent-handler\b|\bsession-cleanup\b|\bprogress-tracker\b|\bcheck-plan-format\b|\bcheck-state\b|\bcheck-subagent\b|\btrack-context\b|\bsuggest-compact\b|\bauto-continue\b|\bpre-bash\b|\bpre-write\b|\bpost-write\b|\bvalidate-task\b|\bvalidate-commit\b|\bresolve-root\b|\bsession-tracker/i, 'Hooks'],
+  [/\bagent[s]?\b|\bsubagent\b|\bexecutor\b|\bplanner\b|\bverifier\b|\bresearcher\b|\bplan-checker\b|\bcodebase-mapper\b|\bsynthesizer\b|\bintel-updater\b|\bcheckpoint\b.*\bagent/i, 'Agents'],
+  [/\bskill[s]?\b|\bSKILL\.md\b/i, 'Skills'],
+  [/\bpbr-tools\b|\bstatePhaseComplete\b|\bstateRederive\b|\bconfigLoad\b|\bstateLoad\b|\bfrontmatter\b|\blockedFileUpdate\b|\binitResume\b|\bdetectDrift\b|\bclassify-artifact\b|\blearnings\b|\bnegative-knowledge\b|\bverify\.cjs\b|\bstate\.cjs\b|\binit\.cjs\b|\bconfig\.cjs\b|\bspec /i, 'CLI Tools'],
+  [/\bdashboard\b|\brecharts\b|\bvite\b|\bchokidar/i, 'Dashboard'],
+  [/\btemplate\b|\btmpl\b|\b\.tmpl\b/i, 'Templates'],
+  [/\bconfig-schema\b|\bconfig\.json\b|\bdepth_profiles\b|\bmodel_profiles\b|\bmodel profile/i, 'Configuration'],
+  [/\bplugin\.json\b|\bCLAUDE\.md\b|\bcommands\/\b|\breferences\/\b/i, 'Plugin'],
+  [/\bci\b.*\bjob\b|\bworkflow\b|\bgithub action\b|\bcoverage\b|\blint\b|\bmarkdownlint\b|\beslint\b|\bCI\b/i, 'CI/CD'],
+  [/\btest[s]?\b|\bfixture[s]?\b|\bjest\b|\bvitest/i, 'Testing'],
+  [/\bcontext\b.*\b(?:budget|quality|scoring|ledger)\b|\bcompact\b|\btoken[s]?\b|\b1M\b|\bscale\b|\bthreshold/i, 'Context Management'],
+];
+
+// Phase-plan scope pattern (internal, should be stripped)
+const PHASE_PLAN_SCOPE = /^\d{1,2}-\d{1,2}$/;
+
+// TDD markers at start of description
+const TDD_MARKER_PATTERN = /^(RED|GREEN|REFACTOR)\s*[-–—]\s*/i;
+
+// Conventional commit parsing
+const COMMIT_REGEX = /^([a-f0-9]+)\s+(feat|fix|refactor|test|docs|chore|wip|revert|perf|ci|build)(\([^)]*\))?!?:\s+(.+)/;
+
+// Types that appear in changelog (others are hidden)
+const VISIBLE_TYPES = new Set(['feat', 'fix', 'revert', 'perf']);
+
+// Features removed from PBR v2 — entries matching these are dropped
+const DEAD_FEATURE_PATTERNS = [
+  /\bintel-index\b/i,
+  /\bgraph\s*database\b|\bsql\.js\b|\bSQLite\s*graph\b/i,
+  /\bquery-intel\b|\banalyze-codebase\b/i,
+  /\bentity-generator\b|\bpbr-indexer\b|\bgsd-indexer\b/i,
+  /\bintel\s*directory\b|\bintel\s*hooks?\b/i,
+  /\bgraph\s*query\b|\bgraph-backed\b|\bgraph\s*summary\b/i,
+  /\bsync\s*entity\s*files\b/i,
+  /\bsemantic\s*entity\b/i,
+  /\bcodebase\s*intel(?:ligence)?\b/i,
+  /\bintel\s*injection\b/i,
+  /\bconvention\s*detection\b/i,
+  /\bMistral\s*Vibe\b|\bvibe\s*CLI\b/i,
+  /\bAntigravity\b/i,
+  /\bJules\b/i,
+  /\/pbr:add-tests\b|\/gsd:add-tests\b|\badd-tests\b.*command\b/i,
+  /\bBrave\s*Search\b/i,
+  /\bcross-project\s*knowledge\b|\bPBR\s*Memory\s*cross/i,
+  /\bDiscord\s*invite\s*link\s*in\s*install\b/i,
+  /\bPBR\s*logo\s*for\s*Moonshot\b|\bGSD\s*logo\b/i,
+  /\bpbr-gemini\s*link\b|\bgsd-gemini\s*link\b/i,
+];
+
+// GSD → PBR rebranding
+const GSD_REPLACEMENTS = [
+  [/\/gsd:/g, '/pbr:'],
+  [/\bgsd-tools\b/g, 'pbr-tools'],
+  [/~\/\.gsd\//g, '~/.claude/'],
+  [/\bgsd-(?=[a-z])/g, 'pbr-'],
+  [/\bGSD\b(?![^(]*\))/g, 'PBR'],
+];
+
+// ─── Core Logic ─────────────────────────────────────────────────────────────
+
+function detectComponent(scope, description) {
+  // 1. Check explicit scope mapping
+  if (scope && SCOPE_TO_COMPONENT[scope.toLowerCase()]) {
+    return SCOPE_TO_COMPONENT[scope.toLowerCase()];
+  }
+
+  // 2. Skip phase-plan scopes for mapping (fall through to keywords)
+  // 3. Check keyword rules against description
+  for (const [pattern, component] of KEYWORD_RULES) {
+    if (pattern.test(description)) {
+      return component;
+    }
+  }
+
+  return 'Other';
+}
+
+function cleanDescription(desc) {
+  let cleaned = desc;
+
+  // Remove TDD markers
+  cleaned = cleaned.replace(TDD_MARKER_PATTERN, '');
+
+  // Rebrand GSD
+  for (const [pattern, replacement] of GSD_REPLACEMENTS) {
+    cleaned = cleaned.replace(pattern, replacement);
+  }
+
+  // Capitalize first letter
+  cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+
+  return cleaned;
+}
+
+const SEMVER_TAG = /^plan-build-run-v\d+\.\d+\.\d+$/;
+
+function getVersionTags() {
+  try {
+    const tags = execSync('git tag -l "plan-build-run-v*" --sort=-version:refname', {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim().split('\n').filter(Boolean);
+    return tags.filter(t => SEMVER_TAG.test(t));
+  } catch (_e) {
+    return [];
+  }
+}
+
+function getCommitsBetween(from, to) {
+  const range = from ? `${from}..${to}` : to;
+  try {
+    const log = execSync(`git log --oneline --no-merges ${range}`, {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim();
+    return log ? log.split('\n') : [];
+  } catch (_e) {
+    return [];
+  }
+}
+
+function getTagDate(tag) {
+  try {
+    return execSync(`git log -1 --format=%ai ${tag}`, {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim().slice(0, 10);
+  } catch (_e) {
+    return new Date().toISOString().slice(0, 10);
+  }
+}
+
+function parseCommit(line) {
+  const m = line.match(COMMIT_REGEX);
+  if (!m) return null;
+
+  const [, hash, type, scopeRaw, description] = m;
+  const scope = scopeRaw ? scopeRaw.slice(1, -1) : '';
+
+  return { hash, type, scope, description };
+}
+
+function generateVersionSection(version, fromTag, toTag, repo) {
+  const commits = getCommitsBetween(fromTag, toTag);
+  if (commits.length === 0) return '';
+
+  const date = getTagDate(toTag);
+  const versionNum = version.replace('plan-build-run-v', '');
+  const compare = fromTag
+    ? `${repo}/compare/${fromTag}...${version}`
+    : `${repo}/commits/${version}`;
+
+  // Group commits by component
+  const groups = {};
+  const seen = new Set();
+
+  for (const line of commits) {
+    const parsed = parseCommit(line);
+    if (!parsed) continue;
+    if (!VISIBLE_TYPES.has(parsed.type)) continue;
+
+    // Skip dead features
+    if (DEAD_FEATURE_PATTERNS.some(p => p.test(parsed.description))) continue;
+
+    const component = detectComponent(parsed.scope, parsed.description);
+    const desc = cleanDescription(parsed.description);
+
+    // Deduplicate by normalized description
+    const normalized = desc.toLowerCase().replace(/\s+/g, ' ').trim();
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+
+    if (!groups[component]) groups[component] = [];
+    groups[component].push({ desc, hash: parsed.hash, type: parsed.type });
+  }
+
+  if (Object.keys(groups).length === 0) return '';
+
+  // Build section
+  let section = `## [${versionNum}](${compare}) — ${date}\n\n`;
+
+  // Sort component groups: alphabetical, but "Other" last
+  const sortedComponents = Object.keys(groups).sort((a, b) => {
+    if (a === 'Other') return 1;
+    if (b === 'Other') return -1;
+    return a.localeCompare(b);
+  });
+
+  for (const component of sortedComponents) {
+    section += `### ${component}\n\n`;
+    for (const { desc, hash } of groups[component]) {
+      section += `* ${desc} ([${hash.slice(0, 8)}](${repo}/commit/${hash}))\n`;
+    }
+    section += '\n';
+  }
+
+  return section;
+}
+
+function generateChangelog() {
+  const repo = 'https://github.com/SienkLogic/plan-build-run';
+  const tags = getVersionTags();
+
+  let changelog = `# Changelog\n\nAll notable changes to Plan-Build-Run will be documented in this file.\n\n`;
+
+  for (let i = 0; i < tags.length; i++) {
+    const tag = tags[i];
+    const prevTag = i + 1 < tags.length ? tags[i + 1] : null;
+    const section = generateVersionSection(tag, prevTag, tag, repo);
+    if (section) changelog += section;
+  }
+
+  return changelog;
+}
+
+// ─── Legacy: Post-process existing CHANGELOG.md ─────────────────────────────
+
+function cleanChangelog(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+  const seen = new Set();
+  const result = [];
+
+  const INTERNAL_SCOPE_PATTERN = /\*\*(\d{1,2}-\d{1,2}|\d{1,2}|quick-\d{1,3}):\*\*\s*/g;
+
+  for (const line of lines) {
+    let cleaned = line;
+
+    if (cleaned.startsWith('* ') && DEAD_FEATURE_PATTERNS.some(p => p.test(cleaned))) {
+      continue;
+    }
+
+    cleaned = cleaned.replace(INTERNAL_SCOPE_PATTERN, '');
+
+    for (const [pattern, replacement] of GSD_REPLACEMENTS) {
+      cleaned = cleaned.replace(pattern, replacement);
+    }
+
+    cleaned = cleaned.replace(/^(\* )(.*)$/, (_match, prefix, desc) => {
+      return prefix + desc.replace(TDD_MARKER_PATTERN, '');
+    });
+
+    if (/^\* [^*]/.test(cleaned) && !/^\* \*\*/.test(cleaned)) {
+      for (const [pattern, component] of KEYWORD_RULES) {
+        if (pattern.test(cleaned)) {
+          const scope = Object.entries(SCOPE_TO_COMPONENT)
+            .find(([, v]) => v === component)?.[0] || component.toLowerCase();
+          cleaned = cleaned.replace(/^\* /, `* **${scope}:** `);
+          break;
+        }
+      }
+    }
+
+    cleaned = cleaned.replace(/^(\* (?:\*\*[^*]+:\*\* )?)([a-z])/, (_match, prefix, letter) => {
+      return prefix + letter.toUpperCase();
+    });
+
+    if (cleaned.startsWith('* ')) {
+      const norm = cleaned.toLowerCase().replace(/\(\[[a-f0-9]+\]\([^)]+\)\)/g, '').replace(/\s+/g, ' ').trim();
+      if (seen.has(norm)) continue;
+      seen.add(norm);
+    }
+
+    result.push(cleaned);
+  }
+
+  return result.join('\n');
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const writeMode = args.includes('--write');
+  const latestOnly = args.includes('--latest');
+  const postProcess = args.includes('--post-process');
+
+  if (postProcess) {
+    // Legacy: clean an existing CHANGELOG.md
+    const fileIdx = args.indexOf('--file');
+    const filePath = fileIdx !== -1 ? args[fileIdx + 1] : path.resolve(process.cwd(), 'CHANGELOG.md');
+    if (!fs.existsSync(filePath)) { console.error(`File not found: ${filePath}`); process.exit(1); }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const cleaned = cleanChangelog(content);
+    if (writeMode) { fs.writeFileSync(filePath, cleaned, 'utf8'); console.log(`Cleaned: ${filePath}`); }
+    else { process.stdout.write(cleaned); }
+    return;
+  }
+
+  if (latestOnly) {
+    const repo = 'https://github.com/SienkLogic/plan-build-run';
+    const tags = getVersionTags();
+    if (tags.length === 0) { console.log('No tags found.'); return; }
+    const section = generateVersionSection(tags[0], tags[1] || null, tags[0], repo);
+    process.stdout.write(section || 'No visible changes.\n');
+    return;
+  }
+
+  // Full changelog generation
+  const changelog = generateChangelog();
+  if (writeMode) {
+    fs.writeFileSync(path.resolve(process.cwd(), 'CHANGELOG.md'), changelog, 'utf8');
+    console.log('Generated: CHANGELOG.md');
+  } else {
+    process.stdout.write(changelog);
+  }
+}
+
+module.exports = { cleanChangelog, generateChangelog, detectComponent, cleanDescription, getVersionTags, SEMVER_TAG };
+if (require.main === module) main();