@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

package/scripts/prompt-injection-scan.sh

@@ -69,15 +69,15 @@ ALLOWLIST=(
   'scripts/prompt-injection-scan.sh'
   'scripts/base64-scan.sh'
   'scripts/secret-scan.sh'
-  'tests/security-scan.test.cjs'
+  'tests/security-scan.security.test.cjs'
   'tests/security.test.cjs'
-  'tests/prompt-injection-scan.test.cjs'
+  'tests/prompt-injection-scan.security.test.cjs'
   'tests/verify.test.cjs'
   'gsd-core/bin/lib/security.cjs'
   'hooks/gsd-prompt-guard.js'
   'hooks/gsd-read-injection-scanner.js'
-  'tests/read-injection-scanner.test.cjs'
-  'tests/security-prompt-injection.test.cjs'
+  'tests/read-injection-scanner.security.test.cjs'
+  'tests/security-prompt-injection.security.test.cjs'
   'tests/fixtures/adversarial/security/'
   'SECURITY.md'
   # These files contain intentional injection examples / security-model prose

package/scripts/research-profiles.cjs

@@ -13,7 +13,7 @@
  *   color            — verbatim frontmatter `color:` value
  *   tools            — verbatim frontmatter `tools:` value (single string, comma-separated)
  *   requiredIncludes — @~/.claude/gsd-core/references/<file>.md strings the body MUST contain
- *   requiredSeamCalls — `gsd-tools query <cmd>` strings the body MUST contain
+ *   requiredSeamCalls — `gsd_run query <cmd>` strings the body MUST contain
  *   outputContract   — strings the body MUST contain (output path, return marker, etc.)
  */
 
@@ -31,9 +31,9 @@ const PROFILES = [
       '@~/.claude/gsd-core/references/research-verification-protocol.md',
     ],
     requiredSeamCalls: [
-      'gsd-tools query research-plan',
-      'gsd-tools query research-store put',
-      'gsd-tools query classify-confidence',
+      'gsd_run query research-plan',
+      'gsd_run query research-store put',
+      'gsd_run query classify-confidence',
     ],
     outputContract: [
       '.planning/research/',
@@ -53,10 +53,10 @@ const PROFILES = [
       '@~/.claude/gsd-core/references/research-verification-protocol.md',
     ],
     requiredSeamCalls: [
-      'gsd-tools query research-plan',
-      'gsd-tools query research-store put',
-      'gsd-tools query classify-confidence',
-      'gsd-tools query package-legitimacy check',
+      'gsd_run query research-plan',
+      'gsd_run query research-store put',
+      'gsd_run query classify-confidence',
+      'gsd_run query package-legitimacy check',
     ],
     outputContract: [
       '.planning/phases/XX-name/{phase_num}-RESEARCH.md',
@@ -122,7 +122,7 @@ const PROFILES = [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
     requiredSeamCalls: [
-      'gsd-tools query commit',
+      'gsd_run query commit',
     ],
     outputContract: [
       'UI-SPEC.md',
@@ -137,7 +137,7 @@ const PROFILES = [
     tools: 'Read, Write, Bash',
     requiredIncludes: [],
     requiredSeamCalls: [
-      'gsd-tools query commit',
+      'gsd_run query commit',
     ],
     outputContract: [
       '.planning/research/SUMMARY.md',

package/scripts/run-tests.cjs

@@ -20,7 +20,7 @@
 // See docs/TESTING-SUITES.md for full grouping policy.
 'use strict';
 
-const { readdirSync, existsSync } = require('fs');
+const { readdirSync } = require('fs');
 const { join } = require('path');
 const { execFileSync } = require('child_process');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
@@ -31,21 +31,84 @@ const SUITES = ['all', 'unit', 'integration', 'install', 'security', 'slow'];
 // src/*.cts and gitignored, so on a clean checkout (fresh CI, before any build)
 // the artifact is absent — yet test files require it. This is the universal
 // chokepoint every test path funnels through (test:unit, --files-from, direct
-// invocation), so build the artifact here if missing. It is a no-op once built
-// (dev, pretest, a prior run in the same job), which keeps the harness test's
-// spawned invocations side-effect-free. Paths resolve from __dirname (not cwd),
-// so it works regardless of GSD_TEST_DIR / temp-dir cwd. NOTE: the sentinel is
-// the pilot module; revisit (or switch to an unconditional quiet build) as more
-// modules migrate into src/.
-function ensureBuiltArtifacts() {
-  const root = join(__dirname, '..');
-  const sentinel = join(root, 'gsd-core', 'bin', 'lib', 'semver-compare.cjs');
-  if (existsSync(sentinel)) return;
+// invocation), so build the artifact here.
+//
+// Strategy (incremental + re-emit-on-missing, closes both #969 failure modes):
+//   1. Run tsc incrementally (fast ~380ms no-op when sources unchanged).
+//   2. Verify every src/*.cts (non-.d.cts) maps to a non-empty gsd-core/bin/lib/*.cjs.
+//   3. If any expected .cjs is missing or zero-bytes (persistent-mirror scenario:
+//      tsc no-ops because tsbuildinfo looks current even though the file was deleted),
+//      delete the tsbuildinfo and run tsc ONCE MORE (clean re-emit), then re-verify.
+//
+// Common case: fast incremental no-op. Stale/deleted-output case: detected by
+// the cheap existsSync loop and force-rebuilt. Paths resolve from __dirname so
+// it works regardless of GSD_TEST_DIR / temp-dir cwd.
+function ensureBuiltArtifacts(overrides = {}) {
+  const { existsSync, readdirSync, statSync, unlinkSync } = require('fs');
+  const root = overrides.root || join(__dirname, '..');
+  const srcDir = overrides.srcDir || join(root, 'src');
+  const outDir = overrides.outDir || join(root, 'gsd-core', 'bin', 'lib');
+  const tsBuildInfoPath = overrides.tsBuildInfoPath || join(root, 'tsconfig.build.tsbuildinfo');
+  const tsconfigPath = overrides.tsconfigPath || join(root, 'tsconfig.build.json');
   const tscBin = require.resolve('typescript/bin/tsc');
-  execFileSync(process.execPath, [tscBin, '-p', join(root, 'tsconfig.build.json')], {
-    cwd: root,
-    stdio: 'inherit',
-  });
+  const tscArgs = [tscBin, '-p', tsconfigPath];
+
+  // Build the 1:1 map of expected output paths from src/*.cts sources.
+  // Excludes *.d.cts (declaration-only files that produce no output).
+  // Handles subdirectories (e.g. src/installer-migrations/*.cts → gsd-core/bin/lib/installer-migrations/*.cjs).
+  function gatherExpectedOutputs() {
+    const expected = [];
+    function scan(dir, relBase) {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          scan(join(dir, entry.name), relBase ? `${relBase}/${entry.name}` : entry.name);
+        } else if (entry.name.endsWith('.cts') && !entry.name.endsWith('.d.cts')) {
+          const stem = entry.name.slice(0, -'.cts'.length);
+          const rel = relBase ? `${relBase}/${stem}.cjs` : `${stem}.cjs`;
+          expected.push(join(outDir, rel));
+        }
+      }
+    }
+    scan(srcDir, '');
+    return expected;
+  }
+
+  function checkMissingOutputs(expectedPaths) {
+    return expectedPaths.filter(p => !existsSync(p) || statSync(p).size === 0);
+  }
+
+  // #996 placed the tsbuildinfo inside gsd-core/bin/ (a copied/shipped tree), which
+  // raced install-test copies. It now lives at the repo root. Best-effort purge any
+  // stale bin-local copy so persistent workspaces/mirrors self-heal (no-op on a temp
+  // override root or a clean checkout).
+  const legacyTsBuildInfo = join(root, 'gsd-core', 'bin', 'tsconfig.build.tsbuildinfo');
+  try { if (existsSync(legacyTsBuildInfo)) unlinkSync(legacyTsBuildInfo); } catch { /* best-effort */ }
+
+  // Step 1: incremental build (fast no-op when sources unchanged).
+  execFileSync(process.execPath, tscArgs, { cwd: root, stdio: 'inherit' });
+
+  // Step 2: verify expected outputs.
+  const expected = gatherExpectedOutputs();
+  const missing = checkMissingOutputs(expected);
+
+  // Step 3: if any output is missing/zero-bytes, force a clean re-emit.
+  // This handles the persistent-mirror case where tsc's incremental no-op left
+  // a deleted .cjs unregenerated (tsbuildinfo recorded it as up-to-date).
+  if (missing.length > 0) {
+    if (existsSync(tsBuildInfoPath)) {
+      unlinkSync(tsBuildInfoPath);
+    }
+    execFileSync(process.execPath, tscArgs, { cwd: root, stdio: 'inherit' });
+    // Re-verify after clean re-emit; surface any remaining gaps loudly.
+    const stillMissing = checkMissingOutputs(expected);
+    if (stillMissing.length > 0) {
+      const names = stillMissing.map(p => require('path').basename(p)).join(', ');
+      throw new Error(
+        `ensureBuiltArtifacts: tsc clean re-emit still missing outputs: ${names}. ` +
+        `Check src/ for compilation errors.`
+      );
+    }
+  }
 }
 const MARKED_SUITES = ['integration', 'install', 'security', 'slow'];
 
@@ -256,14 +319,13 @@ function main() {
   // Default concurrency: 4 on Linux/macOS, 2 on Windows.
   //
   // Windows has significantly higher per-subprocess overhead than Linux/macOS:
-  //   - Windows Defender scans each spawned process
-  //   - NTFS has higher file-system latency under concurrent access
-  //   - synckit worker_threads (used by the SDK bridge in gsd-tools.cjs) spawn
-  //     native threads that contend on SharedArrayBuffer + Atomics.wait; under
-  //     Node 24 on Windows, 4-way concurrent gsd-tools invocations (each spawning
-  //     a synckit worker) caused intermittent process crashes with empty stderr —
-  //     a signature of OS-level resource exhaustion killing worker threads before
-  //     they could flush. Reducing to 2 halves the peak concurrent worker count.
+  //   - Windows Defender scans each spawned process on first execution, adding
+  //     latency proportional to the number of concurrent spawns.
+  //   - NTFS has higher file-system latency under concurrent access compared to
+  //     ext4/APFS, which amplifies contention when multiple test chunks run in
+  //     parallel and all read/write the same fixture directories.
+  // Reducing to 2 halves the peak concurrent subprocess count on Windows and
+  // keeps per-chunk wall-clock time well within the 20m CI job cap.
   //
   // Operator override via TEST_CONCURRENCY env var for local debugging.
   const defaultConcurrency = process.platform === 'win32' ? 2 : 4;
@@ -280,7 +342,21 @@ function main() {
   const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
     ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
     : 28000; // headroom below the 32,767 Windows ceiling
-  const FIXED_OVERHEAD = process.execPath.length + '--test'.length + concurrency.length + 8;
+
+  // node:test does not exit until the event loop drains. A unit test that leaks
+  // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
+  // makes a chunk's `node --test` child hang ~150s on Windows AFTER its last test
+  // prints; two such stalls push the windows full lane past its 20m cap and the
+  // job is CANCELLED with no failed step — a false-negative gate (#1051, recurrence
+  // of #869). --test-force-exit (Node >=22; engines requires >=22.0.0) exits the
+  // runner once all tests finish regardless of lingering handles. The leaking
+  // tests are also fixed at the source; this is the defensive backstop.
+  // RUN_TESTS_NO_FORCE_EXIT=1 disables it (used by the harness regression test to
+  // observe the pre-fix hang).
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  const forceExit = nodeMajor >= 22 && !process.env.RUN_TESTS_NO_FORCE_EXIT;
+
+  const FIXED_OVERHEAD = process.execPath.length + '--test'.length + concurrency.length + (forceExit ? '--test-force-exit'.length + 1 : 0) + 8;
   const chunks = [];
   let current = [];
   let currentLen = FIXED_OVERHEAD;
@@ -296,17 +372,45 @@ function main() {
   }
   if (current.length > 0) chunks.push(current);
 
+  // A chunk that still hangs (a leak the backstop somehow misses, or a wedged
+  // subprocess) must fail loudly rather than silently burn the job's wall-clock
+  // budget until the CI runner cancels the whole job. Default 10 min per chunk:
+  // well above a healthy chunk (~4-5 min on the windows lane) but below the 20m
+  // job cap. Operator/test override via RUN_TESTS_CHUNK_TIMEOUT_MS.
+  const chunkTimeoutMs = process.env.RUN_TESTS_CHUNK_TIMEOUT_MS
+    ? Number(process.env.RUN_TESTS_CHUNK_TIMEOUT_MS)
+    : 600000;
+
   let firstFailureExit = 0;
   for (let i = 0; i < chunks.length; i++) {
     if (chunks.length > 1) {
       console.error(`run-tests: chunk ${i + 1}/${chunks.length} — ${chunks[i].length} files`);
     }
     try {
-      execFileSync(process.execPath, ['--test', concurrency, ...chunks[i]], {
-        stdio: 'inherit',
-        env: { ...process.env },
-      });
+      execFileSync(
+        process.execPath,
+        ['--test', ...(forceExit ? ['--test-force-exit'] : []), concurrency, ...chunks[i]],
+        {
+          stdio: 'inherit',
+          env: { ...process.env },
+          timeout: chunkTimeoutMs,
+        },
+      );
     } catch (err) {
+      // When the per-chunk timeout fires, execFileSync kills the child and
+      // surfaces it as err.code === 'ETIMEDOUT' (POSIX) and/or err.killed === true
+      // (platform-dependent). Check both so detection holds on Windows and POSIX.
+      const timedOut = err.killed === true || err.code === 'ETIMEDOUT';
+      if (timedOut) {
+        console.error(
+          `run-tests: chunk ${i + 1}/${chunks.length} exceeded the per-chunk timeout ` +
+            `of ${chunkTimeoutMs}ms and was killed — a test in this chunk is likely leaking ` +
+            `an open handle (un-terminated Worker, un-killed child process, or ref'd timer) ` +
+            `so node --test never exits. Files: ${chunks[i]
+              .map(f => f.split(/[\\/]/).pop())
+              .join(' ')}`,
+        );
+      }
       const code = err.status || 1;
       // Run every chunk so the operator sees all failures in one pass; report
       // the first non-zero exit at the end.
@@ -320,4 +424,4 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { suiteOf };
+module.exports = { suiteOf, ensureBuiltArtifacts };

package/scripts/secret-scan.sh

@@ -218,9 +218,9 @@ should_skip_file() {
   # Skip the scan scripts themselves and test files
   case "$file" in
     */secret-scan.sh) return 0 ;;
-    */secret-scan-lint.test.cjs) return 0 ;;
-    */security-scan.test.cjs) return 0 ;;
-    */security-prompt-injection.test.cjs) return 0 ;;
+    */secret-scan-lint.security.test.cjs) return 0 ;;
+    */security-scan.security.test.cjs) return 0 ;;
+    */security-prompt-injection.security.test.cjs) return 0 ;;
     tests/fixtures/adversarial/security/*|*/tests/fixtures/adversarial/security/*) return 0 ;;
   esac
   return 1

package/scripts/sync-next-version.cjs

@@ -0,0 +1,133 @@
+'use strict';
+/**
+ * Sync the `next` branch's package.json version to a published release version.
+ *
+ * The release pipeline bumps the version only on the release/X.Y.Z branch at
+ * publish time, so `next` drifts and can carry a never-published placeholder
+ * (e.g. 1.3.1-dev.0) that leaks to source/dev installs reporting package.json
+ * version. This keeps `next` equal to the last published release for every
+ * release type (rc / hotfix / final). See issue #1104.
+ *
+ * Modes:
+ *   default     — open + admin-merge a `chore: sync next version` PR (used by
+ *                 release.yml's rc job, which has no next-targeting PR of its
+ *                 own). Idempotent: a no-op when `next` is already at the target.
+ *   --in-place  — set the version (+ manifests, via the npm `version` hook) in
+ *                 the current working tree only; the caller commits/pushes (used
+ *                 by auto-backmerge.yml, which folds it into its existing
+ *                 main->next PR).
+ *
+ * Subprocesses are bounded (repo convention) and the exec seam is injectable so
+ * the orchestration is unit-testable without git/gh/npm.
+ */
+const { execFileSync } = require('child_process');
+
+const RELEASE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(-(rc|beta)\.[0-9]+)?$/;
+
+/** True iff `v` is a publishable release version: X.Y.Z optionally -rc.N / -beta.N. Rejects -dev and anything else. */
+function isReleaseVersion(v) {
+  return typeof v === 'string' && RELEASE_VERSION.test(v);
+}
+
+/** Read the `version` field out of a package.json text blob. Throws on a missing/non-string version. */
+function versionFromPackageJson(text) {
+  const parsed = JSON.parse(text);
+  if (typeof parsed.version !== 'string') throw new Error('package.json has no string version');
+  return parsed.version;
+}
+
+function defaultRun(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    encoding: 'utf8',
+    timeout: opts.timeout ?? 30000,
+    stdio: opts.stdio ?? ['ignore', 'pipe', 'inherit'],
+  });
+}
+
+/** Set package.json version (and manifests, via the npm `version` lifecycle hook) in the current tree. */
+function applyVersion(version, { run = defaultRun } = {}) {
+  if (!isReleaseVersion(version)) {
+    throw new Error(`refusing to sync next to invalid/non-release version '${version}'`);
+  }
+  run('npm', ['version', version, '--no-git-tag-version', '--allow-same-version'], { timeout: 60000 });
+}
+
+/** Full PR-based sync to the `next` branch. Returns 'noop' | 'synced'. */
+function syncViaPr(version, { run = defaultRun } = {}) {
+  if (!isReleaseVersion(version)) {
+    throw new Error(`refusing to sync next to invalid/non-release version '${version}'`);
+  }
+  run('git', ['fetch', 'origin', 'next'], { timeout: 30000 });
+  const current = versionFromPackageJson(run('git', ['show', 'origin/next:package.json'], { timeout: 15000 }));
+  if (current === version) {
+    process.stdout.write(`next already at ${version} — nothing to sync\n`);
+    return 'noop';
+  }
+  const branch = `chore/sync-next-version-${version}`;
+  run('git', ['checkout', '-B', branch, 'origin/next'], { timeout: 15000 });
+  applyVersion(version, { run });
+  run('git', ['add', '-u'], { timeout: 15000 });
+  // `git diff --cached --quiet` exits 0 when there is NO staged diff (execFileSync
+  // returns), exits 1 when there IS one (execFileSync throws). Proceed only on a diff.
+  let hasDiff = false;
+  try {
+    run('git', ['diff', '--cached', '--quiet'], { timeout: 15000 });
+  } catch (err) {
+    // exit 1 == there is a staged diff (expected); anything else is a real failure.
+    if (err && err.status === 1) hasDiff = true;
+    else throw err;
+  }
+  if (!hasDiff) {
+    process.stdout.write('no changes to commit — nothing to sync\n');
+    return 'noop';
+  }
+  run('git', ['commit', '-m', `chore: sync next package version to ${version}`], { timeout: 15000 });
+  run('git', ['push', '--force-with-lease', 'origin', branch], { timeout: 60000 });
+  let prUrl = run('gh', ['pr', 'list', '--head', branch, '--base', 'next', '--state', 'open',
+    '--json', 'url', '--jq', '.[0].url // ""'], { timeout: 30000 }).trim();
+  if (!prUrl) {
+    prUrl = run('gh', ['pr', 'create', '--base', 'next', '--head', branch,
+      '--title', `chore: sync next package version to ${version}`,
+      '--body', `Automated: keep \`next\`'s package.json at the last published release (\`${version}\`) so the default branch never carries a never-published version. Generated by the release pipeline (#1104).`,
+    ], { timeout: 60000 }).trim();
+  }
+  const m = prUrl.match(/\/pull\/(\d+)\b/);
+  if (!m) throw new Error(`could not parse PR number from gh output: ${prUrl}`);
+  const prNum = m[1];
+  try {
+    run('gh', ['pr', 'edit', prNum, '--add-label', 'automation', '--add-label', 'no-changelog'], { timeout: 30000 });
+  } catch {
+    /* labels are best-effort; admin-merge below still lands the PR */
+  }
+  try {
+    run('gh', ['pr', 'merge', '--admin', '--merge', prNum], { timeout: 60000 });
+  } catch (err) {
+    // tolerate "already merged"; rethrow anything else
+    const msg = String((err && (err.stderr || err.message)) || '');
+    if (!/already merged|not mergeable|Merged/i.test(msg)) throw err;
+  }
+  process.stdout.write(`synced next -> ${version} via PR #${prNum}\n`);
+  return 'synced';
+}
+
+function main(argv = process.argv.slice(2), deps = {}) {
+  const inPlace = argv.includes('--in-place');
+  const version = argv.find((a) => !a.startsWith('--'));
+  if (!version) throw new Error('usage: sync-next-version.cjs <version> [--in-place]');
+  if (inPlace) {
+    applyVersion(version, deps);
+    return;
+  }
+  syncViaPr(version, deps);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (e) {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main };

package/scripts/sync-runtime-launcher.cjs

@@ -2,8 +2,8 @@
 /**
  * sync-runtime-launcher.cjs
  *
- * Idempotent transform: for every gsd-core/workflows/*.md (and subdirs),
- * rewrite all bash/sh/shell fenced blocks to:
+ * Idempotent transform: for every gsd-core/workflows/*.md (and subdirs)
+ * AND every agents/*.md, rewrite all bash/sh/shell fenced blocks to:
  *   1. Strip ALL old resolver forms from every bash block (GSD_TOOLS=,
  *      GSD_SDK=, the if/elif/else/fi resolver, _GSD_SHIM_NAME=, and any
  *      previously-inserted gsd_run preamble).
@@ -20,6 +20,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const SNIPPET_FILE = path.join(WORKFLOWS_DIR, '_runtime-launcher.snippet.sh');
 
 // Read canonical preamble (full content of snippet file)
@@ -376,18 +377,33 @@ function escapeRegExp(str) {
 // Main
 function main() {
   const preamble = loadPreamble();
-  const files = collectFiles(WORKFLOWS_DIR);
 
   let transformedCount = 0;
   let unchangedCount = 0;
 
-  for (const f of files) {
+  // Process workflow files
+  const workflowFiles = collectFiles(WORKFLOWS_DIR);
+  for (const f of workflowFiles) {
     const content = fs.readFileSync(f, 'utf8');
     const result = transformFile(content, preamble);
     if (result !== null) {
       fs.writeFileSync(f, result, 'utf8');
       transformedCount++;
-      console.log(`transformed: ${path.relative(WORKFLOWS_DIR, f)}`);
+      console.log(`transformed (workflow): ${path.relative(WORKFLOWS_DIR, f)}`);
+    } else {
+      unchangedCount++;
+    }
+  }
+
+  // Process agent files
+  const agentFiles = collectFiles(AGENTS_DIR);
+  for (const f of agentFiles) {
+    const content = fs.readFileSync(f, 'utf8');
+    const result = transformFile(content, preamble);
+    if (result !== null) {
+      fs.writeFileSync(f, result, 'utf8');
+      transformedCount++;
+      console.log(`transformed (agent): ${path.relative(AGENTS_DIR, f)}`);
     } else {
       unchangedCount++;
     }

package/scripts/update-size-baseline.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * @file update-size-baseline.cjs
+ *
+ * Regenerates the committed per-file workflow size baseline
+ * (`tests/workflow-size-baseline.json`) from the current workflow files.
+ *
+ * Run via `npm run size:baseline` whenever a workflow file legitimately grows
+ * or shrinks.  Growth must still be justified in the PR; this script only
+ * records the new reality so the CI guard (issue #1074) can diff against it.
+ *
+ * Idempotent: running it twice with no file changes produces no diff.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { measureMdFiles, WORKFLOWS_DIR } = require('./workflow-size.cjs');
+
+const BASELINE_PATH = path.join(__dirname, '..', 'tests', 'workflow-size-baseline.json');
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
+const AGENT_BASELINE_PATH = path.join(__dirname, '..', 'tests', 'agent-size-baseline.json');
+const isGsdAgent = (f) => f.startsWith('gsd-');
+
+/**
+ * Serialize a size map to the on-disk baseline format: keys sorted, 2-space
+ * indent, trailing newline (so the file is a stable, minimal-diff artifact).
+ *
+ * @param {Object<string, number>} sizes
+ * @returns {string}
+ */
+function serializeBaseline(sizes) {
+  const sorted = {};
+  for (const key of Object.keys(sizes).sort()) sorted[key] = sizes[key];
+  return JSON.stringify(sorted, null, 2) + '\n';
+}
+
+/**
+ * Write a baseline file from the measured `.md` sizes in a directory.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir]       - Directory to measure (default: workflows).
+ * @param {string} [opts.outPath]   - Baseline file to write (default: workflow).
+ * @param {function(string): boolean} [opts.predicate] - Filename filter.
+ * @returns {{ outPath: string, count: number, content: string }}
+ */
+function generateBaseline({ dir = WORKFLOWS_DIR, outPath = BASELINE_PATH, predicate } = {}) {
+  const sizes = measureMdFiles(dir, predicate);
+  const content = serializeBaseline(sizes);
+  fs.writeFileSync(outPath, content);
+  return { outPath, count: Object.keys(sizes).length, content };
+}
+
+if (require.main === module) {
+  const targets = [
+    { label: 'workflow', dir: WORKFLOWS_DIR, outPath: BASELINE_PATH },
+    { label: 'agent', dir: AGENTS_DIR, outPath: AGENT_BASELINE_PATH, predicate: isGsdAgent },
+  ];
+  for (const t of targets) {
+    const { outPath, count } = generateBaseline(t);
+    process.stdout.write(
+      `Wrote ${count} ${t.label} sizes to ${path.relative(process.cwd(), outPath)}\n`
+    );
+  }
+}
+
+module.exports = { generateBaseline, serializeBaseline, BASELINE_PATH, AGENT_BASELINE_PATH };

package/scripts/workflow-policy.cjs

@@ -36,6 +36,26 @@ function runnerDefault(runner) {
   return 'bash'; // ubuntu-* and macos-* both default to bash on GHA
 }
 
+// ---------------------------------------------------------------------------
+// Matrix expansion helpers
+// ---------------------------------------------------------------------------
+
+// Build the GitHub Actions Cartesian product of the given base-list matrix
+// keys. Returns one context object per realized job, each mapping every key
+// to a stringified value. A single key yields one context per value (identical
+// to the legacy base-list expansion); N keys yield the full cross-product.
+// Values are stringified to match runner-label comparison and matrix-expression
+// resolution, which operate on strings.
+function cartesianProduct(keys, matrix) {
+  return keys.reduce(
+    (contexts, key) =>
+      contexts.flatMap((context) =>
+        matrix[key].map((value) => ({ ...context, [key]: String(value) })),
+      ),
+    [{}],
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Matrix expansion
 // ---------------------------------------------------------------------------
@@ -88,19 +108,32 @@ function expandRunsOn(runsOnRaw, matrix) {
     }
   }
 
-  // Collect values from matrix.<key> list (e.g. matrix.os: [ubuntu, macos])
-  // These base-list entries have no extra context beyond the key itself.
-  // Each entry is pushed unconditionally — deduplicating by runner alone
-  // would collapse distinct Cartesian rows (e.g. duplicate os values paired
-  // with different shell values) and hide policy violations on later rows.
+  // GitHub Actions realizes one job per element of the Cartesian product of all
+  // base-list matrix keys (every matrix.<k> that is an array, excluding the
+  // include/exclude control keys), and each realized job's context carries a
+  // value for EVERY matrix key — so ${{ matrix.<key> }} references (e.g. in a
+  // shell: field) resolve against any realization, not only the runs-on key.
+  // Single-axis matrices yield exactly one realization per value, identical to
+  // the prior behavior; only multi-axis matrices change shape.
+  // Each realization is pushed unconditionally — deduplicating by runner label
+  // would collapse distinct Cartesian rows (e.g. matrix.os: [macos-latest,
+  // macos-latest] paired with different shells) and hide policy violations.
   if (Array.isArray(matrix[key])) {
-    for (const val of matrix[key]) {
-      const runner = String(val);
-      realizations.push({ runner, resolvable: true, context: { [key]: runner } });
+    const baseListKeys = Object.keys(matrix).filter(
+      (k) => k !== 'include' && k !== 'exclude' && Array.isArray(matrix[k]),
+    );
+    for (const context of cartesianProduct(baseListKeys, matrix)) {
+      realizations.push({ runner: context[key], resolvable: true, context });
     }
   }
 
-  // matrix.exclude: remove matches
+  // matrix.exclude: remove matches by runner label (first match only).
+  // KNOWN LIMITATION (out of scope for #435, tracked as a follow-up): this
+  // matches on the runs-on key's runner label rather than the full exclude
+  // tuple, so a multi-axis exclude like { os: macos-latest, shell: bash } can
+  // remove the wrong cross-product cell. Full GitHub Actions tuple-match
+  // (including the include-rows-are-not-excluded rule) is deferred; #435 scopes
+  // only the base-list cross-product expansion above.
   if (Array.isArray(matrix.exclude)) {
     for (const excl of matrix.exclude) {
       if (excl && excl[key] != null) {