@adia-ai/adia-ui-forge 0.1.2

package/skills/adia-ui-release/scripts/audit-gate-roster.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// audit-gate-roster.mjs — §SelfAudit Axis 9 enforcement.
+//
+// Compares the `check:*` / `verify:*` / `smoke:*` / `test:*` scripts
+// declared in the target repo's `package.json` against the gate roster
+// documented in this skill's `references/gates-catalog.md`. Flags drift
+// in either direction:
+//   - Gates that exist in package.json but aren't documented (new
+//     gate added without catalog update).
+//   - Gates documented in the catalog but no longer in package.json
+//     (gate removed without catalog cleanup).
+//
+// Usage (run from the @adia-ai-style monorepo root):
+//   node audit-gate-roster.mjs
+//   node audit-gate-roster.mjs --json
+//   node audit-gate-roster.mjs --strict   # exit 1 on any drift
+//   node audit-gate-roster.mjs --repo /path/to/monorepo
+//
+// Path resolution: the gate catalog ships with the skill. It is resolved
+// via ${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-release/references/gates-catalog.md,
+// with a fallback relative to this script (../references/gates-catalog.md)
+// for when the plugin-root env var is not set.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+function parseArgs(argv) {
+  const args = { json: false, strict: false, repo: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--json') args.json = true;
+    else if (argv[i] === '--strict') args.strict = true;
+    else if (argv[i] === '--repo') args.repo = argv[++i];
+    else if (argv[i] === '-h' || argv[i] === '--help') {
+      console.log('Usage: node audit-gate-roster.mjs [--json] [--strict] [--repo <monorepo-root>]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+// The gate catalog is skill-owned (ships in references/). Resolve it via the
+// plugin root, falling back to a path relative to this script.
+function resolveCatalog() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (pluginRoot) {
+    const p = path.join(pluginRoot, 'skills/adia-ui-release/references/gates-catalog.md');
+    if (fs.existsSync(p)) return p;
+  }
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  return path.join(here, '..', 'references', 'gates-catalog.md');
+}
+
+// The catalog documents the gates the RELEASE FLOW runs — a curated set, NOT
+// every quality script in package.json (which has many check:/verify:/smoke:/
+// audit:/test: scripts, most of them component-authoring audits). Two universes:
+//
+//   - releaseGates (drives the UNDOCUMENTED check): the gates composed into the
+//     `npm run check` pre-flight aggregate PLUS the roster gates run directly in
+//     a cut (ROSTER_EXTRAS). A release-flow gate missing from the catalog is real
+//     drift worth flagging.
+//   - allScripts (drives the OBSOLETE check): every package.json script name. A
+//     documented gate that no longer exists ANYWHERE has been removed/renamed —
+//     real drift.
+//
+// This intentionally does NOT flag component-authoring `audit:*` scripts or
+// `test:*` runner scripts as "undocumented" — they are not release-flow gates
+// (audit:* are an authoring-side §SelfAudit domain, invoked indirectly via
+// `check:dogfood-audits`).
+const PREFLIGHT_AGGREGATE = 'check';
+const ROSTER_EXTRAS = [
+  'check:lockstep', 'verify:traits', 'smoke:engines', 'smoke:register-engine',
+  'test:a2ui', 'test:unit', 'dogfood:status',
+];
+
+function loadScripts(repo) {
+  const pkgJson = path.join(repo, 'package.json');
+  if (!fs.existsSync(pkgJson)) {
+    console.error(`error: ${pkgJson} not found (run from the monorepo root, or pass --repo)`);
+    process.exit(2);
+  }
+  return JSON.parse(fs.readFileSync(pkgJson, 'utf8')).scripts || {};
+}
+
+// Gates the release flow runs: every `npm run <gate>` composed into the
+// `npm run check` pre-flight aggregate, plus the roster gates run directly.
+function loadReleaseGates(scripts) {
+  const gates = new Set();
+  const agg = scripts[PREFLIGHT_AGGREGATE] || '';
+  const re = /\brun ([a-z][\w-]*(?::[\w-]+)+)/g;
+  let m;
+  while ((m = re.exec(agg)) !== null) gates.add(m[1]);
+  for (const g of ROSTER_EXTRAS) if (scripts[g]) gates.add(g);
+  return [...gates].sort();
+}
+
+function loadDocumentedGates(catalog) {
+  if (!fs.existsSync(catalog)) {
+    console.error(`error: ${catalog} not found`);
+    process.exit(2);
+  }
+  const txt = fs.readFileSync(catalog, 'utf8');
+  // Match ONLY heading-form gate documentation:
+  //   ### `npm run <gate-name>`
+  // NOT inline references to `npm run X` (which are typically
+  // recovery commands cited in another gate's body).
+  const matches = new Set();
+  // Match `### `npm run X`` (Category 1-9 row form) OR
+  //       `#### `npm run X`` (Category 10 stub form).
+  const re = /^#{3,4} `npm run ([a-z][\w-]*(?::[\w-]+)+)`(.*)$/gm;
+  let m;
+  while ((m = re.exec(txt)) !== null) {
+    // Skip explicitly forward-looking entries — a documented gate marked
+    // "(NOT YET SHIPPED — recommended)" is an intentional recommendation, not
+    // obsolete drift; it lives in the catalog before its script exists.
+    if (/NOT YET SHIPPED|recommended/i.test(m[2])) continue;
+    matches.add(m[1]);
+  }
+  return [...matches].sort();
+}
+
+// Suffix variants that count as documented if the base gate is documented.
+// Per the §Suffix variant convention in references/gates-catalog.md.
+const VARIANT_SUFFIXES = ['strict', 'fix', 'json', 'quiet', 'baseline', 'thinking', 'pro'];
+
+function isCovered(gate, documentedSet) {
+  if (documentedSet.has(gate)) return true;
+  // Strip a single trailing variant suffix and check the base.
+  const lastColon = gate.lastIndexOf(':');
+  if (lastColon > 0) {
+    const suffix = gate.slice(lastColon + 1);
+    const base = gate.slice(0, lastColon);
+    if (VARIANT_SUFFIXES.includes(suffix) && documentedSet.has(base)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function diff(releaseGates, allScripts, documented) {
+  const allSet = new Set(allScripts);
+  const documentedSet = new Set(documented);
+  return {
+    // Release-flow gate not in the catalog → document it.
+    undocumented: releaseGates.filter((g) => !isCovered(g, documentedSet)),
+    // Documented gate whose script no longer exists anywhere → remove the row.
+    obsolete: documented.filter((g) => !allSet.has(g)),
+    both: releaseGates.filter((g) => isCovered(g, documentedSet)),
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const catalog = resolveCatalog();
+  const scripts = loadScripts(args.repo);
+  const releaseGates = loadReleaseGates(scripts);
+  const allScripts = Object.keys(scripts);
+  const documented = loadDocumentedGates(catalog);
+  const d = diff(releaseGates, allScripts, documented);
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      releaseGates: releaseGates.length,
+      documented: documented.length,
+      both: d.both.length,
+      undocumented: d.undocumented,
+      obsolete: d.obsolete,
+    }, null, 2));
+  } else {
+    console.log(`[audit-gate-roster] adia-ui-release §SelfAudit Axis 9`);
+    console.log(`  release-flow gates (check + roster): ${releaseGates.length}`);
+    console.log(`  documented in gates-catalog.md:      ${documented.length}`);
+    console.log(`  both:                                ${d.both.length}`);
+    console.log();
+    if (d.undocumented.length === 0 && d.obsolete.length === 0) {
+      console.log('  Clean — gate roster in sync.');
+    } else {
+      if (d.undocumented.length > 0) {
+        console.log(`  Undocumented gates (${d.undocumented.length}) — exist in package.json but NOT in catalog:`);
+        for (const g of d.undocumented) console.log(`      ${g}`);
+        console.log(`    -> add a row in references/gates-catalog.md describing this gate.`);
+      }
+      if (d.obsolete.length > 0) {
+        console.log(`  Obsolete catalog entries (${d.obsolete.length}) — in catalog but NO LONGER in package.json:`);
+        for (const g of d.obsolete) console.log(`      ${g}`);
+        console.log(`    -> remove the rows from references/gates-catalog.md.`);
+      }
+    }
+  }
+
+  if (args.strict && (d.undocumented.length > 0 || d.obsolete.length > 0)) {
+    process.exit(1);
+  }
+}
+
+main();

package/skills/adia-ui-release/scripts/bump.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// bump.mjs — bump 9 @adia-ai/* package.json from --from to --to.
+//
+// Idempotent. Stops on the first mismatch (a package not at --from) so
+// you can investigate before any mutation lands.
+//
+// Usage:
+//   node bump.mjs --from 0.6.20 --to 0.6.21
+//   node bump.mjs --from 0.6.20 --to 0.6.21 --dry
+//
+// Phase 1 of the adia-ui-release skill. Replaces the /tmp/vXXX-prep.mjs
+// improvisation pattern from the v0.6.13 → v0.6.21 cycles.
+//
+// Exits:
+//   0  — all 9 bumped successfully (or --dry succeeded)
+//   1  — at least one package not at --from (no mutation)
+//   2  — bad args / file I/O error
+//   3  — partial mutation (shouldn't happen if --from validation passes)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const PACKAGES = [
+  'packages/web-components',
+  'packages/web-modules',
+  'packages/llm',
+  'packages/a2ui/compose',
+  'packages/a2ui/corpus',
+  'packages/a2ui/mcp',
+  'packages/a2ui/retrieval',
+  'packages/a2ui/runtime',
+  'packages/a2ui/validator',
+];
+
+function parseArgs(argv) {
+  const args = { from: null, to: null, dry: false, repo: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--from') args.from = argv[++i];
+    else if (argv[i] === '--to') args.to = argv[++i];
+    else if (argv[i] === '--dry') args.dry = true;
+    else if (argv[i] === '--repo') args.repo = argv[++i];
+    else if (argv[i] === '-h' || argv[i] === '--help') {
+      console.log('Usage: node bump.mjs --from X.Y.Z --to X.Y.Z+1 [--dry] [--repo <path>]');
+      process.exit(0);
+    }
+  }
+  if (!args.from || !args.to) {
+    console.error('error: both --from and --to are required (e.g. --from 0.6.20 --to 0.6.21)');
+    process.exit(2);
+  }
+  if (!/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(args.from) || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(args.to)) {
+    console.error('error: --from and --to must be semver (e.g. 0.6.21 or 0.6.22-rc.1)');
+    process.exit(2);
+  }
+  return args;
+}
+
+function loadPackageJsons(repo) {
+  const result = [];
+  for (const pkg of PACKAGES) {
+    const p = path.join(repo, pkg, 'package.json');
+    if (!fs.existsSync(p)) {
+      console.error(`error: missing ${p}`);
+      process.exit(2);
+    }
+    const txt = fs.readFileSync(p, 'utf8');
+    const json = JSON.parse(txt);
+    result.push({ pkg, path: p, txt, version: json.version });
+  }
+  return result;
+}
+
+function validateAllAtFrom(packages, from) {
+  const wrong = packages.filter((p) => p.version !== from);
+  if (wrong.length > 0) {
+    console.error(`error: ${wrong.length}/${packages.length} package(s) NOT at ${from}:`);
+    for (const w of wrong) {
+      console.error(`  ${w.pkg}: ${w.version}`);
+    }
+    return false;
+  }
+  return true;
+}
+
+function bumpAll(packages, from, to, dry) {
+  const FROM_PATTERN = new RegExp(`"version":\\s*"${from.replace(/\./g, '\\.')}"`);
+  const TO_LITERAL = `"version": "${to}"`;
+  let bumped = 0;
+  for (const p of packages) {
+    const out = p.txt.replace(FROM_PATTERN, TO_LITERAL);
+    if (out === p.txt) {
+      console.error(`error: ${p.pkg} — regex did not match (corrupted package.json?)`);
+      return -1;
+    }
+    if (!dry) fs.writeFileSync(p.path, out);
+    bumped++;
+    console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}: ${from} → ${to}`);
+  }
+  return bumped;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const packages = loadPackageJsons(args.repo);
+  if (!validateAllAtFrom(packages, args.from)) process.exit(1);
+  const bumped = bumpAll(packages, args.from, args.to, args.dry);
+  if (bumped < 0) process.exit(3);
+  console.log(`\n[bump] ${bumped}/9 ${args.dry ? '(dry — no files written)' : 'bumped'}`);
+  if (!args.dry) {
+    console.log(`\n[next] regenerate the lockfile:`);
+    console.log(`  npm install --package-lock-only --no-audit --no-fund`);
+    console.log(`\n[next] verify lockstep:`);
+    console.log(`  npm run check:lockstep`);
+  }
+}
+
+main();

package/skills/adia-ui-release/scripts/dispatch-publish.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// dispatch-publish.mjs — dispatch the 9 publish workflows for a
+// version, optionally waiting for an earlier batch to settle first.
+//
+// Usage:
+//   # Single-version dispatch:
+//   node dispatch-publish.mjs --version 0.6.22
+//
+//   # Batch push: dispatch v0.6.21 first, wait, then v0.6.22:
+//   node dispatch-publish.mjs --version 0.6.21
+//   # ... wait for completion ...
+//   node dispatch-publish.mjs --version 0.6.22 --after 0.6.21
+//
+//   # Dry mode:
+//   node dispatch-publish.mjs --version 0.6.22 --dry
+//
+// Phase 2 of the adia-ui-release skill. Mechanizes the dispatch loop
+// + handles the npm-latest ordering rule for batch pushes.
+
+import { execSync } from 'node:child_process';
+import process from 'node:process';
+import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+
+// Instance data — fork-configurable. The npm scope the 9 packages publish under.
+// Default preserves @adia-ai behavior; override via --scope or $ADIA_NPM_SCOPE.
+const DEFAULT_SCOPE = '@adia-ai';
+
+const PACKAGES = [
+  'web-components',
+  'web-modules',
+  'llm',
+  'a2ui-runtime',
+  'a2ui-compose',
+  'a2ui-corpus',
+  'a2ui-mcp',
+  'a2ui-retrieval',
+  'a2ui-validator',
+];
+
+function parseArgs(argv) {
+  const args = {
+    version: null, after: null, dry: false, sleepBefore: 4,
+    scope: process.env.ADIA_NPM_SCOPE || DEFAULT_SCOPE,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--version') args.version = argv[++i];
+    else if (k === '--after') args.after = argv[++i];
+    else if (k === '--dry') args.dry = true;
+    else if (k === '--sleep-before') args.sleepBefore = parseInt(argv[++i], 10);
+    else if (k === '--scope') args.scope = argv[++i];
+    else if (k === '-h' || k === '--help') {
+      console.log('Usage: node dispatch-publish.mjs --version X.Y.Z [--after X.Y.Z-1] [--dry] [--sleep-before <seconds>] [--scope @org]');
+      console.log('');
+      console.log('--after  Verify npm latest is at the given version before dispatching this one.');
+      console.log('         Used in batch push to ensure publish ordering.');
+      console.log(`--scope  npm scope the packages publish under (default: ${DEFAULT_SCOPE};`);
+      console.log('         or set $ADIA_NPM_SCOPE). The --after npm-latest check uses this scope.');
+      process.exit(0);
+    }
+  }
+  if (!args.version) {
+    console.error('error: --version is required');
+    process.exit(2);
+  }
+  return args;
+}
+
+function run(cmd, dry) {
+  if (dry) {
+    console.log(`  [dry] ${cmd}`);
+    return '';
+  }
+  return execSync(cmd, { encoding: 'utf8' });
+}
+
+function checkAfter(afterVersion, scope) {
+  console.log(`Checking npm latest is at ${afterVersion} before dispatching...`);
+  try {
+    const latest = execSync(`npm view ${scope}/web-components dist-tags.latest`, { encoding: 'utf8' }).trim();
+    if (latest !== afterVersion) {
+      console.error(`error: npm ${scope}/web-components latest is '${latest}', expected '${afterVersion}'`);
+      console.error('  This means the previous batch hasn\'t completed publishing.');
+      console.error('  Wait for the previous --version cycle to settle, then re-run.');
+      process.exit(1);
+    }
+    console.log(`  ✓ npm latest = ${latest}`);
+  } catch (e) {
+    console.error(`error: failed to query npm latest: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+function dispatch(pkg, version, dry) {
+  const ref = `${pkg}-v${version}`;
+  const cmd = `gh workflow run "publish-${pkg}.yml" --ref "${ref}"`;
+  try {
+    const out = run(cmd, dry);
+    if (!dry && out) {
+      const url = out.split('\n').find((l) => l.startsWith('http')) || '';
+      console.log(`  ✓ dispatched ${pkg} (${url.trim()})`);
+    } else if (dry) {
+      // already printed by run()
+    } else {
+      console.log(`  ✓ dispatched ${pkg}`);
+    }
+    return true;
+  } catch (e) {
+    console.error(`  ✗ ERROR ${pkg}: ${e.message}`);
+    return false;
+  }
+}
+
+async function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // Fail-fast guard: refuse to run npm/gh against a non-monorepo directory.
+  assertMonorepoRoot(process.cwd());
+  if (args.after) checkAfter(args.after, args.scope);
+
+  if (args.sleepBefore > 0 && !args.dry) {
+    console.log(`Sleeping ${args.sleepBefore}s to let GH index the new tags...`);
+    await sleep(args.sleepBefore * 1000);
+  }
+
+  console.log(`Dispatching 9 publish workflows for v${args.version}:`);
+  let succeeded = 0;
+  for (const pkg of PACKAGES) {
+    if (dispatch(pkg, args.version, args.dry)) succeeded++;
+  }
+  console.log(`\n[dispatch] ${succeeded}/${PACKAGES.length} dispatched ${args.dry ? '(dry)' : ''}`);
+
+  if (!args.dry) {
+    console.log(`\n[next] wait for workflows to settle:`);
+    console.log(`  until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`);
+    console.log(`\n[next] verify all 9 succeeded:`);
+    console.log(`  for pkg in ${PACKAGES.join(' ')}; do`);
+    console.log(`    gh run list --workflow=publish-$pkg.yml --limit 1 --json conclusion -q '.[0].conclusion'`);
+    console.log(`  done`);
+  }
+
+  if (succeeded !== PACKAGES.length) process.exit(1);
+}
+
+main().catch((e) => {
+  console.error(`error: ${e.message}`);
+  process.exit(1);
+});

package/skills/adia-ui-release/scripts/insert-stub.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// insert-stub.mjs — insert the ride-along lockstep stub block into N
+// package CHANGELOGs above the previous version's heading.
+//
+// Idempotent. Stops if any target already has the [vX.Y.Z] heading.
+//
+// Usage:
+//   node insert-stub.mjs --version 0.6.22 --date 2026-05-22 \
+//     --substantive "<one-line summary>" \
+//     --xref "packages/web-modules/CHANGELOG.md#0622--2026-05-22" \
+//     --previous-version 0.6.21 \
+//     --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
+//
+// Phase 2 of the adia-ui-release skill. Replaces the inline stub-
+// insertion pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21
+// cycles.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+function parseArgs(argv) {
+  const args = {
+    version: null,
+    date: null,
+    substantive: null,
+    xref: null,
+    previous: null,
+    packages: null,
+    dry: false,
+    repo: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--version') args.version = argv[++i];
+    else if (k === '--date') args.date = argv[++i];
+    else if (k === '--substantive') args.substantive = argv[++i];
+    else if (k === '--xref') args.xref = argv[++i];
+    else if (k === '--previous-version') args.previous = argv[++i];
+    else if (k === '--packages') args.packages = argv[++i].split(',').map((s) => s.trim());
+    else if (k === '--dry') args.dry = true;
+    else if (k === '--repo') args.repo = argv[++i];
+    else if (k === '-h' || k === '--help') {
+      console.log('Usage: node insert-stub.mjs --version X.Y.Z --date YYYY-MM-DD --substantive "..." --xref "..." --previous-version X.Y.Z-1 --packages comma,list [--dry] [--repo <path>]');
+      process.exit(0);
+    }
+  }
+  for (const [k, v] of Object.entries(args)) {
+    if (v === null && k !== 'dry') {
+      console.error(`error: --${k.replace(/([A-Z])/g, '-$1').toLowerCase()} is required`);
+      process.exit(2);
+    }
+  }
+  if (!/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(args.version)) {
+    console.error('error: --version must be semver');
+    process.exit(2);
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) {
+    console.error('error: --date must be YYYY-MM-DD');
+    process.exit(2);
+  }
+  return args;
+}
+
+function buildStub(version, date, substantive, xref) {
+  return `## [${version}] — ${date}
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 9-package version coherence enforced by \`scripts/release/check-lockstep.mjs\`. Substantive v${version} work shipped in ${substantive}. See \`${xref}\` for details.
+
+`;
+}
+
+function insertStub(repo, pkg, anchor, stubBlock, version, dry) {
+  const p = path.join(repo, 'packages', pkg, 'CHANGELOG.md');
+  if (!fs.existsSync(p)) {
+    console.error(`  ERROR ${pkg} — CHANGELOG.md not found at ${p}`);
+    return 'missing';
+  }
+  const txt = fs.readFileSync(p, 'utf8');
+  if (txt.includes(`## [${version}]`)) {
+    console.error(`  ERROR ${pkg} — already has [${version}] heading`);
+    return 'already-present';
+  }
+  if (!txt.includes(anchor)) {
+    console.error(`  ERROR ${pkg} — anchor '${anchor}' not found`);
+    return 'no-anchor';
+  }
+  const out = txt.replace(anchor, stubBlock + anchor);
+  if (!dry) fs.writeFileSync(p, out);
+  console.log(`  ${dry ? '[dry] ' : ''}stub inserted: ${pkg}`);
+  return 'inserted';
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // Anchor — find this in each CHANGELOG, insert ABOVE it.
+  // Read previous date from the actual anchor's line (auto-detect) — we
+  // only know the previous version, not the date. So we look for any
+  // line matching `## [<previous>] — `.
+  const PREV_HEADING_RE = new RegExp(`^## \\[${args.previous.replace(/\./g, '\\.')}\\] — \\d{4}-\\d{2}-\\d{2}$`, 'm');
+  const stubBlock = buildStub(args.version, args.date, args.substantive, args.xref);
+  const results = args.packages.map((pkg) => {
+    const p = path.join(args.repo, 'packages', pkg, 'CHANGELOG.md');
+    if (!fs.existsSync(p)) {
+      console.error(`  ERROR ${pkg} — not found`);
+      return 'missing';
+    }
+    const txt = fs.readFileSync(p, 'utf8');
+    const m = txt.match(PREV_HEADING_RE);
+    if (!m) {
+      console.error(`  ERROR ${pkg} — no '## [${args.previous}] — YYYY-MM-DD' heading found`);
+      return 'no-anchor';
+    }
+    const anchor = m[0];
+    return insertStub(args.repo, pkg, anchor, stubBlock, args.version, args.dry);
+  });
+  const inserted = results.filter((r) => r === 'inserted').length;
+  const failed = results.filter((r) => r !== 'inserted').length;
+  console.log(`\n[insert-stub] ${inserted}/${args.packages.length} ${args.dry ? '(dry)' : 'inserted'}`);
+  if (failed > 0) {
+    console.error(`[insert-stub] ${failed} target(s) failed — see ERRORs above`);
+    process.exit(1);
+  }
+}
+
+main();