@pareto4/pp-core 1.5.0

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/generate-package-identity.cjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Single source for GSD's published-package coordinates (issue #498).
+ *
+ * `deriveIdentity(pkg)` is the pure core: it turns a parsed package.json into
+ * the coordinate record every consumer needs. The generated runtime module
+ * `pp-core/bin/lib/package-identity.cjs` bakes those values at build
+ * time, because the installed tree carries only a synthetic
+ * `{"type":"commonjs"}` package.json (no `.name`) — so a runtime
+ * `require('package.json').name` resolves to `undefined` (the #378 bug this
+ * seam retires). Baking from package.json reconciles #378 (renames survive)
+ * with #2992 (the value is never an LLM runtime choice).
+ */
+
+/**
+ * Parse `owner/name` out of a package.json `repository.url`, stripping the
+ * `git+` prefix and `.git` suffix npm conventionally adds.
+ */
+function parseRepoSlug(repository) {
+  const url = typeof repository === 'string' ? repository : (repository && repository.url) || '';
+  const m = url.replace(/^git\+/, '').replace(/\.git$/, '').match(/((?:github|gitlab)\.com)[/:]([^/]+\/[^/]+)$/);
+  return m ? m[2] : '';
+}
+
+// Extract the git host (github.com or gitlab.com) from a repository URL
+function parseRepoHost(repository) {
+  const url = typeof repository === 'string' ? repository : (repository && repository.url) || '';
+  const m = url.replace(/^git\+/, '').replace(/\.git$/, '').match(/((?:github|gitlab)\.com)[/:]([^/]+\/[^/]+)$/);
+  return m ? m[1] : 'github.com';
+}
+
+/**
+ * Pure: turn an npm package name into a filesystem-safe slug for cache filenames.
+ * Strips a leading `@`, replaces `/` with `-`, then collapses any run of
+ * characters that are NOT `[a-z0-9]` to a single `-`, and trims leading/trailing `-`.
+ */
+function slugifyPackageName(name) {
+  if (!name) return '';
+  return name
+    .replace(/^@/, '')
+    .replace(/\//g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Pure: package.json object -> the package identity coordinates.
+ */
+function deriveIdentity(pkg = {}) {
+  const packageName = pkg.name || '';
+  const binName = pkg.bin ? Object.keys(pkg.bin)[0] || '' : '';
+  const repoSlug = parseRepoSlug(pkg.repository);
+  const repoHost = parseRepoHost(pkg.repository);
+  const isGitHub = repoHost === 'github.com';
+  const repoUrl = repoSlug ? `https://${repoHost}/${repoSlug}` : '';
+  const changelogRawUrl = repoSlug && isGitHub
+    ? `https://raw.githubusercontent.com/${repoSlug}/main/CHANGELOG.md`
+    : repoSlug ? `https://${repoHost}/${repoSlug}/-/raw/main/CHANGELOG.md` : '';
+  const cacheSlug = slugifyPackageName(packageName);
+  const updateCacheFileName = cacheSlug ? `pp-update-check-${cacheSlug}.json` : 'pp-update-check.json';
+  return { packageName, binName, repoSlug, repoUrl, changelogRawUrl, cacheSlug, updateCacheFileName };
+}
+
+/**
+ * Pure: format the `npx` fallback install command. Shape matches the literal
+ * the update workflow embeds: `npx -y --package=<pkg>@latest -- <bin>
+ * [--<runtime>] --<scope>`. The runtime flag is omitted when not supplied.
+ *
+ * This function is the canonical source — `render()` serializes it verbatim
+ * into the generated module, so the runtime copy can never drift from it.
+ */
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+const GENERATED_HEADER =
+  '// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.\n' +
+  '// Single source for PP package coordinates (issue #498). Regenerate with:\n' +
+  '//   node scripts/generate-package-identity.cjs\n';
+
+/**
+ * Render the generated runtime module text for a derived identity. Values are
+ * baked as literals; `formatManualInstall` is embedded by `.toString()` so the
+ * runtime command builder is byte-identical to the tested source above.
+ */
+function render(identity) {
+  const { packageName, binName, repoSlug, repoUrl, changelogRawUrl, cacheSlug, updateCacheFileName } = identity;
+  const j = (v) => JSON.stringify(v);
+  return (
+    GENERATED_HEADER +
+    "'use strict';\n\n" +
+    `const packageName = ${j(packageName)};\n` +
+    `const binName = ${j(binName)};\n` +
+    `const repoSlug = ${j(repoSlug)};\n` +
+    `const repoUrl = ${j(repoUrl)};\n` +
+    `const changelogRawUrl = ${j(changelogRawUrl)};\n` +
+    `const cacheSlug = ${j(cacheSlug)};\n` +
+    `const updateCacheFileName = ${j(updateCacheFileName)};\n\n` +
+    `${formatManualInstall.toString()}\n\n` +
+    'function manualInstallCommand(opts = {}) {\n' +
+    '  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });\n' +
+    '}\n\n' +
+    'module.exports = Object.freeze({\n' +
+    '  packageName,\n' +
+    '  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it\n' +
+    "  // survives the installed tree's synthetic package.json (fixes the #378 undefined).\n" +
+    '  PACKAGE_NAME: packageName,\n' +
+    '  binName,\n' +
+    '  repoSlug,\n' +
+    '  repoUrl,\n' +
+    '  changelogRawUrl,\n' +
+    '  cacheSlug,\n' +
+    '  updateCacheFileName,\n' +
+    '  manualInstallCommand,\n' +
+    '});\n'
+  );
+}
+
+function main() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  const out = path.join(__dirname, '..', 'pp-core', 'bin', 'lib', 'package-identity.cjs');
+  fs.writeFileSync(out, render(deriveIdentity(pkg)));
+  process.stdout.write(`wrote ${path.relative(path.join(__dirname, '..'), out)}\n`);
+}
+
+if (require.main === module) main();
+
+module.exports = { deriveIdentity, parseRepoSlug, slugifyPackageName, formatManualInstall, render, 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,
+};