Merge remote-tracking branch 'origin/master' into garrytan/pr-gate

Three defects a second blind reviewer found that survived round 5. All three
reproduced against cf7a1616 before the fix and are pinned after it.

1. The fence scanner still falsely closed compliant descriptions. CommonMark 4.5
   forbids a backtick in a BACKTICK fence's info string, so ```foo`bar is an
   ordinary paragraph. The scanner opened a fence on it, never found a closer,
   and stripped the body to EOF:

     body = '```foo`bar' + three sentences of real prose + an image embed
     before: intentWordCount 0, misses [missing_intent, missing_screenshot]
     after:  intentWordCount 52, misses []

   Same class as round 5's closing-length bug and the same cost — opening a
   block CommonMark would not open deletes the author's prose exactly the way
   closing one late did. Tilde fences keep the permissive rule (4.5 restricts
   backtick fences only).

2. The spend guard hashed less than the model consumes. hashInputs covered
   title, modelBody, head.sha, exemption and policy ids — but the payload also
   carries the changed-file list and the diff, and the workflow degrades the
   diff to a marker line when the API 406s on a huge one. So a run that
   classified with no diff cached a diff-blind verdict, and the next run — real
   diff in hand, same title/body/sha — matched the hash and was served that
   verdict permanently (measured: anthropicCalls 1 across both runs). The
   assembled payload is now folded in as a fixed-width digest, inside the JSON
   tuple where quoting still makes a forged boundary impossible. Round 5's
   property is re-pinned: a policy fix past the model's body cap invalidates
   even when the payload is byte-identical.

3. The workflow's ${{ }}-in-run scanner missed a legal commented block header.
   `run: | # shell block` is valid YAML — js-yaml puts the following
   interpolation in the script — but the header fell through to the
   single-line branch, which captured `| # shell block` as the whole command
   and never looked at the block body. The rule protecting against shell
   injection reported clean over an interpolating workflow. The scanner now
   handles a trailing comment on the header, and scans the comment text too
   rather than leaving itself a hiding place. Guarded against js-yaml's actual
   parse, not against the scanner's own opinion.

Also corrected one overstated claim in the file's security block: a BARE url in
a sanitized string still autolinks under GFM. That is a self-labelled link and
the deliberate stopping point — the escaping targets the masking characters so
it cannot forge `![APPROVED](…)` or `[click to approve](…)` — but "no live
links" was too strong for what the code does.

Self-audit: all 13 interpolations into the sticky comment are either literals in
this file or pass sanitizeModelText/sanitizeList; the only unsanitized one
(titleCheck.reason) is a hardcoded literal and renders inside a code span. Every
rendered statement matches behavior the code performs. The four realistic-human
fixtures and the three new fence cases all PASS; empty, "fixes bug", the
unfilled template, ten words of lorem and a fenced-away screenshot all still
FAIL.

test/pr-gate-workflow.test.ts 158 -> 163 pass, 0 fail. Six mutations (the
CommonMark rule, the tilde exemption, the payload digest, the runGate wiring,
the scanner's comment group, the header-comment scan) each fail at least one
test. typecheck, actionlint, verify (34/34) green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.github/workflows/pr-gate.yml

@@ -0,0 +1,110 @@
+name: PR Gate
+
+# Strict PR usefulness gate (#3698): classifies every PR to master into
+# merge-lane / close-lane / needs-maintainer BEFORE any human review effort.
+# Verdict + reviewer checklist land in one sticky comment; exactly one
+# gate:* label is applied; close-lane exits 1 (red X = strong signal).
+#
+# SECURITY MODEL (pull_request_target on a 30k-star public repo):
+# - PR code is NEVER checked out or executed. Metadata + diff come from the
+#   GitHub API only; the diff is capped at 120KB.
+# - The checkout below is the BASE repo (master) — rubric/script only.
+#   NEVER add a `ref:` pointing at the PR head.
+# - Attacker-controlled values (title/body/diff) never touch the shell:
+#   every ${{ }} is env-bound; run: scripts use plain env vars.
+# - Only the issues API is used (comments + labels), so issues:write is the
+#   single write grant; the checkout drops its credentials.
+# - The mechanical CONTRIBUTING.md #3745 check (intent paragraph + screenshot)
+#   runs BEFORE any API dependency, so a PR missing either still lands in
+#   close-lane during an Anthropic outage — an outage is not a way through.
+# - If ANTHROPIC_API_KEY is missing or the API is unreachable on an otherwise
+#   compliant PR, the script NEUTRAL-skips loudly (sticky comment + warning
+#   annotation, exit 0) and CLEARS any stale gate:* label — never a silent
+#   green, never a red X for a missing secret, never a stale verdict. A model
+#   REFUSAL is not a skip: it routes to needs-maintainer so refusing is not a
+#   way to dodge the gate.
+#
+# #3745 EXEMPTION (deliberate — mirrors policyExemption() in
+# scripts/pr-gate.mjs): the intent-paragraph + screenshot requirement filters
+# INCOMING OUTSIDE CONTRIBUTIONS. It is waived for repo owners / members /
+# collaborators, bot authors, and drafts.
+# Release automation cannot take a screenshot of itself, and without the
+# exemption every /ship release PR lands in close-lane
+# (measured: 40 of the last 40 merged PRs) — a check that is red
+# on every release gets switched off within a week, and then it filters
+# nothing. Exempt PRs still get the FULL usefulness verdict, the title rule and
+# every mechanical red flag; only the description requirement is skipped, and
+# the sticky comment says so on its own line.
+# author_association / draft / user.type are read from the pr.json fetched
+# below — GitHub-computed, not author-settable (except `draft`), and already
+# on disk, so nothing new is fetched and there is one source of truth.
+# `ready_for_review` is in the trigger list precisely because `draft` IS
+# author-settable: leaving draft re-runs the gate with the exemption gone, and
+# the exemption is folded into the spend-guard hash so the draft-era verdict
+# cannot be reused.
+# Pinned by test/pr-gate-workflow.test.ts.
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+    branches: [master]
+
+# issues:write is the ONLY write grant. Everything the script calls is the
+# issues API (comments, label create, label add/remove on the PR's issue), so
+# pull-requests:write would be a redundant second grant on the same objects.
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: pr-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # Base repo (master) only — provides scripts/pr-gate.mjs.
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          # Nothing here needs git auth after the clone; don't leave a token
+          # in .git/config for the rest of the job.
+          persist-credentials: false
+
+      - name: Fetch PR metadata + diff (API only — PR code is never checked out)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/pr-gate"
+          gh api "repos/${REPO}/pulls/${PR_NUMBER}" > "$RUNNER_TEMP/pr-gate/pr.json"
+          # First 100 files is enough: red flags key off pr.json's changed_files
+          # count, and >40 files already flags.
+          gh api "repos/${REPO}/pulls/${PR_NUMBER}/files?per_page=100" \
+            > "$RUNNER_TEMP/pr-gate/files.json"
+          # Diff via the .diff media type; GitHub can 406 on huge diffs —
+          # degrade to a marker instead of failing the gate.
+          gh api "repos/${REPO}/pulls/${PR_NUMBER}" \
+            -H "Accept: application/vnd.github.diff" \
+            > "$RUNNER_TEMP/pr-gate/pr.diff.full" \
+            || printf '[diff unavailable from the GitHub API — too large or unfetchable]\n' \
+              > "$RUNNER_TEMP/pr-gate/pr.diff.full"
+          MAX=122880  # 120KB cap
+          if [ "$(wc -c < "$RUNNER_TEMP/pr-gate/pr.diff.full")" -gt "$MAX" ]; then
+            head -c "$MAX" "$RUNNER_TEMP/pr-gate/pr.diff.full" > "$RUNNER_TEMP/pr-gate/pr.diff"
+            printf '\n\n[TRUNCATED: diff capped at 120KB]\n' >> "$RUNNER_TEMP/pr-gate/pr.diff"
+          else
+            mv "$RUNNER_TEMP/pr-gate/pr.diff.full" "$RUNNER_TEMP/pr-gate/pr.diff"
+          fi
+          rm -f "$RUNNER_TEMP/pr-gate/pr.diff.full"
+
+      - name: Gate verdict (sticky comment + label; exit 1 only on close-lane)
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: node scripts/pr-gate.mjs "$RUNNER_TEMP/pr-gate"

scripts/pr-gate.d.mts

@@ -0,0 +1,94 @@
+/** Type surface of scripts/pr-gate.mjs for test/pr-gate-workflow.test.ts (tsc-only). */
+export interface TitleCheck {
+  ok: boolean;
+  reason?: string;
+}
+export declare function checkTitle(title: string): TitleCheck;
+
+export interface ChangedFile {
+  filename: string;
+  status: string;
+  patch?: string;
+  additions?: number;
+  deletions?: number;
+}
+export interface RedFlag {
+  id: string;
+  detail: string;
+}
+export declare function detectRedFlags(input: {
+  changedFiles: number;
+  files: ChangedFile[];
+  diff: string;
+}): RedFlag[];
+
+export declare const RUBRIC: string;
+export declare const MAX_STRING: number;
+export declare const MAX_ITEMS: number;
+export declare const NET_SOURCE_LINE_LIMIT: number;
+export declare const DOWNGRADE_FLAG_IDS: string[];
+
+/** CONTRIBUTING.md #3745: human-written intent paragraph + screenshot of gbrain in use. */
+export declare const CONTRIBUTING_URL: string;
+export declare const INTENT_MIN_WORDS: number;
+export declare const POLICY_FLAG_IDS: string[];
+export declare const POLICY_SCAN_MAX: number;
+export declare const POLICY_EXEMPT_ASSOCIATIONS: string[];
+export declare const AI_INTENT_DOWNGRADE: string;
+export declare function stripCodeFences(body: unknown): string;
+export declare const MODEL_BODY_MAX: number;
+export declare function modelBody(pr: { body?: string } | null | undefined): string;
+export declare function hasScreenshot(body: unknown): boolean;
+export declare function intentWordCount(body: unknown): number;
+export declare function hasIntentParagraph(body: unknown): boolean;
+export declare function detectPolicyMisses(body: unknown): RedFlag[];
+
+export declare function sanitizeModelText(value: unknown, max?: number): string;
+export declare function sanitizeList(value: unknown, maxItems?: number, maxString?: number): string[];
+
+export declare function applyMechanicalDowngrades(
+  lane: string,
+  flags: RedFlag[],
+  intentAuthenticity?: string,
+): { lane: string; downgrades: string[] };
+
+/** The pr.json fields the #3745 exemption reads (all GitHub-computed). */
+export interface PrIdentity {
+  author_association?: string;
+  draft?: boolean;
+  user?: { type?: string; login?: string };
+}
+export declare function policyExemption(pr: PrIdentity | null | undefined): string | null;
+
+export interface GhComment {
+  id?: number;
+  body?: unknown;
+  user?: { type?: string; login?: string };
+}
+export declare function isOwnComment(comment: GhComment | null | undefined): boolean;
+
+export declare function hashInputs(
+  pr: PrIdentity & { title?: string; body?: string; head?: { sha?: string } },
+  /** The assembled model payload (changed files + diff). runGate always passes it. */
+  payload?: string,
+): string;
+export declare function parseState(body: unknown): { hash: string; lane?: string } | null;
+
+export declare function renderComment(input: {
+  lane?: string;
+  verdict?: { confidence?: number; reasons?: unknown; reviewer_checklist?: unknown };
+  titleCheck: TitleCheck;
+  flags: RedFlag[];
+  neutralReason?: string;
+  downgrades?: string[];
+  policyMisses?: RedFlag[];
+  policyExempt?: string | null;
+  labelsCleared?: boolean;
+  state?: { hash: string; lane: string };
+}): string;
+
+export declare function runGate(
+  dir: string,
+  env?: Record<string, string | undefined>,
+  fetchImpl?: typeof fetch,
+): Promise<number>;