@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/check-glossary-refs.cjs

@@ -65,7 +65,7 @@ const TRACKED_PREFIXES = [
 const TRACKED_EXACT = new Set(['bin/install.js', 'package.json']);
 
 /**
- * Paths CONTEXT.md documents whose ABSENCE is the healthy steady state (#2778).
+ * Paths CONTEXT.md documents whose ABSENCE is the healthy steady state.
  *
  * `TRACKED_PREFIXES` skips claims this gate *cannot* check. This is the narrower
  * third case: a claim it must not check, because "does not exist" is the correct
@@ -78,14 +78,43 @@ const TRACKED_EXACT = new Set(['bin/install.js', 'package.json']);
  * shipping an empty stub. So the file is absent on a healthy `next` and present
  * only inside a PR that needs it, and asserting either way is wrong.
  *
- * Until #2778 this passed only by accident: CONTEXT.md's `RULESET.` entries are
- * themselves backtick-wrapped and contain backticks, so the sequential pairing in
- * `extractTrackedRefs` happened to leave this token outside a code span. Any edit
- * that shifted the parity — such as #2778's own — exposed it. A gate that passes
- * by luck is not passing; naming the exemption makes the intent explicit and
- * survives the next edit.
+ * The emitted-attribution family (`tests/fixtures/golden-install-parity`,
+ * `tests/golden-install-parity.test.cjs`, `scripts/gen-golden-install-parity-zcode.cjs`,
+ * `tests/agent-size-baseline.json`, `tests/workflow-size-baseline.json`,
+ * `scripts/git-merge-regen-driver.cjs`, `scripts/update-size-baseline.cjs`) was RETIRED
+ * by the #2724 cutover — the differential attribution check replaced the committed
+ * baselines and their generator/bridge tooling. CONTEXT.md's RULESET.EMITTED_ATTRIBUTION
+ * predicate documents that retirement ("Historically …"), so the mentions are history,
+ * not live claims, and their absence is exactly the healthy state the retirement
+ * produced. The whole documented family is listed, not just the members today's tick
+ * parity happens to hide — the two tooling paths were invisible only because of where
+ * line 585's inner backticks sat, which is the #2778 luck this gate must not rely on.
+ *
+ * `scripts/eslint-rules` appears only inside a CONTRASTIVE mention ("the local
+ * plugin lives at `eslint-rules/` (repo root, NOT `scripts/eslint-rules/`)") — the
+ * predicate asserts where the directory is NOT, so non-existence is the claim
+ * being made, not drift away from one.
+ *
+ * Until #2778 this set's first entry passed only by accident: CONTEXT.md's
+ * `RULESET.` entries are themselves backtick-wrapped and contain backticks, so the
+ * sequential pairing in `extractTrackedRefs` happened to leave this token outside a
+ * code span. Any edit that shifted the parity — such as #2778's own — exposed it.
+ * A gate that passes by luck is not passing; naming the exemption makes the intent
+ * explicit and survives the next edit. #3604 removed the luck itself (pairing is
+ * per line), which is what surfaced the entries above: each names a path whose
+ * absence is deliberate, so each is exempted by name for the same reason.
  */
-const INTENTIONALLY_ABSENT = new Set(['tests/emitted-drift-ack.json']);
+const INTENTIONALLY_ABSENT = new Set([
+  'tests/emitted-drift-ack.json',
+  'tests/fixtures/golden-install-parity',
+  'tests/golden-install-parity.test.cjs',
+  'scripts/gen-golden-install-parity-zcode.cjs',
+  'tests/agent-size-baseline.json',
+  'tests/workflow-size-baseline.json',
+  'scripts/git-merge-regen-driver.cjs',
+  'scripts/update-size-baseline.cjs',
+  'scripts/eslint-rules',
+]);
 
 /**
  * Shape a backticked token must have to even be considered a path candidate:
@@ -119,18 +148,51 @@ function isWithinRoot(token) {
 /**
  * Every distinct, trackable file-path token referenced in `text`, with any
  * trailing `:<line>` suffix stripped.
+ *
+ * #3604: pairing is per LINE, not over the whole text. A single whole-text pass
+ * `[^`]+` crosses newlines, so one odd-backtick line (the `RULESET.*` predicate
+ * format is backtick-wrapped and its values sometimes contain backticks) shifted
+ * the pairing of every later line — a tracked token's visibility depended on
+ * where it sat, which is how a renamed test file stayed invisible for weeks.
+ *
+ * The fact-store predicate lines (one `CLASS.subkey=value` fact per line,
+ * backtick-wrapped as a whole) carry REAL paths in their values; the span itself
+ * is not path-shaped (spaces, `=`), so a second pass harvests path-shaped tracked
+ * tokens from inside any predicate-shaped span rather than letting the outer
+ * wrapper hide them.
+ *
+ * Fragment guards: a real path in this repo never ends in `-` or `.` — those are
+ * remnants of glob/template mentions (`scripts/gen-*.cjs`, `tests/foo.*.test.cjs`)
+ * split at the `*` — and `NNNN` is the ADR filename template token
+ * (CONTRIBUTING's "Do not compute a next number locally"), never a real path.
  */
 function extractTrackedRefs(text) {
   const tokens = new Set();
-  const re = /`([^`]+)`/g;
-  let m;
-  while ((m = re.exec(text)) !== null) {
-    const raw = m[1];
-    if (!PATH_TOKEN_RE.test(raw)) continue;
+  const add = (raw) => {
+    if (!PATH_TOKEN_RE.test(raw)) return;
     const token = raw.replace(/:\d+$/, '');
-    if (!isTracked(token)) continue;
-    if (!isWithinRoot(token)) continue;
+    // Fragment guard, on the EMITTED token (after the :line strip, so
+    // `src/foo-:12` is judged on `src/foo-`): glob/template remnants end in `-`
+    // or `.`, a real path in this repo never does.
+    if (!/[A-Za-z0-9_]$/.test(token)) return;
+    if (token.includes('NNNN')) return;
+    if (!isTracked(token)) return;
+    if (!isWithinRoot(token)) return;
     tokens.add(token);
+  };
+  const subTokenRe = /[\w.-]+(?:\/[\w.-]+)*/g;
+  for (const line of text.split(/\r?\n/)) {
+    const re = /`([^`]+)`/g;
+    let m;
+    while ((m = re.exec(line)) !== null) {
+      const span = m[1];
+      if (PATH_TOKEN_RE.test(span)) {
+        add(span);
+        continue;
+      }
+      if (!/^[A-Z][A-Za-z0-9_.-]*=/.test(span)) continue;
+      for (const sub of span.matchAll(subTokenRe)) add(sub[0]);
+    }
   }
   return tokens;
 }

package/scripts/check-mutation-score-ratchet.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/check-mutation-score-ratchet.cjs
+ *
+ * #3881 follow-up ("one YAML parser" mutation-matrix piece 3): makes each
+ * module's `minScore` floor (scripts/mutation-matrix.cjs COVERED) ratchet
+ * UPWARD instead of sitting wherever it was last hand-set.
+ *
+ * Two halves of "never lowerable without a reasoned marker":
+ *   1. `tests/mutation-matrix-ratchet.test.cjs`'s RATCHET_BASELINE already
+ *      enforces the DOWN side: any change to a module's minScore — up or
+ *      down — must land in the same diff as a matching RATCHET_BASELINE
+ *      edit, making the change visible in code review (mirrors this repo's
+ *      other shrink-only baselines, e.g. scripts/lint-unreachable-guard-drift.cjs's
+ *      $comment convention: a number cannot move silently).
+ *   2. THIS script enforces the UP side: after a real CI Stryker run, if the
+ *      module's ACHIEVED mutation score exceeds its declared floor by more
+ *      than RATCHET_SLACK points, that is not "run-to-run variance" (this
+ *      file's own header documents variance as 1-2 points; see
+ *      scripts/mutation-matrix.cjs's "Floors are measured scores minus 1-2
+ *      pts") — it is unclaimed headroom, and the floor should have been
+ *      raised. Exits 1 telling the author exactly what to raise it to, so a
+ *      module that improves cannot silently keep a stale, low bar forever.
+ *
+ * Consumes Stryker's `json` reporter output (mutation-testing-report-schema
+ * document; stryker.config.mjs's `reporters` includes `'json'`, default path
+ * `reports/mutation/mutation.json`) via `mutation-testing-metrics` — the same
+ * package Stryker itself uses internally to compute a report's score — rather
+ * than re-deriving killed/survived counts by hand.
+ *
+ * Wired into `.github/workflows/mutation.yml`'s `mutate` job as a step AFTER
+ * `npx stryker run`, gated on the shard having passed (a shard that failed
+ * MUTATION_BREAK is a floor problem, not a ratchet problem — Stryker's own
+ * exit code already reports that).
+ *
+ * CLI:
+ *   node scripts/check-mutation-score-ratchet.cjs --module <name> [--report <path>] [--matrix <path>]
+ * `--report` defaults to reports/mutation/mutation.json (Stryker's own default).
+ * `--matrix` defaults to this repo's own scripts/mutation-matrix.cjs; it is an injectable seam
+ * so tests can point the CLI at a synthetic COVERED fixture instead of the real, live-ratcheting
+ * config (see tests/mutation-score-ratchet.test.cjs — a test asserting this script's fail/pass
+ * behaviour must never hardcode a real module's numeric floor, because that floor is exactly
+ * what this mechanism exists to move).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// Slack, in mutation-score points, above a module's declared minScore floor before this
+// ratchet demands the floor be raised. Deliberately larger than the 1-2 point run-to-run
+// TIMEOUT variance margin scripts/mutation-matrix.cjs's floors are already set with (its own
+// header: "Floors are measured scores minus 1-2 pts for run-to-run variance") — that smaller
+// margin is calibrated for the noise BETWEEN two runs of the SAME test list against the SAME
+// source. RATCHET_SLACK instead has to tolerate the noise this file's own history already
+// shows for the frontmatter module across genuine measurement events (63.35 -> 66.67 ->
+// 60.58 -> pending, each a real CI measurement, not pure jitter, spanning >3 points on its
+// own). 5 points sits comfortably above that observed band without being so wide that a
+// module sitting well above TARGET_MUTATION_SCORE (80) could coast for years without its
+// floor ever being asked to move.
+const RATCHET_SLACK = 5;
+
+/**
+ * Pure: does `achievedScore` (0-100) exceed `floor` (minScore) by more than `slack`?
+ * Returns `{ shouldRatchet, suggestedFloor }` — `suggestedFloor` follows the SAME formula
+ * scripts/mutation-matrix.cjs's own header documents for setting a floor from a measured
+ * score: `floor(measured) - 1`.
+ */
+function evaluateRatchet(achievedScore, floor, slack = RATCHET_SLACK) {
+  const shouldRatchet = achievedScore - floor > slack;
+  return {
+    shouldRatchet,
+    suggestedFloor: shouldRatchet ? Math.floor(achievedScore) - 1 : floor,
+  };
+}
+
+/**
+ * Extract the achieved mutation score from a Stryker `json` reporter document via
+ * `mutation-testing-metrics` (the same library Stryker itself uses to compute scores).
+ * Throws a descriptive error if the document has no scoreable mutants at all (an empty
+ * `files` map, or every file having zero mutants) — that is a wiring bug in the caller
+ * (wrong report path, or the shard mutated nothing), never a score of 0.
+ */
+function extractAchievedScore(report) {
+  // Lazy require: this dependency is only needed on the actual score-extraction path, not
+  // when this module is required purely for evaluateRatchet (used by unit tests without the
+  // mutation-testing-metrics package's schema-validation overhead).
+  const { calculateMutationTestMetrics } = require('mutation-testing-metrics');
+  const metrics = calculateMutationTestMetrics(report);
+  const score = metrics && metrics.systemUnderTestMetrics && metrics.systemUnderTestMetrics.metrics
+    ? metrics.systemUnderTestMetrics.metrics.mutationScore
+    : undefined;
+  if (typeof score !== 'number' || Number.isNaN(score)) {
+    throw new Error('mutation report produced no scoreable mutants — check --report points at the right shard\'s reports/mutation/mutation.json');
+  }
+  return score;
+}
+
+function parseArgs(argv) {
+  const out = { module: null, report: 'reports/mutation/mutation.json', matrix: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--module') {
+      out.module = argv[++i];
+    } else if (arg === '--report') {
+      out.report = argv[++i];
+    } else if (arg === '--matrix') {
+      out.matrix = argv[++i];
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!out.module) throw new Error('--module <name> is required');
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const matrixPath = args.matrix ? path.resolve(args.matrix) : path.join(__dirname, 'mutation-matrix.cjs');
+  const { COVERED } = require(matrixPath);
+  const entry = COVERED[args.module];
+  if (!entry) {
+    throw new ExitError(1, `check-mutation-score-ratchet: unknown module '${args.module}' — not in ${args.matrix ? matrixPath : 'scripts/mutation-matrix.cjs'} COVERED`);
+  }
+
+  const reportPath = path.resolve(args.report);
+  if (!fs.existsSync(reportPath)) {
+    throw new ExitError(1, `check-mutation-score-ratchet: report not found at ${reportPath} — run \`npx stryker run\` first (with the 'json' reporter enabled)`);
+  }
+  let report;
+  try {
+    report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+  } catch (err) {
+    throw new ExitError(1, `check-mutation-score-ratchet: ${reportPath} is not valid JSON: ${err.message}`);
+  }
+
+  const achieved = extractAchievedScore(report);
+  const { shouldRatchet, suggestedFloor } = evaluateRatchet(achieved, entry.minScore);
+
+  if (!shouldRatchet) {
+    console.log(`ok mutation-score-ratchet: ${args.module} achieved ${achieved.toFixed(2)}% against floor ${entry.minScore} (within ${RATCHET_SLACK}-point slack)`);
+    return;
+  }
+
+  console.error(`mutation-score-ratchet: ${args.module} achieved ${achieved.toFixed(2)}%, more than ${RATCHET_SLACK} points above its declared floor (${entry.minScore}).`);
+  console.error(`  This is unclaimed headroom, not run-to-run variance — raise the floor.`);
+  console.error(`  remedy: in scripts/mutation-matrix.cjs, set COVERED['${args.module}'].minScore = ${suggestedFloor} (floor(achieved) - 1, this file's own convention),`);
+  console.error(`  and update the matching entry in tests/mutation-matrix-ratchet.test.cjs's RATCHET_BASELINE in the same diff.`);
+  throw new ExitError(1);
+}
+
+module.exports = { RATCHET_SLACK, evaluateRatchet, extractAchievedScore };
+
+if (require.main === module) runMain(main);

package/scripts/ci-check-job-near-cap.cjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const { computeElapsedPct, isNearCap, formatNearCapNotice } = require('./lib/ci-job-timing.cjs');
+
+function run(env = process.env, nowMs = Date.now(), appendFileSync = fs.appendFileSync) {
+  const label = env.CI_JOB_LABEL;
+  const startEpochMs = Number(env.CI_JOB_START_EPOCH_MS);
+  const timeoutMinutes = Number(env.CI_JOB_TIMEOUT_MINUTES);
+
+  if (!label || !Number.isFinite(startEpochMs) || !Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
+    console.error(
+      'ci-check-job-near-cap: missing or invalid CI_JOB_LABEL / CI_JOB_START_EPOCH_MS / '
+      + 'CI_JOB_TIMEOUT_MINUTES — skipping near-cap check (advisory only, not a failure).',
+    );
+    return { skipped: true };
+  }
+
+  const { elapsedMs, capMs, pct } = computeElapsedPct({
+    startedAt: new Date(startEpochMs).toISOString(),
+    completedAt: new Date(nowMs).toISOString(),
+    timeoutMinutes,
+  });
+
+  if (!isNearCap(pct)) {
+    return { skipped: false, nearCap: false, pct };
+  }
+
+  const { warningLine, summaryMarkdown } = formatNearCapNotice({ label, pct, elapsedMs, capMs });
+  console.log(warningLine);
+
+  if (env.GITHUB_STEP_SUMMARY) {
+    try {
+      appendFileSync(env.GITHUB_STEP_SUMMARY, `${summaryMarkdown}\n`);
+    } catch (err) {
+      console.error(`ci-check-job-near-cap: could not write GITHUB_STEP_SUMMARY: ${err.message}`);
+    }
+  }
+
+  return { skipped: false, nearCap: true, pct };
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  run();
+  process.exitCode = 0;
+}

package/scripts/ci-pr-mergeability.cjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+
+// ci-pr-mergeability.cjs — #3833 PR mergeability preflight.
+//
+// Risk asymmetry drives this design: a false positive (a clean PR wrongly
+// classified CONFLICTED) skips every gated compute lane in all eight gated
+// workflows on EVERY PR — a repo-wide outage. A false negative (a real
+// conflict missed) is today's behavior; the per-job scripts/ci-rebase-check.cjs
+// backstop still catches it there. So the weight is entirely on the
+// false-positive surface: the single predicate `mergeable === false`, and
+// every falsy-but-not-false value around it.
+//
+// GitHub's `mergeable` field on GET /repos/:owner/:repo/pulls/:number is a
+// documented tri-state: `true`, `false`, or `null` while a background
+// computation is still running. `null` is falsy — `if (!mergeable)` would
+// misclassify "still computing" as "conflicted" and would have red every PR
+// in the repo the moment this job started running. Only strict `=== false`
+// counts as a conflict.
+//
+// `mergeable_state` is read only for the human-facing annotation, never for
+// the verdict: its `blocked` value means "required checks have not passed",
+// which is true for every PR while THIS preflight job itself is one of the
+// required checks still running — classifying on it would self-deadlock the
+// pipeline (the gate can never go green because it is itself ungreen).
+//
+// Because `mergeable` starts null and GitHub computes it asynchronously, this
+// polls with linear backoff up to a small budget, then fails OPEN
+// (INDETERMINATE => exit 0) rather than blocking the world on an API that
+// hasn't finished thinking.
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const VERDICT = Object.freeze({
+  MERGEABLE: 'MERGEABLE',
+  CONFLICTED: 'CONFLICTED',
+  INDETERMINATE: 'INDETERMINATE',
+  SKIPPED_NOT_A_PR: 'SKIPPED_NOT_A_PR',
+});
+
+const MAX_ATTEMPTS = 5;
+const BASE_DELAY_MS = 2000;
+
+/**
+ * Pure, total classifier: payload -> VERDICT atom. Never throws.
+ * Deliberately reads ONLY `mergeable`, and only with strict equality — see
+ * the header comment for why `mergeable_state` and truthiness are excluded.
+ */
+function classifyMergeability(payload) {
+  if (payload === null || typeof payload !== 'object') return VERDICT.INDETERMINATE;
+  if (payload.mergeable === true) return VERDICT.MERGEABLE;
+  if (payload.mergeable === false) return VERDICT.CONFLICTED;
+  return VERDICT.INDETERMINATE;
+}
+
+/**
+ * Linear backoff: attempt 1..N-1 gives 1x..(N-1)x baseMs. Non-positive/NaN
+ * attempts clamp to one base interval rather than producing 0 or NaN delays.
+ */
+function nextDelayMs(attempt, { baseMs = BASE_DELAY_MS } = {}) {
+  const n = Number.isFinite(attempt) && attempt > 0 ? Math.floor(attempt) : 1;
+  return baseMs * n;
+}
+
+/**
+ * Dependency-injected poll loop. Resolves as soon as GitHub reports a
+ * definite mergeable/conflicted state, or gives up after maxAttempts and
+ * reports INDETERMINATE (fail-open).
+ *
+ * @returns {Promise<{verdict:string, attempts:number, payload:*, reason:string}>}
+ */
+async function resolveMergeability({
+  fetchPr,
+  sleep,
+  eventName,
+  prNumber,
+  maxAttempts = MAX_ATTEMPTS,
+  baseDelayMs = BASE_DELAY_MS,
+} = {}) {
+  if (eventName !== 'pull_request') {
+    return { verdict: VERDICT.SKIPPED_NOT_A_PR, attempts: 0, payload: null, reason: 'not-a-pull-request' };
+  }
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    return { verdict: VERDICT.INDETERMINATE, attempts: 0, payload: null, reason: 'no-pr-number' };
+  }
+
+  let attempts = 0;
+  let lastPayload = null;
+  let lastError = null;
+
+  for (let i = 1; i <= maxAttempts; i++) {
+    attempts = i;
+    let payload;
+    try {
+      payload = await fetchPr(prNumber);
+      lastPayload = payload;
+      lastError = null;
+    } catch (err) {
+      lastError = err;
+      payload = null;
+    }
+
+    const verdict = classifyMergeability(payload);
+    if (verdict === VERDICT.MERGEABLE || verdict === VERDICT.CONFLICTED) {
+      return { verdict, attempts, payload, reason: 'resolved' };
+    }
+
+    if (i < maxAttempts) {
+      await sleep(nextDelayMs(i, { baseMs: baseDelayMs }));
+    }
+  }
+
+  return {
+    verdict: VERDICT.INDETERMINATE,
+    attempts,
+    payload: lastPayload,
+    reason: lastError ? 'fetch-failed' : 'mergeability-not-computed',
+  };
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/ci-pr-mergeability.cjs',
+    '',
+    'CI-only preflight: polls the GitHub API for a PR\'s mergeable state and',
+    'fails the job (exit 1) only on a definite conflict. Everything else',
+    '(unknown, unreadable, not a PR) fails open (exit 0).',
+    '',
+    'Environment variables read:',
+    '  GITHUB_EVENT_NAME    workflow trigger event; only "pull_request" is polled',
+    '  GITHUB_REPOSITORY    owner/repo',
+    '  GITHUB_TOKEN         optional bearer token for the API read',
+    '  GITHUB_BASE_REF      PR base branch name (default: next)',
+    '  GITHUB_API_URL       GitHub API base URL (default: https://api.github.com)',
+    '  PR_NUMBER            the pull request number',
+    '  GITHUB_OUTPUT        path to append verdict=/mergeable= step outputs to',
+    '  GITHUB_STEP_SUMMARY  path to append a human-readable summary to',
+    '  GSD_PR_MERGEABILITY_BASE_DELAY_MS  optional numeric override of the base backoff, for tests',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(`${usage()}\n`);
+      throw new ExitError(0);
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+}
+
+function writeOutput(lines) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (typeof outputPath !== 'string' || outputPath === '') return;
+  try {
+    const fs = require('node:fs');
+    fs.appendFileSync(outputPath, `${lines.join('\n')}\n`);
+  } catch (err) {
+    // A failure while REPORTING the verdict must never invert the gate.
+    process.stderr.write(`::warning::failed to write GITHUB_OUTPUT: ${err.message}\n`);
+  }
+}
+
+function writeSummary(text) {
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (typeof summaryPath !== 'string' || summaryPath === '') return;
+  try {
+    const fs = require('node:fs');
+    fs.appendFileSync(summaryPath, `${text}\n`);
+  } catch (err) {
+    process.stderr.write(`::warning::failed to write GITHUB_STEP_SUMMARY: ${err.message}\n`);
+  }
+}
+
+// `argv` defaults to real CLI argv but is a parameter so tests can call
+// main() in-process (e.g. main([])) without inheriting the test runner's own
+// argv, which would otherwise trip parseArgs's "unknown argument" branch.
+async function main(argv = process.argv.slice(2)) {
+  parseArgs(argv);
+
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  const repo = process.env.GITHUB_REPOSITORY || '';
+  const token = process.env.GITHUB_TOKEN || '';
+  const baseBranch = process.env.GITHUB_BASE_REF || 'next';
+  const apiBase = process.env.GITHUB_API_URL || 'https://api.github.com';
+  const prNumberRaw = process.env.PR_NUMBER;
+  const prNumber = Number.parseInt(prNumberRaw, 10);
+
+  const overrideDelay = Number(process.env.GSD_PR_MERGEABILITY_BASE_DELAY_MS);
+  const baseDelayMs = Number.isFinite(overrideDelay) && overrideDelay >= 0 ? overrideDelay : BASE_DELAY_MS;
+
+  const fetchPr = async (number) => {
+    const url = `${apiBase}/repos/${repo}/pulls/${number}`;
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': 'gsd-core-ci-pr-mergeability',
+    };
+    if (token) headers.authorization = `Bearer ${token}`;
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(10000) });
+    if (!response.ok) {
+      throw new Error(`GitHub API responded ${response.status}`);
+    }
+    const text = await response.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  };
+
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  const result = await resolveMergeability({
+    fetchPr,
+    sleep,
+    eventName,
+    prNumber: Number.isNaN(prNumber) ? NaN : prNumber,
+    maxAttempts: MAX_ATTEMPTS,
+    baseDelayMs,
+  });
+
+  const mergeable = result.verdict === VERDICT.CONFLICTED ? 'false' : 'true';
+  writeOutput([`verdict=${result.verdict}`, `mergeable=${mergeable}`]);
+  writeSummary(`PR mergeability preflight: ${result.verdict}`);
+
+  if (result.verdict === VERDICT.CONFLICTED) {
+    process.stderr.write(
+      `::error::This pull request cannot cleanly merge ${baseBranch}. Rebase onto current ${baseBranch} and push again; no CI will run until the conflict is resolved.\n`,
+    );
+    const state = result.payload && typeof result.payload === 'object' ? result.payload.mergeable_state : undefined;
+    if (state) {
+      process.stderr.write(`::error::mergeable_state: ${state}\n`);
+    }
+    return 1;
+  }
+
+  if (result.verdict === VERDICT.INDETERMINATE) {
+    process.stderr.write(
+      '::warning::GitHub did not report mergeability within the polling budget; proceeding (fail-open). scripts/ci-rebase-check.cjs remains the in-job backstop.\n',
+    );
+    return 0;
+  }
+
+  process.stdout.write(`PR mergeability preflight: ${result.verdict}\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  VERDICT,
+  MAX_ATTEMPTS,
+  BASE_DELAY_MS,
+  classifyMergeability,
+  nextDelayMs,
+  resolveMergeability,
+  main,
+};