@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

package/scripts/gen-research-agents.cjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-research-agents.cjs — profile-driven drift guard for the 7 researcher agents.
+ *
+ * Usage:
+ *   node scripts/gen-research-agents.cjs           # same as --check
+ *   node scripts/gen-research-agents.cjs --check   # assert every agent matches its profile
+ *   node scripts/gen-research-agents.cjs --write   # regenerate frontmatter from profiles
+ *
+ * --check assertions per agent:
+ *   (a) frontmatter name/description/color/tools exactly match the profile
+ *   (b) every requiredInclude string is present in the body
+ *   (c) every requiredSeamCall string is present in the body
+ *   (d) every outputContract marker string is present in the body
+ *
+ * --write regenerates ONLY the opening `---\n...\n---` frontmatter block from the
+ * profile, leaving the body byte-identical. After --write, --check must pass and
+ * `git diff` must be empty (profiles were derived from current state).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { PROFILES } = require('./research-profiles.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const AGENTS_DIR = path.join(ROOT, 'agents');
+
+// ─── Frontmatter serialization ────────────────────────────────────────────────
+
+/**
+ * Build the frontmatter block for a profile.
+ *
+ * The agent files have two patterns for commented hooks:
+ *   - Agents with Write in tools (file-writers): include the commented hooks block
+ *   - The advisor-researcher (Read-only tools, no Write): no commented hooks
+ *
+ * We read the CURRENT commented-hooks block from the agent file and preserve it
+ * byte-for-byte; only name/description/tools/color are regenerated.
+ */
+function buildFrontmatter(profile, existingFrontmatter) {
+  // Extract the commented hooks section from the existing frontmatter, if any.
+  // The hooks block starts at `# hooks:` and runs to (but not including) the
+  // closing `---`. In the committed files there is NO blank line between
+  // `color:` and `# hooks:`, so we append it directly after the color line's `\n`.
+  const hooksMatch = existingFrontmatter.match(/(# hooks:[\s\S]*?)(?=\n---)/);
+  // hooksSuffix: if present, the block followed by a newline so `---` is on its own line;
+  // if absent, empty string (the closing `---` follows directly after color's `\n`).
+  const hooksSuffix = hooksMatch ? hooksMatch[1] + '\n' : '';
+
+  return (
+    '---\n' +
+    'name: ' + profile.name + '\n' +
+    'description: ' + profile.description + '\n' +
+    'tools: ' + profile.tools + '\n' +
+    'color: ' + profile.color + '\n' +
+    hooksSuffix +
+    '---'
+  );
+}
+
+// ─── Parse agent file ─────────────────────────────────────────────────────────
+
+/**
+ * Parse a .md file and return { frontmatterRaw, body, frontmatterFields }.
+ *
+ * frontmatterRaw: the raw text between the first and second `---` delimiters (exclusive)
+ * body: everything after the closing `---\n`
+ * frontmatterFields: { name, description, color, tools }
+ */
+function parseAgentFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // The frontmatter is between the first `---` line and the next `---` line.
+  const lines = raw.split('\n');
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      if (start === -1) {
+        start = i;
+      } else {
+        end = i;
+        break;
+      }
+    }
+  }
+
+  if (start === -1 || end === -1) {
+    throw new Error('No valid frontmatter delimiters found in ' + filePath);
+  }
+
+  const frontmatterLines = lines.slice(start + 1, end);
+  const frontmatterRaw = frontmatterLines.join('\n');
+  // body includes the closing `---` line and everything after
+  const fullFrontmatter = lines.slice(start, end + 1).join('\n');
+  const body = lines.slice(end + 1).join('\n');
+
+  const fields = {};
+  // Parse simple key: value pairs (not nested YAML, no multi-line values here)
+  for (const line of frontmatterLines) {
+    // Skip comment lines
+    if (line.trimStart().startsWith('#')) continue;
+    const m = line.match(/^(\w+):\s*(.*)/);
+    if (m) {
+      fields[m[1]] = m[2].trim();
+    }
+  }
+
+  return { raw, frontmatterRaw, fullFrontmatter, body, fields };
+}
+
+// ─── Check ────────────────────────────────────────────────────────────────────
+
+/**
+ * Check one profile against its agent file.
+ * Returns an array of failure strings (empty = pass).
+ */
+function checkAgent(profile) {
+  // Validate required array fields — return a clear failure rather than throwing TypeError.
+  for (const field of ['requiredIncludes', 'requiredSeamCalls', 'outputContract']) {
+    if (!Array.isArray(profile[field])) {
+      return ['profile ' + profile.name + ': missing required array field ' + field];
+    }
+  }
+
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const failures = [];
+
+  if (!fs.existsSync(agentPath)) {
+    return ['agent file not found: ' + agentPath];
+  }
+
+  const { fields } = parseAgentFile(agentPath);
+  const fullContent = fs.readFileSync(agentPath, 'utf8');
+
+  // (a) frontmatter fields
+  if (fields.name !== profile.name) {
+    failures.push(
+      'name mismatch: got "' + fields.name + '", want "' + profile.name + '"',
+    );
+  }
+  if (fields.description !== profile.description) {
+    failures.push(
+      'description mismatch:\n  got:  "' + fields.description + '"\n  want: "' + profile.description + '"',
+    );
+  }
+  if (fields.color !== profile.color) {
+    failures.push(
+      'color mismatch: got "' + fields.color + '", want "' + profile.color + '"',
+    );
+  }
+  if (fields.tools !== profile.tools) {
+    failures.push(
+      'tools mismatch:\n  got:  "' + fields.tools + '"\n  want: "' + profile.tools + '"',
+    );
+  }
+
+  // (b) requiredIncludes
+  for (const include of profile.requiredIncludes) {
+    if (!fullContent.includes(include)) {
+      failures.push('missing required include: ' + include);
+    }
+  }
+
+  // (c) requiredSeamCalls
+  for (const seam of profile.requiredSeamCalls) {
+    if (!fullContent.includes(seam)) {
+      failures.push('missing required seam call: ' + seam);
+    }
+  }
+
+  // (d) outputContract
+  for (const marker of profile.outputContract) {
+    if (!fullContent.includes(marker)) {
+      failures.push('missing output contract marker: ' + marker);
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Run --check for all profiles. Prints pass/fail per agent.
+ * Returns true if all pass, false otherwise.
+ */
+function runCheck() {
+  let allPassed = true;
+
+  for (const profile of PROFILES) {
+    const failures = checkAgent(profile);
+    if (failures.length === 0) {
+      process.stdout.write('  PASS  ' + profile.name + '\n');
+    } else {
+      process.stdout.write('  FAIL  ' + profile.name + '\n');
+      for (const f of failures) {
+        process.stdout.write('        ' + f.replace(/\n/g, '\n        ') + '\n');
+      }
+      allPassed = false;
+    }
+  }
+
+  return allPassed;
+}
+
+// ─── Write ────────────────────────────────────────────────────────────────────
+
+/**
+ * Regenerate the frontmatter block of one agent file from its profile.
+ * The body (everything after the closing ---) is preserved byte-for-byte.
+ */
+function writeAgent(profile) {
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const { fullFrontmatter, body } = parseAgentFile(agentPath);
+
+  const newFrontmatter = buildFrontmatter(profile, fullFrontmatter);
+  const newContent = newFrontmatter + '\n' + body;
+
+  fs.writeFileSync(agentPath, newContent, 'utf8');
+}
+
+function runWrite() {
+  for (const profile of PROFILES) {
+    const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+    if (!fs.existsSync(agentPath)) {
+      throw new ExitError(1, 'ERROR: agent file not found: ' + agentPath);
+    }
+    writeAgent(profile);
+    process.stdout.write('  wrote  ' + profile.name + '.md\n');
+  }
+  process.stdout.write('\nRun --check to verify:\n');
+  process.stdout.write('  node scripts/gen-research-agents.cjs --check\n');
+}
+
+// ─── Exports (for tests) ──────────────────────────────────────────────────────
+
+module.exports = { PROFILES, checkAgent, runCheck, parseAgentFile };
+
+// ─── CLI entry point ──────────────────────────────────────────────────────────
+
+function main() {
+  const flag = process.argv[2] || '--check';
+
+  if (flag === '--write') {
+    process.stdout.write('Writing frontmatter from profiles...\n');
+    runWrite();
+    process.stdout.write('\nVerifying...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nERROR: --check failed after --write. Fix serialization.\n');
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll agents match their profiles.\n');
+  } else if (flag === '--check') {
+    process.stdout.write('Checking research agent profiles...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nSome agents do not match their profiles.\n');
+      process.stdout.write(
+        '\nTo regenerate frontmatter from profiles:\n' +
+        '  node scripts/gen-research-agents.cjs --write\n',
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll 7 agents match their profiles.\n');
+  } else {
+    throw new ExitError(1, 'Unknown flag: ' + flag + '\nUsage: node scripts/gen-research-agents.cjs [--check|--write]');
+  }
+}
+
+if (require.main === module) {
+  runMain(main);
+}

package/scripts/issue-dedupe.cjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const POSSIBLE_DUPLICATE_LABEL = 'possible-duplicate';
+const HUMAN_REVIEW_LABEL = 'needs-maintainer-review';
+const CHALLENGE_MARKER = '<!-- gsd-dedupe-challenge -->';
+const DEFAULT_WINDOW_HOURS = 24;
+const DEFAULT_THRESHOLD = 0.6;
+const DEFAULT_MAX_CANDIDATES = 5;
+const MIN_TOKEN_LENGTH = 3;
+
+const EXEMPT_LABELS = [
+  'priority: critical',
+  'pinned',
+  'confirmed-bug',
+  'confirmed',
+  'fix-pending',
+  'needs-maintainer-review',
+];
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'if', 'then', 'is', 'are', 'was',
+  'be', 'to', 'of', 'in', 'on', 'for', 'with', 'as', 'at', 'by', 'from',
+  'this', 'that', 'it', 'its', 'not', 'no', 'when', 'what', 'why', 'how',
+  'does', 'do', 'doing', 'did', 'can', 'will', 'would', 'should',
+  'i', 'we', 'you', 'your', 'my', 'me',
+  'issue', 'bug', 'error', 'problem', 'feature', 'request',
+  'help', 'support', 'please', 'question',
+  'after', 'before', 'into', 'only', 'then', 'than', 'them', 'they',
+  'use', 'used', 'using',
+]);
+
+// ---------------------------------------------------------------------------
+// tokenize(title) -> string[]
+//
+// Lowercase the title, replace any non-[a-z0-9] run with a space, split on
+// whitespace, drop tokens shorter than MIN_TOKEN_LENGTH, drop STOPWORDS, and
+// dedupe while preserving stable first-occurrence order.
+//
+// Non-string, null, or empty input returns []. Must not throw on any input.
+// ---------------------------------------------------------------------------
+
+function tokenize(title) {
+  if (typeof title !== 'string' || !title) return [];
+
+  const normalized = title.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+  if (!normalized) return [];
+
+  const seen = new Set();
+  const result = [];
+
+  for (const token of normalized.split(' ')) {
+    if (!token || token.length < MIN_TOKEN_LENGTH) continue;
+    if (STOPWORDS.has(token)) continue;
+    if (seen.has(token)) continue;
+    seen.add(token);
+    result.push(token);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// diceSimilarity(aTokens, bTokens) -> number 0..1
+//
+// Sørensen–Dice over the token sets: 2 * |A ∩ B| / (|A| + |B|).
+// Both inputs are treated as sets (duplicates ignored). Empty either side -> 0.
+// Identical sets -> 1.
+// ---------------------------------------------------------------------------
+
+function diceSimilarity(aTokens, bTokens) {
+  const setA = new Set(aTokens);
+  const setB = new Set(bTokens);
+
+  if (setA.size === 0 || setB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection += 1;
+  }
+
+  return (2 * intersection) / (setA.size + setB.size);
+}
+
+// ---------------------------------------------------------------------------
+// scoreCandidates(newTitle, candidates, opts) -> [{number, title, score}]
+//
+// opts: { threshold=DEFAULT_THRESHOLD, limit=DEFAULT_MAX_CANDIDATES, excludeNumber }
+//
+// Tokenizes newTitle once. If no tokens -> []. Filters out null/garbage
+// candidates, those missing a number, and the excluded number. Scores each
+// using diceSimilarity. Keeps score >= threshold. Sorts DESC by score,
+// tie-break ASC by number. Caps to limit.
+// ---------------------------------------------------------------------------
+
+function scoreCandidates(newTitle, candidates, opts) {
+  const threshold = (opts && opts.threshold != null) ? opts.threshold : DEFAULT_THRESHOLD;
+  const limit = (opts && opts.limit != null) ? opts.limit : DEFAULT_MAX_CANDIDATES;
+  const excludeNumber = opts && opts.excludeNumber;
+
+  const newTokens = tokenize(newTitle);
+  if (newTokens.length === 0) return [];
+
+  const scored = [];
+
+  const safeCandidates = Array.isArray(candidates) ? candidates : [];
+  for (const candidate of safeCandidates) {
+    if (!candidate || typeof candidate !== 'object') continue;
+    if (!(typeof candidate.number === 'number' && Number.isFinite(candidate.number))) continue;
+    if (candidate.number === excludeNumber) continue;
+
+    const score = diceSimilarity(newTokens, tokenize(candidate.title));
+    if (score < threshold) continue;
+
+    scored.push({ number: candidate.number, title: candidate.title, score });
+  }
+
+  scored.sort((a, b) => {
+    if (Math.abs(a.score - b.score) > 1e-9) return b.score - a.score;
+    return a.number - b.number;
+  });
+
+  return scored.slice(0, limit);
+}
+
+// ---------------------------------------------------------------------------
+// renderChallengeComment(candidates, opts) -> string
+//
+// opts: { windowHours=DEFAULT_WINDOW_HOURS }
+//
+// Deterministic. Must start with CHALLENGE_MARKER on its own line. Must list
+// each candidate as a line with #<number>, title, and percentage similarity.
+// Must mention windowHours and the 👎 veto.
+// ---------------------------------------------------------------------------
+
+function renderChallengeComment(candidates, opts) {
+  const windowHours = (opts && opts.windowHours != null) ? opts.windowHours : DEFAULT_WINDOW_HOURS;
+
+  const lines = [CHALLENGE_MARKER, ''];
+
+  lines.push('**Possible duplicate detected.** This issue may already be reported:');
+  lines.push('');
+
+  for (const candidate of candidates) {
+    const pct = Math.round(candidate.score * 100);
+    lines.push(`- #${candidate.number} — ${candidate.title} (similarity ${pct}%)`);
+  }
+
+  lines.push('');
+  lines.push(
+    `If this is **not** a duplicate, react with 👎 on this comment to veto and keep the issue open. ` +
+    `If no response is received within ${windowHours} hours, this issue may be closed as a duplicate.`,
+  );
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// isChallengeComment(body) -> boolean
+//
+// True iff body is a string containing CHALLENGE_MARKER.
+// ---------------------------------------------------------------------------
+
+function isChallengeComment(body) {
+  if (typeof body !== 'string') return false;
+  return body.includes(CHALLENGE_MARKER);
+}
+
+// ---------------------------------------------------------------------------
+// hasExemptLabel(labels) -> boolean
+//
+// labels may be an array of strings or array of {name}. True if any name is
+// in EXEMPT_LABELS.
+// ---------------------------------------------------------------------------
+
+function hasExemptLabel(labels) {
+  if (!Array.isArray(labels)) return false;
+  const exemptSet = new Set(EXEMPT_LABELS);
+  for (const label of labels) {
+    const name = typeof label === 'string' ? label : (label && label.name);
+    if (name && exemptSet.has(name)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// toMs(value) -> number
+//
+// Coerce a Date, ISO string, or ms-number to milliseconds since epoch.
+// ---------------------------------------------------------------------------
+
+function toMs(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'string') return new Date(value).getTime();
+  return Number(value);
+}
+
+// ---------------------------------------------------------------------------
+// shouldClose(input) -> {close: boolean, reason: string}
+//
+// input: { now, labels, challengeComment, laterUserComments, windowHours=DEFAULT_WINDOW_HOURS }
+//
+// Decision order (returns first match):
+//   1. hasExemptLabel(labels)          -> {close:false, reason:'exempt-label'}
+//   2. !challengeComment               -> {close:false, reason:'no-challenge-comment'}
+//   3. challengeComment.downvoted      -> {close:false, reason:'vetoed'}
+//   4. laterUserComments > 0           -> {close:false, reason:'reporter-responded'}
+//   5. ageHours < windowHours          -> {close:false, reason:'within-window'}
+//   6. else                            -> {close:true,  reason:'duplicate-no-response'}
+// ---------------------------------------------------------------------------
+
+function shouldClose(input) {
+  const {
+    now,
+    labels = [],
+    challengeComment,
+    laterUserComments = 0,
+  } = input;
+  const windowHours = (input.windowHours != null) ? input.windowHours : DEFAULT_WINDOW_HOURS;
+
+  if (hasExemptLabel(labels)) {
+    return { close: false, reason: 'exempt-label' };
+  }
+
+  if (!challengeComment) {
+    return { close: false, reason: 'no-challenge-comment' };
+  }
+
+  if (challengeComment.downvoted) {
+    return { close: false, reason: 'vetoed' };
+  }
+
+  if (laterUserComments > 0) {
+    return { close: false, reason: 'reporter-responded' };
+  }
+
+  const nowMs = toMs(now);
+  const createdMs = toMs(challengeComment.createdAt);
+
+  if (!Number.isFinite(nowMs) || !Number.isFinite(createdMs)) {
+    return { close: false, reason: 'invalid-timestamp' };
+  }
+
+  const ageHours = (nowMs - createdMs) / 3600000;
+
+  if (ageHours < windowHours) {
+    return { close: false, reason: 'within-window' };
+  }
+
+  return { close: true, reason: 'duplicate-no-response' };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  POSSIBLE_DUPLICATE_LABEL,
+  HUMAN_REVIEW_LABEL,
+  CHALLENGE_MARKER,
+  DEFAULT_WINDOW_HOURS,
+  DEFAULT_THRESHOLD,
+  DEFAULT_MAX_CANDIDATES,
+  MIN_TOKEN_LENGTH,
+  EXEMPT_LABELS,
+  STOPWORDS,
+  tokenize,
+  diceSimilarity,
+  scoreCandidates,
+  renderChallengeComment,
+  isChallengeComment,
+  hasExemptLabel,
+  shouldClose,
+};

package/scripts/lib/cli-exit.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Error that carries a process exit code. CLI logic throws this instead of
+ * calling process.exit() (banned by n/no-process-exit); runMain() translates it
+ * into process.exitCode at the entrypoint.
+ *
+ * @param {number} code  exit code (default 1)
+ * @param {string} [message]  optional human message; when set and code != 0 it is
+ *   written to stderr by runMain before the process exits.
+ */
+class ExitError extends Error {
+  constructor(code = 1, message) {
+    super(message === undefined ? `process exit ${code}` : message);
+    this.name = 'ExitError';
+    this.code = code;
+    // Whether runMain should print this.message to stderr (only when a real
+    // message was provided, not the synthetic default).
+    this.hasUserMessage = message !== undefined;
+  }
+}
+
+/**
+ * Run a CLI main function and translate its outcome into process.exitCode
+ * (never process.exit(), so n/no-process-exit stays satisfied). Supports sync or
+ * async main.
+ *   - main returns a number  -> process.exitCode = that number
+ *   - main throws/rejects ExitError -> process.exitCode = err.code, and if
+ *       err.hasUserMessage && err.code !== 0, err.message is written to stderr
+ *   - main throws/rejects anything else -> the stack is written to stderr and
+ *       process.exitCode = 1
+ * Letting the event loop drain (vs process.exit) means buffered stdout/stderr is
+ * flushed and process.on('exit') cleanup handlers still fire.
+ *
+ * @param {() => (number|void|Promise<number|void>)} main
+ */
+function runMain(main) {
+  Promise.resolve()
+    .then(() => main())
+    .then((code) => {
+      if (typeof code === 'number') process.exitCode = code;
+    })
+    .catch((err) => {
+      if (err instanceof ExitError) {
+        if (err.hasUserMessage && err.code !== 0) {
+          process.stderr.write(`${err.message}\n`);
+        }
+        process.exitCode = err.code;
+        return;
+      }
+      process.stderr.write(`${err && err.stack ? err.stack : String(err)}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { ExitError, runMain };

package/scripts/lint-command-contract.cjs

@@ -28,6 +28,8 @@ const {
   executionContextRefs: extractExecutionContextRefs,
 } = require('./command-contract-helpers.cjs');
 
+const { runMain } = require('./lib/cli-exit.cjs');
+
 // ─── check one file ───────────────────────────────────────────────────────────
 
 function check(filePath) {
@@ -79,30 +81,34 @@ function check(filePath) {
 
 // ─── run ─────────────────────────────────────────────────────────────────────
 
-const commandFiles = fs
-  .readdirSync(COMMANDS_DIR)
-  .filter(f => f.endsWith('.md'))
-  .map(f => path.join(COMMANDS_DIR, f));
+function main() {
+  const commandFiles = fs
+    .readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(COMMANDS_DIR, f));
 
-const results = commandFiles.map(check).filter(Boolean);
+  const results = commandFiles.map(check).filter(Boolean);
 
-if (results.length === 0) {
-  console.log(
-    `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
-  );
-  process.exit(0);
-}
+  if (results.length === 0) {
+    console.log(
+      `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
+    );
+    return 0;
+  }
 
-const total = results.reduce((n, r) => n + r.violations.length, 0);
-process.stderr.write(
-  `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
-);
-for (const r of results) {
-  process.stderr.write(`  ${r.file}\n`);
-  for (const v of r.violations) {
-    process.stderr.write(`    - ${v}\n`);
+  const total = results.reduce((n, r) => n + r.violations.length, 0);
+  process.stderr.write(
+    `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
+  );
+  for (const r of results) {
+    process.stderr.write(`  ${r.file}\n`);
+    for (const v of r.violations) {
+      process.stderr.write(`    - ${v}\n`);
+    }
+    process.stderr.write('\n');
   }
-  process.stderr.write('\n');
+  process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
+  return 1;
 }
-process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
-process.exit(1);
+
+runMain(main);