@opengsd/gsd-core 1.13.0 → 1.15.0

package/scripts/ci-prepare-test-scope.cjs

@@ -4,9 +4,9 @@
 // Shell-agnostic: invoked as `node scripts/ci-prepare-test-scope.cjs` from any shell.
 //
 // Required environment variables (set by the workflow step's `env:` block):
-//   TEST_SCOPE       — "windows" | "targeted"
+//   TEST_SCOPE       — "targeted" (the `windows` scope was retired by #4641:
+//                      test-conformance is now the sole Windows selector)
 //   TARGETED_TESTS   — space-separated test file list (from ci-test-scope.cjs output)
-//   WINDOWS_TESTS    — space-separated test file list for the windows lane
 //
 // Writes: .ci-selected-tests.txt (one file per line, no blanks)
 // Exit 0 = success; exit 1 = unknown scope.
@@ -46,13 +46,14 @@ function isResolvable(entry, root) {
 
 // Resolve the scoped test selection for the lane. Pure (no I/O beyond the
 // existence probe under `root`) so it can be unit-tested directly.
-function resolveSelection({ scope, targeted, windows, root }) {
+function resolveSelection({ scope, targeted, root }) {
   let selected;
-  if (scope === 'windows') {
-    selected = windows;
-  } else if (scope === 'targeted') {
+  if (scope === 'targeted') {
     selected = targeted;
   } else {
+    // #4641: the `windows` scope was retired (test-conformance is now the
+    // sole Windows selector) — an unknown/retired scope must fail loudly
+    // rather than silently selecting nothing.
     throw new ExitError(1, `::error::Unknown test scope: ${scope}`);
   }
 
@@ -75,7 +76,6 @@ function main() {
   const lines = resolveSelection({
     scope: process.env.TEST_SCOPE || '',
     targeted: process.env.TARGETED_TESTS || '',
-    windows: process.env.WINDOWS_TESTS || '',
     root,
   });
 

package/scripts/ci-test-scope.cjs

@@ -3,9 +3,10 @@
 
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { existsSync, readdirSync, appendFileSync } = require('fs');
+const { existsSync, readdirSync, appendFileSync, readFileSync } = require('fs');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { classifyContent, NOISY_FOR_SOURCE_REACHABILITY } = require('./gen-platform-conformance-tier.cjs');
 
 // Workflow files that are purely administrative / policy bots. Changes to these
 // files do NOT require the cross-platform test matrix — only a lightweight
@@ -484,12 +485,68 @@ function addAll(set, values) {
 // fullMatrix=true, so the full Windows lane already runs when those paths
 // change. The old six-hint list pulled 102 of ~633 test files into the scoped
 // windows lane, turning it into a ~10-minute job on every PR.
+// #4641: the scoped windows lane itself is gone. These hints now drive
+// full_matrix instead — a matched RULE whose tests[] includes a
+// windows-hint filename AND that hinted file is itself in the conformance
+// tier (per reachesConformanceTierOrSeam) escalates straight to full_matrix
+// (routed to test-conformance, the sole Windows selector) rather than
+// feeding a side lane. Tier-backed on purpose: full_matrix only ever runs
+// CONFORMANCE_TIER_FILES, so a hint on a non-tier file would cost 4 CI jobs
+// with zero Windows coverage of that file. See
+// docs/adr/4641-windows-selector-consolidation.md.
 const WINDOWS_HINTS = ['windows', 'win32', 'shell', 'path'];
 const isWindowsHint = s => WINDOWS_HINTS.some(k => s.toLowerCase().includes(k));
 
-function classify(files) {
+// A change to the classification mechanism itself cannot be presumed safe by
+// the very mechanism being changed (#4592).
+const CLASSIFIER_DEFINITION_FILES = new Set([
+  'scripts/gen-platform-conformance-tier.cjs',
+  'scripts/lib/platform-conformance-tier.generated.cjs',
+  'scripts/lib/suite-detection.cjs',
+]);
+
+/**
+ * Does `file`'s blast radius reach (a) Phase 2's conformance-tier test-file
+ * list or (b) a live platform-conditional signal in src/? Fail-safe: any
+ * thrown error (a require failure, a readFileSync failure, a malformed
+ * generated module, etc.) is treated as uncertainty and returns true — per
+ * #4592's explicit "fail-safe to full_matrix=true on any reachability-
+ * computation error or uncertainty" requirement.
+ * `loadConformanceTier` is injectable (defaults to the real generated module)
+ * solely so tests can simulate a load failure without touching the real,
+ * committed generated file.
+ * @param {string} file
+ * @param {{loadConformanceTier?: () => {CONFORMANCE_TIER_FILES: string[]}}} [deps]
+ * @returns {boolean}
+ */
+function reachesConformanceTierOrSeam(file, deps = {}) {
+  const loadConformanceTier =
+    deps.loadConformanceTier || (() => require('./lib/platform-conformance-tier.generated.cjs'));
+  try {
+    if (file.startsWith('tests/') && file.endsWith('.test.cjs')) {
+      const { CONFORMANCE_TIER_FILES } = loadConformanceTier();
+      return CONFORMANCE_TIER_FILES.includes(file);
+    }
+
+    if (file.startsWith('src/')) {
+      const content = readFileSync(file, 'utf8');
+      const { signals } = classifyContent(content);
+      const narrowSignals = signals.filter(signal => !NOISY_FOR_SOURCE_REACHABILITY.has(signal));
+      return narrowSignals.length > 0;
+    }
+
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+// `reachabilityDeps` is injectable (defaults to {}, which makes
+// reachesConformanceTierOrSeam use the real generated module) solely so
+// tests can simulate a reachability-computation failure without touching
+// the real, committed generated file.
+function classify(files, reachabilityDeps = {}) {
   const targeted = new Set();
-  const windows = new Set();
   const reasons = [];
   let productOrPipelineChanged = false; // product/pipeline code (excludes docs)
   let inertCiChanged = false;           // inert workflow files
@@ -526,15 +583,35 @@ function classify(files) {
 
     if (file.startsWith('tests/') && file.endsWith('.test.cjs')) {
       targeted.add(file);
-      // #494 invariant, narrowed: a changed test must still be exercised on
-      // the divergent OS before merge, but at per-file cost — it ALWAYS joins
-      // the scoped windows lane instead of triggering the three full parity
-      // lanes. (full_matrix fired on 15/15 sampled PRs because test-driven
-      // PRs always touch tests/, costing ~25 runner-minutes each.) Changed
-      // tests already run on the two ubuntu-24 lanes via targeted_tests; the
-      // residual macOS / windows cross-product is covered by the full
-      // matrix on every push to next.
-      windows.add(file);
+      // #494 originally narrowed this to skip full_matrix for changed test
+      // files, on the theory that ubuntu targeted_tests + the scoped windows
+      // lane already covered them. Rescinded per #4421: PR #4384 landed a
+      // macOS-only regression on 2026-09-06 that stayed invisible pre-merge
+      // precisely because this carve-out suppressed the only macOS signal.
+      // #4592: the blanket rule is replaced with a reachability check — only
+      // a changed test file that actually reaches Phase 2's conformance-tier
+      // list (or is the classification mechanism itself) forces full_matrix.
+      if (reachesConformanceTierOrSeam(file, reachabilityDeps)) {
+        fullMatrix = true;
+        reasons.push(`${file}: conformance-tier reachability`);
+      }
+    }
+
+    // #4592: a src/-only diff (no test file touched) must still be able to
+    // set full_matrix=true when it carries a live platform-conditional
+    // signal — this is independent of the tests/ branch above.
+    if (file.startsWith('src/') && reachesConformanceTierOrSeam(file, reachabilityDeps)) {
+      fullMatrix = true;
+      reasons.push(`${file}: platform seam reachability`);
+    }
+
+    // #4592: a changed file that IS the classification mechanism itself
+    // (neither under tests/ nor src/, so neither branch above reaches it)
+    // must also force full_matrix — a change to the mechanism cannot be
+    // presumed safe by the very mechanism being changed.
+    if (CLASSIFIER_DEFINITION_FILES.has(file)) {
+      fullMatrix = true;
+      reasons.push(`${file}: reachability classifier definition changed`);
     }
 
     for (const rule of RULES) {
@@ -542,6 +619,32 @@ function classify(files) {
         addAll(targeted, rule.tests);
         reasons.push(`${file}: ${rule.name}`);
         if (rule.fullMatrix) fullMatrix = true;
+        // #4641: a rule that pulls in a test file matching a Windows-sensitive
+        // filename hint is the one non-redundant residue of the deleted
+        // scoped windows lane — escalate to full_matrix (test-conformance)
+        // instead of feeding a side lane. TIER-BACKED (measured): full_matrix
+        // routes to test-conformance, which runs ONLY CONFORMANCE_TIER_FILES —
+        // escalating on the filename hint alone can fire on a hinted test that
+        // isn't in that tier, costing 4 CI jobs while never actually running it
+        // on Windows. The predicate below requires BOTH the hint AND tier
+        // membership (via reachesConformanceTierOrSeam, the same fail-safe
+        // reachability helper used elsewhere in this file, so error/uncertainty
+        // behavior stays identical). Measured: over the 16 RULES entries this
+        // narrowed form fires on the same rules as the un-narrowed form today
+        // (no behavior change now, correct-by-construction going forward). The
+        // broader alternative — escalate on ANY tier member a rule pulls in,
+        // ignoring the filename hint — was measured and rejected: it fires on
+        // 14 of 16 rules, newly escalating most ordinary product-code PRs
+        // (src/, agents/, commands/, hooks/, skills/, config paths). Only one
+        // rule's escalation is live today: 'portability lint rules (ADR-1703)'.
+        // Four others already had fullMatrix: true (no-op here), and 'inert
+        // CI''s escalation is overridden downstream by the inert-CI reset.
+        // Distinct, greppable reason so the conformance-lane coverage for it
+        // is traceable per rule.
+        if (rule.tests.some(t => isWindowsHint(t) && reachesConformanceTierOrSeam(t, reachabilityDeps))) {
+          fullMatrix = true;
+          reasons.push(`${file}: ${rule.name} (windows-hint rule test, #4641)`);
+        }
       }
     }
   }
@@ -555,7 +658,7 @@ function classify(files) {
     // covered by .github/workflows/install-smoke.yml
     'tests/release-tarball-smoke.install.test.cjs',
   ]);
-  for (const f of SCOPED_LANE_EXCLUDE) { targeted.delete(f); windows.delete(f); }
+  for (const f of SCOPED_LANE_EXCLUDE) { targeted.delete(f); }
 
   // code_changed: true when product/pipeline OR inert CI changed.
   // Docs-only PRs (neither flag set) get code_changed=false → full matrix skip.
@@ -569,8 +672,6 @@ function classify(files) {
     targetedTests.push('unit');
   }
 
-  const windowsTests = existingTests([...new Set([...windows, ...targetedTests.filter(isWindowsHint)])].sort());
-
   // Inert-CI-only: full_matrix must be false (override any RULES that fired).
   if (inertCiChanged && !productOrPipelineChanged) {
     fullMatrix = false;
@@ -579,12 +680,11 @@ function classify(files) {
   // Normalize: when code_changed is false, the output must be self-consistent.
   // A docs file can coincidentally match a coarse content RULE (e.g. docs/installer-migrations.md
   // matches the installer rule via path.includes('install')), leaving full_matrix=true and
-  // non-empty targeted_tests/windows_tests. The workflow skips correctly (gated on code_changed)
+  // non-empty targeted_tests. The workflow skips correctly (gated on code_changed)
   // but the output object would be self-contradictory. Force a clean "nothing to run" result.
   if (!codeChanged) {
     fullMatrix = false;
     targetedTests.length = 0;
-    windowsTests.length = 0;
   }
 
   return {
@@ -592,7 +692,6 @@ function classify(files) {
     product_changed: productOrPipelineChanged,
     full_matrix: fullMatrix,
     targeted_tests: targetedTests,
-    windows_tests: windowsTests,
     reasons: [...new Set(reasons)].sort(),
   };
 }
@@ -604,7 +703,6 @@ function writeOutputs(result) {
     `product_changed=${result.product_changed}`,
     `full_matrix=${result.full_matrix}`,
     `targeted_tests=${result.targeted_tests.join(' ')}`,
-    `windows_tests=${result.windows_tests.join(' ')}`,
   ];
   appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join('\n')}\n`);
 }
@@ -630,4 +728,12 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { RULES, missingRuleTestFiles, PROTECTED_WORKFLOWS, INERT_WORKFLOWS, missingProtectedWorkflows };
+module.exports = {
+  RULES,
+  missingRuleTestFiles,
+  PROTECTED_WORKFLOWS,
+  INERT_WORKFLOWS,
+  missingProtectedWorkflows,
+  classify,
+  reachesConformanceTierOrSeam,
+};

package/scripts/ci-timeout-report.cjs

@@ -33,8 +33,8 @@ const WORKFLOWS_DIR = path.join(__dirname, '..', '.github', 'workflows');
 const JOB_RULES = [
   { workflowFile: 'test.yml', jobKey: 'test-inert', test: (name) => name === 'test (inert CI)' },
   { workflowFile: 'test.yml', jobKey: 'test', test: (name) => name.startsWith('test (') && name !== 'test (inert CI)' },
-  { workflowFile: 'test.yml', jobKey: 'test-full', test: (name) => name.startsWith('full test (') },
   { workflowFile: 'test.yml', jobKey: 'coverage-gate', test: (name) => name === 'Coverage gate (merged shards)' },
+  { workflowFile: 'test.yml', jobKey: 'test-conformance', test: (name) => name.startsWith('conformance test (') },
   { workflowFile: 'install-smoke.yml', jobKey: 'smoke', test: (name) => name.startsWith('smoke (') },
 ];
 

package/scripts/command-contract-helpers.cjs

@@ -890,6 +890,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 +926,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/diff-touches-shipped-paths.cjs

@@ -72,7 +72,7 @@ function isShipped(diffPath, shipPrefixes) {
   // forward slashes, but a developer running this locally on a different
   // tool's output shouldn't get a false negative).
   const p = diffPath.replace(/\\/g, '/');
-  return shipPrefixes.some((s) => p === s || p.startsWith(s + '/'));
+  return shipPrefixes.some((s) => p === s || p.startsWith(s + '/')); // allow-handrolled-containment: shipped-path filtering for a CI check, not a safety decision
 }
 
 // #2980: commits that touch `.github/workflows/*` cannot be cherry-picked

package/scripts/docs-guard-registry.cjs

@@ -9,8 +9,12 @@
  *
  * A prior version of this PR added a `docs guards` RULE to `RULES` in
  * scripts/ci-test-scope.cjs, on the theory that classify()'s `!codeChanged`
- * normalization (which zeroes fullMatrix/targeted_tests/windows_tests for
- * docs-only diffs) made the RULE inert to classify()'s scope decision.
+ * normalization (which at the time zeroed fullMatrix/targeted_tests/
+ * windows_tests for docs-only diffs) made the RULE inert to classify()'s
+ * scope decision. (#4641 later removed `windows_tests` from classify()'s
+ * output entirely; the normalization today only zeroes fullMatrix and
+ * targeted_tests. This paragraph is historical narration of a rejected
+ * design, not a description of current behaviour.)
  *
  * That is true for docs-ONLY diffs and FALSE for MIXED docs+code diffs:
  * `codeChanged` is true whenever ANY changed file is product/pipeline code,
@@ -170,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',
@@ -193,6 +198,7 @@ const DOCS_GUARD_TESTS = {
   // (commit-files-pathspec.test.cjs:1618) — cannot be resolved to specific
   // files without re-deriving the scan's own file-discovery logic.
   'tests/commit-files-pathspec.test.cjs': ['*'],
+  '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'],
   'tests/context-index-sync.test.cjs': ['docs/CONTEXT-INDEX.json'],
@@ -267,6 +273,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',
@@ -371,6 +403,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',

package/scripts/gen-adr-index.cjs

@@ -31,6 +31,7 @@ const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 const { escapeRegex: escapeRegExp } = require('../gsd-core/bin/lib/pattern.cjs');
+const { isContainedIn } = require('../gsd-core/bin/lib/security.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const ADR_DIR = path.join(ROOT, 'docs', 'adr');
@@ -176,10 +177,15 @@ const ADR_FILENAME_RE = /^[0-9]+-[a-z0-9-]+\.md$/;
  * segment merely BEGINS with two dots (`..hidden.md`), and a false "escapes
  * the repository" on a valid path is a worse failure than a miss — hence the
  * whole-segment `rel === '..' || rel.startsWith('..' + sep)` form.
+ *
+ * Delegates to the shared `isContainedIn` (ADR-4650): every call site here
+ * already resolved both operands itself (either lexically, before any
+ * filesystem call, or via realpathSync after a symlink) and needs only this
+ * comparison step — the exact already-resolved-caller case `isContainedIn`
+ * documents.
  */
 function escapesRoot(abs, root) {
-  const rel = path.relative(root, abs);
-  return rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+  return !isContainedIn(abs, root);
 }
 
 /**

package/scripts/gen-inventory-manifest.cjs

@@ -91,6 +91,18 @@ const NESTED_FAMILIES = [
     subdir: 'steps',
     filter: (f) => f.endsWith('.md'),
   },
+  {
+    name: 'workflow_detail',
+    root: path.join(ROOT, 'gsd-core', 'workflows'),
+    subdir: 'detail',
+    filter: (f) => f.endsWith('.md'),
+  },
+  {
+    name: 'workflow_templates',
+    root: path.join(ROOT, 'gsd-core', 'workflows'),
+    subdir: 'templates',
+    filter: (f) => f.endsWith('.md'),
+  },
 ];
 
 /**

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

@@ -78,6 +78,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 +245,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 +394,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 +734,7 @@ function getWiredLoopPoints(repoRoot) {
 module.exports = {
   parseLoopHostBlock,
   crossCheckRoles,
+  crossCheckRoleFamilies,
   assertPointsCoverage,
   buildContract,
   serializeContract,
@@ -676,6 +744,7 @@ module.exports = {
   CANONICAL_POINTS,
   EXPECTED_POINTS_BY_STEP,
   ROLE_TO_AGENT,
+  ROLE_FAMILY,
   scanWiredPoints,
   getWiredLoopPoints,
   coveredKindsInRegion,