@therocketcode/gsd-core 1.4.0

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/allowlist-ratchet.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * @file allowlist-ratchet.cjs
+ *
+ * Reusable "better than a count ratchet" primitives for CI guards.
+ *
+ * ## Motivation (issue #597)
+ *
+ * A count ratchet (`assert(offenders.length <= N)`) has a masking blind spot:
+ * fixing one offender and introducing a new one keeps the count constant, so a
+ * novel defect slips through green.  These helpers enforce on IDENTITY instead,
+ * making every individual offender visible and requiring monotonic progress
+ * toward zero.
+ *
+ * ## Design
+ *
+ * Both functions are pure (no I/O, no global state).  The `fail` callback is
+ * injected by the caller so the same logic can be used with `node:assert.fail`,
+ * a custom throw, or a message-collector in unit tests.
+ */
+
+/**
+ * Assert that `current` offenders are all within the known allowlist, and that
+ * every entry in the allowlist still offends (forcing the allowlist to shrink
+ * as defects are fixed).
+ *
+ * Fails when:
+ * - Any id in `current` is NOT in `known` → novel offender introduced.
+ * - Any id in `known` is NOT in `current` → stale allowlist entry must be
+ *   pruned so the guard ratchets toward zero (the ratchet-DOWN direction).
+ *
+ * ## Masking blind spot this prevents (issue #597)
+ *
+ * A count ratchet (`assert(count <= N)`) allows one offender to be silently
+ * replaced by another while the count stays at N.  By asserting on identity
+ * instead, every new offender is caught by name, and every fixed offender
+ * forces the allowlist to shrink.
+ *
+ * @param {object} opts
+ * @param {string}   opts.label      - Human-readable name for the guard (used
+ *                                     in failure messages).
+ * @param {Iterable<string>} opts.current - The offending ids found in the
+ *                                     current run.
+ * @param {Iterable<string>} opts.known   - The allowlisted ids (baseline).
+ * @param {function(string): void} opts.fail - Callback invoked with a
+ *                                     descriptive message on any violation.
+ *                                     Pass `require('node:assert').fail`, a
+ *                                     custom thrower, or a collector.  The
+ *                                     function is NOT imported here so callers
+ *                                     control the failure mode.
+ * @param {string}  [opts.pruneHint] - Optional hint appended to the stale-
+ *                                     entry failure message (e.g. the name of
+ *                                     the allowlist file to edit).
+ * @returns {{ novel: string[], stale: string[] }} Sorted arrays of novel ids
+ *   (in current but not known) and stale ids (in known but not current).
+ */
+function assertWithinAllowlist({ label, current, known, fail, pruneHint }) {
+  const currentSet = new Set(current);
+  const knownSet = new Set(known);
+
+  const novel = [...currentSet].filter((id) => !knownSet.has(id)).sort();
+  const stale = [...knownSet].filter((id) => !currentSet.has(id)).sort();
+
+  if (novel.length > 0) {
+    const list = novel.map((id) => `  - ${id}`).join('\n');
+    fail(
+      `[${label}] ${novel.length} NEW offender(s) introduced — fix at the source; do not just add to the allowlist.\n${list}`
+    );
+  }
+
+  if (stale.length > 0) {
+    const list = stale.map((id) => `  - ${id}`).join('\n');
+    const hint = pruneHint ? `\n(${pruneHint})` : '';
+    fail(
+      `[${label}] ${stale.length} allowlisted id(s) no longer offend and MUST be pruned so the guard ratchets toward zero.${hint}\n${list}`
+    );
+  }
+
+  return { novel, stale };
+}
+
+/**
+ * Assert that an artifact's measured maximum stays within a declared ceiling,
+ * and that the ceiling itself does not creep above the high-water mark (budgets
+ * may only decrease, not increase over time).
+ *
+ * Fails when:
+ * - `actualMax > ceiling`           → regression: artifact exceeds budget.
+ * - `ceiling - actualMax > grace`   → ceiling sits too far above the measured
+ *                                     value; tighten it toward `actualMax`.
+ *
+ * ## Masking blind spot this prevents (issue #597)
+ *
+ * A plain `assert(size <= ceiling)` with a ceiling set generously high allows
+ * the artifact to grow unchecked as long as it stays under the ceiling.  The
+ * `grace` band forces the ceiling to stay close to the high-water mark,
+ * ensuring that any upward creep is immediately visible.
+ *
+ * @param {object} opts
+ * @param {string}   opts.label     - Human-readable name for the guard (used
+ *                                    in failure messages).
+ * @param {number}   opts.actualMax - The measured value (e.g. bundle size in
+ *                                    bytes, line count).
+ * @param {number}   opts.ceiling   - The declared budget ceiling.
+ * @param {number}   opts.grace     - Maximum allowed slack (`ceiling -
+ *                                    actualMax`) before the ceiling is
+ *                                    considered too loose.
+ * @param {function(string): void} opts.fail - Callback invoked with a
+ *                                    descriptive message on any violation.
+ * @returns {{ ok: boolean, slack: number }} Whether both checks passed and the
+ *   current slack value.
+ */
+function assertTightCeiling({ label, actualMax, ceiling, grace, fail }) {
+  const slack = ceiling - actualMax;
+  let ok = true;
+
+  if (actualMax > ceiling) {
+    ok = false;
+    fail(
+      `[${label}] Regression: artifact value ${actualMax} exceeds budget ceiling ${ceiling}. ` +
+        `Raise the ceiling to at most ${actualMax} only if the increase is justified.`
+    );
+  } else if (slack > grace) {
+    ok = false;
+    fail(
+      `[${label}] Ceiling ${ceiling} sits too far above the high-water mark ${actualMax} ` +
+        `(slack ${slack} > grace ${grace}). Tighten the ceiling toward ${actualMax}. ` +
+        `Budgets may only decrease.`
+    );
+  }
+
+  return { ok, slack };
+}
+
+module.exports = { assertWithinAllowlist, assertTightCeiling };

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

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * lint-command-contract.cjs  (ADR-0002)
+ *
+ * Enforces the commands/gsd/*.md contract across all 65 command files:
+ *
+ *   1. name:        present, non-empty, matches gsd: or gsd- prefix
+ *   2. description: present, non-empty
+ *   3. allowed-tools: block present, non-empty, all entries from CANONICAL_TOOLS
+ *   4. execution_context @-refs: every @-reference resolves to an existing file on disk
+ *   5. execution_context @-refs: each appears on its own line (no trailing prose)
+ *
+ * Exit 0 = clean. Exit 1 = violations (with diagnostics).
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT          = path.join(__dirname, '..');
+const COMMANDS_DIR  = path.join(ROOT, 'commands', 'gsd');
+const GSD_ROOT      = path.join(ROOT, 'gsd-core');
+
+const {
+  CANONICAL_TOOLS,
+  parseFrontmatter,
+  executionContextRefs: extractExecutionContextRefs,
+} = require('./command-contract-helpers.cjs');
+
+const { runMain } = require('./lib/cli-exit.cjs');
+
+// ─── check one file ───────────────────────────────────────────────────────────
+
+function check(filePath) {
+  const content  = fs.readFileSync(filePath, 'utf-8');
+  const rel      = path.relative(ROOT, filePath);
+  const fm       = parseFrontmatter(content);
+  const violations = [];
+
+  // 1. name: present + gsd: / gsd- prefix
+  if (!fm.name || !fm.name.trim()) {
+    violations.push('name: field missing or empty');
+  } else if (!/^gsd[:-]/.test(fm.name.trim())) {
+    violations.push(`name: must start with "gsd:" or "gsd-", got "${fm.name.trim()}"`);
+  }
+
+  // 2. description: present + non-empty
+  if (!fm.description || !fm.description.trim()) {
+    violations.push('description: field missing or empty');
+  }
+
+  // 3. allowed-tools: present + non-empty + all entries canonical
+  if (!fm['allowed-tools'] || !fm['allowed-tools'].trim()) {
+    violations.push('allowed-tools: block missing or empty');
+  } else {
+    const tools = fm['allowed-tools'].split('\n').map(t => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      const valid =
+        CANONICAL_TOOLS.has(tool) ||
+        (tool.startsWith('mcp__context7__') && CANONICAL_TOOLS.has('mcp__context7__*'));
+      if (!valid) violations.push(`allowed-tools: unknown tool "${tool}"`);
+    }
+  }
+
+  // 4+5. execution_context @-refs resolve + no trailing prose
+  const refs = extractExecutionContextRefs(content);
+  for (const { token, normalized, trailingProse } of refs) {
+    const absPath = path.join(GSD_ROOT, normalized);
+    if (!fs.existsSync(absPath)) {
+      violations.push(`execution_context: @-ref "${normalized}" does not exist on disk`);
+    }
+    if (trailingProse) {
+      violations.push(`execution_context: @-ref "${token}" has trailing prose on the same line`);
+    }
+  }
+
+  if (violations.length === 0) return null;
+  return { file: rel, violations };
+}
+
+// ─── run ─────────────────────────────────────────────────────────────────────
+
+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);
+
+  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`);
+    }
+    process.stderr.write('\n');
+  }
+  process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
+  return 1;
+}
+
+runMain(main);

package/scripts/lint-descriptions.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * lint-descriptions.cjs
+ *
+ * Enforces the 100-char description budget for commands/gsd/*.md files.
+ *
+ * Usage:
+ *   node scripts/lint-descriptions.cjs [file.md ...]
+ *
+ * If no args are given, scans commands/gsd/ automatically.
+ * Exits 1 if any description exceeds 100 chars; exits 0 if all pass.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const MAX_LENGTH = 100;
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+
+/**
+ * Parse the description field from frontmatter in a .md file.
+ * Returns null if no description is found.
+ */
+function parseDescription(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+
+  const quoted = fm.match(/^description:\s+"((?:[^"\\]|\\.)*)"\s*$/m);
+  if (quoted) return quoted[1];
+
+  const plain = fm.match(/^description:\s+(.+)$/m);
+  if (plain) return plain[1].trim();
+
+  return null;
+}
+
+function getFiles() {
+  if (process.argv.length > 2) {
+    return process.argv.slice(2);
+  }
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(COMMANDS_DIR, f));
+}
+
+function main() {
+  const files = getFiles();
+  const violations = [];
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      throw new ExitError(1, `ERROR: Cannot read file: ${filePath}\n  ${err.message}`);
+    }
+
+    const description = parseDescription(content);
+    if (description === null) continue;
+
+    if (description.length > MAX_LENGTH) {
+      violations.push({ filePath, length: description.length, description });
+    }
+  }
+
+  if (violations.length === 0) {
+    const checked = files.length;
+    process.stdout.write(`ok lint-descriptions: ${checked} file(s) checked, 0 violations\n`);
+    return 0;
+  }
+
+  process.stderr.write(`\nERROR lint-descriptions: ${violations.length} violation(s) found\n\n`);
+  for (const v of violations) {
+    const preview = v.description.length > 120 ? v.description.slice(0, 117) + '...' : v.description;
+    process.stderr.write(`  ${v.filePath}\n`);
+    process.stderr.write(`    Length : ${v.length} (max ${MAX_LENGTH})\n`);
+    process.stderr.write(`    Desc   : ${preview}\n\n`);
+  }
+  process.stderr.write(`Trim descriptions to <= ${MAX_LENGTH} chars. Flag docs belong in argument-hint:.\n\n`);
+  return 1;
+}
+
+runMain(main);