Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions crates/squabble-core/data/first-line-rules.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -35,11 +35,11 @@ SQ-CANON-01 FIX an instance's canon-lockstep job is an old inline copy and goes
SQ-PERM-01 FIX Resource not accessible by integration at get-a-workflow-run in a job that uploads SARIF on a private repository Add actions: read to that job's permissions, with a comment that names the reason The upload step passes on a re-run The permission is already present, or the repository is public
SQ-RUN-01 ACT a setup or download step fails with API rate limit exceeded and the same workflow passes on an adjacent commit Re-run the failed jobs once after the rate-limit reset, only if that commit is still the head The re-run passes It fails twice on the same commit, the log has no rate-limit text, or the step is not a setup or download step
SQ-RUN-02 ACT a PR is blocked with required checks green under a strict ruleset and its base is behind the default branch Update the branch by merging the base; never rebase a branch the squabbler did not open The required checks pass on the new head Merge conflict, or still blocked on an up-to-date head
SQ-RUN-03 ACT a step fails on a transient host or API error: gh: HTTP 5xx, a git remote returning 5xx, Could not resolve host, or Failed to connect 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, or the status is 401 or 403 (a token problem: SQ-OWN-09, or a rate limit: SQ-RUN-01)
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, Could not resolve host, or Failed to connect 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, or the status is 401 or 403 (a token problem: SQ-OWN-09, or a rate limit: SQ-RUN-01)
SQ-RUN-04 ACT gitleaks fails with fatal: ambiguous argument <sha>^..<sha>: 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-CODE-01 FIX a Rust readiness or integration test cannot find its binary under target/debug/build Use PathBuf::from(env!("CARGO_BIN_EXE_<bin>")); 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 or S7679 in shell scripts Make the mechanical edit; decline S1192 in test files, where repetition is a convention bash -n, shellcheck and the repository's shell tests pass 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
SQ-REF-06 REFER the DEED job fails could not read Username for https://github.com on a private repository Root cause: OTP 28 (28.3 and 28.5.0.8) miscompiles Hypatia.Rules.PinSites.walk/4; the template #328 shape only shifts memory layout. The fix is hyperpolymath/hypatia#1062. Never change the workflow to hide it DEED syntax passes on a private PR Always, until hypatia#1062 lands
SQ-REF-08 REFER Repo self-tests fails in dismiss-code-scanning-alerts-test.sh with <file>:<line> is not a write permission after lines were added above a permissions: block that .github/code-scanning-dismissals.json keys by line number Suggest keeping the recorded line where it is: put new comments inline or below it; never re-key the dismissal (it must match the live Scorecard alert's start_line on main) The test reports 0 failed Always when the permission line itself must move or change (re-keying after Scorecard re-scans main is the owner's call)
SQ-CODE-04 FIX an adapter prints a valid findings array but exits other than 0 or 1 and is reported as ran Accept arrays only for exit 0 or 1 (fleet-report-back.sh translate_or_error) Tests for exits 2, 3, 9 and 137 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
Expand All @@ -58,6 +58,7 @@ SQ-OWN-12 OWNER the same scanner (panic-attack) is pinned at more than one commi
SQ-OWN-13 OWNER a workflow push is refused by a repository ruleset: gh: Repository rule violations found / Code coverage checks require a pull request. (HTTP 409) (Apodeixis.jl run 43257204071, Publish the lane badges, red on its base too) Report: a ruleset requires a pull request for that push, so the workflow cannot push to the protected branch. The owner changes the workflow to open a PR or adjusts the ruleset. The squabbler never changes a ruleset and never pushes around one (owner) (owner)
SQ-OWN-14 OWNER <file>: non-v8 UUID literal (<uuid>) / UUID check failed. Use ESTATE-UUID-V8 (ADR-008) (Apodeixis.jl run 43257204302, ./Project.toml) Report: an identifier needs the owner or the A7 identity process. The squabbler never mints, rewrites or retypes a UUID (owner) (owner)
SQ-OWN-15 OWNER SonarQube ERROR Fail to load the list of plugins installed on the server: Not authorized or organization not found, then sonar-scanner failed with exit code 3 (lithoglyph run 43152462261) Report: the Sonar token or organization is missing or wrong; the owner fixes the secret or the Sonar project. Never remove or skip the Sonar step (owner) (owner)
SQ-OWN-16 OWNER a workflow force- or mirror-pushes to a forge, gated on a *_MIRROR_ENABLED variable, with no check of the source repository visibility anywhere in the file (Hypatia WF030, found statically: standards mirror-reusable.yml gates the job at line 93 and runs git push --force gitlab main at line 144; github-backup-mirror-reusable.yml too) Report: the owner decides the guard (refuse, or skip loudly, when the source is private and the forge copy is not confirmed private; escalate when the forge visibility cannot be read). The squabbler never edits a mirror workflow, never pushes to a forge and never changes a visibility setting (owner) (owner)
SQ-NOI-01 NOISE Fork governance failed (deed=cancelled) on a head that a newer commit replaced Label superseded; read the newest head The newest head is not deed=cancelled deed=cancelled on the newest head
SQ-NOI-02 NOISE couldn't find remote ref refs/pull/<N>/merge and the PR closed before the job started None: do not re-run a closed PR The PR API shows the PR closed The PR is still open (conflict or deleted ref)
SQ-NOI-03 NOISE Inbox Steward ends startup_failure only on runs triggered by chatgpt-codex-connector[bot] None Count of startup failures by actor Inbox Steward becomes a required check
16 changes: 10 additions & 6 deletions crates/squabble-core/src/rules.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
//! rules have none and are left out of it: SQ-LOCK-03, SQ-PIN-01, SQ-PIN-04,
//! SQ-PIN-05, SQ-TOOL-01, SQ-CANON-01, SQ-RUN-02, SQ-CODE-02, SQ-CODE-03,
//! SQ-CODE-04, SQ-REF-08, SQ-OWN-03, SQ-OWN-05, SQ-OWN-06, SQ-OWN-07,
//! SQ-OWN-08, SQ-OWN-11, SQ-OWN-12 and SQ-NOI-03. Their evidence is the
//! SQ-OWN-08, SQ-OWN-11, SQ-OWN-12, SQ-OWN-16 and SQ-NOI-03. Their evidence is the
//! workflow source, run metadata or PR state, not a log line. SQ-LOCK-01,
//! SQ-PIN-03 and SQ-GEN-03 also have static detectors below.

Expand Down Expand Up @@ -51,7 +51,7 @@ use RuleClass::{Act, Fix, Noise, Owner, Refer};
/// here.
const CATALOGUE_TSV: &str = include_str!("../data/first-line-rules.tsv");

/// The 44 catalogue rows, in ADR 0004 order.
/// The 45 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:
Expand Down Expand Up @@ -188,6 +188,7 @@ static LOG_MATCHERS: &[LogMatcher] = &[
("SQ-RUN-01", |c| c.rate_limited()),
("SQ-RUN-03", |c| {
c.http_5xx_after("gh: HTTP ")
|| c.http_5xx_after("gh: Server Error (HTTP ")
|| c.http_5xx_after("returned error: ")
|| c.has("Could not resolve host")
|| c.has("Failed to connect to")
Expand Down Expand Up @@ -856,19 +857,19 @@ 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(), 44);
assert_eq!(parsed.len(), 45);
}

#[test]
fn catalogue_shape() {
assert_eq!(CATALOGUE.len(), 44);
assert_eq!(CATALOGUE.len(), 45);
let uniq: HashSet<_> = CATALOGUE.iter().map(|r| r.id).collect();
assert_eq!(uniq.len(), 44);
assert_eq!(uniq.len(), 45);
let n = |c| CATALOGUE.iter().filter(|r| r.class == c).count();
assert_eq!(n(Fix), 20);
assert_eq!(n(Act), 4);
assert_eq!(n(Refer), 2);
assert_eq!(n(Owner), 15);
assert_eq!(n(Owner), 16);
assert_eq!(n(Noise), 3);
assert!(rule("SQ-OWN-04").is_some());
for gone in [
Expand Down Expand Up @@ -918,6 +919,8 @@ mod tests {
"##[error]lockfile verification did not produce a result for this action. Unable to resolve action `dtolnay/rust-toolchain@v1`",
),
("SQ-RUN-03", "gh: HTTP 502 (https://api.github.com/graphql)"),
// standards run 43446385277, Rust coverage (playbook-to-recipe).
("SQ-RUN-03", "gh: Server Error (HTTP 502)"),
("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://x/': Could not resolve host: x"),
(
Expand Down Expand Up @@ -970,6 +973,7 @@ mod tests {
"gh: HTTP 404",
"gh: HTTP 5",
"gh: HTTP 5x2",
"gh: Server Error (HTTP 404)",
"returned error: 403",
] {
assert!(!ids(log, None).contains(&"SQ-RUN-03"), "{log}");
Expand Down
21 changes: 14 additions & 7 deletions docs/decisions/0004-first-line-rule-catalogue.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ evidence from one or more repositories, not yet a verified general rule. When
the implementation lands, its rule table in code is authoritative and this
record lists the decisions behind it.

Amended 2026-11-13 (increment 2): twelve rules and one widened rule were added
Amended 2026-11-13 (increment 2): thirteen rules and three widened rules (SQ-LOCK-02, SQ-RUN-03, SQ-CODE-03) were added
from the evidence that the rule reconciliation thread sent after #156 merged
(hypatia#1064). The rows quote that evidence; rows marked "reconstructed" have
no run URL yet.
Expand Down Expand Up @@ -173,7 +173,7 @@ holds, or when its check does not pass on the PR head.
| Merge conflict, or still blocked on an up-to-date head.

| SQ-RUN-03 | ACT
| A step fails on a transient host or API error: `gh: HTTP 5xx` (hypatia run 43358533401: `gh: HTTP 502` on an owner-wide GraphQL query), a git remote answering `returned error: 5xx`, `Could not resolve host`, or `Failed to connect to`.
| A step fails on a transient host or API error: `gh: HTTP 5xx` (hypatia run 43358533401: `gh: HTTP 502` on an owner-wide GraphQL query), `gh: Server Error (HTTP 5xx)` (standards run 43446385277: `gh: Server Error (HTTP 502)` while the coverage job read the workflow catalogue), a git remote answering `returned error: 5xx`, `Could not resolve host`, or `Failed to connect to`.
| 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, or the status is 401 or 403 (a token problem is SQ-OWN-09; a rate limit is SQ-RUN-01).
Expand All @@ -197,10 +197,10 @@ holds, or when its check does not pass on the PR head.
| The fix would hit the code-fix unsafe list (guard 6), the code is vendored or third-party, or the check does not pass on the PR head.

| SQ-CODE-03 | FIX
| Sonar S7688 or S7679 in shell scripts.
| Make the mechanical edit. Decline S1192 in test files, where repetition is a convention.
| Sonar S7688, S7679 or S131 in shell scripts.
| Make the mechanical edit. For S7688 rewrite `[ … ]` to `[[ … ]]` only in files with a bash shebang, never in `/bin/sh` or POSIX scripts. For S131 add a no-op default case `*) ;;`, which changes nothing in shell. Decline S1192 in test files, where repetition is a convention.
| `bash -n`, shellcheck and the repository's shell tests pass.
| The fix would hit the code-fix unsafe list (guard 6), the code is vendored or third-party, or the check does not pass on the PR head.
| An S7688 test uses `-a` or `-o` or relies on word splitting, the fix would hit the code-fix unsafe list (guard 6), the code is vendored or third-party, or the check does not pass on the PR head.

| SQ-REF-06 | REFER
| The DEED job fails `could not read Username for 'https://github.com'` on a private repository (checkout with `persist-credentials: false`, then an anonymous fetch).
Expand Down Expand Up @@ -310,6 +310,12 @@ holds, or when its check does not pass on the PR head.
| (owner)
| (owner)

| SQ-OWN-16 | OWNER
| A workflow force- or mirror-pushes to a forge, gated on a `*_MIRROR_ENABLED` variable, with no check of the source repository's visibility anywhere in the file (Hypatia WF030, found statically). Standards `mirror-reusable.yml` gates the job at line 93 and runs `git push --force gitlab main` at line 144, with the same shape per forge (bitbucket 196, codeberg 248); `github-backup-mirror-reusable.yml` too. It fires on nothing in hypatia, gitbot-fleet or this repository.
| Report: the owner decides the guard (refuse, or skip loudly, when the source is private and the forge copy is not confirmed private; escalate when the forge visibility cannot be read). The squabbler never edits a mirror workflow, never pushes to a forge and never changes a visibility setting. Hypatia detects and refers it; this row only reports.
| (owner)
| (owner)

| SQ-NOI-01 | NOISE
| `Fork governance failed (deed=cancelled)` on a head that a newer commit replaced.
| Label superseded; read the newest head.
Expand Down Expand Up @@ -365,6 +371,7 @@ and fix belongs to the squabbler.
| `ruleset_blocks_push` | SQ-OWN-13 | owner
| `uuid_conformance` | SQ-OWN-14 | owner
| `sonar_not_authorized` | SQ-OWN-15 | owner
| `mirror_without_visibility_guard` (WF030) | SQ-OWN-16 | owner, report only; static detection
| `generated_file_stale` | none | a referral: the squabbler never runs a command named in a log; each new generated file becomes its own row
| `bench_regression` | SQ-OWN-11 | owner
| `scanner_pin_drift` | SQ-OWN-12 | owner
Expand All @@ -379,8 +386,8 @@ base).

== Consequences

* 24 rules are first-line (20 `FIX`, 4 `ACT`), 2 are referrals, 15 are
owner-only and 3 are noise; 44 in all. Every rule names its check and its
* 24 rules are first-line (20 `FIX`, 4 `ACT`), 2 are referrals, 16 are
owner-only and 3 are noise; 45 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
Expand Down
Loading