@opengsd/gsd-core 1.19.0 → 1.20.1

package/pi/package-agents/gsd-code-reviewer.md

@@ -60,6 +60,8 @@ This ensures project-specific patterns, conventions, and best practices are appl
 
 **3. Code Quality** — Dead code, unused imports/variables, poor naming conventions, missing error handling, inconsistent patterns, overly complex functions (high cyclomatic complexity), code duplication, magic numbers, commented-out code
 
+**4. Necessity** (#4100) — reachable code whose guarded-against problem cannot occur in this stack: impossible-state guard, already-defended-elsewhere, cargo-culted pattern, phantom requirement, generality without instantiation. At `standard`/`deep`, Read `__GSD_PI_ENGINE_ROOT__/gsd-core/references/necessity-review.md` before classifying findings; if it cannot be read, say so in the Summary and omit `necessity:`. `quick` does not assess necessity. Warning when provable from the repo, Info when it rests on judgment, Never Critical; each finding cites the evidence that the state cannot occur and carries a `**Category:** necessity` line.
+
 **Out of Scope (v1):** Performance issues (O(n²) algorithms, memory leaks, inefficient queries) are NOT in scope for v1. Focus on correctness, security, and maintainability.
 
 </review_scope>
@@ -70,12 +72,17 @@ This ensures project-specific patterns, conventions, and best practices are appl
 
 **quick** — Pattern-matching only. Use grep/regex to scan for common anti-patterns without reading full file contents. Target: under 2 minutes.
 
-Patterns checked:
-- Hardcoded secrets: `(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['"][^'"]+['"]`
-- Dangerous functions: `eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru`
-- Debug artifacts: `console\.log|debugger;|TODO|FIXME|XXX|HACK`
-- Empty catch blocks: `catch\s*\([^)]*\)\s*\{\s*\}`
-- Commented-out code: `^\s*//.*[{};]|^\s*#.*:|^\s*/\*`
+Checks (commands in `review_by_depth`):
+- Hardcoded secrets
+- Dangerous functions
+- Debug artifacts
+- Empty catch blocks
+- Commented-out code
+- Unpinned actions
+- Non-idempotent install
+- Missing job timeout
+
+The last three: GitHub Actions workflows only.
 
 **standard** (default) — Read each changed file. Check for bugs, security issues, and quality problems in context. Cross-reference imports and exports. Target: 5-15 minutes.
 
@@ -85,6 +92,7 @@ Language-aware checks:
 - **Go**: Unchecked error returns, goroutine leaks, context not passed, `defer` in loops, race conditions
 - **C/C++**: Buffer overflow patterns, use-after-free indicators, null pointer dereferences, missing bounds checks, memory leaks
 - **Shell**: Unquoted variables, `eval` usage, missing `set -e`, command injection via interpolation
+- **CI/CD pipelines** (by path: `.github/workflows/*.yml`, `Dockerfile*`, `docker-compose*.yml`, deploy scripts): Read `__GSD_PI_ENGINE_ROOT__/gsd-core/references/cicd-review-patterns.md`; if it cannot be read, say so in the Summary and check: non-idempotent steps (`npm install` vs `npm ci`, unlocked `pip install`, unguarded `mkdir`/`rm`), no job `timeout-minutes`, deploy without `concurrency` + `cancel-in-progress`, per-environment rebuild (not build-once), no health check or rollback, load-bearing `continue-on-error`, static credentials where OIDC works, unpinned actions
 
 **deep** — All of standard, plus cross-file analysis. Trace function call chains across imports. Target: 15-30 minutes.
 
@@ -173,6 +181,7 @@ NOTE: Do NOT exclude all `.md` files — commands, workflows, and agents are sou
 - Go: `.go`
 - C/C++: `.c`, `.cpp`, `.h`, `.hpp`
 - Shell: `.sh`, `.bash`
+- CI/CD (by path): `.github/workflows/*.yml`/`*.yaml`, `Dockerfile*`, `docker-compose*.yml`, `deploy*.sh` (also Shell)
 - Other: Review generically
 
 **3. Exit early if empty:** If no source files remain after filtering, create REVIEW.md with:
@@ -193,22 +202,48 @@ NOTE: `status: clean` means "reviewed and found no issues." `status: skipped` me
 Branch on depth level:
 
 **For depth=quick:**
-Run grep patterns (from `<depth_levels>` quick section) against all files:
+Run every check from `<depth_levels>` quick section:
 ```bash
+# Set FILE per scoped path with: while IFS= read -r FILE (never paste a name into code).
+
 # Hardcoded secrets
-grep -n -E "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"]\w+['\"]" file
+grep -n -E -- "(password|secret|api_key|token|apikey|api-key)\s*[=:]\s*['\"][^'\"]+['\"]" "$FILE"
 
 # Dangerous functions
-grep -n -E "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec" file
+grep -n -E -- "eval\(|innerHTML|dangerouslySetInnerHTML|exec\(|system\(|shell_exec|passthru" "$FILE"
 
 # Debug artifacts
-grep -n -E "console\.log|debugger;|TODO|FIXME|XXX|HACK" file
-
-# Empty catch
-grep -n -E "catch\s*\([^)]*\)\s*\{\s*\}" file
+grep -n -E -- "console\.log|debugger;|TODO|FIXME|XXX|HACK" "$FILE"
+
+# Empty catch blocks
+grep -n -E -- "catch\s*\([^)]*\)\s*\{\s*\}" "$FILE"
+
+# Commented-out code
+grep -n -E -- "^\s*//.*[{};]|^\s*#[[:space:]]*(if|for|while|def|class|elif|else|try|except|with)[[:space:](].*:[[:space:]]*$|^\s*/\*[^*].*[{};]" "$FILE"
+
+# Unpinned actions
+grep -n -E -- "^[[:space:]]*(-[[:space:]]+)?uses:[[:space:]]*['\"]?[^[:space:]'\"]+@(main|master|latest)['\"]?([[:space:]]|$)" "$FILE"
+
+# Non-idempotent install
+[ -f package-lock.json ] && grep -n -E -- "(^|[^[:alnum:]_-])npm[[:space:]]+(install|i)([[:space:]]|$)" "$FILE" | grep -v -E "^[0-9]+:[[:space:]]*#|[[:space:]](-g|--global)([[:space:]]|$)"
+
+# Missing job timeout
+awk '
+function flush() { if (job != "" && runs && !timed) print line ": " job ": no job-level timeout-minutes"; job = "" }
+{ sub(/\r$/, "") }
+/^[^[:space:]#]/ { flush(); injobs = ($0 ~ /^jobs:[[:space:]]*(#.*)?$/); jind = -1; next }
+!injobs || /^[[:space:]]*(#.*)?$/ { next }
+{ ind = match($0, /[^ ]/) - 1 }
+jind < 0 { jind = ind }
+ind == jind { flush(); job = $0; sub(/^ +/, "", job); sub(/:.*/, "", job); line = NR; kind = -1; runs = 0; timed = 0; next }
+kind < 0 { kind = ind }
+ind == kind && /^ *runs-on:/ { runs = 1 }
+ind == kind && /^ *timeout-minutes:/ { timed = 1 }
+END { flush() }
+' "$FILE"
 ```
 
-Record findings with severity: secrets/dangerous=Critical, debug=Info, empty catch=Warning
+Record findings with severity: secrets/dangerous=Critical, debug and commented-out code=Info, empty catch and the three CI/CD checks=Warning
 
 **For depth=standard:**
 For each file:
@@ -252,6 +287,7 @@ For each finding, assign severity:
 - Type coercion issues (`==` vs `===`)
 - Unhandled promise rejections
 - Dead code paths that indicate logic errors
+- CI/CD pipeline findings: every check in the CI/CD entry
 
 **Info** — Style issues, naming improvements, dead code, unused imports, suggestions:
 - Unused imports/variables
@@ -286,10 +322,13 @@ findings:
   warning: N
   info: N
   total: N
+  necessity: N
 status: clean | issues_found
 ---
 ```
 
+Emit `necessity:` only at standard/deep depth. It counts the necessity findings among `warning` + `info` and is never added to `total`.
+
 **3. Body sections (required order):**
 1) `## Structural Findings (fallow)` — only when structural findings were provided; list normalized items first.
 2) `## Narrative Findings (AI reviewer)` — your adversarial findings from direct code review, including any external-reviewer claim you independently verified (`(external: {slug})`, see `load_context` step 5).

package/pi/package-agents/gsd-executor.md

@@ -761,7 +761,14 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 </self_check>
 
 <state_updates>
-After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (named flags):
+After SUMMARY.md, update ROADMAP.md progress FIRST, then STATE.md. The ROADMAP write is the step that can decline (`missing_phase_details`), and a decline stops the plan before any STATE.md write, so STATE.md never advances past a plan the ROADMAP did not record:
+
+```bash
+# Update ROADMAP.md progress for this phase (plan counts, status). A decline stops here, before STATE.md moves.
+PROGRESS=$(gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}") && REASON=$(jq -er '.reason//""' <<<"$PROGRESS") && [ "$REASON" != missing_phase_details ] || { echo "ERROR: ROADMAP update-plan-progress did not complete for ${PHASE_NUMBER}-${PLAN} (missing_phase_details decline, failed query, or jq not installed). STOP: skip this plan's completion steps." >&2; exit 1; }
+```
+
+Then update STATE.md using `gsd-tools query` state handlers (named flags):
 
 ```bash
 # Advance plan counter (handles edge cases automatically)
@@ -788,9 +795,6 @@ gsd_run query state.record-session \
 ```
 
 ```bash
-# Update ROADMAP.md progress for this phase (plan counts, status)
-gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}"
-
 # Mark completed requirements from PLAN.md frontmatter
 # Extract the `requirements` array from the plan's frontmatter, then mark each complete
 gsd_run query requirements.mark-complete ${REQ_IDS}

package/pi/package-agents/manifest.json

@@ -3,8 +3,8 @@
     "gsd-advisor-researcher.md": "6988b236b53568bbcea7886d11ca9f0badf9aedb3f650d42ca894211d91aafe4",
     "gsd-ai-researcher.md": "bdc567357f7361d7e427a2730bdac17c0b28ecb1bcbbc687df68d573f0ee9f3e",
     "gsd-assumptions-analyzer.md": "56b243f4c50403cbc133ad8c91ae40aa1aeceadd6624d0fd26406ebf8c113205",
-    "gsd-code-fixer.md": "11a76631ffe74bf5deb707d69b8412bf4251fe8ae87e03cdd59bc28fc6e3904d",
-    "gsd-code-reviewer.md": "de2a37a6e76bf1d70ff16cb16881326b60a7236194d6126abe5a40d0fd9a98f5",
+    "gsd-code-fixer.md": "2d806b6bae3797a7757b4872a93790fe33a4f22e90f6e71f6344b52df3048d52",
+    "gsd-code-reviewer.md": "459b38676fd7e6b7bf147a9c3d88243630ff289366a359c7c489536d38b2bd21",
     "gsd-codebase-mapper.md": "5901db6721a6f2365be52819a41ab1c1590a7cbbbdc6d992dce2a7b99f7d12fb",
     "gsd-debug-session-manager.md": "7b68386a6ab0169eb4c1b44afa921b8196db1eac1af3a0dd07a87d5ae2b208ef",
     "gsd-debugger.md": "7328920b7fbee1b76af7259a14b96290562544d97c6ced1291e1e1f3529e1598",
@@ -16,7 +16,7 @@
     "gsd-domain-researcher.md": "f1b07d9c79dcb89c90e5af7f61adfa5dc73ebe8429783d8cb281d7ae2bdc682b",
     "gsd-eval-auditor.md": "9d77e7329c52741e7e62185b566231eb872c6b34afa6c869960a922af573b3d5",
     "gsd-eval-planner.md": "efc12a2822d77a5989db2e3efe83b7fda9f0509bb203910d7e26eb9369f89949",
-    "gsd-executor.md": "2302fb8b45608b422eb956db27d449e7d5f5c2d41c772188d675ad4f260c342e",
+    "gsd-executor.md": "45e9540f6380b1883ad5b144411b21447eef20f310cbd0ab7c72c2bdaf5f8c47",
     "gsd-framework-selector.md": "96d52931468372ee88c4f1d551c13c97d2be8079053b55d992e0ea1720d3d5c9",
     "gsd-integration-checker.md": "a233ab8c5c97b6099c649d1e9a09e88ff1ed1bf7df7c1b13bc766c33d58e09b9",
     "gsd-intel-updater.md": "26c70b81580cc5bf713959bdcc84a16a35569861d2e79c07c71258ccd05ba9bc",

package/pi/package-skills/gsd-new-milestone/SKILL.md

@@ -26,7 +26,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 - `.planning/ROADMAP.md` — phase structure (continues numbering)
 - `.planning/STATE.md` — reset for new milestone
 
-**After:** `/skill:gsd-plan-phase [N]` to start execution.
+**After:** Run `/skill:gsd-discuss-phase [N]` to clarify the approach (or `/skill:gsd-plan-phase [N]` to plan directly); then `/skill:gsd-execute-phase [N]` to execute.
 </objective>
 
 <execution_context>

package/pi/package-skills/gsd-new-project/SKILL.md

@@ -32,7 +32,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
 
-**After this command:** Run `/skill:gsd-plan-phase 1` to start execution.
+**After this command:** Run `/skill:gsd-discuss-phase 1` to clarify the approach (or `/skill:gsd-plan-phase 1` to plan directly); then `/skill:gsd-execute-phase 1` to execute.
 </objective>
 
 <execution_context>

package/pi/package-skills/gsd-update/SKILL.md

@@ -33,14 +33,17 @@ Routes to the update workflow which handles:
 <flags>
 - **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
 - **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+  - **--interactive[=exceptions|all]** (with `--reapply` only): show each user edit next to the stock text with a recommended disposition and wait for a keep / retire / rewrite decision per edit. `all` shows every edit; `exceptions` (bare `--interactive`) shows only edits upstream adopted, partly adopted, reworded around, or orphaned, and keeps the rest. Without it, `--reapply` behaves exactly as before.
 - **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
 - **(no flag)**: Standard update — check for new version, show changelog, install.
 </flags>
 
 <process>
+If the arguments contain `--interactive` (bare or with a value) but not `--reapply`, STOP with: `--interactive applies only to --reapply (for example: /skill:gsd-update --reapply --interactive=all)`. Do nothing else.
+
 Parse the first token of the `<arguments>` block:
 - If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
-- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow, passing the remaining arguments (for example `--interactive=all`) to it.
 - Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing the `<arguments>` block through so the workflow's parse_update_channel step can select the release channel.
 
 </process>

package/scripts/changeset/lint.cjs

@@ -20,6 +20,9 @@ const LINT_REASON = Object.freeze({
   OK_FRAGMENT_PRESENT: 'ok_fragment_present',
   OK_OPT_OUT_LABEL: 'ok_opt_out_label',
   OK_NO_USER_FACING_CHANGES: 'ok_no_user_facing_changes',
+  // #5903: the release pipeline's own PRs consume every fragment into
+  // CHANGELOG.md, so they carry none by design.
+  OK_RELEASE_PIPELINE: 'ok_release_pipeline',
   FAIL_MISSING_FRAGMENT: 'fail_missing_fragment',
   FAIL_INVALID_FRAGMENT: 'fail_invalid_fragment',
   FAIL_PR_FIELD_DRIFT: 'fail_pr_field_drift',
@@ -86,13 +89,18 @@ function findPrFieldDrift(prEntries, realPrNumber) {
   return drift;
 }
 
-function evaluateLint({ changedFiles, labels, fragmentFailures = [], prFieldDrift = [] }) {
+function evaluateLint({
+  changedFiles, labels, fragmentFailures = [], prFieldDrift = [], releasePipelineKind = null,
+}) {
   if (fragmentFailures.length > 0) {
     return { ok: false, reason: LINT_REASON.FAIL_INVALID_FRAGMENT, failures: fragmentFailures };
   }
   if (prFieldDrift.length > 0) {
     return { ok: false, reason: LINT_REASON.FAIL_PR_FIELD_DRIFT, drift: prFieldDrift };
   }
+  if (releasePipelineKind) {
+    return { ok: true, reason: LINT_REASON.OK_RELEASE_PIPELINE, releasePipelineKind };
+  }
   if (changedFiles.some(isFragment)) {
     return { ok: true, reason: LINT_REASON.OK_FRAGMENT_PRESENT };
   }
@@ -107,6 +115,7 @@ function evaluateLint({ changedFiles, labels, fragmentFailures = [], prFieldDrif
 
 const { ExitError, runMain } = require('../lib/cli-exit.cjs');
 const { parseFragment } = require('./parse.cjs');
+const { releasePipelinePrKind } = require('../release-pipeline-pr.cjs');
 
 function main() {
   const fs = require('node:fs');
@@ -119,6 +128,12 @@ function main() {
   // `pull_request` in the payload, or no payload at all) — the drift check
   // below is a no-op in that case, it never fails a push run.
   let realPrNumber = null;
+  // #5903: head/base refs and whether the head lives in this repository, for
+  // the release-pipeline exemption. sameRepo is false when anything is missing
+  // (a deleted fork has head.repo === null).
+  let headRef;
+  let baseRef;
+  let sameRepo = false;
   if (eventPath && fs.existsSync(eventPath)) {
     try {
       const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
@@ -126,6 +141,12 @@ function main() {
       if (event.pull_request && Number.isInteger(event.pull_request.number)) {
         realPrNumber = event.pull_request.number;
       }
+      headRef = event.pull_request?.head?.ref;
+      baseRef = event.pull_request?.base?.ref;
+      const headRepo = event.pull_request?.head?.repo?.full_name;
+      const thisRepo = process.env.GITHUB_REPOSITORY;
+      sameRepo = typeof headRepo === 'string' && typeof thisRepo === 'string'
+        && headRepo !== '' && headRepo.toLowerCase() === thisRepo.toLowerCase();
     } catch { /* fall through */ }
   }
   // #2988: local fallback must match the repo's integration branch (`next`),
@@ -176,11 +197,15 @@ function main() {
   }
 
   const prFieldDrift = findPrFieldDrift(prEntries, realPrNumber);
-  const verdict = evaluateLint({ changedFiles, labels, fragmentFailures, prFieldDrift });
+  const releasePipelineKind = releasePipelinePrKind({ headRef, baseRef, sameRepo });
+  const verdict = evaluateLint({
+    changedFiles, labels, fragmentFailures, prFieldDrift, releasePipelineKind,
+  });
   if (process.argv.includes('--json')) {
     process.stdout.write(JSON.stringify({ ...verdict, changedFiles, labels }, null, 2) + '\n');
   } else if (verdict.ok) {
-    process.stdout.write(`ok changeset-lint: ${verdict.reason}\n`);
+    const kind = verdict.releasePipelineKind ? ` (${verdict.releasePipelineKind})` : '';
+    process.stdout.write(`ok changeset-lint: ${verdict.reason}${kind}\n`);
   } else if (verdict.reason === LINT_REASON.FAIL_INVALID_FRAGMENT) {
     process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
     process.stderr.write(`The following .changeset fragment(s) failed content validation:\n`);

package/scripts/ci-next-health.cjs

@@ -59,14 +59,158 @@ function classifyRunConclusion(payload) {
   return VERDICT.RED;
 }
 
+// Run statuses that mean "an attempt is still going". A run object reports the
+// state of its LATEST attempt only, so a re-run of a red run reads as
+// in-flight with no trace of the failure it is re-running.
+const IN_FLIGHT_STATUSES = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
+
+function isInFlight(run) {
+  return Boolean(run) && IN_FLIGHT_STATUSES.has(run.status);
+}
+
+/**
+ * Pure, total: the "list workflow runs" payload (newest first, ANY status) ->
+ * the verdict, the run it rests on, and why. Never throws.
+ *
+ * A completed newest run is judged by classifyRunConclusion. An in-flight
+ * newest run is never read as healthy on its own:
+ *  - a re-run (`run_attempt` > 1) whose previous attempt did not succeed is RED
+ *    — the fetcher attaches that attempt's conclusion as
+ *    `previous_attempt_conclusion`, because the list endpoint cannot show it;
+ *  - otherwise the newest SETTLED run decides (red stays RED, green is CLEAN).
+ * This is what stops a mid-flight re-run from hiding the failure it re-runs
+ * (2026-10-27: it let #5755 and #5750 through behind a red `next`).
+ *
+ * @returns {{verdict:string, run:(object|null), reason:string}}
+ */
+function classifyBaseRuns(payload) {
+  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.workflow_runs)) {
+    return { verdict: VERDICT.INDETERMINATE, run: null, reason: 'malformed-payload' };
+  }
+  const runs = payload.workflow_runs;
+  if (runs.length === 0) return { verdict: VERDICT.CLEAN, run: null, reason: 'resolved' };
+
+  const [newest] = runs;
+  if (!isInFlight(newest)) {
+    return {
+      verdict: classifyRunConclusion({ workflow_runs: [newest] }),
+      run: newest,
+      reason: 'resolved',
+    };
+  }
+
+  const prior = newest.previous_attempt_conclusion;
+  if (typeof prior === 'string' && prior !== '' && prior !== 'success') {
+    return { verdict: VERDICT.RED, run: newest, reason: 'rerun-in-flight-after-failure' };
+  }
+  // A re-run of an attempt that succeeded: the newest evidence is green, so an
+  // older red run must not turn the gate red.
+  if (prior === 'success') {
+    return { verdict: VERDICT.CLEAN, run: newest, reason: 'rerun-in-flight-after-success' };
+  }
+
+  const settled = runs.find((run) => !isInFlight(run));
+  if (!settled) return { verdict: VERDICT.CLEAN, run: null, reason: 'newest-in-flight-no-history' };
+  return {
+    verdict: classifyRunConclusion({ workflow_runs: [settled] }),
+    run: settled,
+    reason: 'newest-in-flight',
+  };
+}
+
+// merge_group heads are `gh-readonly-queue/<base>/pr-<N>-<40-hex sha>`; the
+// name carries only the LAST PR of the group.
+const QUEUE_REF_PATTERN = /^(?:refs\/heads\/)?gh-readonly-queue\/(.+)\/pr-(\d+)-[0-9a-f]{40}$/;
+
+/** @returns {{base:string, prNumber:number}|null} */
+function parseQueueRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const match = QUEUE_REF_PATTERN.exec(ref.trim());
+  if (!match) return null;
+  return { base: match[1], prNumber: Number(match[2]) };
+}
+
+// Repository permissions that may apply the bypass label. `maintain` is
+// reported as `write` by this endpoint's legacy `permission` field; both are
+// accepted so a role-name change cannot silently lock the bypass out.
+const BYPASS_PERMISSIONS = new Set(['admin', 'maintain', 'write']);
+const EVENT_PAGES_MAX = 10;
+
+/**
+ * merge_group has no label surface, so read it back from the API. The bypass
+ * is honoured only when ALL hold, and every failure is "not authorized" (RED),
+ * never fail-open:
+ *  1. the ref names a PR and the group holds exactly that one commit — a group
+ *     of several PRs would let one labelled PR carry unlabelled ones;
+ *  2. the PR currently carries the label;
+ *  3. the actor of the label's latest `labeled` event has write or admin
+ *     permission (triage-role users can apply labels).
+ *
+ * `ghGet(path)` returns parsed JSON or throws.
+ *
+ * @returns {Promise<{authorized:boolean, reason:string, actor?:string, prNumber?:number}>}
+ */
+async function evaluateQueueBypass({ headRef, baseRef, baseSha, headSha, repo, ghGet } = {}) {
+  const parsed = parseQueueRef(headRef);
+  if (!parsed) return { authorized: false, reason: 'queue-ref-unparseable' };
+  // The queue branch must be for the branch whose health is being judged.
+  if (typeof baseRef === 'string' && baseRef !== '' && parsed.base !== baseRef) {
+    return { authorized: false, reason: 'queue-base-mismatch', prNumber: parsed.prNumber };
+  }
+  const { prNumber } = parsed;
+  if (!baseSha || !headSha) return { authorized: false, reason: 'no-group-shas', prNumber };
+
+  try {
+    const compare = await ghGet(`/repos/${repo}/compare/${baseSha}...${headSha}`);
+    if (!compare || compare.total_commits !== 1) {
+      return { authorized: false, reason: 'multi-pr-group', prNumber };
+    }
+
+    const labels = await ghGet(`/repos/${repo}/issues/${prNumber}/labels?per_page=100`);
+    const hasLabel = Array.isArray(labels) && labels.some((l) => l && l.name === BYPASS_LABEL);
+    if (!hasLabel) return { authorized: false, reason: 'no-label', prNumber };
+
+    let actor = null;
+    let exhausted = false;
+    for (let page = 1; page <= EVENT_PAGES_MAX; page += 1) {
+      const events = await ghGet(`/repos/${repo}/issues/${prNumber}/events?per_page=100&page=${page}`);
+      if (!Array.isArray(events)) break;
+      for (const event of events) {
+        if (event && event.event === 'labeled' && event.label && event.label.name === BYPASS_LABEL) {
+          actor = event.actor && typeof event.actor.login === 'string' ? event.actor.login : null;
+        }
+      }
+      if (events.length < 100) break;
+      if (page === EVENT_PAGES_MAX) exhausted = true;
+    }
+    // More events than we read: the latest `labeled` event may be unseen, so
+    // the applier is unknown. Fail closed.
+    if (exhausted) return { authorized: false, reason: 'label-applier-unknown', prNumber };
+    if (!actor) return { authorized: false, reason: 'label-applier-unknown', prNumber };
+
+    const perm = await ghGet(`/repos/${repo}/collaborators/${encodeURIComponent(actor)}/permission`);
+    const level = perm && typeof perm.permission === 'string' ? perm.permission : '';
+    if (!BYPASS_PERMISSIONS.has(level)) {
+      return { authorized: false, reason: 'label-applier-lacks-write', actor, prNumber };
+    }
+    return { authorized: true, reason: 'queue-label', actor, prNumber };
+  } catch (err) {
+    return { authorized: false, reason: `bypass-check-failed: ${err.message}`, prNumber };
+  }
+}
+
 /**
  * Dependency-injected orchestrator. `fetchLatestRun` is an async function
  * taking the resolved base branch name and returning the parsed API payload
  * (or throwing) — injected so tests never touch the network.
+ * `evaluateQueueBypass` (merge_group only) is an async function returning
+ * `{authorized, reason, actor}`; it is how a queued fix-forward is recognised.
  *
  * @returns {Promise<{verdict:string, payload:*, reason:string}>}
  */
-async function resolveNextHealth({ fetchLatestRun, eventName, baseRef, labels } = {}) {
+async function resolveNextHealth({
+  fetchLatestRun, eventName, baseRef, labels, evaluateQueueBypass: queueBypass,
+} = {}) {
   if (!APPLICABLE_EVENTS.has(eventName)) {
     return { verdict: VERDICT.SKIPPED_NOT_APPLICABLE, payload: null, reason: 'not-applicable-event' };
   }
@@ -82,23 +226,46 @@ async function resolveNextHealth({ fetchLatestRun, eventName, baseRef, labels }
     return { verdict: VERDICT.INDETERMINATE, payload: null, reason: `fetch-failed: ${err.message}` };
   }
 
-  const classified = classifyRunConclusion(payload);
-  if (classified !== VERDICT.RED) {
-    return { verdict: classified, payload, reason: 'resolved' };
+  const assessed = classifyBaseRuns(payload);
+  // The run the verdict rests on, so annotations link the red run and not the
+  // in-flight re-run that sits in front of it.
+  const evidence = assessed.run ? { workflow_runs: [assessed.run] } : payload;
+  if (assessed.verdict !== VERDICT.RED) {
+    const reason = assessed.reason === 'resolved' ? 'resolved' : assessed.reason;
+    return { verdict: assessed.verdict, payload: evidence, reason };
   }
 
-  // Escape hatch. `labels` is empty/absent for merge_group — that event has no
-  // label surface today, which means a queued merge-group commit cannot use
-  // this bypass. Known gap, not solved here: a maintainer must land the
-  // fix-forward as a direct pull_request merge (where the label IS readable)
-  // rather than through the merge queue, until GitHub exposes an equivalent
-  // signal for merge_group.
+  // Escape hatch for the PR that is itself the fix-forward. pull_request runs
+  // read the label from the event (`labels`). merge_group events carry no
+  // labels, so the queue run asks the API instead (evaluateQueueBypass).
   const labelList = Array.isArray(labels) ? labels : [];
   if (labelList.includes(BYPASS_LABEL)) {
-    return { verdict: VERDICT.BYPASSED, payload, reason: 'bypass-label' };
+    return { verdict: VERDICT.BYPASSED, payload: evidence, reason: 'bypass-label' };
+  }
+
+  if (eventName === 'merge_group' && typeof queueBypass === 'function') {
+    let decision;
+    try {
+      decision = await queueBypass();
+    } catch (err) {
+      decision = { authorized: false, reason: `bypass-check-failed: ${err.message}` };
+    }
+    if (decision && decision.authorized) {
+      return {
+        verdict: VERDICT.BYPASSED,
+        payload: evidence,
+        reason: decision.reason || 'queue-label',
+        actor: decision.actor,
+      };
+    }
+    return {
+      verdict: VERDICT.RED,
+      payload: evidence,
+      reason: `${assessed.reason === 'resolved' ? 'red' : assessed.reason}; bypass: ${decision && decision.reason}`,
+    };
   }
 
-  return { verdict: VERDICT.RED, payload, reason: 'red' };
+  return { verdict: VERDICT.RED, payload: evidence, reason: assessed.reason === 'resolved' ? 'red' : assessed.reason };
 }
 
 function usage() {
@@ -108,9 +275,15 @@ function usage() {
     '',
     'CI-only gate: checks whether the PR/merge-group\'s base branch\'s own last',
     'push-triggered Tests run is red, and fails the job (exit 1) when it is —',
-    'unless the PR carries the "fix-next" bypass label. Every other case',
-    '(wrong event, no resolvable base ref, an unreadable API read) fails open',
-    '(exit 0).',
+    'unless the PR carries the "fix-next" bypass label. A push run that is',
+    'still in flight (including a re-run of a failed run) never counts as',
+    'healthy: a re-run whose previous attempt failed is RED, otherwise the',
+    'newest settled run decides. Every other case (wrong event, no',
+    'resolvable base ref, an unreadable API read) fails open (exit 0).',
+    '',
+    'On merge_group the label is read back from the API: the queue ref must',
+    'name a PR, the group must hold exactly one commit, the PR must carry the',
+    'label, and whoever applied it must have write or admin permission.',
     '',
     'Environment variables read:',
     '  GITHUB_EVENT_NAME     workflow trigger event; only "pull_request" and',
@@ -128,6 +301,12 @@ function usage() {
     '                        the caller workflow must populate this from',
     '                        github.event.pull_request.labels.*.name); checked',
     '                        for the literal "fix-next" bypass label',
+    '  MERGE_GROUP_HEAD_REF  merge-group queue branch',
+    '                        (github.event.merge_group.head_ref; falls back to',
+    '                        GITHUB_REF)',
+    '  MERGE_GROUP_BASE_SHA  merge-group base sha (github.event.merge_group.base_sha)',
+    '  MERGE_GROUP_HEAD_SHA  merge-group head sha (github.event.merge_group.head_sha;',
+    '                        falls back to GITHUB_SHA)',
     '  GITHUB_OUTPUT         path to append verdict= step output to',
     '  GITHUB_STEP_SUMMARY   path to append a human-readable summary to',
   ].join('\n');
@@ -200,9 +379,10 @@ async function main(argv = process.argv.slice(2)) {
   const baseRef = resolveBaseRef(eventName);
   const labels = parseLabels(process.env.PR_LABELS);
 
-  const fetchLatestRun = async (branch) => {
-    const url = `${apiBase}/repos/${repo}/actions/workflows/${TESTS_WORKFLOW_FILE}/runs`
-      + `?branch=${encodeURIComponent(branch)}&event=push&status=completed&per_page=1`;
+  // JSON GET against the API. `path` is either absolute-from-root (starts with
+  // `/`) or a full URL. Returns parsed JSON (null if the body is not JSON).
+  const ghGet = async (pathOrUrl) => {
+    const url = pathOrUrl.startsWith('http') ? pathOrUrl : `${apiBase}${pathOrUrl}`;
     const headers = {
       accept: 'application/vnd.github+json',
       'x-github-api-version': '2022-11-28',
@@ -221,26 +401,66 @@ async function main(argv = process.argv.slice(2)) {
     }
   };
 
-  const result = await resolveNextHealth({ fetchLatestRun, eventName, baseRef, labels });
+  // No `status=completed` filter: an in-flight re-run must be visible so it
+  // cannot hide the failure it is re-running (see classifyBaseRuns).
+  const fetchLatestRun = async (branch) => {
+    const payload = await ghGet(
+      `/repos/${repo}/actions/workflows/${TESTS_WORKFLOW_FILE}/runs`
+      + `?branch=${encodeURIComponent(branch)}&event=push&per_page=5`,
+    );
+    const newest = payload && Array.isArray(payload.workflow_runs) ? payload.workflow_runs[0] : undefined;
+    if (isInFlight(newest) && Number(newest.run_attempt) > 1) {
+      // The list shows only the latest attempt; the previous one holds the
+      // failure being re-run. An API error here propagates -> INDETERMINATE.
+      // If this read fails we cannot show the re-run is not hiding a failure,
+      // and failing open here would reopen the hole this closes: treat an
+      // unreadable previous attempt as not-success (RED).
+      try {
+        const previous = await ghGet(
+          `/repos/${repo}/actions/runs/${newest.id}/attempts/${Number(newest.run_attempt) - 1}`,
+        );
+        newest.previous_attempt_conclusion = previous && typeof previous.conclusion === 'string'
+          ? previous.conclusion : 'unknown';
+      } catch {
+        newest.previous_attempt_conclusion = 'unknown';
+      }
+    }
+    return payload;
+  };
+
+  const evaluateQueue = () => evaluateQueueBypass({
+    headRef: process.env.MERGE_GROUP_HEAD_REF || process.env.GITHUB_REF || '',
+    baseRef,
+    baseSha: process.env.MERGE_GROUP_BASE_SHA || '',
+    headSha: process.env.MERGE_GROUP_HEAD_SHA || process.env.GITHUB_SHA || '',
+    repo,
+    ghGet,
+  });
+
+  const result = await resolveNextHealth({
+    fetchLatestRun, eventName, baseRef, labels, evaluateQueueBypass: evaluateQueue,
+  });
 
   writeOutput([`verdict=${result.verdict}`]);
-  writeSummary(`Base branch health: ${result.verdict}`);
+  writeSummary(`Base branch health: ${result.verdict}${result.reason ? ` (${result.reason})` : ''}`);
 
   if (result.verdict === VERDICT.RED) {
     const runUrl = runUrlOf(result.payload);
     process.stderr.write(
-      `::error::the base branch "${baseRef}"'s own last Tests run is red: ${runUrl} — `
+      `::error::the base branch "${baseRef}"'s own last Tests run is red or still re-running after a failure: ${runUrl} (${result.reason}) — `
       + 'wait for a fix-forward merge, or if THIS pull request is the fix, ask a '
-      + `maintainer to apply the "${BYPASS_LABEL}" label to explicitly override this gate.\n`,
+      + `maintainer with write access to apply the "${BYPASS_LABEL}" label and re-queue it `
+      + '(the queue run reads the label from the API; it must be the only PR in its merge group).\n',
     );
     return 1;
   }
 
   if (result.verdict === VERDICT.BYPASSED) {
     const runUrl = runUrlOf(result.payload);
+    const by = result.actor ? ` (label applied by ${result.actor})` : '';
     process.stderr.write(
       `::warning::the base branch "${baseRef}"'s own last Tests run is red: ${runUrl} — `
-      + `a human applied the "${BYPASS_LABEL}" label to explicitly override this gate.\n`,
+      + `a human applied the "${BYPASS_LABEL}" label to explicitly override this gate${by}.\n`,
     );
     return 0;
   }
@@ -266,6 +486,9 @@ module.exports = {
   BYPASS_LABEL,
   TESTS_WORKFLOW_FILE,
   classifyRunConclusion,
+  classifyBaseRuns,
+  parseQueueRef,
+  evaluateQueueBypass,
   resolveNextHealth,
   main,
 };