@bhargavvc/sdd-cc 1.35.0 → 1.42.3

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

@@ -0,0 +1,198 @@
+'use strict';
+
+const cp = require('node:child_process');
+const path = require('node:path');
+
+const { parseFragment } = require('./parse.cjs');
+
+const SECTION_ORDER = ['Fixed', 'Added', 'Changed', 'Deprecated', 'Removed', 'Security'];
+
+const FIXED_GROUPS = [
+  {
+    title: 'Verification, update & review safety',
+    pattern: /\b(verifier|verification|verify|probe|probes|debt|tbd|fixme|xxx|detect-custom-files|review|summary|blocker|critical)\b/i,
+  },
+  {
+    title: 'State, planning & execution',
+    pattern: /\b(state|planning|planner|plan-phase|phase|roadmap|execute|executor|worktree|worktrees|resolve-model|init\.progress|model override|human_needed|ship preflight)\b/i,
+  },
+  {
+    title: 'Install & runtime conversion',
+    pattern: /\b(install|installer|runtime|windows|powershell|codex|gemini|antigravity|hook|hooks|sdd-sdk|sdk readiness|cjs|model-catalog|path|shim)\b/i,
+  },
+];
+
+const REMOVED_GROUPS = [
+  {
+    title: 'Intel updater',
+    pattern: /\b(intel|sdd-intel-updater|layout detection)\b/i,
+  },
+];
+
+function runGit(repo, args) {
+  return cp.execFileSync('git', args, {
+    cwd: repo,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function validateGitRef({ repo, ref, label }) {
+  if (typeof ref !== 'string' || ref.trim() !== ref || ref.length === 0) {
+    throw new Error(`Invalid git ref for ${label}: expected a non-empty trimmed string`);
+  }
+  if (
+    ref.startsWith('-') ||
+    ref.includes('..') ||
+    ref.includes('//') ||
+    !/^[A-Za-z0-9._/-]+$/.test(ref)
+  ) {
+    throw new Error(`Invalid git ref for ${label}: ${ref}`);
+  }
+  runGit(repo, ['rev-parse', '--verify', `${ref}^{commit}`]);
+  return ref;
+}
+
+function changedFragmentPaths({ repo, fromRef, toRef }) {
+  const from = validateGitRef({ repo, ref: fromRef, label: 'fromRef' });
+  const to = validateGitRef({ repo, ref: toRef, label: 'toRef' });
+  const out = runGit(repo, ['diff', '--name-only', `${from}..${to}`, '--', '.changeset']);
+  return out
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .filter((file) => /^\.changeset\/[^/]+\.md$/.test(file));
+}
+
+function readFileAtRef({ repo, ref, file }) {
+  return runGit(repo, ['show', `${ref}:${file}`]);
+}
+
+function loadFragmentsFromRange({ repo, fromRef, toRef }) {
+  const files = changedFragmentPaths({ repo, fromRef, toRef });
+  const fragments = [];
+  const failures = [];
+
+  for (const file of files) {
+    try {
+      const src = readFileAtRef({ repo, ref: toRef, file });
+      const parsed = parseFragment(src);
+      if (parsed.ok) {
+        fragments.push({
+          ...parsed.fragment,
+          file,
+          slug: path.basename(file, '.md'),
+        });
+      } else {
+        failures.push({ file, reason: parsed.reason, detail: parsed.detail || null });
+      }
+    } catch (e) {
+      failures.push({ file, reason: 'read_failed', detail: e.message });
+    }
+  }
+
+  return { fragments, failures };
+}
+
+function classifyGroup(fragment) {
+  const haystack = `${fragment.slug || ''}\n${fragment.body || ''}`;
+  const groups = fragment.type === 'Removed' ? REMOVED_GROUPS : FIXED_GROUPS;
+  const match = groups.find((group) => group.pattern.test(haystack));
+  if (match) return match.title;
+  if (fragment.type === 'Removed') return 'Removed';
+  if (fragment.type === 'Fixed') return 'Other fixes';
+  return fragment.type;
+}
+
+function buildGithubReleaseNotesIr({ fragments }) {
+  const sections = [];
+  for (const type of SECTION_ORDER) {
+    const typed = fragments.filter((fragment) => fragment.type === type);
+    if (typed.length === 0) continue;
+
+    const groupMap = new Map();
+    for (const fragment of typed) {
+      const groupTitle = classifyGroup(fragment);
+      if (!groupMap.has(groupTitle)) groupMap.set(groupTitle, []);
+      groupMap.get(groupTitle).push(fragment);
+    }
+
+    sections.push({
+      type,
+      groups: Array.from(groupMap, ([title, bullets]) => ({ title, bullets })),
+    });
+  }
+  return { sections };
+}
+
+function formatBullet(fragment) {
+  if (!Number.isInteger(fragment.pr) || fragment.pr <= 0) {
+    throw new Error(`Fragment ${fragment.slug || fragment.file || '<unknown>'} missing valid pr field`);
+  }
+  const body = `${fragment.body.trim()} (#${fragment.pr})`;
+  const lines = body.split(/\r?\n/);
+  return lines.map((line, index) => (index === 0 ? `- ${line}` : `  ${line}`)).join('\n');
+}
+
+function compareUrl({ repoSlug, fromRef, toRef }) {
+  const normalizedSlug = String(repoSlug || '').trim();
+  if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(normalizedSlug)) {
+    throw new Error(`Invalid repoSlug format: ${repoSlug} (expected "owner/repo")`);
+  }
+  return `https://github.com/${normalizedSlug}/compare/${fromRef}...${toRef}`;
+}
+
+function serializeGithubReleaseNotes({
+  ir,
+  fromRef,
+  toRef,
+  repoSlug = 'bhargavvc/sdd-cc',
+  installCommand = 'npx @bhargavvc/sdd-cc@latest',
+}) {
+  if (installCommand.includes('`')) {
+    throw new Error('installCommand cannot contain backtick characters');
+  }
+  const lines = [];
+  for (const section of ir.sections) {
+    lines.push(`## ${section.type}`);
+    lines.push('');
+    for (const group of section.groups) {
+      lines.push(`### ${group.title}`);
+      for (const bullet of group.bullets) {
+        lines.push(formatBullet(bullet));
+      }
+      lines.push('');
+    }
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push(`Install/upgrade: \`${installCommand}\``);
+  lines.push('');
+  lines.push(`**Full Changelog**: ${compareUrl({ repoSlug, fromRef, toRef })}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderGithubReleaseNotes(options) {
+  const { fragments, failures } = loadFragmentsFromRange(options);
+  if (failures.length > 0) {
+    return { ok: false, fragments, failures, body: null };
+  }
+  const ir = buildGithubReleaseNotesIr({ fragments });
+  return {
+    ok: true,
+    fragments,
+    failures: [],
+    ir,
+    body: serializeGithubReleaseNotes({ ir, ...options }),
+  };
+}
+
+module.exports = {
+  changedFragmentPaths,
+  loadFragmentsFromRange,
+  buildGithubReleaseNotesIr,
+  serializeGithubReleaseNotes,
+  renderGithubReleaseNotes,
+  classifyGroup,
+  validateGitRef,
+};

package/scripts/changeset/lint.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Changeset-fragment lint (#2975).
+ *
+ * Pure verdict function evaluateLint({ changedFiles, labels }) returns
+ * { ok, reason } using the LINT_REASON enum. The CLI wrapper calls it with
+ * the PR diff (via `git diff --name-only origin/main...HEAD` or the GitHub
+ * Actions event payload) and the labels list (via the GitHub event).
+ *
+ * Tests assert on the typed verdict, never on free text.
+ */
+
+const LINT_REASON = Object.freeze({
+  OK_FRAGMENT_PRESENT: 'ok_fragment_present',
+  OK_OPT_OUT_LABEL: 'ok_opt_out_label',
+  OK_NO_USER_FACING_CHANGES: 'ok_no_user_facing_changes',
+  FAIL_MISSING_FRAGMENT: 'fail_missing_fragment',
+});
+
+const OPT_OUT_LABEL = 'no-changelog';
+
+// Files counted as "user-facing" — touching any of these requires either a
+// fragment or an explicit opt-out label. Test/CI/docs/lock files do not.
+const USER_FACING_PREFIXES = [
+  'bin/',
+  'sdd/',
+  'agents/',
+  'commands/',
+  'hooks/',
+  'sdk/src/',
+  'sdk/prompts/',
+];
+
+// Exact-match user-facing files. Any direct edit to one of these without a
+// fragment also fails the lint — closes the bypass where a contributor edits
+// CHANGELOG.md directly to sneak past the new workflow.
+const USER_FACING_FILES = new Set(['CHANGELOG.md']);
+
+function isUserFacing(file) {
+  if (USER_FACING_FILES.has(file)) return true;
+  return USER_FACING_PREFIXES.some((p) => file.startsWith(p));
+}
+
+function isFragment(file) {
+  return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
+}
+
+function evaluateLint({ changedFiles, labels }) {
+  if (changedFiles.some(isFragment)) {
+    return { ok: true, reason: LINT_REASON.OK_FRAGMENT_PRESENT };
+  }
+  if (labels.includes(OPT_OUT_LABEL)) {
+    return { ok: true, reason: LINT_REASON.OK_OPT_OUT_LABEL };
+  }
+  if (!changedFiles.some(isUserFacing)) {
+    return { ok: true, reason: LINT_REASON.OK_NO_USER_FACING_CHANGES };
+  }
+  return { ok: false, reason: LINT_REASON.FAIL_MISSING_FRAGMENT };
+}
+
+function main() {
+  const fs = require('node:fs');
+  const cp = require('node:child_process');
+  // GitHub Actions event payload path
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  let labels = [];
+  if (eventPath && fs.existsSync(eventPath)) {
+    try {
+      const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+      labels = (event.pull_request?.labels || []).map((l) => l.name);
+    } catch { /* fall through */ }
+  }
+  const base = process.env.GITHUB_BASE_REF || 'main';
+  let changedFiles = [];
+  try {
+    // Use execFileSync with an argv array — the base ref is interpolated
+    // into a refspec argument, but execFileSync does not invoke a shell, so
+    // even a malicious GITHUB_BASE_REF cannot inject shell syntax. The
+    // refspec-bound metacharacters that git itself rejects (e.g. spaces in
+    // ref names) are caught by git's own arg parser.
+    const out = cp.execFileSync(
+      'git',
+      ['diff', '--name-only', `origin/${base}...HEAD`],
+      { encoding: 'utf8' },
+    );
+    changedFiles = out.split('\n').filter(Boolean);
+  } catch (e) {
+    process.stderr.write(`could not compute diff: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const verdict = evaluateLint({ changedFiles, labels });
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify({ ...verdict, changedFiles, labels }, null, 2) + '\n');
+  } else if (verdict.ok) {
+    process.stdout.write(`ok changeset-lint: ${verdict.reason}\n`);
+  } else {
+    process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
+    process.stderr.write(`PR touches user-facing files but does not include a .changeset/*.md fragment.\n`);
+    process.stderr.write(`Run \`npm run changeset\` to create one, or add the \`${OPT_OUT_LABEL}\` label\n`);
+    process.stderr.write(`if this PR genuinely has no user-facing impact (test refactor, CI tweak, etc.).\n`);
+  }
+  process.exit(verdict.ok ? 0 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment };

package/scripts/changeset/new.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Scaffolds a new changeset fragment (#2975).
+ *
+ *   npm run changeset -- --type Fixed --pr 1234 --body "fix the thing"
+ *
+ * Writes `.changeset/<adjective>-<noun>-<noun>.md` with frontmatter
+ * + body. The random three-word filename minimizes filename collision
+ * across concurrent PRs.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Small word lists — keep the function simple and dependency-free.
+// Together this gives ~40 * 40 * 40 = 64,000 distinct names. The lint
+// rejects any duplicate filename, so collisions are caught even when
+// the random draw repeats.
+const ADJECTIVES = [
+  'silly', 'brave', 'calm', 'eager', 'gentle', 'happy', 'jolly', 'kind',
+  'lively', 'merry', 'nimble', 'plucky', 'quick', 'sturdy', 'witty', 'zesty',
+  'bold', 'clever', 'daring', 'fierce', 'graceful', 'humble', 'lucky', 'noble',
+  'proud', 'rapid', 'sharp', 'tidy', 'vivid', 'wise', 'agile', 'curious',
+  'eager', 'gallant', 'mellow', 'patient', 'serene', 'steady', 'sturdy', 'sunny',
+];
+const NOUNS_A = [
+  'bears', 'birds', 'cats', 'dogs', 'elks', 'foxes', 'goats', 'hawks',
+  'ibex', 'jays', 'koalas', 'lynx', 'moles', 'newts', 'otters', 'pumas',
+  'quails', 'rams', 'seals', 'tigers', 'voles', 'wolves', 'yaks', 'zebras',
+  'badgers', 'cranes', 'deer', 'eagles', 'finches', 'geese', 'herons', 'jaguars',
+  'lemurs', 'mice', 'orcas', 'pandas', 'ravens', 'sloths', 'tunas', 'wasps',
+];
+const NOUNS_B = [
+  'dance', 'sing', 'leap', 'run', 'jump', 'climb', 'fly', 'swim',
+  'rest', 'wake', 'roam', 'greet', 'wander', 'gather', 'forage', 'travel',
+  'glide', 'sprint', 'tumble', 'wave', 'cheer', 'rally', 'parade', 'march',
+  'hop', 'frolic', 'caper', 'romp', 'zip', 'dart', 'snooze', 'munch',
+  'chatter', 'squeak', 'howl', 'bark', 'purr', 'roar', 'hum', 'click',
+];
+
+function pick(arr) {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+function generateFragmentName() {
+  return `${pick(ADJECTIVES)}-${pick(NOUNS_A)}-${pick(NOUNS_B)}`;
+}
+
+// Allowed Keep-a-Changelog section types. Used by both scaffoldFragment
+// (sanitization at write time) and parse.cjs (validation at consume time).
+const ALLOWED_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']);
+
+function scaffoldFragment({ repo, type, pr, body }) {
+  // Sanitize: reject any type value not on the allowlist BEFORE embedding it
+  // in frontmatter. A newline in `type` would corrupt the fragment; an
+  // unrecognized value would be rejected later by parse.cjs but with a
+  // confusing diagnostic. Catch both at the write boundary.
+  if (!ALLOWED_TYPES.has(type)) {
+    throw new Error(
+      `scaffoldFragment: type=${JSON.stringify(type)} is not one of [${[...ALLOWED_TYPES].join(', ')}]`,
+    );
+  }
+  const dir = path.join(repo, '.changeset');
+  fs.mkdirSync(dir, { recursive: true });
+  const content = `---\ntype: ${type}\npr: ${pr}\n---\n${body}\n`;
+  // Atomic create: writeFileSync with `flag: 'wx'` fails (EEXIST) when the
+  // file already exists, so concurrent invocations can't race past
+  // `existsSync` and overwrite each other. Re-roll the random name on
+  // collision; fail loudly after exhausting the retry budget.
+  for (let i = 0; i < 16; i++) {
+    const name = generateFragmentName();
+    const target = path.join(dir, `${name}.md`);
+    try {
+      fs.writeFileSync(target, content, { flag: 'wx' });
+      return target;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // collision — try another random draw
+    }
+  }
+  throw new Error(
+    'scaffoldFragment: 16 random filename draws all collided; ' +
+    'expand the word lists or investigate corrupted .changeset/ state',
+  );
+}
+
+function parseArgs(argv) {
+  const opts = { type: null, pr: null, body: null, repo: process.cwd() };
+  // Validate flag values: argv[++i] could be undefined (flag with no value)
+  // or another flag (silently misparsed). Match the cli.cjs convention: return
+  // { ok: true, opts } on success, { ok: false, error } on malformed input.
+  const requireValue = (flag, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      return { ok: false, error: `missing value for ${flag}` };
+    }
+    return { ok: true, value: v };
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--type' || a === '--pr' || a === '--body' || a === '--repo') {
+      const r = requireValue(a, i);
+      if (!r.ok) return { ok: false, error: r.error };
+      if (a === '--type') opts.type = r.value;
+      else if (a === '--pr') opts.pr = Number(r.value);
+      else if (a === '--body') opts.body = r.value;
+      else if (a === '--repo') opts.repo = r.value;
+      i++;
+      continue;
+    }
+    return { ok: false, error: `unknown argument: ${a}` };
+  }
+  return { ok: true, opts };
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}\n`);
+    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
+    process.exit(2);
+  }
+  const { opts } = parsed;
+  if (!opts.type || !opts.pr || !opts.body) {
+    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
+    process.exit(2);
+  }
+  const file = scaffoldFragment(opts);
+  process.stdout.write(`${path.relative(process.cwd(), file)}\n`);
+}
+
+if (require.main === module) main();
+
+module.exports = { generateFragmentName, scaffoldFragment, parseArgs, ALLOWED_TYPES };

package/scripts/changeset/parse.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * Parses a changeset fragment file (text → typed record).
+ *
+ *   ---
+ *   type: Fixed
+ *   pr: 2975
+ *   ---
+ *   <markdown body>
+ *
+ * Returns { ok: true, fragment: { type, pr, body } } on success,
+ * { ok: false, reason: FRAGMENT_ERROR.X, detail } on failure.
+ *
+ * The reason field is a frozen enum so tests assert on stable codes,
+ * not free-text error messages (CONTRIBUTING.md: "Prohibited: Raw
+ * Text Matching on Test Outputs").
+ */
+const FRAGMENT_ERROR = Object.freeze({
+  MISSING_FRONTMATTER: 'missing_frontmatter',
+  MISSING_TYPE: 'missing_type',
+  INVALID_TYPE: 'invalid_type',
+  MISSING_PR: 'missing_pr',
+  INVALID_PR: 'invalid_pr',
+  EMPTY_BODY: 'empty_body',
+});
+
+const ALLOWED_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']);
+
+function parseFragment(src) {
+  const fmMatch = src.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!fmMatch) return { ok: false, reason: FRAGMENT_ERROR.MISSING_FRONTMATTER };
+  const [, fmBlock, body] = fmMatch;
+
+  const fields = {};
+  for (const line of fmBlock.split(/\r?\n/)) {
+    const m = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (m) fields[m[1]] = m[2].trim();
+  }
+
+  if (!fields.type) return { ok: false, reason: FRAGMENT_ERROR.MISSING_TYPE };
+  if (!ALLOWED_TYPES.has(fields.type)) {
+    return { ok: false, reason: FRAGMENT_ERROR.INVALID_TYPE, detail: fields.type };
+  }
+  if (!fields.pr) return { ok: false, reason: FRAGMENT_ERROR.MISSING_PR };
+  const pr = Number(fields.pr);
+  if (!Number.isInteger(pr) || pr <= 0) {
+    return { ok: false, reason: FRAGMENT_ERROR.INVALID_PR, detail: fields.pr };
+  }
+  // Use trim() only for the emptiness check; preserve the body verbatim
+  // (including significant leading/trailing whitespace, code blocks, etc.)
+  // so render → serialize round-trips exactly. Strip only a single trailing
+  // newline added by editors so byte-equality holds for typical fragments.
+  if (!body.trim()) return { ok: false, reason: FRAGMENT_ERROR.EMPTY_BODY };
+  const verbatimBody = body.endsWith('\n') ? body.slice(0, -1) : body;
+
+  return { ok: true, fragment: { type: fields.type, pr, body: verbatimBody } };
+}
+
+module.exports = { parseFragment, FRAGMENT_ERROR, ALLOWED_TYPES };

package/scripts/changeset/render.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * Pure renderer for the changeset-fragment workflow (#2975).
+ *
+ * Returns a typed Changelog IR — no file I/O. The IR is the contract that
+ * tests assert on; the markdown serializer is a separate concern.
+ *
+ *   IR shape: {
+ *     releaseHeader: { version: string, date: string },
+ *     sections: [{ type: string, bullets: [{ pr: number, body: string }] }],
+ *     priorChangelog: string | null,
+ *   }
+ */
+// Keep a Changelog (https://keepachangelog.com) standard section order.
+const SECTION_ORDER = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'];
+
+function renderChangelog({ fragments, version, date, priorChangelog }) {
+  const byType = new Map();
+  for (const f of fragments) {
+    if (!byType.has(f.type)) byType.set(f.type, []);
+    byType.get(f.type).push({ pr: f.pr, body: f.body });
+  }
+  const sections = SECTION_ORDER
+    .filter((type) => byType.has(type))
+    .map((type) => ({ type, bullets: byType.get(type) }));
+  return {
+    releaseHeader: { version, date },
+    sections,
+    priorChangelog: priorChangelog || null,
+  };
+}
+
+module.exports = { renderChangelog };

package/scripts/changeset/serialize.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Markdown serializer + parser for the changelog IR. The two are inverses
+ * over the well-formed subset; tests assert via round-trip (parse(serialize(ir)))
+ * rather than by inspecting serialized text — see CONTRIBUTING.md
+ * "Prohibited: Raw Text Matching on Test Outputs".
+ *
+ * Serialized form (Keep a Changelog):
+ *
+ *   ## [1.42.0] - 2026-05-01
+ *
+ *   ### Fixed
+ *
+ *   - body of the bullet (#NNNN)
+ *
+ *   <priorChangelog appended verbatim>
+ */
+
+function serializeChangelog(ir) {
+  const lines = [];
+  const { version, date } = ir.releaseHeader;
+  lines.push(`## [${version}] - ${date}`);
+  lines.push('');
+  for (const section of ir.sections) {
+    lines.push(`### ${section.type}`);
+    lines.push('');
+    for (const b of section.bullets) {
+      lines.push(`- ${b.body} (#${b.pr})`);
+    }
+    lines.push('');
+  }
+  let out = lines.join('\n');
+  if (ir.priorChangelog) {
+    out += '\n' + ir.priorChangelog;
+  }
+  return out;
+}
+
+/**
+ * Inverse parser: extracts the structured releases from a CHANGELOG.md
+ * text. Returns { releases: [{ version, date, sections: [{ type, bullets:
+ * [{ pr, body }] }] }] }. Tolerates the actual repo's CHANGELOG dialect.
+ */
+function parseChangelog(text) {
+  const releases = [];
+  const lines = text.split(/\r?\n/);
+  let cur = null;
+  let curSection = null;
+  for (const line of lines) {
+    const releaseMatch = line.match(/^##\s+\[([^\]]+)\](?:\s*-\s*(\S+))?/);
+    if (releaseMatch) {
+      cur = { version: releaseMatch[1], date: releaseMatch[2] || null, sections: [] };
+      curSection = null;
+      releases.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+    const sectionMatch = line.match(/^###\s+(.+?)\s*$/);
+    if (sectionMatch) {
+      curSection = { type: sectionMatch[1], bullets: [] };
+      cur.sections.push(curSection);
+      continue;
+    }
+    if (!curSection) continue;
+    const bulletMatch = line.match(/^-\s+(.*?)\s*\(#(\d+)\)\s*$/);
+    if (bulletMatch) {
+      curSection.bullets.push({ body: bulletMatch[1], pr: Number(bulletMatch[2]) });
+    }
+  }
+  return { releases };
+}
+
+module.exports = { serializeChangelog, parseChangelog };

package/scripts/command-contract-helpers.cjs

@@ -0,0 +1,61 @@
+'use strict';
+/**
+ * command-contract-helpers.cjs  (ADR-0002)
+ *
+ * Single source of truth for the commands/sdd/*.md contract constants and
+ * parsers shared by scripts/lint-command-contract.cjs and
+ * tests/command-contract.test.cjs.
+ *
+ * Keeping these in one place ensures the lint script and the test suite
+ * always agree on what constitutes a valid tool, a valid @-ref, and a valid
+ * frontmatter structure. A new canonical tool added here is automatically
+ * enforced by both consumers.
+ */
+
+const CANONICAL_TOOLS = new Set([
+  'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
+  'Task', 'Agent', 'Skill', 'SlashCommand',
+  'AskUserQuestion', 'WebFetch', 'WebSearch', 'TodoWrite',
+  'mcp__context7__resolve-library-id',
+  'mcp__context7__query-docs',
+  'mcp__context7__*',
+]);
+
+function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') return {};
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return {};
+  const fm = {};
+  let key = null;
+  for (const line of lines.slice(1, end)) {
+    const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (kv) { key = kv[1]; fm[key] = kv[2].trim(); }
+    else if (key && line.match(/^\s+-\s+/)) {
+      const val = line.replace(/^\s+-\s+/, '').trim();
+      fm[key] = fm[key] ? fm[key] + '\n' + val : val;
+    }
+  }
+  return fm;
+}
+
+function executionContextRefs(content) {
+  const refs = [];
+  const re = /<execution_context(?:_extended)?>([\s\S]*?)<\/execution_context(?:_extended)?>/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    for (const rawLine of m[1].split('\n')) {
+      const line = rawLine.trim();
+      if (!line.startsWith('@')) continue;
+      const token = line.split(/\s+/)[0];
+      const trailingProse = line.length > token.length;
+      const normalized = token
+        .replace(/^@(?:~|\$HOME)\//, '')
+        .replace(/^(?:\.claude\/)?(?:sdd\/)?/, '');
+      refs.push({ token, normalized, trailingProse });
+    }
+  }
+  return refs;
+}
+
+module.exports = { CANONICAL_TOOLS, parseFrontmatter, executionContextRefs };