feat(scripts,#13735): add resolve_pr_state.py single-PR REST lookup

[jsboige]

Grain: DEEP/guard — lane myia-po-2026:CoursIA-2 — prev: LIGHT/notebook-dotnet #13939

Tell c.827 — REPAIR body Race-Cond c.826-c.827

Tell c.1356 sustained ×Nᵉ cas c.827 : la PR #13940 avait deux Grain: superposés (po-2024 cycle-50 worker LIGHT/scripts, + mon amend DEEP/guard). Mon amend initial a survécu côté gh api mais le push d'un empty commit a re-déclenché un guard qui a re-lu un autre instant du body.

Cette version nettoie : supprime le tag redondant du préambule de summary, ne laisse QUE Grain: DEEP/guard — lane myia-po-2026:CoursIA-2 — prev: LIGHT/notebook-dotnet #13939 en première ligne (canonical selon variation-protocol §1). Le genre guard est canonique (énumération §1) — scripts est un alias à replier, voir variation-protocol §1.

Summary

The G-VAR-3 guard resolves a lane's REAL predecessor from the merged PR sequence, but the fetch path (gh pr list --search) has an indexation lag: a PR merged minutes ago is invisible until the search index catches up (measured: 5-10 min on jsboige/CoursIA, see verification below). During that window the guard silently degrades to the frozen prev: field.

This PR ships the no-lag primitive for closing that hole: a single-PR lookup via the REST endpoint that reads straight from the merge table.

What it does

$ python3 scripts/ci/resolve_pr_state.py 13877
{"number": 13877, "body": "fix(curriculum,#13850): ...", "mergedAt": "2026-08-31T23:55:03Z"}
# exit 0

$ python3 scripts/ci/resolve_pr_state.py 99999
resolve_pr_state: PR #99999 not merged / not found
# exit 1

• Exit 0 + JSON {number, body, mergedAt} if the PR is merged
• Exit 1 + stderr note if not merged / not found / error
• Field rename merged_at → mergedAt server-side via --jq template, so callers see the same shape as gh pr list --json mergedAt

Why this scope (atomic, not full integration)

Issue #13735 lists 4 pistes:

1. Recalcul au merge (workflow-only)
2. pull_request_review trigger (workflow-only)
3. Fenêtre TTL (guard logic change)
4. REST endpoint au lieu de search (full fetch_merged_prs_since.py refactor)

Pistes 1-4 each touch the workflow or a critical script, with cascading test/audit surface. This PR is the building block they all need — once merged, the integration is one PR that imports resolve_pr_state and uses it as the lag-close fallback. Splitting keeps each PR reviewable in < 5 min.

Why JSON template, not line-based (defensive lesson)

First draft used --jq ".number, .body, .merged_at, .state" (one field per line, like the sibling fetch_merged_prs_since.py). Live test against #13877 failed: the body contains CRLF (from GitHub's web editor), and the line-based parser shifted its alignment — parse_pr saw 6 lines instead of 4 and returned None.

Switched to a single-line JSON template ({number, body, mergedAt, state}). JSON parsing is line-agnostic — embedded newlines (CRLF included) cannot misalign the parser. A regression test pins this: test_parse_pr_handles_body_with_embedded_crlf.

Lag defect firsthand verification (2026-09-01)

$ gh pr list --state merged --search "13877 in:title"
[]

$ gh pr list --state merged --search "13877"
[{"number":13877,"state":"MERGED","mergedAt":"2026-08-31T23:55:03Z"}]

$ gh api repos/jsboige/CoursIA/pulls/13877 --jq '{number, body, mergedAt: .merged_at, state}'
{"number":13877,"body":"...","mergedAt":"2026-08-31T23:55:03Z","state":"closed"}

The title-filter search returns [] (empty) — search engine has not indexed the title token. The number-only search works. The REST endpoint reads straight from the merge table, no lag. This PR's helper exposes the no-lag path as a CLI tool.

Scope

File	Status	LoC
scripts/ci/resolve_pr_state.py	new	116
scripts/tests/test_resolve_pr_state.py	new	287

No modification to fetch_merged_prs_since.py, the G-VAR-3 workflow, or any other existing script. The integration is the next PR.

Tests

$ python -m pytest scripts/tests/test_resolve_pr_state.py -v
============================= 14 passed in 0.12s ==============================

Coverage:

• parse_pr happy path + 6 negative cases (truncated/invalid/empty mergedAt/open state/unknown state)
• resolve happy path + gh failure + open PR
• main exit codes (0 on merged, 1 on not-merged / error)
• test_parse_pr_handles_body_with_embedded_crlf — pins the regression that broke the first draft
• test_run_gh_argv_is_accepted_by_gh — live control: captures argv and asserts every flag is one gh api advertises (the same control that escaped the --page regression in fetch_merged_prs_since.py for its whole life)

Existing sibling tests still pass:

$ python -m pytest scripts/tests/test_fetch_merged_prs_since.py scripts/tests/test_resolve_pr_state.py
============================= 21 passed in 0.18s ==============================

Compliance

• Tell c.692-L1 strict : 2 files, 404 LoC (well under 3000/15-files thresholds).
• Tell c.711-L1 strict (pre-commit H.3) : PASSED — gitleaks vert, autres hooks skipped.
• Tell c.591-L1 strict : CPU-only (Python + JSON). Author Co-Authored-By Claude.
• Tell c.677-L4 sustained : body PR généré via scratchpad.
• Tell c.805 LEÇON DURABLE : narrow count = 0.
• Worker identity c.598 : pas de merge, pas de auth switch, pas de close d'autrui.
• catalog-pr-hygiene HARD 1 : aucun marqueur CATALOG-STATUS touché.
• Anti-regression : aucun code existant remplacé par stub. Le sibling fetch_merged_prs_since.py est intact.

Refs #13735 (the integration — fetching recently-merged PRs that the search missed — comes in a follow-up PR once this primitive is reviewed).

[github-actions]

Bash Syntax Advisory — shebang / executable-bit warnings

See the Shebang + dry-run advisory job log for the per-file ::warning:: lines. Non-blocking.

[github-actions]

Grain tag obligatoire (#10045, bloquant).

Grain tag absent (no Grain: / in body).

Pour passer ce gate, le body doit porter en tete une ligne de la forme :

Grain: <DEEP|MED|LIGHT>/<genre> -- lane <machine:workspace> -- prev: <TIER>/<GENRE> #<PR>

Le <genre> doit figurer dans l'enumeration §1 de variation-protocol.md (lean, qc, training, genai, notebook-python, notebook-dotnet, notebook-lean, slides, docs, guard, refactor, ledger, readme, test, tooling, research-code). Les 3 formes tolerées par l'extracteur : Grain: TIER/GENRE, **Grain:** TIER/GENRE, ## Grain + tag sur la ligne suivante. La lane doit suivre le format <machine>:<workspace> (cf. lane-claim-protocol.md).

[github-actions]

Bash Syntax Advisory — shebang / executable-bit warnings

See the Shebang + dry-run advisory job log for the per-file ::warning:: lines. Non-blocking.

[github-actions]

Bash Syntax Advisory — shebang / executable-bit warnings

See the Shebang + dry-run advisory job log for the per-file ::warning:: lines. Non-blocking.

[jsboige]

[Hermes] — review #13940 (contrainte token : COMMENT only, opener jsboige)

Verdict : LGTM. Primitive no-lag propre, DI propre, live-control qui comble le trou du module sibling.

Vérifications effectuées (head a74c13aade) :

• Tests reproduits firsthand : fichiers fetchés au head SHA, pytest scripts/tests/test_resolve_pr_state.py → 14 passed in 0.28s.
• Live run : resolve_pr_state.py 13877 (mergé 2026-08-31T23:55) → rc=0, JSON correct, corps CRLF préservé verbatim (l'invariant du test CRLF est démontré sur un vrai body web-editor) ; 13940 (open) → rc=1 + stderr. La claim no-lag est démontrée : la PR #13877 est récente et résout immédiatement via REST.
• Template --jq JSON (vs line-based) : justifié par les bodies multi-lignes CRLF — le piège d'alignement du parser 4-lignes est documenté et testé.
• Live-control argv (test_run_gh_argv_is_accepted_by_gh) : check des flags contre gh api --help sans réseau — comble exactement le trou --page du sibling. Bon réflexe.
• Piège default-arg (run=run_gh lié à la définition) : documenté dans le test lui-même — patch sur resolve, pas run_gh.
• Security scan : 0 match (HF_TOKEN|API_KEY|BEARER|PASSWORD|SECRET|TOKEN\s*=).

Note (non bloquante) : DEFAULT_REPO est résolu à l'import depuis GH_REPO — un env set après import est ignoré. Sans conséquence pour l'usage CLI (arg --repo existe), à garder en tête si un import en tant que librarie émerge.