@opengsd/gsd-core 1.13.0 → 1.15.0

package/scripts/build-hooks.js

@@ -11,16 +11,25 @@ const path = require('path');
 const vm = require('vm');
 
 const HOOKS_DIR = path.join(__dirname, '..', 'hooks');
+const REPO_ROOT = path.join(HOOKS_DIR, '..');
 const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Per-process staging directory for atomic writes. Using process.pid in the
 // name eliminates all contention between concurrent builders: each process
 // owns its own staging dir and never races with another builder's cleanup.
-// Lives under hooks/ so it shares a filesystem with DIST_DIR (POSIX
-// rename(2) is only atomic within the same filesystem) but is NOT inside
-// DIST_DIR — so readers that readdirSync(DIST_DIR) (e.g. bin/install.js,
-// install-hooks-copy tests) never observe a transient ".tmp" sibling.
-// The parent pattern hooks/.dist-staging-*/ is gitignored.
-const STAGE_DIR = path.join(HOOKS_DIR, `.dist-staging-${process.pid}`);
+// A SIBLING of hooks/ (not inside it) — still on the same filesystem as
+// DIST_DIR (both live under the repo checkout), so rename(2) stays atomic —
+// but this way nothing that walks or copies hooks/ as a whole can ever
+// observe this directory being created/populated/deleted concurrently.
+// tests/gsd-validate-commit-sigpipe.test.cjs's fixture setup does exactly
+// that (fs.cpSync(HOOKS_DIR, ..., {recursive: true})), and when its walk
+// entered a staging dir that a concurrent build-hooks.js run deleted
+// mid-iteration, Node's native recursive-copy (std::filesystem under the
+// hood) threw an uncaught C++ exception and aborted the whole process with
+// SIGABRT — not a catchable JS error. Moving the staging dir out of hooks/
+// closes that race for every current and future hooks/-tree walker, not
+// just that one call site (which also gained its own defensive filter).
+// The parent pattern .dist-staging-*/ (repo root) is gitignored.
+const STAGE_DIR = path.join(REPO_ROOT, `.dist-staging-${process.pid}`);
 
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [

package/scripts/check-contract-drift.cjs

@@ -27,6 +27,10 @@
  *   7. Reverse direction: a workflow/command matching a quoted `## TOKEN`
  *      no agent declares or emits is dispatch-on-phantom
  *      (unmatched_consumer_token) — F9's shape from the consumer side.
+ *   8. Every reference pointer an agent file carries either resolves to
+ *      exactly the regular file it names, contained under
+ *      gsd-core/references/, or is reported (unresolved_reference_include) —
+ *      a pointer the follower declines is never silently dropped (#4930).
  *
  * Exit 0 = clean. Exit 1 = violations (with diagnostics on stderr).
  */
@@ -35,6 +39,9 @@
 
 const fs   = require('fs');
 const path = require('path');
+// The repo's ONE containment decision (ADR-4650, src/security.cts) — realpath-resolved, so an
+// intermediate component referring outside the root is refused before this loop reads the file.
+const { tryWithinRoot } = require('../gsd-core/bin/lib/security.cjs');
 
 function resolveRoot(argv) {
   const idx = argv.indexOf('--root');
@@ -92,8 +99,9 @@ function toRepoRelative(absPath) {
 /**
  * referenceIncludes(content)
  *
- * Plain scan for `@~/.claude/gsd-core/references/*.md` tokens anywhere in an
- * agent file's content -- inside an `<execution_context>` block (already
+ * Plain scan for `@~/.claude/gsd-core/references/*.md` tokens (and the bare
+ * `@gsd-core/references/*.md` spelling, #4841) anywhere in an agent file's
+ * content -- inside an `<execution_context>` block (already
  * covered structurally by `executionContextRefs` in command-contract-helpers,
  * but a raw regex over the whole string picks those up too) and, just as
  * importantly, OUTSIDE one: agents frequently point at a reference doc from
@@ -105,17 +113,94 @@ function toRepoRelative(absPath) {
  * lives in `gsd-core/references/planner-guidance.md`, which the agent only
  * `@`-includes -- so the producer scan below must follow these includes to
  * see markers an agent's contract legitimately delegates to a reference doc.
- * Returns ROOT-relative paths (`gsd-core/references/foo.md`), de-duplicated.
+ * Returns `{ includes, declined }`: `includes` are ROOT-relative paths
+ * (`gsd-core/references/foo.md`), de-duplicated; `declined` are the pointers
+ * this scan refused to follow, as written, each with its reason (#4930).
  */
 function referenceIncludes(content) {
   const seen = new Set();
-  const re = /@~\/\.claude\/gsd-core\/references\/[A-Za-z0-9._-]+\.md/g;
+  const declined = new Map();
+  // Both spellings the agent corpus has carried: the installed-path form the
+  // installer rewrites per profile, and the bare repo-relative `@gsd-core/…`
+  // form (#4841) that it does not. The bare form is now refused in agents/ by
+  // tests/shipped-reference-cites.test.cjs; it is followed here so a pointer
+  // that slips past that gate is still scanned rather than silently dropped.
+  //
+  // THE TOKEN IS CAPTURED WHOLE AND THE NAME GRAMMAR IS ANCHORED AT BOTH ENDS.
+  // Nested names are allowed (`few-shot-examples/verifier.md`); every segment
+  // starts with `[A-Za-z0-9_-]` — narrower than "non-dot", since `+x.md` and
+  // `é.md` do not match either — so a `.` or `..` segment is never a name.
+  // Anchoring is what makes that a statement about the whole pointer rather
+  // than about its first few segments: an earlier form of this pattern ended
+  // at `\.md` with no following boundary, so `…/references/tdd.md/xx/yy` was
+  // followed as `tdd.md`, and THIS FUNCTION'S CALLER READS THE PATH IT
+  // RETURNS — `fs.readFileSync` in main()'s agent loop — so a truncated prefix
+  // folded the wrong file's text into the scanned corpus. Matching the whole
+  // whitespace-delimited token and requiring it to satisfy the grammar end to
+  // end closes that by construction, and for any separator spelling rather
+  // than the ones a boundary lookahead happens to enumerate.
+  //
+  // ANCHORING DOES NOT ESTABLISH CONTAINMENT, and an earlier revision of this
+  // comment said it did. The grammar's refusal of `.`/`..` segments covers the
+  // TEXTUAL half only: an intermediate component that refers outside the tree
+  // is resolved transparently on the way to the file. Containment is decided
+  // separately, below, by `tryWithinRoot` — and it has to be, because this
+  // loop READS what it resolves.
+  //
+  // A token that does not parse WHOLE is declined rather than truncated — the
+  // conservative half of the same rule — and the decline is RETURNED, not
+  // dropped (#4930): main() reports it as unresolved_reference_include. A
+  // skipped pointer is a scan this tool did not perform, and the verdict it
+  // prints depends on that scan, so the skip has to be visible in the tool's
+  // own output. tests/shipped-reference-cites.test.cjs reports the same token
+  // for the shipped agents/ tree; this is the half that holds for any --root.
+  // FOUR spellings. `@$HOME/.claude/` is a second installed-path form the installer rewrites
+  // explicitly (applyAgentPathRewritesInner's `/\$HOME\/\.claude\//g` replace, beside the `~/.claude/`
+  // one). The fourth is a FAMILY rather than a string: `--relative-includes` (#4377) makes a local
+  // install emit project-relative includes whose prefix is DERIVED from the resolved config dir, so it
+  // is matched by SHAPE — one or MORE leading segments before `gsd-core` (a config dir nested under
+  // the project root emits `@config/nested/gsd-core/…`), none of them `.` or `..`. The `+` keeps the
+  // bare form the bare form by construction, since it needs a segment BEFORE `gsd-core`.
+  //
+  // THE SHAPE IS NARROWER THAN THE FAMILY, and saying otherwise would be the overstatement this
+  // function has already had to retract once. `_computePathPrefix` can emit a prefix this character
+  // class does not match — a config dir named `config+nested` or `ümlaut` — and widening the class to
+  // arbitrary directory names is what would turn every `@scope/…` token in prose into a pointer. So a
+  // prefix outside the class is not followed, which is where this follower was for ALL
+  // project-relative spellings before #4841. The gate's own comment states the same bound; the two
+  // must not drift apart, because between them they are the only record of it.
+  const re = /@(?:(?:~|\$HOME)\/\.claude\/|(?:(?!\.\.?\/)[A-Za-z0-9._-]+\/)+)?gsd-core\/references\/(\S+)/g;
+  const name = /^(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*\.md$/;
+  // Trailing prose punctuation is not part of a filename — a pointer may end a
+  // sentence or sit inside backticks, parentheses or bold markers. The class
+  // cannot eat into `.md`, which ends at `d`.
+  // START-ANCHORED: this tests a CUT SUFFIX, so it must be punctuation END TO END. An unanchored
+  // `/…$/` answers true for `/xx?`, which would let the loop cut a separator and call the remainder a
+  // name — `tdd.md/xx?` following as `tdd.md`, the defect this whole function was rewritten to close.
+  const trailingProseOnly = /^[.,;:!?)\]}>"'`*]+$/;
   let m;
   while ((m = re.exec(content)) !== null) {
-    const relPath = 'gsd-core/references/' + m[0].slice('@~/.claude/gsd-core/references/'.length);
-    seen.add(relPath);
+    const raw = m[1];
+    // MINIMAL strip, same rule as the gate: shortest trailing run whose removal yields a valid name.
+    let candidate = null;
+    for (let cut = 0; cut <= raw.length; cut++) {
+      const probe = raw.slice(0, raw.length - cut);
+      if (cut > 0 && !trailingProseOnly.test(raw.slice(raw.length - cut))) break;
+      if (name.test(probe)) { candidate = probe; break; }
+    }
+    if (candidate === null) {
+      declined.set(m[0], 'does not name a reference whole — the text continues past the name, so nothing is followed');
+      continue;
+    }
+    // AMBIGUITY, mirrored from the gate. If the UNSTRIPPED token also names something, the strip would
+    // pick one of two readings — and this loop READS what it picks, so it declines rather than guess.
+    if (candidate !== raw && fs.existsSync(path.join(ROOT, 'gsd-core', 'references', raw))) {
+      declined.set(m[0], `is ambiguous — \`${raw}\` itself names something on disk, so stripping it to \`${candidate}\` would pick one of two readings; neither is followed`);
+      continue;
+    }
+    seen.add('gsd-core/references/' + candidate);
   }
-  return [...seen];
+  return { includes: [...seen], declined: [...declined].map(([pointer, reason]) => ({ pointer, reason })) };
 }
 
 function remedyFor(kind) {
@@ -158,9 +243,13 @@ function main() {
   const candidateMarkers = new Map();
   const agentTexts = new Map();
   const unclosedFenceViolations = [];
+  const includeViolations = [];
 
+  // #4407: .compact.md variant siblings are an alternate rendering of their
+  // canonical agent's SAME contract, not a distinct one — excluded so they
+  // don't need (and can't drift from) their own registry row.
   const agentFiles = fs.existsSync(AGENTS_DIR)
-    ? fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'))
+    ? fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md') && !f.endsWith('.compact.md'))
     : [];
 
   for (const file of agentFiles) {
@@ -170,12 +259,41 @@ function main() {
     // Single pass over the agent's @-included references: each file is read
     // once and feeds BOTH the read-tag fold (agentTexts) and marker
     // extraction (producer/candidate attribution).
+    // #4930: every include this loop does NOT fold in is reported, never
+    // swallowed. An unfollowed include is text the marker verdict below was
+    // computed without, so a decline that leaves no trace in the output makes
+    // that verdict unexplainable. (lint-command-contract's @-ref existence rule
+    // covers commands' <execution_context> only, not agents.)
     const includeTexts = [];
-    for (const refRelPath of referenceIncludes(content)) {
+    const reportInclude = (pointer, reason) => includeViolations.push({
+      kind: 'unresolved_reference_include',
+      agent,
+      marker: null,
+      detail: `${toRepoRelative(abs)}: ${pointer} ${reason}`,
+    });
+    const { includes, declined } = referenceIncludes(content);
+    for (const { pointer, reason } of declined) reportInclude(pointer, reason);
+    for (const refRelPath of includes) {
+      // CONTAIN BEFORE READ. The name grammar refuses `.`/`..` segments, which covers the TEXTUAL
+      // half of containment and nothing else: an intermediate path component that refers outside
+      // the tree is resolved transparently on the way to the file, so a textually-clean name can
+      // still address something outside `references/`. This loop READS what it resolves and folds
+      // the text into the scanned corpus, so the real path is what has to be checked.
+      const refsDir = path.join(ROOT, 'gsd-core', 'references');
+      const contained = tryWithinRoot(refRelPath.slice('gsd-core/references/'.length), refsDir);
+      if (contained === null) {
+        reportInclude(refRelPath, 'does not resolve inside gsd-core/references/');
+        continue;
+      }
       try {
-        includeTexts.push(fs.readFileSync(path.join(ROOT, refRelPath), 'utf-8'));
-      } catch {
-        // include miss — lint-command-contract rule 4 owns @-ref existence
+        // Read the ContainedPath the predicate returned, never a re-joined path (ADR-4650).
+        if (!fs.lstatSync(contained).isFile()) {
+          reportInclude(refRelPath, 'is not a regular file');
+          continue;
+        }
+        includeTexts.push(fs.readFileSync(contained, 'utf-8'));
+      } catch (e) {
+        reportInclude(refRelPath, e && e.code === 'ENOENT' ? 'does not exist' : `could not be read (${e && e.code})`);
       }
     }
     agentTexts.set(agent, [content, ...includeTexts].join('\n'));
@@ -234,6 +352,7 @@ function main() {
   const allViolations = [
     ...parseViolations,
     ...unclosedFenceViolations,
+    ...includeViolations,
     ...contractViolationsList,
     ...readTagViolationsList,
     ...reverseViolationsList,

package/scripts/check-env.cjs

@@ -30,7 +30,17 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { describeNpmVersionCheckFailure } = require('./lib/npm-version-check-diagnosis.cjs');
 
+// #4460 follow-up: check-env.cjs runs as its own standalone CI step BEFORE
+// `npm ci` / `npm run build:lib` (a deliberate pre-flight, run before there
+// is even a node_modules to build with) -- confirmed the hard way, by a
+// MODULE_NOT_FOUND crash on every real CI platform after a first attempt at
+// this fix routed the npm-version check through the canonical execNpm seam
+// (gsd-core/bin/lib/shell-command-projection.cjs), a tsc-compiled artifact
+// that plain does not exist yet at that point in the pipeline. This file
+// must stay self-contained: no requires reaching into gsd-core/bin/lib.
+//
 // On Windows, npm ships as npm.cmd (a batch wrapper); spawnSync without
 // shell:true requires the exact filename including extension.
 const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
@@ -180,18 +190,36 @@ function main() {
   // Check 2: npm version vs engines.npm (skip if field absent)
   // ---------------------------------------------------------------------------
   const enginesNpm = pkgField('engines.npm', PROJECT_ROOT);
-  let currentNpm = '';
-  try {
-    const res = spawnSync(npmCmd, ['--version'], { encoding: 'utf8', timeout: 10_000, shell: process.platform === 'win32' });
-    if (res.status === 0 && res.stdout) {
-      currentNpm = res.stdout.trim();
-    }
-  } catch { /* ignore */ }
+  // #4460: 15_000ms, not the original 10_000 -- matches the default this
+  // repo's canonical (but here unusable, see the file-header note above)
+  // execNpm seam already uses for npm subprocess calls generally, rather
+  // than inventing a new number. Confirmed via real Windows CI: a 10s
+  // window was insufficient twice under ~51-file concurrent test load.
+  const NPM_VERSION_TIMEOUT_MS = 15_000;
+  // No try/catch needed: spawnSync's documented contract routes ENOENT and a
+  // timeout-triggered kill through the RETURNED result's `.error` field, not
+  // a thrown exception -- there is nothing here for a catch to intercept.
+  const npmVersionSpawn = spawnSync(npmCmd, ['--version'], { encoding: 'utf8', timeout: NPM_VERSION_TIMEOUT_MS, shell: process.platform === 'win32' });
+  const npmVersionResult = {
+    exitCode: npmVersionSpawn.status ?? 1,
+    stdout: (npmVersionSpawn.stdout || '').toString().trim(),
+    signal: npmVersionSpawn.signal ?? null,
+    error: npmVersionSpawn.error ?? null,
+    // Canonical cross-platform timeout predicate (matches this repo's
+    // execNpm/isSpawnTimeout convention, src/shell-command-projection.cts):
+    // error.code === 'ETIMEDOUT', which Node's spawnSync guarantees when its
+    // own `timeout` option fires. Checking `signal === 'SIGTERM'` instead
+    // (what an earlier version of this fix did) is platform-fragile -- that
+    // module's own docstring flags a Windows-specific false-negative risk,
+    // the exact platform this bug was discovered on.
+    timedOut: (npmVersionSpawn.error && npmVersionSpawn.error.code === 'ETIMEDOUT') === true,
+  };
+  const currentNpm = npmVersionResult.exitCode === 0 && npmVersionResult.stdout ? npmVersionResult.stdout : '';
 
   if (!enginesNpm) {
     addCheck('npm-version', 'skip', 'engines.npm not set in package.json — skipping');
   } else if (!currentNpm) {
-    addCheck('npm-version', 'fail', 'npm binary not found on PATH');
+    addCheck('npm-version', 'fail', describeNpmVersionCheckFailure(npmVersionResult));
   } else {
     if (satisfiesConstraint(currentNpm, enginesNpm)) {
       addCheck('npm-version', 'pass', `npm ${currentNpm} satisfies ${enginesNpm}`);

package/scripts/check-glossary-refs.cjs

@@ -37,6 +37,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { tryWithinRoot, PathAcceptance } = require('../gsd-core/bin/lib/security.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const CONTEXT_PATH = path.join(ROOT, 'CONTEXT.md');
@@ -131,20 +132,6 @@ function isTracked(token) {
   return TRACKED_EXACT.has(token) || TRACKED_PREFIXES.some((prefix) => token.startsWith(prefix));
 }
 
-/**
- * True if joining `token` to ROOT stays inside ROOT. `PATH_TOKEN_RE` admits `.`
- * inside a segment, so a token like `src/../../../etc/passwd` matches and (via
- * the `src/` prefix) reads as "tracked" — `path.join(ROOT, token)` would then
- * normalize to an out-of-tree absolute path and `fs.existsSync` would probe it,
- * turning a doc lint into a filesystem-existence oracle on the CI host. A
- * CONTEXT.md reference is always a plain in-repo path, so a `..` escape is never
- * legitimate: confine to ROOT and drop anything that climbs out.
- */
-function isWithinRoot(token) {
-  const resolved = path.resolve(ROOT, token);
-  return resolved === ROOT || resolved.startsWith(ROOT + path.sep);
-}
-
 /**
  * Every distinct, trackable file-path token referenced in `text`, with any
  * trailing `:<line>` suffix stripped.
@@ -167,7 +154,11 @@ function isWithinRoot(token) {
  * (CONTRIBUTING's "Do not compute a next number locally"), never a real path.
  */
 function extractTrackedRefs(text) {
-  const tokens = new Set();
+  // Maps token -> the ContainedPath tryWithinRoot returned for it. ADR-4650:
+  // the value that was validated for containment must be the exact value
+  // that gets probed later — never a path re-derived (e.g. re-joined) from
+  // the token, which could diverge from what was actually checked.
+  const tokens = new Map();
   const add = (raw) => {
     if (!PATH_TOKEN_RE.test(raw)) return;
     const token = raw.replace(/:\d+$/, '');
@@ -177,8 +168,18 @@ function extractTrackedRefs(text) {
     if (!/[A-Za-z0-9_]$/.test(token)) return;
     if (token.includes('NNNN')) return;
     if (!isTracked(token)) return;
-    if (!isWithinRoot(token)) return;
-    tokens.add(token);
+    // Containment decision is the canonical predicate's, per ADR-4650. Carry
+    // the returned ContainedPath forward so checkFileRefs stats the SAME
+    // value that was validated, instead of re-joining `token` onto ROOT.
+    //
+    // The containment ANSWER is unchanged from the retired lexical-only
+    // `isWithinRoot`, but the canonical predicate resolves symlinks, so a
+    // rejected token is now realpath-resolved before being rejected rather
+    // than rejected by string comparison alone; the result is still never
+    // surfaced and the token is never stat'd unless it is contained.
+    const contained = tryWithinRoot(token, ROOT, PathAcceptance.AbsoluteInsideRoot);
+    if (contained === null) return;
+    tokens.set(token, contained);
   };
   const subTokenRe = /[\w.-]+(?:\/[\w.-]+)*/g;
   for (const line of text.split(/\r?\n/)) {
@@ -199,14 +200,17 @@ function extractTrackedRefs(text) {
 
 /** Check A: every tracked reference must resolve on disk. */
 function checkFileRefs(contextText) {
-  const tokens = [...extractTrackedRefs(contextText)].sort();
+  const entries = [...extractTrackedRefs(contextText)].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
   const findings = [];
-  for (const token of tokens) {
-    if (!fs.existsSync(path.join(ROOT, token))) {
+  for (const [token, contained] of entries) {
+    // Stat the ContainedPath returned by tryWithinRoot — NOT a re-joined
+    // path.join(ROOT, token) — so the path that was validated for
+    // containment is the path that is probed (ADR-4650).
+    if (!fs.existsSync(contained)) {
       findings.push(`CONTEXT.md references \`${token}\` which does not exist in the repo.`);
     }
   }
-  return { findings, checked: tokens.length };
+  return { findings, checked: entries.length };
 }
 
 /** The glossary's own claim: `Runtime enum: `allRuntimes` (N values: a, b, c)`. */

package/scripts/ci-next-health.cjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+'use strict';
+
+// ci-next-health.cjs — #4422 base-branch health gate.
+//
+// Risk asymmetry drives this design, same shape as scripts/ci-pr-mergeability.cjs
+// but pointed the other direction: on 2026-09-06 three unrelated PRs merged on
+// top of an already-broken `next` before anyone noticed, because nothing checked
+// the base branch's OWN health before letting a PR land on it. A false positive
+// here (a healthy `next` wrongly reported RED) blocks every PR merge in the repo
+// until a human notices and applies the `fix-next` bypass label — annoying, but
+// loud and immediately actionable. A false negative (a broken `next` reported
+// healthy) reproduces the #4422 incident exactly. So, unlike the mergeability
+// preflight, this gate does NOT fail open on a definite red signal — it fails
+// open only when the signal itself is unavailable or inapplicable (wrong event,
+// no resolvable base ref, an API read that throws). Once GitHub actually answers
+// with a non-success conclusion for the base branch's last push-triggered Tests
+// run, that is treated as authoritative and blocks — with one explicit, visible,
+// human-operated escape hatch (the `fix-next` label) for the PR that is itself
+// the fix-forward.
+//
+// Every non-success conclusion (`failure`, `cancelled`, `timed_out`,
+// `action_required`, ...) is treated as RED, not just `failure` — a cancelled or
+// timed-out run on the base branch is not evidence the branch is healthy, it is
+// evidence nobody knows yet.
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const VERDICT = Object.freeze({
+  CLEAN: 'CLEAN',
+  RED: 'RED',
+  BYPASSED: 'BYPASSED',
+  SKIPPED_NOT_APPLICABLE: 'SKIPPED_NOT_APPLICABLE',
+  INDETERMINATE: 'INDETERMINATE',
+});
+
+const APPLICABLE_EVENTS = new Set(['pull_request', 'merge_group']);
+const BYPASS_LABEL = 'fix-next';
+const TESTS_WORKFLOW_FILE = 'test.yml';
+
+/**
+ * Pure, total classifier: the GitHub "list workflow runs" response payload ->
+ * CLEAN | RED | INDETERMINATE. Never throws.
+ *
+ * - Not an object, or `workflow_runs` isn't an array -> INDETERMINATE: the
+ *   shape we depend on is not present, so nothing can be concluded.
+ * - No completed push runs found yet (e.g. a brand-new `release/**`/`hotfix/**`
+ *   branch with no Tests history) -> CLEAN: absence of evidence of red is not
+ *   evidence of red, and a brand-new branch must not be permanently unmergeable.
+ * - The most recent run's `conclusion === 'success'` -> CLEAN.
+ * - Anything else (failure, cancelled, timed_out, action_required, ...) -> RED.
+ */
+function classifyRunConclusion(payload) {
+  if (payload === null || typeof payload !== 'object') return VERDICT.INDETERMINATE;
+  if (!Array.isArray(payload.workflow_runs)) return VERDICT.INDETERMINATE;
+  if (payload.workflow_runs.length === 0) return VERDICT.CLEAN;
+  const [latest] = payload.workflow_runs;
+  if (latest && latest.conclusion === 'success') return VERDICT.CLEAN;
+  return VERDICT.RED;
+}
+
+/**
+ * Dependency-injected orchestrator. `fetchLatestRun` is an async function
+ * taking the resolved base branch name and returning the parsed API payload
+ * (or throwing) — injected so tests never touch the network.
+ *
+ * @returns {Promise<{verdict:string, payload:*, reason:string}>}
+ */
+async function resolveNextHealth({ fetchLatestRun, eventName, baseRef, labels } = {}) {
+  if (!APPLICABLE_EVENTS.has(eventName)) {
+    return { verdict: VERDICT.SKIPPED_NOT_APPLICABLE, payload: null, reason: 'not-applicable-event' };
+  }
+
+  if (typeof baseRef !== 'string' || baseRef.trim() === '') {
+    return { verdict: VERDICT.INDETERMINATE, payload: null, reason: 'no-base-ref' };
+  }
+
+  let payload = null;
+  try {
+    payload = await fetchLatestRun(baseRef);
+  } catch (err) {
+    return { verdict: VERDICT.INDETERMINATE, payload: null, reason: `fetch-failed: ${err.message}` };
+  }
+
+  const classified = classifyRunConclusion(payload);
+  if (classified !== VERDICT.RED) {
+    return { verdict: classified, payload, reason: 'resolved' };
+  }
+
+  // Escape hatch. `labels` is empty/absent for merge_group — that event has no
+  // label surface today, which means a queued merge-group commit cannot use
+  // this bypass. Known gap, not solved here: a maintainer must land the
+  // fix-forward as a direct pull_request merge (where the label IS readable)
+  // rather than through the merge queue, until GitHub exposes an equivalent
+  // signal for merge_group.
+  const labelList = Array.isArray(labels) ? labels : [];
+  if (labelList.includes(BYPASS_LABEL)) {
+    return { verdict: VERDICT.BYPASSED, payload, reason: 'bypass-label' };
+  }
+
+  return { verdict: VERDICT.RED, payload, reason: 'red' };
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/ci-next-health.cjs',
+    '',
+    'CI-only gate: checks whether the PR/merge-group\'s base branch\'s own last',
+    'push-triggered Tests run is red, and fails the job (exit 1) when it is —',
+    'unless the PR carries the "fix-next" bypass label. Every other case',
+    '(wrong event, no resolvable base ref, an unreadable API read) fails open',
+    '(exit 0).',
+    '',
+    'Environment variables read:',
+    '  GITHUB_EVENT_NAME     workflow trigger event; only "pull_request" and',
+    '                        "merge_group" are checked',
+    '  GITHUB_REPOSITORY     owner/repo',
+    '  GITHUB_TOKEN          optional bearer token for the API read',
+    '  GITHUB_BASE_REF       PR base branch name (pull_request events; set',
+    '                        automatically by GitHub Actions)',
+    '  MERGE_GROUP_BASE_REF  merge-group base ref (merge_group events; the',
+    '                        caller workflow must populate this from',
+    '                        github.event.merge_group.base_ref — a leading',
+    '                        "refs/heads/" prefix is stripped if present)',
+    '  GITHUB_API_URL        GitHub API base URL (default: https://api.github.com)',
+    '  PR_LABELS             comma-separated PR label names (pull_request events;',
+    '                        the caller workflow must populate this from',
+    '                        github.event.pull_request.labels.*.name); checked',
+    '                        for the literal "fix-next" bypass label',
+    '  GITHUB_OUTPUT         path to append verdict= step output to',
+    '  GITHUB_STEP_SUMMARY   path to append a human-readable summary to',
+  ].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`);
+  }
+}
+
+function resolveBaseRef(eventName) {
+  if (eventName === 'pull_request') {
+    return process.env.GITHUB_BASE_REF || '';
+  }
+  if (eventName === 'merge_group') {
+    const raw = process.env.MERGE_GROUP_BASE_REF || '';
+    return raw.startsWith('refs/heads/') ? raw.slice('refs/heads/'.length) : raw;
+  }
+  return '';
+}
+
+function parseLabels(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+  return raw.split(',').map((s) => s.trim()).filter((s) => s !== '');
+}
+
+function runUrlOf(payload) {
+  const run = payload && Array.isArray(payload.workflow_runs) ? payload.workflow_runs[0] : undefined;
+  return run && typeof run.html_url === 'string' ? run.html_url : '(unknown run URL)';
+}
+
+// `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 apiBase = process.env.GITHUB_API_URL || 'https://api.github.com';
+  const baseRef = resolveBaseRef(eventName);
+  const labels = parseLabels(process.env.PR_LABELS);
+
+  const fetchLatestRun = async (branch) => {
+    const url = `${apiBase}/repos/${repo}/actions/workflows/${TESTS_WORKFLOW_FILE}/runs`
+      + `?branch=${encodeURIComponent(branch)}&event=push&status=completed&per_page=1`;
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': 'gsd-core-ci-next-health',
+    };
+    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 result = await resolveNextHealth({ fetchLatestRun, eventName, baseRef, labels });
+
+  writeOutput([`verdict=${result.verdict}`]);
+  writeSummary(`Base branch health: ${result.verdict}`);
+
+  if (result.verdict === VERDICT.RED) {
+    const runUrl = runUrlOf(result.payload);
+    process.stderr.write(
+      `::error::the base branch "${baseRef}"'s own last Tests run is red: ${runUrl} — `
+      + 'wait for a fix-forward merge, or if THIS pull request is the fix, ask a '
+      + `maintainer to apply the "${BYPASS_LABEL}" label to explicitly override this gate.\n`,
+    );
+    return 1;
+  }
+
+  if (result.verdict === VERDICT.BYPASSED) {
+    const runUrl = runUrlOf(result.payload);
+    process.stderr.write(
+      `::warning::the base branch "${baseRef}"'s own last Tests run is red: ${runUrl} — `
+      + `a human applied the "${BYPASS_LABEL}" label to explicitly override this gate.\n`,
+    );
+    return 0;
+  }
+
+  if (result.verdict === VERDICT.INDETERMINATE) {
+    process.stderr.write(
+      `::warning::could not determine "${baseRef || '(no base ref)'}"'s Tests health (${result.reason}); `
+      + 'proceeding (fail-open).\n',
+    );
+    return 0;
+  }
+
+  process.stdout.write(`Base branch health: ${result.verdict}\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  VERDICT,
+  BYPASS_LABEL,
+  TESTS_WORKFLOW_FILE,
+  classifyRunConclusion,
+  resolveNextHealth,
+  main,
+};