ci: unblock docs-only PRs without weakening the gate

.github/workflows/docs-only-gate.yml

@@ -0,0 +1,198 @@
+name: Docs-only gate
+
+# Unblocks DOCS-ONLY pull requests WITHOUT weakening the gate.
+#
+# ci.yml carries `paths-ignore: ['**/*.md', '.myrobots/**', 'LICENSE']` so a
+# prose-only change doesn't burn a ~25-minute pipeline. But ruleset 16042163
+# REQUIRES two contexts — `typecheck + unit + ART + E2E` and
+# `vrt-strict (visual regression — strict subset)` — and a path-skipped workflow
+# reports NOTHING, which GitHub treats as pending forever. A docs-only PR then
+# sits BLOCKED with zero failures and can never auto-merge (live case: #1184).
+#
+# This workflow fires on the EXACT INVERSE path filter (same list P: ci.yml uses
+# `paths-ignore: P`, this uses `paths: P`) and posts those two contexts as
+# COMMIT STATUSES — but only after TWO independent guards agree. The full
+# rationale, including why it posts statuses instead of naming its jobs after
+# the required contexts, lives in scripts/docs-only-gate.mjs; the invariants are
+# ENFORCED by scripts/docs-only-gate.test.ts in the `unit` lane (the path list,
+# the context strings, and the negative controls all fail the build on drift).
+#
+# The one thing to keep in mind when editing: this workflow DOES fire on a PR
+# that touches BOTH docs and code (path filters are per-file ANY-match — they
+# cannot express "every file is a doc"). It must post NOTHING in that case, and
+# it doesn't: guard G1 sees the non-doc file, and guard G2 sees the real ci.yml
+# run that GitHub started for the same SHA. Either one alone is sufficient.
+#
+# Cost: one ~1-minute ubuntu job, and only on PRs that touch a doc path. Code
+# PRs are completely unaffected — ci.yml is untouched by this change, so their
+# wall time does not move.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+    # INVERSE of ci.yml's `paths-ignore`. Keep byte-identical to it — the
+    # complement property is the whole safety argument, and
+    # scripts/docs-only-gate.test.ts fails if the two lists ever drift.
+    paths:
+      - '**/*.md'
+      - '.myrobots/**'
+      - 'LICENSE'
+
+permissions:
+  contents: read
+  actions: read # read: does a ci.yml run exist for this head SHA? (guard G2)
+  pull-requests: read # read: the PR's changed-file list (guard G1)
+  statuses: write # write: the two required contexts, ONLY when both guards pass
+
+concurrency:
+  group: docs-only-gate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # NOTE: this job's `name:` is deliberately NOT one of the required contexts.
+  # A job named after a required context creates a check run the instant it
+  # starts and cannot withdraw it — and a job-level `if:` skip reports as
+  # SUCCESS to branch protection, which would satisfy the gate on precisely the
+  # mixed docs+code PRs where it must not. The contexts are only ever created by
+  # the explicitly guarded API call in the last step.
+  docs-only-gate:
+    name: docs-only gate (bypass check, not a required context)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # ---------------------------------------------------------------------
+      # Guard G1 input — the FULL PR diff (merge-base ... head), which is the
+      # same file set GitHub's own `paths:`/`paths-ignore` evaluation uses for
+      # pull_request events. `--paginate` so a large docs sweep (#1175 touched
+      # 62 files) is not truncated at one page.
+      # ---------------------------------------------------------------------
+      - name: Resolve the PR's changed files
+        id: files
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          FILES=$(gh api "repos/${REPO}/pulls/${PR}/files" \
+            --paginate --jq '.[].filename')
+          echo "resolved $(printf '%s' "$FILES" | grep -c . || true) changed file(s)"
+          # Random heredoc delimiter (GitHub's documented practice): a git path
+          # may legally contain a newline, and a fixed delimiter appearing inside
+          # the payload would TRUNCATE the file list — which, if it dropped the
+          # source file from a mixed PR, is the one truncation that could turn a
+          # code change into an apparently docs-only one. G2 would still refuse,
+          # but do not rely on the second guard for something this cheap to fix.
+          DELIM="CHANGED_FILES_EOF_$(openssl rand -hex 16)"
+          {
+            echo "files<<${DELIM}"
+            printf '%s\n' "$FILES"
+            echo "${DELIM}"
+          } >> "$GITHUB_OUTPUT"
+
+      # ---------------------------------------------------------------------
+      # Guard G2 input — ask GitHub whether IT started the real suite for this
+      # head SHA. Exact by construction: no re-derivation of glob semantics.
+      #
+      # Both workflow runs are created from the same webhook event, so a ci.yml
+      # run (if the filters admitted one) already exists by the time this job
+      # has booted a runner. The poll is pure belt-and-braces against a slow
+      # run-object materialisation; we must observe ABSENCE for the whole
+      # window before considering a bypass.
+      # ---------------------------------------------------------------------
+      - name: Look for a real CI run on this head SHA (guard G2)
+        id: cirun
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          EXISTS=false
+          ATTEMPTS=12
+          for attempt in $(seq 1 "$ATTEMPTS"); do
+            COUNT=$(gh api \
+              "repos/${REPO}/actions/workflows/ci.yml/runs?head_sha=${HEAD_SHA}&per_page=1" \
+              --jq '.total_count' 2>/dev/null || echo "unknown")
+            if [ "$COUNT" = "unknown" ]; then
+              echo "::warning::could not query ci.yml runs (attempt ${attempt}) — treating as PRESENT (fail safe)"
+              EXISTS=true
+              break
+            fi
+            if [ "$COUNT" != "0" ]; then
+              echo "attempt ${attempt}: ci.yml run(s) present for ${HEAD_SHA} (total_count=${COUNT})"
+              EXISTS=true
+              break
+            fi
+            echo "attempt ${attempt}/${ATTEMPTS}: no ci.yml run for ${HEAD_SHA} yet"
+            if [ "$attempt" -lt "$ATTEMPTS" ]; then
+              sleep 5
+            fi
+          done
+          echo "ci_run_exists=${EXISTS}" >> "$GITHUB_OUTPUT"
+
+      # ---------------------------------------------------------------------
+      # The decision — a pure function with unit-tested negative controls
+      # (scripts/docs-only-gate.test.ts). Posts nothing by itself.
+      # ---------------------------------------------------------------------
+      - name: Decide whether the docs-only bypass applies
+        id: decide
+        env:
+          CHANGED_FILES: ${{ steps.files.outputs.files }}
+          CI_RUN_EXISTS: ${{ steps.cirun.outputs.ci_run_exists }}
+          SAME_REPO: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+        run: node scripts/docs-only-gate.mjs decide
+
+      - name: Real CI is authoritative — no bypass
+        if: steps.decide.outputs.post != 'true'
+        env:
+          # Via env, never `${{ }}` inside the script body: the reason embeds
+          # FILENAMES from the PR diff, which are attacker-controllable (a branch
+          # can carry a file whose name contains quotes or backticks) and would
+          # otherwise be spliced into the shell before it runs.
+          REASON: ${{ steps.decide.outputs.reason }}
+        run: |
+          echo "::notice::No docs-only bypass. ${REASON}"
+
+      # ---------------------------------------------------------------------
+      # The ONLY place a required context is ever produced by this workflow.
+      # Guarded on the decision above; contexts come from the same module the
+      # unit test pins against ci.yml's job names.
+      # ---------------------------------------------------------------------
+      - name: Post the required contexts (docs-only bypass)
+        if: steps.decide.outputs.post == 'true'
+        uses: actions/github-script@v7
+        env:
+          # Emitted by the decide step from REQUIRED_CONTEXTS — that module stays
+          # the single source of truth (and the unit test pins it against ci.yml's
+          # job names) without this step needing a dynamic `import()`, which has
+          # no reliable module referrer inside github-script's AsyncFunction body.
+          CONTEXTS: ${{ steps.decide.outputs.contexts }}
+        with:
+          script: |
+            const REQUIRED_CONTEXTS = JSON.parse(process.env.CONTEXTS);
+            const sha = context.payload.pull_request.head.sha;
+            const target_url =
+              `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}` +
+              `/actions/runs/${context.runId}`;
+            for (const ctx of REQUIRED_CONTEXTS) {
+              await github.rest.repos.createCommitStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha,
+                state: 'success',
+                context: ctx,
+                target_url,
+                description: 'docs-only change — CI is path-skipped by design',
+              });
+              core.info(`posted success status "${ctx}" on ${sha}`);
+            }
+            core.notice(
+              `Docs-only bypass: satisfied ${REQUIRED_CONTEXTS.length} required ` +
+                `context(s) on ${sha.slice(0, 9)} without running the suite.`,
+            );

CLAUDE.md

@@ -319,6 +319,32 @@ a just-started green run; it broke main CI and spawned #699/#701/#702 the same
 day. See also `feedback_never_merge_on_red_collab_is_doom_gate` and
 `feedback_no_flake_tolerance`.)
 
+## Docs-only PRs: the path lists in ci.yml and docs-only-gate.yml move TOGETHER
+
+`ci.yml` skips a prose-only change (`paths-ignore: ['**/*.md', '.myrobots/**',
+'LICENSE']`) so a typo fix doesn't burn ~25 min. But ruleset 16042163 REQUIRES
+`typecheck + unit + ART + E2E` and `vrt-strict (visual regression — strict
+subset)`, and a path-skipped workflow reports NOTHING — GitHub treats a
+never-reported required check as pending FOREVER, so the PR sits `BLOCKED` with
+zero failures and can never auto-merge (#1184).
+
+`.github/workflows/docs-only-gate.yml` breaks that: it fires on the **exact
+inverse** filter (`paths:` with the SAME list) and posts those two contexts as
+commit statuses — but only when **both** guards agree: every changed file is a
+doc **and** GitHub started no `ci.yml` run for that head SHA. A PR touching docs
+**and** code fires both workflows; the bypass posts nothing and the real suite
+gates it.
+
+- **Editing `ci.yml`'s `paths-ignore` means editing `docs-only-gate.yml`'s
+  `paths` in the SAME commit** — the complement is the whole safety argument.
+  `scripts/docs-only-gate.test.ts` (unit lane) fails on drift, on a context
+  rename, and on any changeset containing a source file.
+- **Never** satisfy a required context by naming a job after it: a job-level
+  `if:` skip reports as SUCCESS to branch protection, which would green-light
+  the mixed docs+code case. Statuses are posted by an explicit guarded call.
+- Renaming the `ci` or `vrt-strict` job still needs a coordinated ruleset PUT —
+  now plus `REQUIRED_CONTEXTS` in `scripts/docs-only-gate.mjs`.
+
 ## Poly/MIDI modules: e2e the REAL source chain
 
 Any **poly or MIDI module** must ship an e2e that **wires the REAL default-mode