@opengsd/gsd-core 1.14.0 → 1.16.0

package/scripts/command-contract-helpers.cjs

@@ -12,6 +12,11 @@
  * enforced by both consumers.
  */
 
+// The one frontmatter fence owner (src/frontmatter-fence.cts, built to bin/lib by
+// build:lib). Every consumer of this module runs after the build: lint:ci (CI builds
+// bin/lib first) and the test suite (pretest).
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
+
 const CANONICAL_TOOLS = new Set([
   'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
   'Task', 'Agent', 'Skill', 'SlashCommand',
@@ -22,16 +27,15 @@ const CANONICAL_TOOLS = new Set([
 ]);
 
 function parseFrontmatter(content) {
-  // CRLF-tolerant split: Windows checkouts (autocrlf=true) leave a trailing
-  // \r on every line, making lines.indexOf('---', 1) return -1 (the value
-  // would be '---\r', not '---') → returns {} → every field appears missing.
-  const lines = content.split(/\r?\n/);
-  if (lines[0].trim() !== '---') return {};
-  const end = lines.indexOf('---', 1);
-  if (end === -1) return {};
+  // The block is the one the one fence owner finds (found while implementing
+  // #5105) — BOM, CRLF (a Windows autocrlf checkout), an adjacent empty block
+  // and a `----` look-alike all read exactly as every runtime reader sees them.
+  // Its lines are split CRLF-tolerantly so a trailing \r never leaks into a value.
+  const fence = locateFrontmatterFence(content);
+  if (!fence || !fence.closed) return {};
   const fm = {};
   let key = null;
-  for (const line of lines.slice(1, end)) {
+  for (const line of content.slice(fence.openEnd, fence.bodyEnd).split(/\r?\n/)) {
     const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
     if (kv) { key = kv[1]; fm[key] = kv[2].trim(); }
     else if (key && line.match(/^\s+-\s+/)) {
@@ -890,6 +894,7 @@ const VIOLATION_KINDS = Object.freeze({
   LEGACY_READ_TAG: 'legacy_read_tag',
   READ_TAG_GATE_MISSING: 'read_tag_gate_missing',
   UNMATCHED_CONSUMER_TOKEN: 'unmatched_consumer_token',
+  UNRESOLVED_REFERENCE_INCLUDE: 'unresolved_reference_include',
 });
 
 /**
@@ -925,6 +930,8 @@ const REMEDIES = Object.freeze({
     "add the <required_reading> MUST-Read gate clause to this agent's instructions (see docs/AGENTS.md)",
   unmatched_consumer_token:
     'declare the producing agent and marker in the registry, or remove the dispatch — nothing emits this token',
+  unresolved_reference_include:
+    'fix the gsd-core/references/ pointer so it names an existing reference file whole and ends at the name (whitespace, end of line, or closing punctuation)',
 });
 
 /**

package/scripts/docs-guard-registry.cjs

@@ -174,6 +174,7 @@ const DOCS_GUARD_TESTS = {
   // entry).
   'tests/learnings.test.cjs': ['docs/FEATURES.md'],
   'tests/analyze-dependencies.test.cjs': ['docs/COMMANDS.md'],
+  'tests/auto-select-attribute.test.cjs': ['docs/reference/plan-md.md'],
   'tests/autonomous-converge.test.cjs': [
     'docs/COMMANDS.md',
     'docs/how-to/run-phases-autonomously.md',
@@ -200,6 +201,9 @@ const DOCS_GUARD_TESTS = {
   'tests/compact-content-4139.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/config-field-docs.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/config.test.cjs': ['docs/CONFIGURATION.md'],
+  // #4974: doc/workflow content-parity checks read docs/CONFIGURATION.md's
+  // Gate Settings section directly (see tests/gates-confirmation-toggle-config.test.cjs).
+  'tests/gates-confirmation-toggle-config.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/context-index-sync.test.cjs': ['docs/CONTEXT-INDEX.json'],
   'tests/context-predicates-query.test.cjs': ['docs/contributor-standards.md'],
   // SCAN_DIRS includes 'docs' and recursively walks every .md file under it
@@ -272,6 +276,32 @@ const DOCS_GUARD_TESTS = {
   // seeding, so a content edit to any of them (e.g. renaming a landmark
   // heading/string a hostile-input test targets) can change this test's
   // fixture assumptions.
+  // #4728: pins the retirement of Gemini CLI prose from every localized
+  // how-to/ARCHITECTURE/USER-GUIDE/CONFIGURATION/context-monitor mirror, plus
+  // the PRESERVE (Antigravity) and MODEL-AXIS (Gemini 2.5 Pro) negative-space
+  // checks in the same locales.
+  'tests/gemini-runtime-removed.test.cjs': [
+    'docs/ja-JP/how-to/install-on-your-runtime.md',
+    'docs/ko-KR/how-to/install-on-your-runtime.md',
+    'docs/pt-BR/how-to/install-on-your-runtime.md',
+    'docs/zh-CN/how-to/install-on-your-runtime.md',
+    'docs/ja-JP/ARCHITECTURE.md',
+    'docs/ko-KR/ARCHITECTURE.md',
+    'docs/pt-BR/ARCHITECTURE.md',
+    'docs/zh-CN/ARCHITECTURE.md',
+    'docs/ja-JP/USER-GUIDE.md',
+    'docs/ko-KR/USER-GUIDE.md',
+    'docs/pt-BR/USER-GUIDE.md',
+    'docs/zh-CN/USER-GUIDE.md',
+    'docs/ja-JP/CONFIGURATION.md',
+    'docs/ko-KR/CONFIGURATION.md',
+    'docs/pt-BR/CONFIGURATION.md',
+    'docs/zh-CN/CONFIGURATION.md',
+    'docs/ja-JP/context-monitor.md',
+    'docs/ko-KR/context-monitor.md',
+    'docs/pt-BR/context-monitor.md',
+    'docs/zh-CN/context-monitor.md',
+  ],
   'tests/gen-state-md-docs.test.cjs': [
     'docs/reference/state-md.md',
     'docs/ja-JP/reference/state-md.md',
@@ -376,6 +406,7 @@ const DOCS_GUARD_TESTS = {
     'docs/how-to/plan-a-phase.md',
     'docs/AGENTS.md',
   ],
+  'tests/ui-interaction-capture.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/ui-spec-inventory-provenance.test.cjs': [
     'docs/FEATURES.md',
     'docs/how-to/design-a-ui-phase.md',
@@ -390,6 +421,9 @@ const DOCS_GUARD_TESTS = {
   'tests/verifier-behavior-unverified.test.cjs': ['docs/reference/planning-artifacts.md'],
   'tests/verifier-coincidental-reliance.test.cjs': ['docs/AGENTS.md'],
   'tests/verify.test.cjs': ['docs/reference/plan-md.md'],
+  // #5118 V43: asserts the deleted execute-phase/steps/stale-reverification.md
+  // is absent from the generated inventory manifest.
+  'tests/verify-lifecycle-writes-e2e.test.cjs': ['docs/INVENTORY-MANIFEST.json'],
   'tests/workflow-fragments.test.cjs': ['docs/reference/workflow-fragments.md'],
 };
 

package/scripts/gen-features.cjs

@@ -66,6 +66,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+// The one frontmatter fence owner (src/frontmatter-fence.cts, built by build:lib).
+// Every entry point runs after the build: lint:generated-sync inside lint:ci (CI
+// builds bin/lib first), regen:derived (`npm run build` first), and the tests.
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const FEATURES_DIR = path.join(ROOT, 'docs', 'features');
@@ -255,13 +259,12 @@ function renderFrontmatter(data, body) {
  */
 function parseFrontmatter(text) {
   const normalized = String(text).replace(/\r\n/g, '\n');
-  if (!normalized.startsWith('---\n')) return { data: null, body: normalized };
-
-  const end = normalized.indexOf('\n---\n', 3);
-  if (end === -1) return { data: null, body: normalized };
+  // The block is the one the one fence owner finds (found while implementing #5105).
+  const fence = locateFrontmatterFence(normalized);
+  if (!fence || !fence.closed) return { data: null, body: normalized };
 
   const data = {};
-  for (const line of normalized.slice(4, end + 1).split('\n')) {
+  for (const line of normalized.slice(fence.openEnd, fence.bodyEnd).split('\n')) {
     if (line.trim() === '') continue;
     const sep = line.indexOf(':');
     if (sep === -1) continue;
@@ -270,9 +273,11 @@ function parseFrontmatter(text) {
     data[key] = parseScalar(line.slice(sep + 1).trim());
   }
 
-  // `+5` clears "\n---\n"; the blank line renderFrontmatter emits after the
-  // closing fence is consumed here so body text starts at its first real line.
-  let body = normalized.slice(end + 5);
+  // Past the closing fence line and its line ending; the blank line
+  // renderFrontmatter emits after the closing fence is consumed here so body
+  // text starts at its first real line.
+  let body = normalized.slice(fence.closingFenceEnd);
+  if (body.startsWith('\n')) body = body.slice(1);
   if (body.startsWith('\n')) body = body.slice(1);
   return { data, body };
 }

package/scripts/gen-hooks-cli-exit.cjs

@@ -18,6 +18,17 @@
  * target (`.js`, not `.cjs`, to match the hooks/lib/*.js convention) would
  * tangle a script that is otherwise simple and single-purpose.
  *
+ * compileToTemp() itself IS shared (required from ./gen-scripts-cli-exit.cjs)
+ * rather than duplicated: it compiles only src/cli-exit.cts (via a throwaway
+ * tsconfig that extends tsconfig.build.json with files/include scoped to
+ * that one module) rather than the whole project, since the emit this
+ * script needs depends only on cli-exit.cts's own import closure. A
+ * whole-project `-p tsconfig.build.json` type-check of every .cts file under
+ * a fixed COMPILE_TIMEOUT_MS ceiling can get killed by that timeout on a
+ * CPU-contended shared bench even though the one file this script needs
+ * compiles in a fraction of the time — and the compile strategy itself has
+ * nothing sibling-specific to fork.
+ *
  * Usage:
  *   node scripts/gen-hooks-cli-exit.cjs            # same as --write
  *   node scripts/gen-hooks-cli-exit.cjs --write     # write hooks/lib/cli-exit.js
@@ -35,14 +46,12 @@
 
 'use strict';
 
-const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { compileToTemp } = require('./gen-scripts-cli-exit.cjs');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 const OUTPUT_PATH = path.join(REPO_ROOT, 'hooks', 'lib', 'cli-exit.js');
-const COMPILE_TIMEOUT_MS = 60_000;
 
 /** Frozen reason codes so tests assert on structure, not prose. */
 const REASON = Object.freeze({
@@ -78,31 +87,6 @@ const BANNER = [
   '',
 ].join('\n');
 
-/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
-function compileToTemp() {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-hooks-cli-exit-'));
-  try {
-    execFileSync(
-      process.execPath,
-      [
-        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
-        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
-        '--outDir', tmp,
-        // A throwaway outDir must not reuse the in-tree incremental state, or
-        // tsc skips emit for files it believes are already current.
-        '--incremental', 'false',
-        '--tsBuildInfoFile', 'null',
-      ],
-      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe', timeout: COMPILE_TIMEOUT_MS },
-    );
-    return { ok: true, dir: tmp };
-  } catch (err) {
-    fs.rmSync(tmp, { recursive: true, force: true });
-    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
-    return { ok: false, detail };
-  }
-}
-
 /**
  * Compile src/cli-exit.cts to a throwaway outDir and return the expected
  * generated content (banner + compiled bytes, with the sibling registry

package/scripts/gen-loop-host-contract.cjs

@@ -37,7 +37,16 @@ const STEP_WORKFLOWS = [
       { file: 'quick.md', point: 'plan:pre', kinds: ['contribution'], into: 'planner' },
     ],
   },
-  { file: 'execute-phase.md', step: 'execute' },
+  {
+    file: 'execute-phase.md',
+    step: 'execute',
+    // #5118: execute:post's step AND gate dispatch (code_review_gate with
+    // its TDD escalation) lives in the ONE shared verification step that
+    // execute-phase includes (and verify-work includes too) — no per-caller copy.
+    auxiliaryHosts: [
+      { file: 'execute-phase/steps/verify-phase-goal.md', point: 'execute:post', kinds: ['step', 'gate'] },
+    ],
+  },
   { file: 'verify-work.md',   step: 'verify' },
   { file: 'ship.md',          step: 'ship' },
 ];
@@ -78,6 +87,23 @@ const ROLE_TO_AGENT = {
   verifier:   'gsd-verifier',
 };
 
+// #4740 — Role → family mapping. Three families: orchestration, planning,
+// execution. This constrains what a workflow may DECLARE in agent-roles for
+// a given step (admissibility), a separate concern from ROLE_TO_AGENT's
+// agent-file presence check above.
+const ROLE_FAMILY = {
+  orchestrator: 'orchestration',
+  researcher: 'planning', planner: 'planning', checker: 'planning',
+  executor: 'execution', verifier: 'execution',
+};
+const EXPECTED_FAMILY_BY_STEP = {
+  discuss: 'orchestration',
+  plan: 'planning',
+  execute: 'execution',
+  verify: 'orchestration',
+  ship: 'orchestration',
+};
+
 // ─── Parser ───────────────────────────────────────────────────────────────────
 
 /**
@@ -228,6 +254,52 @@ function crossCheckRoles(content, agentRoles, fileName) {
   return errors;
 }
 
+// ─── Cross-check: declared roles vs. their permitted family (#4740) ──────────
+
+/**
+ * For a step, verify every role declared in agentRoles belongs to that step's
+ * expected family (orchestration / planning / execution).
+ *
+ * Unlike `assertPointsCoverage`'s `if (!expected) continue // caught
+ * elsewhere` guard, an unknown step here fails CLOSED: for points
+ * there is a second net (the canonical-set and duplicate checks), but nothing
+ * else in the repo validates role families, so failing open on an unknown
+ * step would make it the one input that silently bypasses this gate — the
+ * "unknown resolving to a safe known" failure mode this check exists to close.
+ *
+ * Pure: never sorts, de-dupes, or otherwise mutates `agentRoles` — the same
+ * array `buildContract` puts into the generated contract.
+ *
+ * @param {string}   step        The step named in the marker block.
+ * @param {string[]} agentRoles  Roles declared in the block.
+ * @param {string}   fileName    For error messages.
+ * @returns {string[]}           Array of error strings; empty = OK.
+ */
+function crossCheckRoleFamilies(step, agentRoles, fileName) {
+  const expectedFamily = EXPECTED_FAMILY_BY_STEP[step];
+  if (!expectedFamily) {
+    return [fileName + ': step "' + step + '" has no entry in EXPECTED_FAMILY_BY_STEP'];
+  }
+
+  const errors = [];
+  for (const role of agentRoles) {
+    const family = ROLE_FAMILY[role];
+    if (!family) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" has no entry in ROLE_FAMILY mapping',
+      );
+      continue;
+    }
+    if (family !== expectedFamily) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" (family "' + family +
+        '") is not permitted at step "' + step + '" (expected family "' + expectedFamily + '")',
+      );
+    }
+  }
+  return errors;
+}
+
 // ─── 12-points coverage assertion ────────────────────────────────────────────
 
 /**
@@ -331,6 +403,10 @@ function buildContract(workflowsDir) {
     const roleErrors = crossCheckRoles(content, entry.agentRoles, file);
     allErrors.push(...roleErrors);
 
+    // Cross-check role families (#4740)
+    const roleFamilyErrors = crossCheckRoleFamilies(entry.step, entry.agentRoles, file);
+    allErrors.push(...roleFamilyErrors);
+
     for (const auxiliary of auxiliaryHosts) {
       let auxiliaryContent;
       try {
@@ -667,6 +743,7 @@ function getWiredLoopPoints(repoRoot) {
 module.exports = {
   parseLoopHostBlock,
   crossCheckRoles,
+  crossCheckRoleFamilies,
   assertPointsCoverage,
   buildContract,
   serializeContract,
@@ -676,6 +753,7 @@ module.exports = {
   CANONICAL_POINTS,
   EXPECTED_POINTS_BY_STEP,
   ROLE_TO_AGENT,
+  ROLE_FAMILY,
   scanWiredPoints,
   getWiredLoopPoints,
   coveredKindsInRegion,

package/scripts/gen-platform-conformance-tier.cjs

@@ -97,6 +97,26 @@
  * point the CLI at a small temp fixture tree instead of this repo's real,
  * 900+-file tests/ tree. Production usage (package.json's lint:generated-sync
  * / regen:derived chains) passes no flags and gets the real repo paths.
+ *
+ * #5074 — the `.platform` sibling rule. A handful of the heaviest tier files
+ * carry their real Windows signal in only a few tests out of hundreds; the
+ * fix is to move those tests into a same-directory `X.platform.test.cjs`
+ * sibling of `X.test.cjs`, so only the sibling (not the whole base) needs
+ * real-OS coverage. That split is enforced here as a FAILING invariant
+ * (`findPlatformSplitViolations`, wired into `classifyTree`) rather than as a
+ * silent filename-based exclusion rule, for two reasons: epic #4589 Phase 2
+ * requires real-OS overrides to be centrally enumerated, not implied by a
+ * naming convention (a bare "base excluded whenever a sibling exists" rule
+ * would BE such a convention); and a platform-sensitive test later added
+ * back into a split base must not silently re-admit the whole base to
+ * Linux-only on the Windows tier — it must fail generation loudly instead, at
+ * the same `lint:generated-sync` gate this module already backs. This
+ * invariant is scoped to the Windows CATEGORIES and wired only into
+ * `classifyTree`; `classifyMacosTree` stays pure content selection by design,
+ * so a macOS-only signal (e.g. case-sensitivity wording) left in a split base
+ * re-admits that base to the macOS tier instead of failing — over-inclusion,
+ * the safe direction. See docs/how-to/split-platform-sensitive-tests.md for
+ * the authoring rules this invariant enforces.
  */
 
 const fs = require('node:fs');
@@ -316,6 +336,140 @@ function classifyMacosContent(content) {
   return { needsRealOs: signals.length > 0, signals };
 }
 
+/**
+ * The `.platform` sibling suffix (#5074). A sibling of `X.test.cjs` is a file
+ * whose basename ENDS with this suffix and has a non-empty stem before it —
+ * `foo.platform.test.cjs` is a sibling of `foo.test.cjs`, but a bare
+ * `platform.test.cjs` (empty stem) is not, and neither is a hyphenated name
+ * like `x-platform.test.cjs` or `platform-conformance-tier.test.cjs` (this
+ * module's own test file) — the rule keys on the literal dotted suffix, not
+ * on the substring "platform" appearing anywhere in the name.
+ */
+const PLATFORM_SIBLING_SUFFIX = '.platform.test.cjs';
+
+/**
+ * Parse `rel` (a POSIX `tests/...`-relative path) as a `.platform` sibling.
+ * Returns `{ dir, stem }` when it is one (dir is the POSIX dirname, stem is
+ * the basename with `PLATFORM_SIBLING_SUFFIX` stripped), or `null` when it is
+ * not — either because the basename does not end with the suffix, or because
+ * the stem would be empty (the `platform.test.cjs` negative-space case).
+ *
+ * @param {string} rel
+ * @returns {{ dir: string, stem: string } | null}
+ */
+function parsePlatformSibling(rel) {
+  const dir = path.posix.dirname(rel);
+  const base = path.posix.basename(rel);
+  if (!base.endsWith(PLATFORM_SIBLING_SUFFIX)) return null;
+  const stem = base.slice(0, -PLATFORM_SIBLING_SUFFIX.length);
+  if (stem.length === 0) return null;
+  return { dir, stem };
+}
+
+/** Resolve `X.test.cjs`'s rel path for a `.platform` sibling's `{ dir, stem }`. */
+function baseRelFor({ dir, stem }) {
+  return (dir === '.' ? '' : dir + '/') + stem + '.test.cjs';
+}
+
+/** Resolve `X.platform.test.cjs`'s rel path for a base rel path (inverse of baseRelFor). */
+function siblingRelForBase(baseRel) {
+  const dir = path.posix.dirname(baseRel);
+  const stem = path.posix.basename(baseRel).slice(0, -'.test.cjs'.length);
+  return (dir === '.' ? '' : dir + '/') + stem + PLATFORM_SIBLING_SUFFIX;
+}
+
+/**
+ * The `.platform` sibling invariant (#5074), pure over an explicit `entries`
+ * array so it can be driven directly against fixtures (and against the real
+ * `ALWAYS_REAL_OS` map, which no temp fixture tree can key into) without
+ * touching the filesystem. `entries` is the ELIGIBLE (unit-suite) test-file
+ * set — a suite-tagged base is never a member, which is what makes it
+ * "never eligible" per the design doc's negative space rather than something
+ * this function has to special-case.
+ *
+ * For every `.platform` sibling present in `entries` (see
+ * `parsePlatformSibling`), checks three independent things against its base
+ * (`X.test.cjs`, same directory):
+ *   - `base-has-signal`   — the base IS in `entries` and still carries a
+ *     genuine Windows signal (`classifyContent` on its own content) — the
+ *     split did not actually remove the signal from the base.
+ *   - `sibling-without-signal` — the sibling's OWN content carries no
+ *     Windows signal, regardless of whether its base exists — a `.platform`
+ *     file whose header claims a platform reason the classifier cannot see
+ *     in its own text.
+ *   - `base-always-real-os` — the base is a key of `alwaysRealOs`: the
+ *     escape hatch says the WHOLE base needs real-OS coverage, which
+ *     contradicts splitting only some of its tests into a sibling.
+ *
+ * A base that is absent from `entries` (suite-tagged, deleted, or renamed)
+ * never triggers `base-has-signal` — there is nothing to read.
+ *
+ * @param {{rel: string, content: string}[]} entries
+ * @param {Map<string, string>} [alwaysRealOs]
+ * @returns {{file: string, kind: 'base-has-signal'|'sibling-without-signal'|'base-always-real-os', signals: string[]}[]}
+ *   sorted by file, then kind.
+ */
+function findPlatformSplitViolations(entries, alwaysRealOs = ALWAYS_REAL_OS) {
+  const byRel = new Map(entries.map((entry) => [entry.rel, entry]));
+  const violations = [];
+
+  for (const entry of entries) {
+    const parsed = parsePlatformSibling(entry.rel);
+    if (!parsed) continue;
+    const baseRel = baseRelFor(parsed);
+
+    const base = byRel.get(baseRel);
+    if (base !== undefined) {
+      const { signals } = classifyContent(base.content);
+      if (signals.length > 0) {
+        violations.push({ file: baseRel, kind: 'base-has-signal', signals });
+      }
+    }
+
+    const { signals: siblingSignals } = classifyContent(entry.content);
+    if (siblingSignals.length === 0) {
+      violations.push({ file: entry.rel, kind: 'sibling-without-signal', signals: [] });
+    }
+
+    if (alwaysRealOs.has(baseRel)) {
+      violations.push({ file: baseRel, kind: 'base-always-real-os', signals: [] });
+    }
+  }
+
+  violations.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind < b.kind ? -1 : 1;
+    return 0;
+  });
+  return violations;
+}
+
+/**
+ * Render `findPlatformSplitViolations`' result as the Error message
+ * `classifyTree` throws: starts with the literal phrase callers/tests grep
+ * for, lists one line per violation (file, kind, residual signal names, and
+ * — for `base-has-signal` only — the sibling path those tests belong in),
+ * and points at the how-to doc for the authoring rules.
+ *
+ * @param {ReturnType<typeof findPlatformSplitViolations>} violations
+ * @returns {string}
+ */
+function formatPlatformSplitViolations(violations) {
+  const lines = violations.map((v) => {
+    let line = `  - ${v.file} [${v.kind}]`;
+    if (v.signals.length > 0) line += ` residual signal(s): ${v.signals.join(', ')}`;
+    if (v.kind === 'base-has-signal') {
+      line += ` — move these tests into ${siblingRelForBase(v.file)}`;
+    }
+    return line;
+  });
+  return (
+    `platform split invariant violated (#5074) — ${violations.length} file(s):\n` +
+    lines.join('\n') +
+    '\nSee docs/how-to/split-platform-sensitive-tests.md for the split-invariant rules.\n'
+  );
+}
+
 /**
  * Recursively collect every `*.test.cjs` file beneath `dir`.
  * @param {string} dir
@@ -355,10 +509,15 @@ function classifyTree(testsDir) {
   // tier — see the header doc-comment for why suite-tagged files are excluded
   // entirely rather than merely deprioritized.
   const unitFiles = absoluteFiles.filter((absPath) => suiteOf(absPath) === null);
+  const entries = [];
   const flagged = [];
   for (const absPath of unitFiles) {
     const rel = 'tests/' + path.relative(testsDir, absPath).replace(/\\/g, '/');
     const content = fs.readFileSync(absPath, 'utf8');
+    // Read once, reused below both for this file's own flagging AND (via
+    // `entries`) for the #5074 split-invariant check — a second read of the
+    // same file for that check would double the I/O for no reason.
+    entries.push({ rel, content });
     const { needsRealOs } = classifyContent(content);
     // The ALWAYS_REAL_OS escape hatch (Windows tier only — see its doc
     // comment) is unioned in HERE, keyed off a file that this walk actually
@@ -369,6 +528,19 @@ function classifyTree(testsDir) {
       flagged.push(rel);
     }
   }
+
+  // #5074: a `.platform` sibling pair that violates the split invariant
+  // (residual signal left in the base, a sibling with no signal of its own,
+  // or a base that ALWAYS_REAL_OS says needs the whole file on real OS) fails
+  // generation loudly rather than being silently included or excluded. This
+  // check is Windows-CATEGORIES-only and wired here, not into
+  // classifyMacosTree below — a macOS-only signal in a split base is handled
+  // there by ordinary content selection (over-inclusion), not this invariant.
+  const violations = findPlatformSplitViolations(entries, ALWAYS_REAL_OS);
+  if (violations.length > 0) {
+    throw new Error(formatPlatformSplitViolations(violations));
+  }
+
   const result = [...new Set(flagged)].sort();
   return { total: absoluteFiles.length, files: result };
 }
@@ -484,7 +656,19 @@ function main() {
   const isMacos = target === 'macos';
   const label = isMacos ? 'gen-platform-conformance-tier --target macos' : 'gen-platform-conformance-tier';
   const exportKey = isMacos ? 'MACOS_CONFORMANCE_TIER_FILES' : 'CONFORMANCE_TIER_FILES';
-  const { total, files } = isMacos ? classifyMacosTree(testsDir) : classifyTree(testsDir);
+  // classifyTree throws a plain Error on a #5074 split-invariant violation
+  // (it has no ExitError/exit-code opinion of its own — it is also called
+  // in-process by tests). runMain only special-cases ExitError (stderr gets
+  // err.message; anything else gets the full err.stack); wrapping it here
+  // keeps the CLI's stderr output to the clean, purpose-built violation
+  // report instead of a raw stack trace.
+  let total, files;
+  try {
+    ({ total, files } = isMacos ? classifyMacosTree(testsDir) : classifyTree(testsDir));
+  } catch (err) {
+    if (err instanceof ExitError) throw err;
+    throw new ExitError(1, err && err.message ? err.message : String(err));
+  }
 
   if (mode === 'write') {
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
@@ -554,4 +738,6 @@ module.exports = {
   MACOS_CATEGORIES,
   classifyMacosTree,
   renderMacosGeneratedFile,
+  PLATFORM_SIBLING_SUFFIX,
+  findPlatformSplitViolations,
 };