From 60b72ed74776f6b55f8e8fd48674367e8b6c863c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 19:32:14 +0000 Subject: [PATCH 1/2] Add SQ-RUN-06: re-run once when a gate could not read GitHub state Evidence, read from the job logs: standards runs 43458638630 (could not read branch rulesets), 43458639621 (could not read the workflow catalogue) and 43459052870 (called workflow could not be read at a SHA), all while the Actions token budget was spent. The gate failed closed, as it should. The rule re-runs once after the budget resets and never edits the gate. DROPPED CLOSURE lines after an unread callee are a consequence; a DROPPED CLOSURE with nothing unread is a real drop and does not match. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zmiut2nCcbtEx25HAU --- .../squabble-core/data/first-line-rules.tsv | 1 + crates/squabble-core/src/rules.rs | 48 +++++++++++++++++-- .../0004-first-line-rule-catalogue.adoc | 10 +++- 3 files changed, 52 insertions(+), 7 deletions(-) diff --git a/crates/squabble-core/data/first-line-rules.tsv b/crates/squabble-core/data/first-line-rules.tsv index 1507778..d7876c2 100644 --- a/crates/squabble-core/data/first-line-rules.tsv +++ b/crates/squabble-core/data/first-line-rules.tsv @@ -38,6 +38,7 @@ SQ-RUN-02 ACT a PR is blocked with required checks green under a strict ruleset SQ-RUN-03 ACT a step fails on a transient host or API error: gh: HTTP 5xx, gh: Server Error (HTTP 5xx), a git remote returning 5xx, or Could not resolve host or Failed to connect to a host name that contains a dot Re-run the failed job once, only if that commit is still the head The re-run passes It fails twice on the same commit, the status is 401 or 403 (a token problem: SQ-OWN-09, or a rate limit: SQ-RUN-01), or the host name has no dot (a service container or localhost is a configuration error a re-run cannot fix) SQ-RUN-04 ACT gitleaks fails with fatal: ambiguous argument ^..: unknown revision or path not in the working tree, because a shallow checkout lacks the range base commit; trufflehog reports commits: 0 for the same range Re-run the failed job once, only if that commit is still the head The re-run passes and the scan covers more than 0 commits It fails twice on the same commit: refer with the suggestion fetch-depth: 0 on the scan checkout SQ-RUN-05 REFER a step fails with Could not resolve host or Failed to connect to a host name that has no dot (a service container, localhost) or no name at all Refer to Hypatia with the log line and the step: this is a configuration error (the service is not running or is named wrongly), so a re-run cannot fix it (owner) Always a referral: the name that does resolve in the workflow is Hypatia's to confirm +SQ-RUN-06 ACT a gate fails closed because it could not read GitHub state: could not read branch rulesets (nothing inspected), could not read the workflow catalogue (enablement is UNKNOWN, not off), or the called workflow could not be read at a SHA (offline with no cache entry, or the API refused) Re-run the failed job once after the Actions token budget resets, only if that commit is still the head; never edit the gate, its baseline or its allowlist to pass The re-run reads the state and the gate passes or fails on its real findings It fails twice on the same commit with the same unread state (a missing permission, not a budget: owner), or the log has a DROPPED CLOSURE line with no could-not-be-read line (a real drop) SQ-CODE-01 FIX a Rust readiness or integration test cannot find its binary under target/debug/build Use PathBuf::from(env!("CARGO_BIN_EXE_")); a code fix, first-line only when the code-fix guard passes cargo test --test readiness passes The fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head SQ-CODE-02 FIX Validate Hypatia Baseline fails on new code_safety findings Fix the code behind the finding; never touch .hypatia-baseline.json The baseline job passes with the baseline file unchanged The fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head SQ-CODE-03 FIX Sonar S7688, S7679 or S131 in shell scripts Make the mechanical edit: for S7688 rewrite [ ] to [[ ]] only in files with a bash shebang (never /bin/sh or POSIX scripts); for S131 add a no-op default case *) ;;; decline S1192 in test files, where repetition is a convention bash -n, shellcheck and the repository's shell tests pass An S7688 test uses -a or -o or relies on word splitting, the fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head diff --git a/crates/squabble-core/src/rules.rs b/crates/squabble-core/src/rules.rs index bd52e81..18d89de 100644 --- a/crates/squabble-core/src/rules.rs +++ b/crates/squabble-core/src/rules.rs @@ -51,7 +51,7 @@ use RuleClass::{Act, Fix, Noise, Owner, Refer}; /// here. const CATALOGUE_TSV: &str = include_str!("../data/first-line-rules.tsv"); -/// The 46 catalogue rows, in ADR 0004 order. +/// The 47 catalogue rows, in ADR 0004 order. /// /// The data file ships inside the crate, so a malformed row is a defect in /// this crate that a caller cannot repair. The catalogue never loads short: @@ -224,6 +224,14 @@ static LOG_MATCHERS: &[LogMatcher] = &[ c.undotted_name_after("Could not resolve host: ") || c.undotted_name_after("Failed to connect to ") }), + // The gate failed closed because it could not read GitHub state. Only the + // unread lines match: a DROPPED CLOSURE line alone is a real drop, and + // the ones that follow an unread callee are a consequence of it. + ("SQ-RUN-06", |c| { + c.has("could not read branch rulesets") + || c.has("could not read the workflow catalogue") + || c.has("(offline with no cache entry, or the API refused)") + }), ("SQ-RUN-04", |c| { c.has("ambiguous argument") && c.has("unknown revision or path not in the working tree") }), @@ -938,17 +946,17 @@ mod tests { #[test] fn shipped_catalogue_file_parses() { let parsed = parse_catalogue(CATALOGUE_TSV).expect("the shipped data file is well formed"); - assert_eq!(parsed.len(), 46); + assert_eq!(parsed.len(), 47); } #[test] fn catalogue_shape() { - assert_eq!(CATALOGUE.len(), 46); + assert_eq!(CATALOGUE.len(), 47); let uniq: HashSet<_> = CATALOGUE.iter().map(|r| r.id).collect(); - assert_eq!(uniq.len(), 46); + assert_eq!(uniq.len(), 47); let n = |c| CATALOGUE.iter().filter(|r| r.class == c).count(); assert_eq!(n(Fix), 20); - assert_eq!(n(Act), 4); + assert_eq!(n(Act), 5); assert_eq!(n(Refer), 3); assert_eq!(n(Owner), 16); assert_eq!(n(Noise), 3); @@ -1005,6 +1013,20 @@ mod tests { ("SQ-RUN-03", "fatal: unable to access 'https://git.sr.ht/x': The requested URL returned error: 503"), ("SQ-RUN-03", "fatal: unable to access 'https://git.sr.ht/x': Could not resolve host: git.sr.ht"), ("SQ-RUN-03", "curl: (7) Failed to connect to github.com port 443 after 21 ms"), + // standards runs 43458638630, 43458639621 and 43459052870 (the + // Actions token budget was spent), read from the job logs. + ( + "SQ-RUN-06", + "##[notice]could not read branch rulesets for metadatastician/standards (API error, rate limit, or missing permission) \u{2014} nothing inspected", + ), + ( + "SQ-RUN-06", + "##[error]could not read the workflow catalogue \u{2014} enablement is UNKNOWN, not off", + ), + ( + "SQ-RUN-06", + "##[error]metadatastician/standards@d55304a01b5260b0511aae0d14ed8b8770b00293: the called workflow .github/workflows/rust-ci-reusable.yml could not be read at d55304a01b5260b0511aae0d14ed8b8770b00293 (offline with no cache entry, or the API refused). An unread callee is NOT a closed closure", + ), ( "SQ-RUN-04", "ERR [git] fatal: ambiguous argument '4190136^..bf33aeb': unknown revision or path not in the working tree.", @@ -1098,6 +1120,22 @@ mod tests { assert_eq!(rule("SQ-RUN-05").unwrap().class, Refer); } + #[test] + fn unreadable_github_state_is_a_rerun_but_a_real_drop_is_not() { + let consequence = "DROPPED CLOSURE \u{2014} the reviewed baseline has a -> b, and this source no longer reaches it."; + // A real drop, with nothing unread, is the gate's own finding. + assert!(ids(consequence, None).is_empty()); + // Unread callee plus the drops that follow it: one re-run, then the owner. + let both = format!( + "the called workflow x.yml could not be read at abc (offline with no cache entry, or the API refused).\n{consequence}" + ); + assert_eq!(ids(&both, None), vec!["SQ-RUN-06"]); + // A git credential prompt is not an unread gate (SQ-REF-06). + let git = "fatal: could not read Username for 'https://github.com'"; + assert!(!ids(git, None).contains(&"SQ-RUN-06")); + assert_eq!(rule("SQ-RUN-06").unwrap().class, Act); + } + #[test] fn push_refusals_are_told_apart() { // The git form is SQ-OWN-04, the gh API form is SQ-OWN-13; neither claims the other. diff --git a/docs/decisions/0004-first-line-rule-catalogue.adoc b/docs/decisions/0004-first-line-rule-catalogue.adoc index c674477..7554cd3 100644 --- a/docs/decisions/0004-first-line-rule-catalogue.adoc +++ b/docs/decisions/0004-first-line-rule-catalogue.adoc @@ -190,6 +190,12 @@ holds, or when its check does not pass on the PR head. | (owner) | Always a referral: the name that does resolve in the workflow is Hypatia's to confirm. +| SQ-RUN-06 | ACT +| A gate fails closed because it could not read GitHub state: `could not read branch rulesets for (API error, rate limit, or missing permission) - nothing inspected` (standards run 43458638630), `could not read the workflow catalogue - enablement is UNKNOWN, not off` (standards run 43458639621), or `the called workflow could not be read at (offline with no cache entry, or the API refused)` (standards run 43459052870). All three ran while the Actions token budget was spent. +| Re-run the failed job once after the Actions token budget resets, only if that commit is still the head. Never edit the gate, its baseline or its allowlist to make it pass. +| The re-run reads the state, and the gate then passes or fails on its real findings. +| It fails twice on the same commit with the same unread state (a missing permission, not a budget: report to the owner), or the log has a `DROPPED CLOSURE` line with no could-not-be-read line (a real drop). `DROPPED CLOSURE` lines that follow an unread callee are a consequence of it, not findings. + | SQ-CODE-01 | FIX | A Rust readiness or integration test cannot find its binary (`failed to run …/target/debug/build/…: No such file`). | Use `PathBuf::from(env!("CARGO_BIN_EXE_"))`. @@ -392,8 +398,8 @@ base). == Consequences -* 24 rules are first-line (20 `FIX`, 4 `ACT`), 3 are referrals, 16 are - owner-only and 3 are noise; 46 in all. Every rule names its check and its +* 25 rules are first-line (20 `FIX`, 5 `ACT`), 3 are referrals, 16 are + owner-only and 3 are noise; 47 in all. Every rule names its check and its referral condition. * A fix that changes code (`SQ-CODE-nn`) is first-line only when the code-fix guard passes on its diff, so a fix that could weaken a check never runs at From 15b42268eef805d3c088e7517f64cea6e2afc89c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 19:39:05 +0000 Subject: [PATCH 2/2] SQ-RUN-06: owner conditions outrank the re-run; a second failure goes to the owner CodeRabbit on #162, both verified against the code. The matcher sat before SQ-OWN-09, so a bad token that also left the gate unable to read picked a re-run, which SQ-OWN-09 forbids; it is now after every owner matcher. And decide() sent a second SQ-RUN-06 failure to Hypatia, where the catalogue row says owner; OWNER_AFTER_RERUN now routes it to the owner report and leaves every other Act rule on the referral path. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zmiut2nCcbtEx25HAU --- crates/squabble-core/src/rules.rs | 64 ++++++++++++++++--- .../0004-first-line-rule-catalogue.adoc | 7 ++ 2 files changed, 63 insertions(+), 8 deletions(-) diff --git a/crates/squabble-core/src/rules.rs b/crates/squabble-core/src/rules.rs index 18d89de..5b809fa 100644 --- a/crates/squabble-core/src/rules.rs +++ b/crates/squabble-core/src/rules.rs @@ -224,14 +224,6 @@ static LOG_MATCHERS: &[LogMatcher] = &[ c.undotted_name_after("Could not resolve host: ") || c.undotted_name_after("Failed to connect to ") }), - // The gate failed closed because it could not read GitHub state. Only the - // unread lines match: a DROPPED CLOSURE line alone is a real drop, and - // the ones that follow an unread callee are a consequence of it. - ("SQ-RUN-06", |c| { - c.has("could not read branch rulesets") - || c.has("could not read the workflow catalogue") - || c.has("(offline with no cache entry, or the API refused)") - }), ("SQ-RUN-04", |c| { c.has("ambiguous argument") && c.has("unknown revision or path not in the working tree") }), @@ -275,6 +267,17 @@ static LOG_MATCHERS: &[LogMatcher] = &[ ("SQ-OWN-15", |c| { c.has("Not authorized or organization not found") }), + // Last of the actionable rules, after every owner-only one: a re-run never + // outranks an owner condition in the same log (a bad token, SQ-OWN-09, + // that also leaves the gate unable to read). The gate failed closed because + // it could not read GitHub state. Only the unread lines match: a DROPPED + // CLOSURE line alone is a real drop, and the ones that follow an unread + // callee are a consequence of it. + ("SQ-RUN-06", |c| { + c.has("could not read branch rulesets") + || c.has("could not read the workflow catalogue") + || c.has("(offline with no cache entry, or the API refused)") + }), ("SQ-NOI-01", |c| c.has("deed=cancelled")), ("SQ-NOI-02", |c| { c.has("couldn't find remote ref refs/pull/") @@ -574,6 +577,11 @@ pub fn is_code_fix(rule: &Rule) -> bool { rule.class == RuleClass::Fix && rule.id.starts_with("SQ-CODE-") } +/// Act rules whose catalogue row sends a second failure to the owner, not to +/// Hypatia: the same unread state twice is a missing permission, which only the +/// owner can grant (SQ-RUN-06). +const OWNER_AFTER_RERUN: &[&str] = &["SQ-RUN-06"]; + /// Apply the ADR 0004 guards to a rule. pub fn decide(rule: &Rule, g: &GuardInput) -> Decision { match rule.class { @@ -596,6 +604,9 @@ pub fn decide(rule: &Rule, g: &GuardInput) -> Decision { reason: "attempt limit reached: 2 fix attempts on this head".to_string(), }; } + if OWNER_AFTER_RERUN.contains(&rule.id) && g.reruns_of_job >= 1 { + return Decision::OwnerReport; + } if rule.class == RuleClass::Act && g.reruns_of_job >= 1 { return Decision::Refer { reason: "re-run limit reached: the job was already re-run once".to_string(), @@ -1136,6 +1147,14 @@ mod tests { assert_eq!(rule("SQ-RUN-06").unwrap().class, Act); } + #[test] + fn an_owner_condition_outranks_a_rerun_in_the_same_log() { + let log = "gh: Bad credentials (HTTP 401)\n##[error]could not read the workflow catalogue \u{2014} enablement is UNKNOWN, not off"; + assert_eq!(ids(log, None), vec!["SQ-OWN-09", "SQ-RUN-06"]); + // The caller acts on the first: the owner report, never a re-run. + assert_eq!(rule(ids(log, None)[0]).unwrap().class, Owner); + } + #[test] fn push_refusals_are_told_apart() { // The git form is SQ-OWN-04, the gh API form is SQ-OWN-13; neither claims the other. @@ -1245,6 +1264,35 @@ mod tests { } } + #[test] + fn a_second_unread_state_failure_goes_to_the_owner_not_hypatia() { + let first = GuardInput { + reruns_of_job: 0, + ..on() + }; + let second = GuardInput { + reruns_of_job: 1, + ..on() + }; + let unread = rule("SQ-RUN-06").unwrap(); + assert_eq!(decide(unread, &first), Decision::Apply); + assert_eq!(decide(unread, &second), Decision::OwnerReport); + // Every other Act rule still refers after its one re-run. + let other = rule("SQ-RUN-01").unwrap(); + assert!(matches!(decide(other, &second), Decision::Refer { .. })); + // The kill switch still comes first. + assert!(matches!( + decide( + unread, + &GuardInput { + reruns_of_job: 1, + ..GuardInput::default() + } + ), + Decision::ReportOnly { .. } + )); + } + #[test] fn every_decision_branch() { let g = |a, rr, pr, c| GuardInput { diff --git a/docs/decisions/0004-first-line-rule-catalogue.adoc b/docs/decisions/0004-first-line-rule-catalogue.adoc index 7554cd3..a28853e 100644 --- a/docs/decisions/0004-first-line-rule-catalogue.adoc +++ b/docs/decisions/0004-first-line-rule-catalogue.adoc @@ -357,6 +357,13 @@ is not `setup-bun`, only SQ-RUN-01 matches. Agreed with the rule reconciliation thread; Hypatia's `api_rate_limit` is advice that defers to SQ-PIN-03, then SQ-RUN-01. +SQ-RUN-06 is last in the table, after every owner-only rule: a re-run never +outranks an owner condition in the same log. A bad token (SQ-OWN-09) that +leaves the gate unable to read gives `SQ-OWN-09, SQ-RUN-06`, and the caller +reports to the owner. A second failure of SQ-RUN-06 on the same commit is an +owner report as well, not a Hypatia referral (`OWNER_AFTER_RERUN` in +`rules.rs`); every other `ACT` rule refers to Hypatia after its one re-run. + === Mapping to Hypatia's `ci_failure_triage` ids (hypatia#1064) Under ADR 0003 Hypatia's triage names the cause and the route; every re-run