@opengsd/gsd-core 1.2.0 → 1.3.0

package/scripts/lint-test-file-count.cjs

@@ -2,24 +2,27 @@
 /**
  * lint-test-file-count.cjs — max 2 test files per production module.
  *
- * Scans sdk/src/query/, sdk/src/, get-shit-done/bin/lib/, bin/ for production
+ * Scans sdk/src/query/, sdk/src/, gsd-core/bin/lib/, bin/ for production
  * modules, then counts matching test files in tests/ and sdk/src (recursive). Cap is 2
- * (primary + one integration). Over-limit clusters must be in the allowlist at
- * their frozen count (ratchet: may only decrease). --json emits structured output.
+ * (primary + one integration). Over-limit clusters must be in the allowlist with the
+ * EXACT set of test filenames grandfathered (identity ratchet via allowlist-ratchet.cjs).
+ * Adding a new test file to a capped module is a novel offender; removing one requires
+ * pruning the allowlist entry (stale). --json emits structured output.
  *
  * Verdicts: OK_UNDER_LIMIT | OK_IN_ALLOWLIST | FAIL_EXCEEDS_LIMIT |
- *           FAIL_EXCEEDS_ALLOWLIST | HINT_CAN_REMOVE_FROM_ALLOWLIST
+ *           FAIL_NOVEL_FILES | FAIL_STALE_ALLOWLIST
  */
 'use strict';
 
 const fs   = require('fs');
 const path = require('path');
+const { assertWithinAllowlist } = require('./lib/allowlist-ratchet.cjs');
 
 const ROOT = path.join(__dirname, '..');
 const PROD_DIRS = [
   path.join(ROOT, 'sdk', 'src', 'query'),
   path.join(ROOT, 'sdk', 'src'),
-  path.join(ROOT, 'get-shit-done', 'bin', 'lib'),
+  path.join(ROOT, 'gsd-core', 'bin', 'lib'),
   path.join(ROOT, 'bin'),
 ];
 const TEST_DIRS = [
@@ -30,11 +33,11 @@ const ALLOWLIST_PATH = path.join(__dirname, 'lint-test-file-count.allowlist.json
 const MAX_FILES = 2;
 
 const Verdict = Object.freeze({
-  OK_UNDER_LIMIT:                 'OK_UNDER_LIMIT',
-  OK_IN_ALLOWLIST:                'OK_IN_ALLOWLIST',
-  FAIL_EXCEEDS_LIMIT:             'FAIL_EXCEEDS_LIMIT',
-  FAIL_EXCEEDS_ALLOWLIST:         'FAIL_EXCEEDS_ALLOWLIST',
-  HINT_CAN_REMOVE_FROM_ALLOWLIST: 'HINT_CAN_REMOVE_FROM_ALLOWLIST',
+  OK_UNDER_LIMIT:       'OK_UNDER_LIMIT',
+  OK_IN_ALLOWLIST:      'OK_IN_ALLOWLIST',
+  FAIL_EXCEEDS_LIMIT:   'FAIL_EXCEEDS_LIMIT',
+  FAIL_NOVEL_FILES:     'FAIL_NOVEL_FILES',
+  FAIL_STALE_ALLOWLIST: 'FAIL_STALE_ALLOWLIST',
 });
 
 function isTestFile(name) {
@@ -120,17 +123,62 @@ function loadAllowlist() {
   catch (_) { return {}; }
 }
 
+/**
+ * Evaluate one module's test files against the allowlist.
+ *
+ * For modules under the default cap (≤ MAX_FILES): simple count check.
+ * For modules with an allowlist entry: identity check via assertWithinAllowlist.
+ *   - count now ≤ MAX_FILES → FAIL_STALE_ALLOWLIST (all known files are stale; prune entry)
+ *   - novel files (in current but not in known) → FAIL_NOVEL_FILES
+ *   - stale files (in known but not in current) → FAIL_STALE_ALLOWLIST
+ *   - exact match → OK_IN_ALLOWLIST
+ * For modules over the cap with no allowlist entry: FAIL_EXCEEDS_LIMIT.
+ *
+ * Returns { verdict, prefix, count, knownFiles, novel, stale, files }
+ */
 function evaluateLint({ prefix, testFiles, allowlist }) {
   const count = testFiles.length;
   const entry = allowlist[prefix];
-  const ceiling = entry ? entry.current : null;
+  const currentNames = testFiles.map(f => path.basename(f));
+
   if (entry !== undefined) {
-    if (count <= MAX_FILES)    return { verdict: Verdict.HINT_CAN_REMOVE_FROM_ALLOWLIST, prefix, count, ceiling, files: testFiles };
-    if (count <= ceiling)      return { verdict: Verdict.OK_IN_ALLOWLIST,                prefix, count, ceiling, files: testFiles };
-    return                            { verdict: Verdict.FAIL_EXCEEDS_ALLOWLIST,          prefix, count, ceiling, files: testFiles };
+    const knownFiles = Array.isArray(entry.files) ? entry.files : [];
+    // If the module is now at or under the default cap, the entire allowlist entry is
+    // stale and must be removed — this is a ratchet-DOWN failure, not a hint.
+    // All known files are stale (the whole entry can go).
+    if (count <= MAX_FILES) {
+      return {
+        verdict: Verdict.FAIL_STALE_ALLOWLIST,
+        prefix, count,
+        knownFiles,
+        novel: [],
+        stale: knownFiles.slice().sort(),
+        files: testFiles,
+      };
+    }
+    // Identity check via assertWithinAllowlist
+    const messages = [];
+    const { novel, stale } = assertWithinAllowlist({
+      label: prefix,
+      current: currentNames,
+      known: knownFiles,
+      fail: (msg) => messages.push(msg),
+      pruneHint: 'scripts/lint-test-file-count.allowlist.json',
+    });
+
+    if (novel.length > 0) {
+      return { verdict: Verdict.FAIL_NOVEL_FILES,     prefix, count, knownFiles, novel, stale, files: testFiles };
+    }
+    if (stale.length > 0) {
+      return { verdict: Verdict.FAIL_STALE_ALLOWLIST, prefix, count, knownFiles, novel, stale, files: testFiles };
+    }
+    return { verdict: Verdict.OK_IN_ALLOWLIST,        prefix, count, knownFiles, novel: [], stale: [], files: testFiles };
+  }
+
+  if (count <= MAX_FILES) {
+    return { verdict: Verdict.OK_UNDER_LIMIT,    prefix, count, knownFiles: null, novel: [], stale: [], files: testFiles };
   }
-  if (count <= MAX_FILES) return { verdict: Verdict.OK_UNDER_LIMIT,    prefix, count, ceiling: null, files: testFiles };
-  return                         { verdict: Verdict.FAIL_EXCEEDS_LIMIT, prefix, count, ceiling: null, files: testFiles };
+  return   { verdict: Verdict.FAIL_EXCEEDS_LIMIT, prefix, count, knownFiles: null, novel: [], stale: [], files: testFiles };
 }
 
 function run() {
@@ -147,35 +195,42 @@ function run() {
   }
 
   const failures = results.filter(r =>
-    r.verdict === Verdict.FAIL_EXCEEDS_LIMIT || r.verdict === Verdict.FAIL_EXCEEDS_ALLOWLIST);
-  const hints = results.filter(r => r.verdict === Verdict.HINT_CAN_REMOVE_FROM_ALLOWLIST);
+    r.verdict === Verdict.FAIL_EXCEEDS_LIMIT ||
+    r.verdict === Verdict.FAIL_NOVEL_FILES ||
+    r.verdict === Verdict.FAIL_STALE_ALLOWLIST);
 
   if (jsonMode) {
-    console.log(JSON.stringify({ ok: failures.length === 0, results, failures, hints }, null, 2));
+    console.log(JSON.stringify({ ok: failures.length === 0, results, failures, hints: [] }, null, 2));
     process.exit(failures.length > 0 ? 1 : 0);
   }
 
   if (failures.length === 0) {
     const inAllowlist = results.filter(r => r.verdict === Verdict.OK_IN_ALLOWLIST).length;
     console.log(`ok lint-test-file-count: ${results.length} module(s) checked, 0 failures` +
-      (inAllowlist > 0 ? `, ${inAllowlist} allowlisted` : '') +
-      (hints.length > 0 ? `, ${hints.length} hint(s)` : ''));
-    for (const h of hints) {
-      console.log(`  hint: "${h.prefix}" is allowlisted at ${h.ceiling} but now has ${h.count} — remove from allowlist`);
-    }
+      (inAllowlist > 0 ? `, ${inAllowlist} allowlisted` : ''));
     process.exit(0);
   }
 
   process.stderr.write(`\nERROR lint-test-file-count: ${failures.length} module(s) exceed the test-file limit\n\n`);
   for (const f of failures) {
-    const tag = f.verdict === Verdict.FAIL_EXCEEDS_LIMIT
-      ? `${f.count} files (limit ${MAX_FILES})`
-      : `${f.count} files (allowlist ceiling ${f.ceiling})`;
-    process.stderr.write(`  ${f.prefix}: ${tag}\n`);
-    for (const tf of f.files) process.stderr.write(`    ${path.relative(ROOT, tf)}\n`);
+    if (f.verdict === Verdict.FAIL_EXCEEDS_LIMIT) {
+      process.stderr.write(`  ${f.prefix}: ${f.count} files (limit ${MAX_FILES}) — not in allowlist\n`);
+      for (const tf of f.files) process.stderr.write(`    ${path.relative(ROOT, tf)}\n`);
+    } else if (f.verdict === Verdict.FAIL_NOVEL_FILES) {
+      process.stderr.write(`  ${f.prefix}: ${f.novel.length} NEW test file(s) not in allowlist\n`);
+      for (const n of f.novel) process.stderr.write(`    + ${n}\n`);
+    } else if (f.verdict === Verdict.FAIL_STALE_ALLOWLIST) {
+      if (f.count <= MAX_FILES) {
+        const staleList = f.stale.join(', ');
+        process.stderr.write(`  "${f.prefix}": now at ${f.count} file(s) (≤ ${MAX_FILES}) — remove its entry from the allowlist (stale: ${staleList})\n`);
+      } else {
+        process.stderr.write(`  ${f.prefix}: ${f.stale.length} allowlisted file(s) no longer present — prune allowlist\n`);
+        for (const s of f.stale) process.stderr.write(`    - ${s}\n`);
+      }
+    }
   }
   process.stderr.write('\nFix: consolidate test files per module (one primary + one integration).\n');
-  process.stderr.write('Or add the module to scripts/lint-test-file-count.allowlist.json with PR justification.\n\n');
+  process.stderr.write('Or update scripts/lint-test-file-count.allowlist.json with PR justification.\n\n');
   process.exit(1);
 }
 

package/scripts/mutation-matrix.cjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/mutation-matrix.cjs
+ *
+ * Single source of truth for the ADR-457 Stryker mutation gate dynamic matrix.
+ *
+ * Computes which covered modules changed vs a base ref and emits a GitHub
+ * Actions matrix JSON so CI can run one Stryker shard per changed module in
+ * parallel rather than a single serial run over all modules.
+ *
+ * Usage:
+ *   node scripts/mutation-matrix.cjs --base origin/next
+ *   printf 'src/config-schema.cts\n' | node scripts/mutation-matrix.cjs
+ *   node scripts/mutation-matrix.cjs --base origin/next --print
+ *
+ * Output (stdout, default): JSON object
+ *   {
+ *     "has_work": "true"|"false",
+ *     "matrix": {
+ *       "include": [
+ *         { "name": "<module>", "mutate": "gsd-core/bin/lib/<module>.cjs", "tests": "<space-joined test files>" },
+ *         ...
+ *       ]
+ *     }
+ *   }
+ *
+ * Exit codes: 0 always (empty matrix is not an error, has_work "false").
+ */
+
+const { execFileSync } = require('child_process');
+const { readFileSync } = require('fs');
+
+// ── Single source of truth: covered modules ───────────────────────────────────
+// Each entry: { cjs: '<built artifact>', tests: ['tests/...', ...] }
+// A module is "covered" iff its tests are wired into the Stryker command runner
+// (stryker.config.mjs commandRunner.command). Mutating an uncovered module can
+// only ever produce survived mutants — so we scope strictly to these 6.
+const COVERED = {
+  'context-utilization': {
+    cjs: 'gsd-core/bin/lib/context-utilization.cjs',
+    tests: [
+      'tests/context-utilization.property.test.cjs',
+    ],
+  },
+  'prompt-budget': {
+    cjs: 'gsd-core/bin/lib/prompt-budget.cjs',
+    tests: [
+      'tests/prompt-budget.property.test.cjs',
+      'tests/prompt-budget.unit.test.cjs',
+    ],
+  },
+  frontmatter: {
+    cjs: 'gsd-core/bin/lib/frontmatter.cjs',
+    tests: [
+      'tests/frontmatter.property.test.cjs',
+      'tests/frontmatter.unit.test.cjs',
+    ],
+  },
+  'adr-parser': {
+    cjs: 'gsd-core/bin/lib/adr-parser.cjs',
+    tests: [
+      'tests/adr-parser.property.test.cjs',
+      'tests/adr-parser.test.cjs',
+      'tests/adr-parser.unit.test.cjs',
+    ],
+  },
+  'config-schema': {
+    cjs: 'gsd-core/bin/lib/config-schema.cjs',
+    tests: [
+      'tests/config-schema.property.test.cjs',
+    ],
+  },
+  'active-workstream-store': {
+    cjs: 'gsd-core/bin/lib/active-workstream-store.cjs',
+    tests: [
+      'tests/active-workstream-store.test.cjs',
+      'tests/active-workstream-store.unit.test.cjs',
+    ],
+  },
+};
+
+// ── Files that, when changed, invalidate ALL modules ─────────────────────────
+// Changes to the Stryker config, this script itself, or any covered test file
+// affect all mutation scores and must force a full re-run.
+const GLOBAL_TRIGGERS = new Set([
+  'stryker.config.mjs',
+  'scripts/mutation-matrix.cjs',
+]);
+
+// Also flag all test files that belong to any covered module as global triggers.
+for (const mod of Object.values(COVERED)) {
+  for (const t of mod.tests) {
+    GLOBAL_TRIGGERS.add(t);
+  }
+}
+
+// ── Argument parsing ──────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const out = { base: null, print: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--base') {
+      out.base = argv[++i];
+      if (!out.base || out.base.startsWith('--')) {
+        throw new Error('--base requires a value');
+      }
+    } else if (arg.startsWith('--base=')) {
+      out.base = arg.slice('--base='.length);
+      if (!out.base) throw new Error('--base requires a value');
+    } else if (arg === '--print') {
+      out.print = true;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log([
+        'Usage:',
+        '  node scripts/mutation-matrix.cjs --base <ref> [--print]',
+        '  printf "src/foo.cts\\n" | node scripts/mutation-matrix.cjs [--print]',
+        '',
+        'Options:',
+        '  --base <ref>   Git ref to diff against (default: origin/${GITHUB_BASE_REF:-next})',
+        '  --print        Human-readable output instead of JSON',
+      ].join('\n'));
+      process.exit(0);
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return out;
+}
+
+// ── Changed-file resolution ───────────────────────────────────────────────────
+function resolveChangedFiles(args) {
+  // When --base is provided, always use git diff (regardless of stdin).
+  // When --base is absent AND stdin is not a TTY (isTTY is falsy / undefined),
+  // read a newline-delimited file list from stdin.
+  if (!args.base && process.stdin.isTTY !== true) {
+    const raw = readFileSync(process.stdin.fd, 'utf8');
+    return raw.split('\n').map(l => l.trim()).filter(Boolean);
+  }
+
+  // Otherwise (--base given, or stdin is a real TTY), diff against the base ref.
+  const defaultBase = `origin/${process.env.GITHUB_BASE_REF || 'next'}`;
+  const base = args.base || defaultBase;
+  const stdout = execFileSync('git', ['diff', '--name-only', `${base}...HEAD`], {
+    encoding: 'utf8',
+  });
+  return stdout.split('\n').map(l => l.trim()).filter(Boolean);
+}
+
+// ── Module classification ─────────────────────────────────────────────────────
+function computeMatrix(changedFiles) {
+  // Check for global triggers first — if any hit, include every covered module.
+  const allModuleNames = Object.keys(COVERED);
+  for (const f of changedFiles) {
+    if (GLOBAL_TRIGGERS.has(f)) {
+      return allModuleNames;
+    }
+  }
+
+  // Otherwise find which modules have their src/*.cts changed.
+  const changed = new Set();
+  for (const f of changedFiles) {
+    // Match src/<module>.cts (top-level src/, not nested)
+    const m = f.match(/^src\/([^/]+)\.cts$/);
+    if (m && COVERED[m[1]]) {
+      changed.add(m[1]);
+    }
+  }
+  return [...changed];
+}
+
+// ── Output formatting ─────────────────────────────────────────────────────────
+function buildResult(moduleNames) {
+  const include = moduleNames.map(name => ({
+    name,
+    mutate: COVERED[name].cjs,
+    tests: COVERED[name].tests.join(' '),
+  }));
+
+  return {
+    has_work: include.length > 0 ? 'true' : 'false',
+    matrix: { include },
+  };
+}
+
+function printHuman(result, changedFiles) {
+  console.log(`Changed files (${changedFiles.length}):`);
+  for (const f of changedFiles) console.log(`  ${f}`);
+  console.log('');
+  console.log(`has_work: ${result.has_work}`);
+  console.log(`Shards (${result.matrix.include.length}):`);
+  for (const shard of result.matrix.include) {
+    console.log(`  [${shard.name}]`);
+    console.log(`    mutate: ${shard.mutate}`);
+    console.log(`    tests:  ${shard.tests}`);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const changedFiles = resolveChangedFiles(args);
+    const moduleNames = computeMatrix(changedFiles);
+    const result = buildResult(moduleNames);
+
+    if (args.print) {
+      printHuman(result, changedFiles);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } catch (err) {
+    console.error(`mutation-matrix: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+main();

package/scripts/prompt-injection-scan.sh

@@ -73,13 +73,17 @@ ALLOWLIST=(
   'tests/security.test.cjs'
   'tests/prompt-injection-scan.test.cjs'
   'tests/verify.test.cjs'
-  'get-shit-done/bin/lib/security.cjs'
+  'gsd-core/bin/lib/security.cjs'
   'hooks/gsd-prompt-guard.js'
   'hooks/gsd-read-injection-scanner.js'
   'tests/read-injection-scanner.test.cjs'
   'tests/security-prompt-injection.test.cjs'
   'tests/fixtures/adversarial/security/'
   'SECURITY.md'
+  # These files contain intentional injection examples / security-model prose
+  # and are not attack vectors — they explain/demonstrate injection patterns.
+  'TEST-EXAMPLES.md'
+  'docs/explanation/security-model.md'
 )
 
 is_allowlisted() {

package/scripts/release-notes/format-github-release-notes.cjs

@@ -0,0 +1,256 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+/**
+ * Classify a What's-Changed bullet line into 'Feature', 'Fix', or 'Enhancement'.
+ * @param {string} bulletLine - Full bullet line including the leading `* ` or `- ` marker.
+ * @returns {'Feature'|'Fix'|'Enhancement'}
+ */
+function classifyTitle(bulletLine) {
+  // Strip leading `* ` or `- ` marker
+  const withoutMarker = bulletLine.replace(/^[*-]\s+/, '');
+
+  // Extract title = text before ` by @`
+  const byIdx = withoutMarker.indexOf(' by @');
+  const title = (byIdx !== -1 ? withoutMarker.slice(0, byIdx) : withoutMarker).trim();
+
+  if (/^feat(?:ure)?\s*(?:\(|!|:)/i.test(title)) return 'Feature';
+  if (/^fix\s*(?:\(|!|:)/i.test(title)) return 'Fix';
+  return 'Enhancement';
+}
+
+/**
+ * Reformat GitHub's auto-generated release notes into the repo's hand-curated format.
+ *
+ * @param {object} opts
+ * @param {string} opts.generatedBody - The raw GitHub-generated release body.
+ * @param {string} opts.version       - Version string (e.g. "1.3.0-rc.1"), no leading "v".
+ * @param {boolean} opts.prerelease   - Whether this is a pre-release.
+ * @param {string} opts.packageName   - npm package name (e.g. "@opengsd/gsd-core").
+ * @returns {string} Formatted release body (no trailing newline).
+ */
+function formatReleaseNotes({ generatedBody, version, prerelease, packageName }) {
+  const lines = generatedBody.split('\n');
+
+  const featureBullets = [];
+  const fixBullets = [];
+  const enhancementBullets = [];
+  const newContributorBullets = [];
+  let fullChangelogLine = null;
+
+  let inWhatsChanged = false;
+  let inNewContributors = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Detect section headings
+    if (trimmed === '## What\'s Changed') {
+      inWhatsChanged = true;
+      inNewContributors = false;
+      continue;
+    }
+
+    if (trimmed === '## New Contributors') {
+      inWhatsChanged = false;
+      inNewContributors = true;
+      continue;
+    }
+
+    // Full changelog line ends the What's Changed section
+    if (trimmed.startsWith('**Full Changelog**:')) {
+      inWhatsChanged = false;
+      inNewContributors = false;
+      fullChangelogLine = trimmed;
+      continue;
+    }
+
+    // Any other `##` heading ends current section
+    if (trimmed.startsWith('## ')) {
+      inWhatsChanged = false;
+      inNewContributors = false;
+      continue;
+    }
+
+    // Collect bullets
+    if (inWhatsChanged && (trimmed.startsWith('* ') || trimmed.startsWith('- '))) {
+      const category = classifyTitle(trimmed);
+      if (category === 'Feature') featureBullets.push(trimmed);
+      else if (category === 'Fix') fixBullets.push(trimmed);
+      else enhancementBullets.push(trimmed);
+      continue;
+    }
+
+    if (inNewContributors && (trimmed.startsWith('* ') || trimmed.startsWith('- '))) {
+      newContributorBullets.push(trimmed);
+      continue;
+    }
+  }
+
+  // Build Install block
+  let installBlock;
+  if (prerelease) {
+    installBlock = [
+      '## Install',
+      '',
+      'This pre-release is published to npm under the `next` dist-tag.',
+      '',
+      '```bash',
+      `npm i ${packageName}@${version}`,
+      '# or',
+      `npm i ${packageName}@next`,
+      '```',
+    ].join('\n');
+  } else {
+    installBlock = [
+      '## Install',
+      '',
+      '```bash',
+      `npm i ${packageName}@${version}`,
+      '# or',
+      `npm i ${packageName}@latest`,
+      '```',
+    ].join('\n');
+  }
+
+  // Assemble groups (omit empty ones)
+  const groups = [];
+
+  // Group A: Install
+  groups.push(installBlock);
+
+  // Group B: What's Changed heading
+  groups.push('## What\'s Changed');
+
+  // Group C: Features
+  if (featureBullets.length > 0) {
+    groups.push('### Feature\n' + featureBullets.join('\n'));
+  }
+
+  // Group D: Enhancements
+  if (enhancementBullets.length > 0) {
+    groups.push('### Enhancement\n' + enhancementBullets.join('\n'));
+  }
+
+  // Group E: Fixes
+  if (fixBullets.length > 0) {
+    groups.push('### Fix\n' + fixBullets.join('\n'));
+  }
+
+  // Group F: New Contributors
+  if (newContributorBullets.length > 0) {
+    groups.push('## New Contributors\n' + newContributorBullets.join('\n'));
+  }
+
+  // Group G: Full Changelog
+  if (fullChangelogLine) {
+    groups.push(fullChangelogLine);
+  }
+
+  return groups.join('\n\n');
+}
+
+// CLI entry point
+if (require.main === module) {
+  try {
+    const argv = process.argv.slice(2);
+
+    let tag = null;
+    let repo = null;
+    let packageName = null;
+    let prerelease = null;
+    let useStdin = false;
+    let doApply = false;
+
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+      if (arg === '--tag') {
+        tag = argv[++i];
+      } else if (arg === '--repo') {
+        repo = argv[++i];
+      } else if (arg === '--package') {
+        packageName = argv[++i];
+      } else if (arg === '--prerelease') {
+        prerelease = true;
+      } else if (arg === '--latest') {
+        prerelease = false;
+      } else if (arg === '--stdin') {
+        useStdin = true;
+      } else if (arg === '--apply') {
+        doApply = true;
+      }
+    }
+
+    // Derive version from tag
+    const version = tag ? tag.replace(/^v/, '') : null;
+
+    // Resolve package name if not provided
+    if (!packageName) {
+      const repoRoot = path.resolve(__dirname, '..', '..');
+      const pkgJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+      packageName = pkgJson.name;
+    }
+
+    let generatedBody;
+
+    if (useStdin) {
+      // Read from stdin
+      if (!version) {
+        throw new Error('--stdin mode requires --tag or --version to derive version');
+      }
+      if (prerelease === null) {
+        throw new Error('--stdin mode requires --prerelease or --latest');
+      }
+      generatedBody = fs.readFileSync('/dev/stdin', 'utf8');
+    } else {
+      // Fetch from gh
+      if (!tag) {
+        throw new Error('--tag <tag> is required');
+      }
+
+      const ghArgs = ['release', 'view', tag, '--json', 'body', '-q', '.body'];
+      if (repo) ghArgs.push('--repo', repo);
+
+      generatedBody = execFileSync('gh', ghArgs, { encoding: 'utf8' });
+
+      // Determine prerelease if not forced
+      if (prerelease === null) {
+        try {
+          const ghPreArgs = ['release', 'view', tag, '--json', 'isPrerelease', '-q', '.isPrerelease'];
+          if (repo) ghPreArgs.push('--repo', repo);
+          const result = execFileSync('gh', ghPreArgs, { encoding: 'utf8' }).trim();
+          prerelease = result === 'true';
+        } catch (_e) {
+          // Final fallback: check if tag contains `-` after version digits
+          prerelease = /-/.test(version);
+        }
+      }
+    }
+
+    const formatted = formatReleaseNotes({ generatedBody, version, prerelease, packageName });
+
+    if (doApply) {
+      const tmpFile = path.join(os.tmpdir(), `release-notes-${Date.now()}.md`);
+      fs.writeFileSync(tmpFile, formatted, 'utf8');
+      try {
+        const ghArgs = ['release', 'edit', tag, '--notes-file', tmpFile];
+        if (repo) ghArgs.push('--repo', repo);
+        execFileSync('gh', ghArgs, { encoding: 'utf8' });
+        process.stderr.write(`Release notes updated for ${tag}\n`);
+      } finally {
+        fs.unlinkSync(tmpFile);
+      }
+    } else {
+      process.stdout.write(formatted + '\n');
+    }
+  } catch (err) {
+    process.stderr.write((err.message || String(err)) + '\n');
+    process.exit(1);
+  }
+}
+
+module.exports = { formatReleaseNotes, classifyTitle };