feat: live gate fetch via gh + FlagNonFunctionalGate move

Closes the "no live plumbing" gap the README named as v0.1's next
step, and models a sixth move class mined from a real incident hit
while stewarding the estate's stuck-PR backlog today.

- squabble-cli fetch <owner>/<repo> <pr>: shells to `gh` to pull the
  branch ruleset's required_status_checks and the PR's
  statusCheckRollup, and emits the resulting Gate as JSON -- pipeable
  straight into `squabble diagnose`. Gate-building is a pure,
  fixture-tested function; only the two `gh` calls touch the network.

- Move::FlagNonFunctionalGate: the required check's own script fails
  unconditionally regardless of any exemption file present, so no
  PR-side change can win it. Mined from hyperpolymath/hypatia#566
  (2026-07-01): standards's validate-hypatia-baseline job never read
  .hypatia-baseline.json's content -- confirmed by main itself failing
  the same check for 5+ days independent of any PR. Not auto-appliable;
  the point is recognition + escalation instead of re-proposing
  GroundTruthCheckNames against a deadlock no ground-truthing can fix.

- diagnose_with_hints: a strict refinement of diagnose that lets a
  host with richer context (like fetch's future classifier) supply a
  known Move per required_context instead of the name-only default.
  diagnose itself is untouched -- existing callers see no behaviour
  change.

Dogfooded against a real PR (hyperpolymath/standards#448): fetch
correctly pulled the live ruleset + rollup and diagnose correctly
proposed ground-truthing the one required context with no matching
run name, unprompted.

15/15 tests pass; clippy clean; cargo fmt clean.

Author: hyperpolymath

Cargo.lock

@@ -16,4 +16,5 @@ path = "src/main.rs"
 
 [dependencies]
 squabble-core = { workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }

crates/squabble-cli/Cargo.toml

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//! Live plumbing: turn a real GitHub PR into a [`squabble_core::gate::Gate`].
+//!
+//! This is the "git/`gh` plumbing" the README named as v0.1's next step. It
+//! shells out to the `gh` CLI (already present on every estate runner and on
+//! the owner's machine) rather than adding an HTTP client dependency here —
+//! `squabble-core` stays host-agnostic; this module is the host.
+//!
+//! Two calls, both needed to build a [`Gate`]:
+//!
+//! 1. the branch ruleset's `required_status_checks` contexts (the
+//!    *requirement* set — what must pass, independent of what ran), and
+//! 2. the PR's `statusCheckRollup` (the *realised* runs on the head commit).
+//!
+//! A required context with no matching rollup entry is [`CheckRun::Missing`];
+//! matching-but-incomplete is [`CheckRun::Pending`]; a `SUCCESS` conclusion is
+//! [`CheckRun::Passed`]; anything else that completed is [`CheckRun::Failed`].
+
+use serde::Deserialize;
+use squabble_core::gate::{CheckRun, Gate, RequiredCheck};
+use std::process::Command;
+
+#[derive(Debug, Deserialize)]
+struct RollupEntry {
+    name: String,
+    status: Option<String>,
+    conclusion: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct PrView {
+    #[serde(rename = "baseRefName")]
+    base_ref_name: String,
+    #[serde(rename = "statusCheckRollup")]
+    status_check_rollup: Vec<RollupEntry>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RulesetRule {
+    #[serde(rename = "type")]
+    rule_type: String,
+    parameters: Option<RulesetParameters>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RulesetParameters {
+    #[serde(default)]
+    required_status_checks: Vec<RulesetContext>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RulesetContext {
+    context: String,
+}
+
+/// Parse a `gh pr view --json baseRefName,statusCheckRollup` payload into the
+/// realised-run half of a [`Gate`]. Pure — no IO, fully testable on fixtures.
+fn parse_rollup(entry: &RollupEntry) -> CheckRun {
+    match entry.conclusion.as_deref() {
+        Some("SUCCESS") => CheckRun::Passed,
+        Some("FAILURE")
+        | Some("ERROR")
+        | Some("TIMED_OUT")
+        | Some("CANCELLED")
+        | Some("STARTUP_FAILURE") => CheckRun::Failed,
+        _ => match entry.status.as_deref() {
+            Some("COMPLETED") => CheckRun::Failed, // completed with no recognised conclusion
+            _ => CheckRun::Pending,
+        },
+    }
+}
+
+/// Build a [`Gate`] from the required-context set and the realised rollup.
+/// Pure and the unit of test coverage for this module — the two `gh` calls
+/// in [`run`] exist only to produce these two slices from a live PR.
+fn build_gate(required_contexts: &[String], rollup: &[RollupEntry]) -> Gate {
+    let checks = required_contexts
+        .iter()
+        .map(|required| {
+            let run = rollup
+                .iter()
+                .find(|r| &r.name == required)
+                .map(parse_rollup)
+                .unwrap_or(CheckRun::Missing);
+            RequiredCheck::new(required.clone(), run)
+        })
+        .collect();
+    Gate::new(checks)
+}
+
+fn run_gh(args: &[&str]) -> Result<String, String> {
+    let out = Command::new("gh")
+        .args(args)
+        .output()
+        .map_err(|e| format!("failed to run `gh {}`: {e}", args.join(" ")))?;
+    if !out.status.success() {
+        return Err(format!(
+            "`gh {}` exited {}: {}",
+            args.join(" "),
+            out.status,
+            String::from_utf8_lossy(&out.stderr).trim()
+        ));
+    }
+    Ok(String::from_utf8_lossy(&out.stdout).into_owned())
+}
+
+/// Fetch a live PR's gate from GitHub via `gh` and return it as a [`Gate`].
+///
+/// `slug` is `owner/repo`. Requires `gh` to be authenticated for that repo —
+/// the same precondition every other `gh`-based estate tool already has.
+pub fn run(slug: &str, pr: &str) -> Result<Gate, String> {
+    let (owner, repo) = slug
+        .split_once('/')
+        .ok_or_else(|| format!("expected `owner/repo`, got `{slug}`"))?;
+
+    let pr_json = run_gh(&[
+        "pr",
+        "view",
+        pr,
+        "--repo",
+        slug,
+        "--json",
+        "baseRefName,statusCheckRollup",
+    ])?;
+    let pr_view: PrView = serde_json::from_str(&pr_json)
+        .map_err(|e| format!("could not parse `gh pr view` output: {e}"))?;
+
+    let rules_json = run_gh(&[
+        "api",
+        &format!(
+            "repos/{owner}/{repo}/rules/branches/{}",
+            pr_view.base_ref_name
+        ),
+    ])?;
+    let rules: Vec<RulesetRule> = serde_json::from_str(&rules_json)
+        .map_err(|e| format!("could not parse ruleset response: {e}"))?;
+
+    let required_contexts: Vec<String> = rules
+        .into_iter()
+        .filter(|r| r.rule_type == "required_status_checks")
+        .filter_map(|r| r.parameters)
+        .flat_map(|p| p.required_status_checks)
+        .map(|c| c.context)
+        .collect();
+
+    if required_contexts.is_empty() {
+        return Err(format!(
+            "no `required_status_checks` rule found on `{owner}/{repo}` branch `{}` — \
+             an unprotected branch has no gate to squabble over",
+            pr_view.base_ref_name
+        ));
+    }
+
+    Ok(build_gate(&required_contexts, &pr_view.status_check_rollup))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn entry(name: &str, status: Option<&str>, conclusion: Option<&str>) -> RollupEntry {
+        RollupEntry {
+            name: name.to_string(),
+            status: status.map(String::from),
+            conclusion: conclusion.map(String::from),
+        }
+    }
+
+    #[test]
+    fn passed_conclusion_maps_to_passed() {
+        assert_eq!(
+            parse_rollup(&entry("x", Some("COMPLETED"), Some("SUCCESS"))),
+            CheckRun::Passed
+        );
+    }
+
+    #[test]
+    fn failure_conclusion_maps_to_failed() {
+        assert_eq!(
+            parse_rollup(&entry("x", Some("COMPLETED"), Some("FAILURE"))),
+            CheckRun::Failed
+        );
+    }
+
+    #[test]
+    fn in_progress_maps_to_pending() {
+        assert_eq!(
+            parse_rollup(&entry("x", Some("IN_PROGRESS"), None)),
+            CheckRun::Pending
+        );
+    }
+
+    #[test]
+    fn required_context_absent_from_rollup_is_missing() {
+        let gate = build_gate(&["required / never-ran".to_string()], &[]);
+        assert_eq!(gate.checks[0].run, CheckRun::Missing);
+    }
+
+    #[test]
+    fn required_context_matched_to_realised_run_by_exact_name() {
+        let rollup = vec![entry(
+            "required / it-ran",
+            Some("COMPLETED"),
+            Some("SUCCESS"),
+        )];
+        let gate = build_gate(&["required / it-ran".to_string()], &rollup);
+        assert_eq!(gate.checks[0].run, CheckRun::Passed);
+    }
+
+    #[test]
+    fn build_gate_evaluates_green_when_all_required_passed() {
+        let rollup = vec![entry("a", Some("COMPLETED"), Some("SUCCESS"))];
+        let gate = build_gate(&["a".to_string()], &rollup);
+        assert_eq!(gate.evaluate(), squabble_core::gate::GateState::Green);
+    }
+}

crates/squabble-cli/src/fetch.rs

@@ -2,11 +2,14 @@
 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 //! `squabble` — the CLI front-end to `squabble-core`.
 //!
-//! v0.1 surface: `squabble diagnose <gate.json>` reads a gate description
-//! (the required contexts and their realised runs), runs the pure engine, and
-//! prints the state plus the legitimate moves it proposes. git/`gh` plumbing
-//! that *applies* moves is the next implementation step (see docs/CHARTER.adoc);
-//! this binary fails loudly rather than pretending to land anything.
+//! v0.1 surface: `squabble fetch <owner/repo> <pr>` turns a live PR into a
+//! gate (via `gh`); `squabble diagnose <gate.json>` reads a gate description
+//! (from `fetch`, or hand-written) and prints the state plus the legitimate
+//! moves the pure engine proposes. Applying a move is still the next
+//! implementation step (see docs/CHARTER.adoc) — this binary fails loudly
+//! rather than pretending to land anything.
+
+mod fetch;
 
 use squabble_core::{diagnose, gate::Gate};
 use std::process::ExitCode;
@@ -21,21 +24,47 @@ fn main() -> ExitCode {
                 ExitCode::from(2)
             }
         },
+        Some("fetch") => match (args.get(2), args.get(3)) {
+            (Some(slug), Some(pr)) => run_fetch(slug, pr),
+            _ => {
+                eprintln!("squabble fetch: usage: squabble fetch <owner>/<repo> <pr-number>");
+                ExitCode::from(2)
+            }
+        },
         Some("--version") | Some("-V") => {
             println!("squabble {}", env!("CARGO_PKG_VERSION"));
             ExitCode::SUCCESS
         }
         _ => {
             eprintln!(
                 "squabble {} — CI/CD fighter (squabble ≠ bypass)\n\n\
-                 USAGE:\n  squabble diagnose <gate.json>\n  squabble --version\n",
+                 USAGE:\n  squabble fetch <owner>/<repo> <pr-number>\n  squabble diagnose <gate.json>\n  squabble --version\n",
                 env!("CARGO_PKG_VERSION")
             );
             ExitCode::from(2)
         }
     }
 }
 
+fn run_fetch(slug: &str, pr: &str) -> ExitCode {
+    match fetch::run(slug, pr) {
+        Ok(gate) => match serde_json::to_string_pretty(&gate) {
+            Ok(json) => {
+                println!("{json}");
+                ExitCode::SUCCESS
+            }
+            Err(e) => {
+                eprintln!("squabble: could not serialise fetched gate: {e}");
+                ExitCode::from(2)
+            }
+        },
+        Err(e) => {
+            eprintln!("squabble fetch: {e}");
+            ExitCode::from(2)
+        }
+    }
+}
+
 fn run_diagnose(path: &str) -> ExitCode {
     let text = match std::fs::read_to_string(path) {
         Ok(t) => t,

crates/squabble-cli/src/main.rs

@@ -40,7 +40,10 @@ pub struct RequiredCheck {
 
 impl RequiredCheck {
     pub fn new(required_context: impl Into<String>, run: CheckRun) -> Self {
-        Self { required_context: required_context.into(), run }
+        Self {
+            required_context: required_context.into(),
+            run,
+        }
     }
 
     /// A requirement is satisfied only by a bound run that passed. This is the
@@ -93,7 +96,11 @@ impl Gate {
             }
             return GateState::Green;
         }
-        if self.checks.iter().any(|c| matches!(c.run, CheckRun::Failed)) {
+        if self
+            .checks
+            .iter()
+            .any(|c| matches!(c.run, CheckRun::Failed))
+        {
             return GateState::Red;
         }
         GateState::Blocked