@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/scripts/audit-kit-roster.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+// audit-kit-roster.mjs — §SelfAudit enforcement for adia-ui-kit (factory/consumer edition).
+// Standalone version — audit-axes inlined (no .agents/ import; safe in bare consumer repos).
+//
+// Axes 1–8 (universal) + Axis 9 = pattern/flow bundle-roster currency.
+//
+// This is the kit's structural self-audit — the mechanical check the
+// §Plan-Execute-Verify loop and §Teach landing name as their verify target
+// ("audit-kit-roster.mjs --strict"). It answers: does the SKILL.md itself still
+// satisfy its structural invariants? (manifest ⊨ disk, reference graph resolves,
+// version literals agree, every pattern/flow bundle the seed advertises exists).
+//
+// Usage (from the skill dir, or from anywhere with --dir):
+//   node scripts/audit-kit-roster.mjs
+//   node scripts/audit-kit-roster.mjs --json
+//   node scripts/audit-kit-roster.mjs --strict   # exit 1 on any drift
+//   node scripts/audit-kit-roster.mjs --dir <path-to-skill-root>
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+
+// Resolve skill dir: --dir flag or parent of scripts/
+function resolveSkillDir(argv) {
+  const dirFlag = argv.find(a => a.startsWith('--dir='));
+  if (dirFlag) return path.resolve(dirFlag.slice('--dir='.length));
+  const idx = argv.indexOf('--dir');
+  if (idx >= 0 && argv[idx + 1]) return path.resolve(argv[idx + 1]);
+  return path.dirname(SCRIPT_DIR);
+}
+
+const SKILL_DIR = resolveSkillDir(process.argv.slice(2));
+const SKILL_MD = path.join(SKILL_DIR, 'SKILL.md');
+const SKILL_JSON = path.join(SKILL_DIR, 'skill.json');
+
+const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
+
+function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(`audit-kit-roster.mjs — adia-ui-kit §SelfAudit (9 axes, factory/consumer edition).
+
+USAGE
+  node scripts/audit-kit-roster.mjs [--json] [--strict] [--dir <skill-root>]
+
+AXES (1-8 universal, inlined; 9 kit-specific)
+  1  Manifest enforcement     — skill.json files[] matches disk (.claude/docs/ excluded)
+  2  Reference graph          — every markdown link in SKILL.md resolves
+  3  Capability-menu drift    — §ColdStartTriage entry refs exist (skipped if absent)
+  4  Version-literal parity   — SKILL.md frontmatter version == skill.json
+  5  Phase-label absence      — no stale "(Phase N)" annotations
+  6  Fence-leak detection     — no headings orphaned inside code fences
+  7  Content currency         — every files[] entry exists on disk
+  8  CLI helper currency      — npm/node helpers cited in SKILL.md resolve
+  9  Bundle-roster currency   — every references/patterns-*.md and
+     references/flows-*.md named in §Patterns/§Flows bundle maps exists on
+     disk AND is declared in skill.json files[].
+
+EXIT CODES
+  0   All axes clean        1   At least one axis drifting (with --strict)
+`);
+    process.exit(0);
+  }
+  return { json: argv.includes('--json'), strict: argv.includes('--strict') };
+}
+
+// ─── inlined audit-axes (universal axes 1-8) ─────────────────────────────────
+
+function walkDir(dir, { include = null, exclude = ['node_modules', '.git', 'docs'] } = {}) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (exclude.some(x => entry.name === x)) continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, { include, exclude }));
+    } else {
+      if (!include || include.some(ext => entry.name.endsWith(ext))) {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+
+function readSafe(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const m = line.match(/^(\w+):\s*['"]?(.*?)['"]?\s*$/);
+    if (m) result[m[1]] = m[2];
+  }
+  return result;
+}
+
+function extractMarkdownLinks(content, filePath) {
+  const links = [];
+  const lines = content.split('\n');
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const lineStripped = line.replace(/`[^`]*`/g, '``');
+    const re = /\[([^\]]*)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(lineStripped)) !== null) {
+      const url = m[2];
+      if (url.startsWith('http') || url.startsWith('#') || url.startsWith('mailto:')) continue;
+      if (url.startsWith('~/')) continue;
+      if (/<[^>]+>/.test(url)) continue;
+      if (/^[a-z]+$/.test(url) && !url.includes('/')) continue;
+      const cleanUrl = url.split('#')[0];
+      if (!cleanUrl) continue;
+      links.push({ text: m[1], url: cleanUrl, line: i + 1, file: filePath });
+    }
+  }
+  return links;
+}
+
+function finding(type, message, extra = {}) {
+  return { type, message, ...extra };
+}
+
+function axis1_manifestEnforcement(ctx) {
+  const { skillDir, skillJson } = ctx;
+  const pkg = JSON.parse(readSafe(skillJson) || '{}');
+  const declared = new Set((pkg.files || []).map(f => path.resolve(skillDir, f)));
+  const onDisk = new Set();
+
+  for (const entry of fs.readdirSync(skillDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!/\.(md|json|mjs|js)$/.test(entry.name)) continue;
+    onDisk.add(path.join(skillDir, entry.name));
+  }
+
+  for (const subDir of ['references', 'scripts', 'evals', 'assets']) {
+    const full = path.join(skillDir, subDir);
+    for (const f of walkDir(full, { include: ['.md', '.json', '.mjs', '.js', '.ts', '.py'] })) {
+      onDisk.add(f);
+    }
+  }
+
+  const undeclared = [...onDisk].filter(f => !declared.has(f)).map(f => path.relative(skillDir, f));
+  const missing = [...declared].filter(f => !onDisk.has(f)).map(f => path.relative(skillDir, f));
+  const status = (undeclared.length + missing.length) > 0 ? 'drift' : 'ok';
+  const findings = [
+    ...undeclared.map(f => finding('undeclared', `on disk but not in files[]: ${f}`, { path: f })),
+    ...missing.map(f => finding('missing', `in files[] but not on disk: ${f}`, { path: f })),
+  ];
+  return { axis: 'manifestEnforcement', axis_num: 1, status, findings, summary: `${undeclared.length} undeclared, ${missing.length} missing` };
+}
+
+function axis2_referenceGraph(ctx) {
+  const { skillDir, skillMd } = ctx;
+  const findings = [];
+  const content = readSafe(skillMd);
+  const links = extractMarkdownLinks(content, skillMd);
+  for (const { url, line, file } of links) {
+    const resolved = path.resolve(path.dirname(file), url);
+    if (!fs.existsSync(resolved)) {
+      const relFile = path.relative(skillDir, file);
+      const relResolved = path.relative(skillDir, resolved);
+      findings.push(finding('broken-link', `${relFile}:${line} → ${url} (resolves to ${relResolved}, not found)`, { file: relFile, line, url }));
+    }
+  }
+  return { axis: 'referenceGraph', axis_num: 2, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} broken link(s)` };
+}
+
+function axis3_capabilityMenuDrift(ctx) {
+  const { skillDir, skillMd } = ctx;
+  const content = readSafe(skillMd);
+  const sectionMatch = content.match(/##\s+§ColdStartTriage[\s\S]*?(?=\n##\s+|$)/);
+  if (!sectionMatch) {
+    return { axis: 'capabilityMenuDrift', axis_num: 3, status: 'ok', findings: [], summary: 'No §ColdStartTriage section found (skip)' };
+  }
+  const section = sectionMatch[0];
+  const links = extractMarkdownLinks(section, skillMd);
+  const barePaths = [...section.matchAll(/`(references\/[^`]+\.md)`/g)].map(m => m[1]);
+  const findings = [];
+  for (const { url, text } of links) {
+    if (!url.startsWith('references/') && !url.startsWith('../')) continue;
+    const resolved = path.resolve(skillDir, url);
+    if (!fs.existsSync(resolved)) findings.push(finding('missing-entry-ref', `Mode entry ref missing: [${text}](${url})`, { url }));
+  }
+  for (const p of barePaths) {
+    const resolved = path.join(skillDir, p);
+    if (!fs.existsSync(resolved)) findings.push(finding('missing-entry-ref', `Bare path in §ColdStartTriage not found: ${p}`, { url: p }));
+  }
+  return { axis: 'capabilityMenuDrift', axis_num: 3, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} missing entry-reference path(s)` };
+}
+
+function axis4_versionLiteralParity(ctx) {
+  const { skillMd, skillJson } = ctx;
+  const content = readSafe(skillMd);
+  const pkg = JSON.parse(readSafe(skillJson) || '{}');
+  const jsonVersion = pkg.version || null;
+  const findings = [];
+  if (!jsonVersion) {
+    findings.push(finding('no-version', 'skill.json has no version field'));
+    return { axis: 'versionLiteralParity', axis_num: 4, status: 'drift', findings, summary: 'no version in skill.json' };
+  }
+  const fm = parseFrontmatter(content);
+  if (fm.version && fm.version !== jsonVersion) {
+    findings.push(finding('frontmatter-drift', `SKILL.md frontmatter version: ${fm.version} != skill.json: ${jsonVersion}`));
+  }
+  const statusMatch = content.match(/##\s+§Status([\s\S]*?)(?=\n##\s+|$)/);
+  if (statusMatch) {
+    const versionRe = /\bv?(\d+\.\d+\.\d+)\b/g;
+    let m;
+    while ((m = versionRe.exec(statusMatch[1])) !== null) {
+      if (m[1] !== jsonVersion) findings.push(finding('status-section-stale', `§Status body contains version ${m[1]} != skill.json ${jsonVersion}`));
+    }
+  }
+  return { axis: 'versionLiteralParity', axis_num: 4, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: findings.length > 0 ? `${findings.length} version-literal mismatch(es)` : `all literals match ${jsonVersion}` };
+}
+
+function axis5_phaseLabelAbsence(ctx) {
+  const { skillMd } = ctx;
+  const content = readSafe(skillMd);
+  const lines = content.split('\n');
+  const findings = [];
+  const phaseRe = /\(Phase\s+\d+[\w\s—.]*\)|Phase\s+\d+\s*\(v\d+\.\d+\.\d+|Phase\s+\d+\s+references\s*\(planned\)/i;
+  for (let i = 0; i < lines.length; i++) {
+    if (phaseRe.test(lines[i])) findings.push(finding('phase-label', `Line ${i + 1}: stale phase annotation — ${lines[i].trim()}`, { line: i + 1 }));
+  }
+  return { axis: 'phaseLabelAbsence', axis_num: 5, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} stale phase label(s)` };
+}
+
+function axis6_fenceLeakDetection(ctx) {
+  const { skillMd } = ctx;
+  const content = readSafe(skillMd);
+  const lines = content.split('\n');
+  const findings = [];
+  let inFence = false;
+  let fenceLang = '';
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceOpen = line.match(/^```(\w*)/);
+    if (fenceOpen && !inFence) { inFence = true; fenceLang = fenceOpen[1].toLowerCase(); continue; }
+    if (inFence && line.startsWith('```') && !line.startsWith('````')) { inFence = false; fenceLang = ''; continue; }
+    if (inFence) {
+      if (['markdown', 'md', 'mdx'].includes(fenceLang)) continue;
+      if (/^#{2,3}\s/.test(line)) findings.push(finding('fence-leak', `Line ${i + 1}: heading inside \`\`\`${fenceLang}\`\`\` fence — ${line.trim()}`, { line: i + 1 }));
+    }
+  }
+  return { axis: 'fenceLeakDetection', axis_num: 6, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} fence-leak heading(s)` };
+}
+
+function axis7_contentCurrency(ctx) {
+  const { skillDir, skillJson } = ctx;
+  const pkg = JSON.parse(readSafe(skillJson) || '{}');
+  const declared = pkg.files || [];
+  const findings = [];
+  for (const relPath of declared) {
+    const full = path.resolve(skillDir, relPath);
+    if (!fs.existsSync(full)) findings.push(finding('missing-declared', `Declared in files[] but not on disk: ${relPath}`, { path: relPath }));
+  }
+  return { axis: 'contentCurrency', axis_num: 7, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} declared-but-missing file(s)` };
+}
+
+function axis8_cliHelperCurrency(ctx) {
+  const { skillDir, skillMd, repoRoot } = ctx;
+  const content = readSafe(skillMd);
+  const findings = [];
+  let pkgScripts = null;
+  if (repoRoot) {
+    try { pkgScripts = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+  }
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/(substrate.only|chat.ui.only)/i.test(line)) continue;
+    if (/^\s*(#|\/\/)/.test(line)) continue;
+    const npmRe = /`npm run ([\w:.-]+)`/g;
+    let m;
+    while ((m = npmRe.exec(line)) !== null) {
+      if (pkgScripts && !pkgScripts[m[1]]) findings.push(finding('missing-npm-script', `Line ${i + 1}: npm run ${m[1]} not found in package.json scripts`, { line: i + 1, script: m[1] }));
+    }
+    const nodeRe = /`node\s+(\.agents\/skills\/[^\s`]+|scripts\/[^\s`]+)`/g;
+    while ((m = nodeRe.exec(line)) !== null) {
+      const scriptPath = m[1];
+      const base = repoRoot || skillDir;
+      const resolved = path.resolve(base, scriptPath);
+      if (!fs.existsSync(resolved)) findings.push(finding('missing-script', `Line ${i + 1}: node ${scriptPath} — file not found`, { line: i + 1, scriptPath }));
+    }
+  }
+  return { axis: 'cliHelperCurrency', axis_num: 8, status: findings.length > 0 ? 'drift' : 'ok', findings, summary: `${findings.length} missing CLI helper(s)` };
+}
+
+// ─── Axis 9 — kit-specific bundle-roster currency ─────────────────────────────
+
+function axis9_bundleRosterCurrency() {
+  const content = read(SKILL_MD);
+  const declared = new Set((JSON.parse(read(SKILL_JSON) || '{}').files) || []);
+  const bundles = new Set();
+  const re = /`(references\/(?:patterns|flows)-[a-z0-9-]+\.md)`/g;
+  let m;
+  while ((m = re.exec(content)) !== null) bundles.add(m[1]);
+
+  const findings = [];
+  for (const b of [...bundles].sort()) {
+    const onDisk = fs.existsSync(path.join(SKILL_DIR, b));
+    if (!onDisk) {
+      findings.push({ type: 'bundle-missing-disk', message: `${b} advertised in a bundle map but not on disk` });
+    } else if (!declared.has(b)) {
+      findings.push({ type: 'bundle-undeclared', message: `${b} on disk + advertised but not in skill.json files[]` });
+    }
+  }
+  return {
+    axis: 'kitBundleRosterCurrency',
+    axis_num: 9,
+    status: findings.length > 0 ? 'drift' : 'ok',
+    findings,
+    summary: `${bundles.size} pattern/flow bundle(s) checked; ${findings.length} issue(s)`,
+  };
+}
+
+function formatResults(results) {
+  const lines = [];
+  for (const r of results) {
+    const icon = r.status === 'ok' ? '✓' : '✗';
+    lines.push(`${icon} ${r.axis}: ${r.summary}`);
+    if (r.status === 'drift' && r.findings.length > 0) {
+      for (const f of r.findings) lines.push(`    ${f.type}: ${f.message}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const ctx = { skillDir: SKILL_DIR, skillMd: SKILL_MD, skillJson: SKILL_JSON };
+  const universal = [
+    axis1_manifestEnforcement(ctx),
+    axis2_referenceGraph(ctx),
+    axis3_capabilityMenuDrift(ctx),
+    axis4_versionLiteralParity(ctx),
+    axis5_phaseLabelAbsence(ctx),
+    axis6_fenceLeakDetection(ctx),
+    axis7_contentCurrency(ctx),
+    axis8_cliHelperCurrency(ctx),
+  ];
+  const allResults = [...universal, axis9_bundleRosterCurrency()];
+  const driftCount = allResults.filter((r) => r.status === 'drift').length;
+
+  if (args.json) {
+    console.log(JSON.stringify({ results: allResults, driftCount }, null, 2));
+  } else {
+    console.log(`[audit-kit-roster] adia-ui-kit §SelfAudit — ${driftCount} drifting axis/axes`);
+    console.log(formatResults(allResults));
+    if (driftCount === 0) console.log('\n✓ All clean.');
+  }
+
+  if (args.strict && driftCount > 0) process.exit(1);
+}
+
+main();

package/skills/adia-ui-kit/scripts/changelog-archive.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// changelog-archive.mjs — keep CHANGELOG.md lean; preserve full history in a per-major archive set.
+//
+// THE SYSTEM: the live CHANGELOG.md holds only the most recent N entries (default 3);
+// every older entry lives in references/changelog-archive/CHANGELOG-v<major>.md (newest-first).
+// Idempotent + re-runnable: run it after each cut and it rolls the now-oldest live entry
+// into the archive. Re-running with nothing to roll is a no-op (only the archive index is
+// regenerated). Merge-by-version + semver-sort means an entry is never duplicated or lost.
+//
+// Usage (from the skill dir, or anywhere with --dir):
+//   node scripts/changelog-archive.mjs            # keep newest 3, archive the rest
+//   node scripts/changelog-archive.mjs --keep 5   # keep newest 5
+//   node scripts/changelog-archive.mjs --check    # report what WOULD change; exit 1 if live > keep
+//
+// Entry heading shape: `## <major>.<minor>.<patch> (date)`. Non-version `##` lines (e.g. a
+// "[Previously-unreleased …]" note) stay attached to the entry they sit under.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.dirname(SCRIPT_DIR);
+
+function parseArgs(argv) {
+  const a = { keep: 3, check: false, dir: SKILL_DIR };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--keep') a.keep = parseInt(argv[++i], 10);
+    else if (argv[i] === '--check') a.check = true;
+    else if (argv[i] === '--dir') a.dir = path.resolve(argv[++i]);
+  }
+  if (!Number.isInteger(a.keep) || a.keep < 1) { console.error('--keep must be a positive integer'); process.exit(2); }
+  return a;
+}
+
+const HEADING = /^## v?(\d+)\.(\d+)\.(\d+)\b/;
+const cmpDesc = (a, b) => b.M - a.M || b.m - a.m || b.p - a.p;
+
+// Split a changelog body into { preamble, entries[] }. Strips any trailing "## Archive"
+// index section first (it is always regenerated, never parsed as an entry).
+function parse(body) {
+  const archiveAt = body.search(/^## Archive\b/m);
+  if (archiveAt >= 0) body = body.slice(0, archiveAt).replace(/\s+$/, '') + '\n';
+  const lines = body.split('\n');
+  const idx = [];
+  for (let i = 0; i < lines.length; i++) if (HEADING.test(lines[i])) idx.push(i);
+  if (idx.length === 0) return { preamble: body.replace(/\s+$/, ''), entries: [] };
+  const preamble = lines.slice(0, idx[0]).join('\n').replace(/\s+$/, '');
+  const entries = idx.map((start, j) => {
+    const end = j + 1 < idx.length ? idx[j + 1] : lines.length;
+    const h = lines[start].match(HEADING);
+    return {
+      version: `${h[1]}.${h[2]}.${h[3]}`, major: h[1],
+      M: +h[1], m: +h[2], p: +h[3],
+      text: lines.slice(start, end).join('\n').replace(/\s+$/, ''),
+    };
+  });
+  return { preamble, entries };
+}
+
+function readEntries(file) {
+  if (!fs.existsSync(file)) return [];
+  return parse(fs.readFileSync(file, 'utf8')).entries;
+}
+
+function dedupe(entries) {
+  const seen = new Set(); const out = [];
+  for (const e of entries.sort(cmpDesc)) { if (seen.has(e.version)) continue; seen.add(e.version); out.push(e); }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const CHANGELOG = path.join(args.dir, 'CHANGELOG.md');
+  const ARCHIVE_DIR = path.join(args.dir, 'references/changelog-archive');
+  if (!fs.existsSync(CHANGELOG)) { console.error(`not found: ${CHANGELOG}`); process.exit(2); }
+
+  const { preamble, entries } = parse(fs.readFileSync(CHANGELOG, 'utf8'));
+  const keep = entries.slice(0, args.keep);
+  const toArchive = entries.slice(args.keep);
+
+  if (args.check) {
+    console.log(`[changelog-archive --check] ${entries.length} live entries; keep ${args.keep}; ${toArchive.length} over budget`);
+    process.exit(toArchive.length > 0 ? 1 : 0);
+  }
+
+  // Group entries-to-archive by major, merge with existing archive files, rewrite each.
+  fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
+  // Entries archived FROM CHANGELOG.md drop 2 dirs into references/changelog-archive/, so
+  // their skill-root-relative markdown links need `../../` prepended (the check-links depth
+  // bug caught on the kit v3.11.0 first cut). Already-archived entries re-read below are
+  // already corrected — reroot only the NEW ones, or the prefixes double up on re-runs.
+  const reroot = (text) => text.replace(/\]\((?!\.\.?\/|\/|https?:|#)([^)]+)\)/g, '](../../$1)');
+  const byMajor = {};
+  for (const e of toArchive) (byMajor[e.major] ||= []).push({ ...e, text: reroot(e.text) });
+
+  const written = [];
+  // Touch every major that has either new entries OR an existing archive file (to keep them current).
+  const majors = new Set([...Object.keys(byMajor), ...fs.readdirSync(ARCHIVE_DIR)
+    .map((f) => (f.match(/^CHANGELOG-v(\d+)\.md$/) || [])[1]).filter(Boolean)]);
+  for (const major of majors) {
+    const file = path.join(ARCHIVE_DIR, `CHANGELOG-v${major}.md`);
+    const merged = dedupe([...(byMajor[major] || []), ...readEntries(file)]);
+    if (merged.length === 0) continue;
+    const header = `# adia-ui-kit Changelog — v${major}.x archive\n\n` +
+      `> Historical entries rolled out of the live [\`CHANGELOG.md\`](../../CHANGELOG.md), which keeps only the most recent ${args.keep}. Newest-first.\n`;
+    fs.writeFileSync(file, `${header}\n${merged.map((e) => e.text).join('\n\n')}\n`);
+    written.push({ major, file, count: merged.length, range: `${merged[merged.length - 1].version} … ${merged[0].version}` });
+  }
+  written.sort((a, b) => b.major - a.major);
+
+  // Rebuild CHANGELOG.md: preamble + kept entries + archive index.
+  let out = `${preamble}\n\n${keep.map((e) => e.text).join('\n\n')}\n`;
+  if (written.length) {
+    out += `\n## Archive\n\nOlder entries live in a per-major archive set (kept out of this file to hold its always-on cost down):\n\n`;
+    for (const w of written) out += `- [\`references/changelog-archive/CHANGELOG-v${w.major}.md\`](references/changelog-archive/CHANGELOG-v${w.major}.md) — v${w.major}.x · ${w.count} entries (${w.range})\n`;
+  }
+  fs.writeFileSync(CHANGELOG, out);
+
+  const kb = (p) => (fs.statSync(p).size / 1024).toFixed(0);
+  console.log(`[changelog-archive] kept newest ${keep.length} in CHANGELOG.md (${kb(CHANGELOG)} KB); archived ${toArchive.length} entries:`);
+  for (const w of written) console.log(`  v${w.major}.x → ${path.relative(args.dir, w.file)} — ${w.count} entries (${w.range}), ${kb(w.file)} KB`);
+}
+
+main();