@opengsd/gsd-core 1.12.0 → 1.14.0

package/scripts/npm-audit-baseline.cjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * #4196: npm-audit baseline diff.
+ *
+ * The #3588 gate (tests/npm-integrity-gate.test.cjs) used to fail on ANY
+ * advisory present in the production tree, regardless of whether the PR
+ * being checked introduced it. Because npm's advisory database updates
+ * continuously and independently of repo state, that made the gate fail
+ * for reasons no PR caused -- see #4196 for the incident where PR #4188
+ * passed this gate at merge time and failed it ~15 minutes later on the
+ * identical commit, purely because a new advisory was disclosed in the
+ * interim.
+ *
+ * This module computes which vulnerable packages are NEW relative to a
+ * baseline tree (typically the PR's target branch), so the gate blocks a
+ * PR only for advisories it actually introduces -- a pre-existing advisory
+ * in an untouched transitive dependency no longer blocks unrelated work.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+// Per-attempt timeout. 60s comfortably covers the worst *working* latency
+// measured against this endpoint (43.41s, see #4260) while staying well
+// under the old single-shot 180s budget once multiplied by AUDIT_MAX_ATTEMPTS.
+const AUDIT_ATTEMPT_TIMEOUT_MS = 60_000;
+// Bounded retry, not unbounded -- a registry-side outage must still fail the
+// gate eventually (see #4260's own caveat: silently disarming a required
+// security check on a transport error is worse than failing it).
+const AUDIT_MAX_ATTEMPTS = 3;
+// Exponential backoff base between attempts (2s, 4s for attempts 1->2, 2->3).
+const AUDIT_BACKOFF_BASE_MS = 2_000;
+
+/**
+ * Synchronous sleep (execFileSync-based retry logic is itself synchronous,
+ * so backoff between attempts must be too). Uses Atomics.wait on a throwaway
+ * SharedArrayBuffer, the standard Node pattern for a blocking sleep with no
+ * external dependency.
+ */
+function sleepSyncMs(ms) {
+  const sab = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(sab), 0, 0, ms);
+}
+
+/**
+ * True when `error` represents a child process execFileSync killed via its
+ * `timeout` option (e.g. AUDIT_ATTEMPT_TIMEOUT_MS firing against a
+ * slow/degraded npm registry) rather than one that exited normally with a
+ * non-zero code. Node sets `killed: true` and `signal` to the kill signal in
+ * that case (see the child_process docs for execFileSync's `timeout`
+ * option); a normal "npm audit found advisories" exit has neither set. The
+ * distinction matters because a killed process's stdout is truncated
+ * mid-write, not complete JSON -- treating it as recoverable JSON produces a
+ * misleading `Unexpected end of JSON input` instead of naming the real
+ * cause.
+ */
+function isTimeoutKill(error) {
+  return Boolean(error && (error.killed === true || error.signal));
+}
+
+/**
+ * Builds the standard timeout-kill error message, shared by every caller
+ * that classifies a killed npm audit process after exhausting retries (see
+ * isTimeoutKill, runNpmAuditWithRetry) -- kept in one place so the message
+ * can't independently drift between callers, per this repo's Generative Fix
+ * Divergence anti-pattern.
+ *
+ * Includes whatever `error.stderr` execFileSync captured before the last
+ * kill (Node buffers stdout/stderr from a killed child in-memory and
+ * attaches them to the thrown error; without surfacing it here that data
+ * was simply discarded, giving zero diagnostic signal into WHY npm was
+ * still running when the timeout fired).
+ */
+function buildTimeoutKillError(cwd, error, attempts = 1) {
+  const stderr = error && error.stderr
+    ? (Buffer.isBuffer(error.stderr) ? error.stderr.toString('utf-8') : String(error.stderr))
+    : '';
+  const stderrSuffix = stderr.trim()
+    ? `\n\nCaptured stderr before the last kill:\n${stderr.trim().slice(0, 2000)}`
+    : '\n\n(no stderr was captured before the last kill)';
+  const attemptsPhrase = attempts > 1
+    ? `after ${attempts} attempts (each up to ${AUDIT_ATTEMPT_TIMEOUT_MS}ms, with exponential backoff between)`
+    : `after ${AUDIT_ATTEMPT_TIMEOUT_MS}ms`;
+  return new Error(
+    `npm audit timed out ${attemptsPhrase} in ${cwd} -- this is not a JSON ` +
+    `parse failure, npm audit did not finish. The npm registry's advisories endpoint ` +
+    `may be degraded; check https://status.npmjs.org before assuming a code regression.` +
+    stderrSuffix,
+  );
+}
+
+const AUDIT_DIFF_REASON = Object.freeze({
+  OK_NO_NEW_VULNERABILITIES: 'ok_no_new_vulnerabilities',
+  FAIL_NEW_VULNERABLE_PACKAGE: 'fail_new_vulnerable_package',
+});
+
+/**
+ * Pure diff: which package names are vulnerable in `headVulnerabilities`
+ * but were NOT already vulnerable in `baselineVulnerabilities`.
+ *
+ * Both args are the `.vulnerabilities` object from `npm audit --json`
+ * (keyed by package name). Matched by package NAME only -- not by the
+ * specific advisory ID or severity -- so a package that stays vulnerable
+ * across a *different* newly-disclosed advisory for the same package is
+ * still "pre-existing", not new. A package whose vulnerability *worsens*
+ * while remaining the same package name is deliberately NOT flagged here;
+ * that tradeoff keeps the predicate simple and matched to the #4196
+ * incident shape (a transitive dependency neither side of the diff
+ * touched). Severity escalation on an already-known-vulnerable package is
+ * exactly the kind of thing the scheduled Dependabot channel should catch
+ * instead (see #4196, PR #4200's auto-merge workflow).
+ */
+function diffNewVulnerablePackages(baselineVulnerabilities, headVulnerabilities) {
+  const baselineNames = new Set(Object.keys(baselineVulnerabilities || {}));
+  return Object.keys(headVulnerabilities || {}).filter((name) => !baselineNames.has(name));
+}
+
+/**
+ * Typed verdict wrapping diffNewVulnerablePackages. `ok: false` means the
+ * diff (head vs baseline) is non-empty -- this PR/push introduced at
+ * least one newly-vulnerable package.
+ */
+function evaluateAuditDiff({ baselineVulnerabilities, headVulnerabilities }) {
+  const newlyIntroduced = diffNewVulnerablePackages(baselineVulnerabilities, headVulnerabilities);
+  if (newlyIntroduced.length > 0) {
+    return { ok: false, reason: AUDIT_DIFF_REASON.FAIL_NEW_VULNERABLE_PACKAGE, newlyIntroduced };
+  }
+  return {
+    ok: true,
+    reason: AUDIT_DIFF_REASON.OK_NO_NEW_VULNERABILITIES,
+    preExisting: Object.keys(headVulnerabilities || {}),
+  };
+}
+
+/**
+ * Runs `npm audit <args> --json` in `cwd` with bounded retry + exponential
+ * backoff. A per-attempt timeout-kill (see isTimeoutKill) is retried rather
+ * than failed immediately -- #4260: the audit backend has real, independent
+ * latency variance from the rest of the registry (measured: 43.41s vs 0.20s
+ * for a plain registry fetch, and two outright non-responses in the same
+ * window), and a single 180s attempt with no retry meant any one bad moment
+ * failed a REQUIRED gate on a transport hiccup, not a real advisory. A
+ * non-timeout failure (e.g. a genuine non-zero exit with recoverable stdout,
+ * or an unrecoverable error) is NOT retried -- only a confirmed timeout-kill
+ * is, since retrying a deterministic failure wastes the budget without
+ * changing the outcome.
+ *
+ * Exhausting all attempts still fails the gate (see #4260's own caveat:
+ * silently skipping a required security check on a transport error is a
+ * worse failure mode than occasionally re-running CI).
+ */
+function runNpmAuditWithRetry(cwd, args, { execFileSyncImpl = execFileSync, sleepImpl = sleepSyncMs } = {}) {
+  const isWindows = process.platform === 'win32';
+  const npmCandidates = isWindows ? ['npm.cmd', 'npm'] : ['npm'];
+  let lastTimeoutError = null;
+
+  for (let attempt = 1; attempt <= AUDIT_MAX_ATTEMPTS; attempt += 1) {
+    let out;
+    let timedOutThisAttempt = false;
+    let lastErr = null;
+
+    for (const npmCmd of npmCandidates) {
+      try {
+        out = execFileSyncImpl(npmCmd, args, {
+          cwd,
+          encoding: 'utf-8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: AUDIT_ATTEMPT_TIMEOUT_MS,
+          shell: isWindows,
+        });
+        lastErr = null;
+        break;
+      } catch (e) {
+        if (isTimeoutKill(e)) {
+          timedOutThisAttempt = true;
+          lastErr = e;
+          break; // do not burn the alt npm-candidate slot on a timeout; go to the next retry attempt instead
+        }
+        // `npm audit` exits non-zero when advisories are present; the JSON is
+        // still on stdout in that case. Recover and let the caller classify —
+        // but only when stdout actually CARRIES the JSON: an audit that was
+        // killed or aborted can exit non-zero with EMPTY stdout, and accepting
+        // the empty string here surfaces as a bare `SyntaxError: Unexpected
+        // end of JSON input` at the parse below, hiding the captured error
+        // (observed on CI 2026-09-03, both lanes; cause undetermined).
+        const recovered = e && typeof e.stdout !== 'undefined' && e.stdout !== null
+          ? (Buffer.isBuffer(e.stdout) ? e.stdout.toString('utf-8') : String(e.stdout))
+          : '';
+        if (recovered.trim()) {
+          out = recovered;
+          lastErr = null;
+          break;
+        }
+        lastErr = e;
+      }
+    }
+
+    if (timedOutThisAttempt) {
+      lastTimeoutError = lastErr;
+      if (attempt < AUDIT_MAX_ATTEMPTS) {
+        sleepImpl(AUDIT_BACKOFF_BASE_MS * (2 ** (attempt - 1)));
+        continue;
+      }
+      throw buildTimeoutKillError(cwd, lastTimeoutError, attempt);
+    }
+
+    if (lastErr) throw lastErr; // non-timeout failure: fail immediately, no retry
+
+    const parsed = JSON.parse(out);
+    if (parsed && parsed.metadata && parsed.metadata.vulnerabilities) {
+      return parsed;
+    }
+    throw new Error(`Unexpected npm audit JSON shape in ${cwd}: missing metadata.vulnerabilities`);
+  }
+  // Unreachable (the loop always returns or throws), but keep a fallback
+  // throw so a future refactor mistake fails loudly instead of returning
+  // undefined.
+  throw buildTimeoutKillError(cwd, lastTimeoutError, AUDIT_MAX_ATTEMPTS);
+}
+
+/**
+ * Runs `npm audit --package-lock-only --omit=dev --json` in `cwd` and
+ * returns the parsed JSON, or `null` if `cwd` has no package.json or no
+ * package-lock.json (not an auditable tree -- callers treat this as
+ * "skip"/"no baseline available", not an error).
+ *
+ * `--package-lock-only` deliberately avoids requiring `node_modules/` to
+ * be installed: it lets a baseline tree be audited from nothing but an
+ * extracted package.json + package-lock.json (see extractBaselineTree),
+ * without a second full `npm ci`.
+ */
+function runPackageLockAudit(cwd, opts = {}) {
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) return null;
+  if (!fs.existsSync(path.join(cwd, 'package-lock.json'))) return null;
+  return runNpmAuditWithRetry(cwd, ['audit', '--package-lock-only', '--omit=dev', '--json'], opts);
+}
+
+/**
+ * Runs `npm audit --omit=dev --json` against the REAL installed node_modules
+ * tree in `cwd` (unlike runPackageLockAudit's --package-lock-only mode,
+ * which only needs package-lock.json on disk). Returns `null` if `cwd` has
+ * no package.json or no node_modules/ (not an auditable/installed tree --
+ * callers treat this as "skip", not an error).
+ */
+function runInstalledTreeAudit(cwd, opts = {}) {
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) return null;
+  if (!fs.existsSync(path.join(cwd, 'node_modules'))) return null;
+  return runNpmAuditWithRetry(cwd, ['audit', '--omit=dev', '--json'], opts);
+}
+
+/**
+ * Extracts package.json + package-lock.json (optionally under `subdir`,
+ * e.g. 'sdk') from `ref` at git object level into a fresh temp directory --
+ * no working-tree checkout, no `node_modules` install. Returns the temp
+ * dir path, or `null` if `ref` cannot be resolved locally (e.g. a shallow
+ * clone that never fetched it) or either file is absent at that ref --
+ * callers treat `null` as "no baseline available", not an error.
+ */
+function extractBaselineTree(ref, repoRoot, subdir = '') {
+  const rel = (name) => (subdir ? path.posix.join(subdir, name) : name);
+  let pkgJson;
+  let lockJson;
+  try {
+    pkgJson = execFileSync('git', ['show', `${ref}:${rel('package.json')}`], {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    lockJson = execFileSync('git', ['show', `${ref}:${rel('package-lock.json')}`], {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return null;
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-audit-baseline-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), pkgJson);
+  fs.writeFileSync(path.join(dir, 'package-lock.json'), lockJson);
+  return dir;
+}
+
+// All-zeros is git's documented sentinel for "this ref did not exist
+// before this push" (a brand-new branch's first push) -- never a real
+// commit to diff against.
+const NULL_SHA = '0000000000000000000000000000000000000000';
+
+/**
+ * Resolves the git ref to diff against, in priority order:
+ *   1. AUDIT_BASELINE_REF env var -- the primary mechanism. CI sets this
+ *      explicitly (see .github/workflows/test.yml) to github.event.pull_
+ *      request.base.sha on a pull_request event, or github.event.before on
+ *      a push event -- both pinned, race-free values Git/GitHub track for
+ *      exactly this purpose. Prefer this over anything below whenever the
+ *      caller can provide it.
+ *   2. GITHUB_BASE_REF (GitHub Actions sets this on pull_request events)
+ *      resolved against the LIVE origin/<branch> tip. Only reached if
+ *      AUDIT_BASELINE_REF wasn't set -- e.g. a workflow that forgot to
+ *      wire it. origin/<branch> can advance mid-run (see the GSD_EMITTED_
+ *      BASE precedent in test.yml), so this is a degraded fallback, not
+ *      the intended path for pull_request events in this repo's own CI.
+ *   3. On a `push` event, `HEAD~1` -- correct ONLY when the push added
+ *      exactly one commit (true for a squash-merge or a single ordinary
+ *      commit). This repo also allows rebase-merge (allow_rebase_merge:
+ *      true), which can land a PR as several discrete commits in one
+ *      push -- HEAD~1 then lands on an EARLIER commit in the same push,
+ *      which may already contain a vulnerable package that commit itself
+ *      introduced, silently marking it "pre-existing". CI never reaches
+ *      this branch (AUDIT_BASELINE_REF is always set by test.yml for
+ *      push events); it exists only for out-of-band invocations (e.g.
+ *      gsd-test) that don't set any of the above.
+ *   4. `origin/next`, else a plain local branch named `next` (gsd-test's
+ *      sandbox fetches the base as a local branch, not a remote-tracking
+ *      ref -- see gsd-test-merges-into-LOCAL-base-branch in this repo's
+ *      own operational notes), if either exists locally (this repo's
+ *      integration branch -- matches DEFAULT_BASE in
+ *      scripts/changeset/lint.cjs).
+ * Returns '' if none resolve -- callers fall back to strict zero-tolerance
+ * rather than silently skipping the gate.
+ */
+function resolveBaselineRef(repoRoot) {
+  if (process.env.AUDIT_BASELINE_REF) return process.env.AUDIT_BASELINE_REF;
+  if (process.env.GITHUB_BASE_REF) return `origin/${process.env.GITHUB_BASE_REF}`;
+  if (process.env.GITHUB_EVENT_NAME === 'push') {
+    try {
+      const parent = execFileSync('git', ['rev-parse', '--verify', 'HEAD~1'], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      if (parent && parent !== NULL_SHA) return parent;
+    } catch {
+      // not enough history; fall through
+    }
+  }
+  try {
+    execFileSync('git', ['rev-parse', '--verify', 'origin/next'], {
+      cwd: repoRoot,
+      stdio: 'ignore',
+    });
+    return 'origin/next';
+  } catch {
+    // fall through to a plain local branch
+  }
+  try {
+    execFileSync('git', ['rev-parse', '--verify', 'next'], {
+      cwd: repoRoot,
+      stdio: 'ignore',
+    });
+    return 'next';
+  } catch {
+    return '';
+  }
+}
+
+module.exports = {
+  AUDIT_DIFF_REASON,
+  diffNewVulnerablePackages,
+  evaluateAuditDiff,
+  runPackageLockAudit,
+  runInstalledTreeAudit,
+  runNpmAuditWithRetry,
+  extractBaselineTree,
+  resolveBaselineRef,
+  isTimeoutKill,
+  buildTimeoutKillError,
+  sleepSyncMs,
+  AUDIT_ATTEMPT_TIMEOUT_MS,
+  AUDIT_MAX_ATTEMPTS,
+  AUDIT_BACKOFF_BASE_MS,
+  NULL_SHA,
+};

package/scripts/prompt-injection-scan.sh

@@ -171,6 +171,28 @@ ALLOWLIST=(
   # allowlist cannot reach it either, because the literal `child_process` is
   # not adjacent to `.exec`. See the note at the pattern itself.
   'tests/continuation-grammar-parity.test.cjs'
+  # #3676 row 11b — quick-batch's task-list parser must treat a
+  # prompt-injection-shaped task description as inert data, never
+  # interpreted. The fixture has to be a real "ignore all previous
+  # instructions…" phrase or the test asserts nothing: it is the payload the
+  # parser is required to carry byte-for-byte through createBatch and STATE
+  # rendering, never a command. Same DEFECT.PROMPT-INJECTION-SCAN-COLLISION
+  # class as the input-validator fixtures above.
+  'tests/quick-batch.test.cjs'
+  # #4209 — the regression test pinning gsd-code-reviewer.md's untrusted-evidence
+  # contract discusses the injection attack it defends against (embedded
+  # redirection, "act as an instruction") without performing it. gsd-code-reviewer.md
+  # ITSELF is deliberately NOT allowlisted — R2 (#4209 review): a production prompt
+  # that ingests untrusted third-party output should stay in-scope for this scanner,
+  # not be exempted wholesale; its defense-contract wording was reworded instead to
+  # avoid literally spelling out the trigger phrase (see git blame on that section).
+  # Same DEFECT.PROMPT-INJECTION-SCAN-COLLISION class as the entries above.
+  'tests/code-review-pipeline-regression.test.cjs'
+  # #4209 agy-F1 regression test — a crafted-filename fixture containing the literal
+  # phrase "Ignore all prior instructions." to prove validatePaths rejects it before
+  # it ever reaches an external-reviewer prompt. Discusses/detects the attack pattern
+  # as test data, never performs it. Same class as the entries above.
+  'tests/reviewer-step-dispatch.test.cjs'
 )
 
 is_allowlisted() {

package/scripts/require-issue-link-policy.cjs

@@ -30,6 +30,7 @@ const { runMain } = require('./lib/cli-exit.cjs');
 const ISSUE_LINK_REASON = Object.freeze({
   OK_CLOSING_KEYWORD: 'ok_closing_keyword',
   OK_BACKMERGE_EXEMPT: 'ok_backmerge_exempt',
+  OK_DEPENDABOT_EXEMPT: 'ok_dependabot_exempt',
   OK_FOLLOWUP_REFERENCE: 'ok_followup_reference',
   FAIL_NO_ISSUE_REFERENCE: 'fail_no_issue_reference',
   FAIL_REFERENCE_NEEDS_CLOSING: 'fail_reference_needs_closing',
@@ -41,6 +42,14 @@ const ISSUE_LINK_REASON = Object.freeze({
 // ONLY when combined with `sameRepo === true` below (see header comment).
 const BACKMERGE_BRANCH_PREFIX = 'chore/backmerge-main-to-next-';
 
+// #4196: Dependabot has no mechanism to link a PR it opens to a repo issue —
+// its alerts live in the Security tab, not as issues, so there is nothing
+// for it to reference. `pr.user.login` is authenticated by GitHub (not
+// forgeable by a crafted title/branch), so this is safe without a sameRepo
+// conjunct: no external actor can make GitHub report this login for a PR
+// they opened.
+const DEPENDABOT_LOGIN = 'dependabot[bot]';
+
 // A follow-up-only PR (references an issue without closing it) is only
 // allowed to skip the closing keyword when every changed file is a test or
 // doc file — i.e. it cannot be the PR that actually implements the fix.
@@ -122,7 +131,11 @@ function allPathsAreTestsOrDocs(changedFiles) {
   });
 }
 
-function evaluateIssueLink({ prBody, headRef, sameRepo, changedFiles, changedFilesTotal }) {
+function evaluateIssueLink({ prBody, headRef, sameRepo, authorLogin, changedFiles, changedFilesTotal }) {
+  if (authorLogin === DEPENDABOT_LOGIN) {
+    return { ok: true, reason: ISSUE_LINK_REASON.OK_DEPENDABOT_EXEMPT };
+  }
+
   if (hasClosingKeyword(prBody)) {
     return { ok: true, reason: ISSUE_LINK_REASON.OK_CLOSING_KEYWORD };
   }
@@ -159,6 +172,7 @@ function main() {
     prBody: process.env.PR_BODY || '',
     headRef: process.env.HEAD_REF || '',
     sameRepo: process.env.SAME_REPO === 'true',
+    authorLogin: process.env.PR_AUTHOR_LOGIN || '',
     changedFiles,
     changedFilesTotal,
   });
@@ -179,6 +193,7 @@ if (require.main === module) runMain(main);
 module.exports = {
   ISSUE_LINK_REASON,
   BACKMERGE_BRANCH_PREFIX,
+  DEPENDABOT_LOGIN,
   EXEMPT_PATH_PREFIXES,
   EXCLUDED_ROOT_DOCS,
   CLOSING_KEYWORD_REGEX,

package/scripts/workflow-size.cjs

@@ -89,10 +89,149 @@ function measureWorkflows(dir = WORKFLOWS_DIR) {
   return measureMdFiles(dir);
 }
 
+/**
+ * #4261: the reserved margin, as a fraction of a tier's hard cap.
+ *
+ * The hard caps are red lines and stay exactly where they are. This is the
+ * second, softer level the caps never had: `execute-phase.md` already carries
+ * a hand-rolled version of this shape (a hard `< 93600` plus a `<= 93400`
+ * margin whose own message says it exists "so minor future edits don't
+ * re-trip the gate"), and it is the only capped file that does. Everywhere
+ * else a file is either fine or already over, with nothing in between — so
+ * the first signal a contributor gets is a failure, and by then the cheap
+ * moment to extract has passed.
+ *
+ * 95% is deliberately not derived from anything. It is the round number the
+ * issue proposed, and the census below is what makes it reviewable: if it
+ * turns out to name too many or too few files, that is visible in one table
+ * rather than argued from first principles.
+ */
+const MARGIN_RATIO = 0.95;
+
+/**
+ * The reserved-margin threshold for a hard cap, in bytes.
+ *
+ * Floor, not round: the margin must never land ON or above the cap it is
+ * meant to sit under, however small the cap.
+ *
+ * @param {number} cap - Tier hard cap in bytes.
+ * @returns {number} Margin threshold in bytes.
+ */
+function marginFor(cap) {
+  return Math.floor(cap * MARGIN_RATIO);
+}
+
+/**
+ * Build the headroom census for a set of measured files.
+ *
+ * Sorted by pressure (least headroom first) because that is the reading
+ * order that matters: the top row is the file that will break next.
+ *
+ * @param {Object<string, number>} sizes - Map of filename -> LF byte size.
+ * @param {function(string): {tier: string, cap: number}} capFor - Tier lookup, keyed by stem.
+ * @returns {Array<{name: string, tier: string, bytes: number, cap: number, margin: number, headroom: number, usedPct: number, overMargin: boolean}>}
+ */
+function buildHeadroomRows(sizes, capFor) {
+  return Object.entries(sizes)
+    .map(([file, bytes]) => {
+      const name = file.replace(/\.md$/, '');
+      const { tier, cap } = capFor(name);
+      const margin = marginFor(cap);
+      return {
+        name,
+        tier,
+        bytes,
+        cap,
+        margin,
+        headroom: cap - bytes,
+        usedPct: (bytes / cap) * 100,
+        overMargin: bytes > margin,
+      };
+    })
+    .sort((a, b) => a.headroom - b.headroom || a.name.localeCompare(b.name));
+}
+
+/**
+ * Render the census as a fixed-width text table for the test diagnostics.
+ *
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @param {{limit?: number}} [opts] - How many rows to render (default: all).
+ * @returns {string[]} Lines, ready to hand to `t.diagnostic` one at a time.
+ */
+function formatHeadroomTable(rows, { limit = Infinity } = {}) {
+  const shown = rows.slice(0, limit);
+  const width = Math.max(4, ...shown.map((r) => r.name.length));
+  const head = `${'file'.padEnd(width)}  ${'tier'.padEnd(7)}  ${'bytes'.padStart(7)}  ${'cap'.padStart(7)}  ${'margin'.padStart(7)}  ${'headroom'.padStart(8)}  ${'used'.padStart(6)}`;
+  const body = shown.map(
+    (r) =>
+      `${r.name.padEnd(width)}  ${r.tier.padEnd(7)}  ${String(r.bytes).padStart(7)}  ${String(r.cap).padStart(7)}  ${String(r.margin).padStart(7)}  ${String(r.headroom).padStart(8)}  ${r.usedPct.toFixed(1).padStart(5)}%`,
+  );
+  return [head, ...body];
+}
+
+/**
+ * Render the census as a GitHub job-summary markdown table.
+ *
+ * Only the rows over the reserved margin: a job summary that lists all 124
+ * capped files is a log dump nobody reads, and every row below the margin is
+ * by definition not the problem. The count of the rest is still reported so
+ * an empty table cannot be mistaken for an unmeasured one.
+ *
+ * @param {string} title - Section heading (e.g. `'Agent size headroom'`).
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @returns {string} Markdown block.
+ */
+function buildHeadroomSummaryMarkdown(title, rows) {
+  const pressured = rows.filter((r) => r.overMargin);
+  const lines = [`### ${title}`, ''];
+  if (pressured.length === 0) {
+    lines.push(`All ${rows.length} files are under the ${Math.round(MARGIN_RATIO * 100)}% reserved margin.`);
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push(
+    `**${pressured.length} of ${rows.length}** files are over the ${Math.round(MARGIN_RATIO * 100)}% reserved margin.`,
+    '',
+    '| file | tier | bytes | cap | headroom | used |',
+    '| --- | --- | ---: | ---: | ---: | ---: |',
+  );
+  for (const r of pressured) {
+    lines.push(`| \`${r.name}\` | ${r.tier} | ${r.bytes} | ${r.cap} | ${r.headroom} | ${r.usedPct.toFixed(1)}% |`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Append a census block to `$GITHUB_STEP_SUMMARY` when running in CI.
+ *
+ * No-op off CI, and never throws: this is reporting, and a test suite must
+ * not go red because a summary file was not writable.
+ *
+ * @param {string} title - Section heading.
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean} Whether anything was written.
+ */
+function appendHeadroomStepSummary(title, rows, env = process.env) {
+  if (!env.GITHUB_STEP_SUMMARY) return false;
+  try {
+    fs.appendFileSync(env.GITHUB_STEP_SUMMARY, `${buildHeadroomSummaryMarkdown(title, rows)}\n`);
+    return true;
+  } catch (err) {
+    process.stderr.write(`workflow-size: could not write GITHUB_STEP_SUMMARY: ${err.message}\n`);
+    return false;
+  }
+}
+
 module.exports = {
   WORKFLOWS_DIR,
+  MARGIN_RATIO,
   lfByteCount,
   listWorkflowStems,
   measureMdFiles,
   measureWorkflows,
+  marginFor,
+  buildHeadroomRows,
+  formatHeadroomTable,
+  buildHeadroomSummaryMarkdown,
+  appendHeadroomStepSummary,
 };

package/skills/gsd-cleanup/SKILL.md

@@ -5,6 +5,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - AskUserQuestion
 ---
 

package/skills/gsd-code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-code-review
 description: "Review source files changed during a phase for bugs, security issues, and code quality problems"
-argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]"
+argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]] [reviewer-lane flags]"
 allowed-tools:
   - Read
   - Bash
@@ -26,6 +26,7 @@ Arguments:
 - `--fix` (optional) — after review completes (or if REVIEW.md already exists), auto-apply fixes found. Spawns gsd-code-fixer agent. Accepts sub-flags:
   - `--all` — include Info findings in fix scope (default: Critical + Warning only)
   - `--auto` — enable fix + re-review iteration loop, capped at 3 iterations
+- Optional reviewer-lane flags (#4209) — any flag returned by `gsd_run review-lane flags` (the canonical reviewer-lane roster; e.g. `--codex`, `--agy`) requests that lane independently review the same already-resolved scope alongside the internal `gsd-code-reviewer` agent. Its findings are corroborating evidence only — `gsd-code-reviewer` alone verifies each claim against the actual source and writes REVIEW.md; there is exactly one REVIEW.md schema. No reviewer-lane flag (the default) reviews with only the internal agent, byte-for-byte unchanged from before #4209.
 
 Output: {padded_phase}-REVIEW.md in phase directory + inline summary of findings
 </objective>

package/skills/gsd-complete-milestone/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
 ---
 
 

package/skills/gsd-config/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - AskUserQuestion
 ---
 

package/skills/gsd-debug/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - Agent
   - AskUserQuestion
 ---

package/skills/gsd-execute-phase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsd-execute-phase
-description: "Execute all plans in a phase with wave-based parallelization"
+description: "SDD phase execution — execute all plans in a phase with dependency-aware wave parallelization"
 argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
 allowed-tools:
   - Read

package/skills/gsd-graphify/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[build|query <term>|status|diff]"
 allowed-tools:
   - Read
   - Bash
+  - Grep
 ---