feat(diagnosis): classify where a run stopped — preflight ≠ finding

.machine_readable/bot_directives/execution_taxonomy.a2ml

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# execution_taxonomy.a2ml — WHERE a run stopped, as step evidence.
+#
+# Read by `squabble phase` (via squabble-fight::execution) and classified by
+# squabble-core::execution. It answers one question the gate model cannot:
+# a red check says *that* a run failed; it never says whether the policy ran.
+#
+# The five outcomes an estate report must keep distinct:
+#   1. not started      — zero jobs: admission or source resolution refused it.
+#                         Attributed by `squabble zero-job` / `squabble chains`.
+#   2. preflight        — a job started and died in runner setup, provisioning or
+#                         lock resolution, BEFORE any policy step executed.
+#   3. prerequisite     — a declared tool/credential/configuration step failed, so
+#                         the policy step could not run.
+#   4. policy failed    — the policy was reached and its step concluded failure.
+#                         The FINDING is read from the policy's own report; this
+#                         classifier only says the policy was reached.
+#   5. verified         — a policy step ran and succeeded (still subject to the
+#                         green-polarity/vacuity check in squabble-core::polarity).
+#
+# WHY THIS FILE EXISTS AT ALL
+# `squabble-core` holds no step names by design: it must stay detachable, and a
+# compiled-in vocabulary would be a taxonomy rather than a classifier. The estate
+# measured that lesson once already — an abbreviated scanner step name in
+# gate_triage.a2ml matched no real job, so the vacuity classifier silently
+# degraded to "genuine" forever (see the note in that directive).
+#
+# MATCHING IS EXACT (after trimming). Do not abbreviate a step name here for
+# readability: an abbreviated name matches nothing and the step silently falls
+# back to "policy step". Copy the `- name:` string from the workflow verbatim.
+#
+# HOW TO EXTEND, HONESTLY
+# Add a step only when you have READ IT in a workflow this estate ships, and say
+# where. A step name guessed from a convention is worse than an empty list: the
+# empty list leaves the classification to the more conservative class.
+#
+# `Set up job` is GitHub's implicit first step in every job. It is compiled into
+# squabble-core (it is a GitHub primitive, not a repo declaration), so listing it
+# here is documentation, not policy.
+
+[metadata]
+version = "0.1.0"
+last-updated = "2026-10-31"
+spec = "https://github.com/hyperpolymath/cicd-squabbler/blob/main/docs/reports/estate-integration/2026-10-31-ci-diagnosis-coverage.adoc"
+status = "wired into `squabble phase`; NOT yet wired into `squabble fight` (see proposal P-2)"
+
+[execution-taxonomy]
+# Steps that run before the policy. A failure in one of these is PROVISIONING:
+# nothing has been said about the code, the policy, or the PR.
+#
+# Measured 2026-10-31 in metadatastician/standards .github/workflows/
+# rust-ci-reusable.yml (jobs `check` and `test`), which is the rust CI this
+# estate's consumers call:
+#     - name: Checkout repository
+#     - name: Install Rust toolchain
+#     - name: Install Zig for native build
+#     - name: Cache cargo registry and build
+# and in that repository's allowlist-preflight-reusable.yml:
+#     - name: Stage policy tools outside the scanned tree
+# `cargo check --locked` is deliberately NOT here: it is the policy step, and a
+# lock-resolution error inside it is indistinguishable from a genuine compile
+# failure at this evidence tier. Attribute that class from job ANNOTATIONS (the
+# estate's B-LOCKFILE detector), never from a step conclusion.
+setup-steps = [
+  "Checkout repository",
+  "Checkout caller repository",
+  "Checkout policy source",
+  "Install Rust toolchain",
+  "Install Zig for native build",
+  "Cache cargo registry and build",
+  "Stage policy tools outside the scanned tree",
+]
+
+# Steps that establish a DECLARED prerequisite — a tool, credential or piece of
+# configuration — whose failure means the policy step could not run.
+#
+# Measured 2026-10-31 in metadatastician/standards
+# .github/workflows/cicd-squabbler-reusable.yml (`fight-report` job): the probe
+# step decides whether the supplied credential can read the whole gate before
+# `squabble fight` is asked to classify anything.
+#
+# Kept deliberately short: an empty or thin list means class 3 is rarely
+# attributed, which is the honest state of the evidence. Adding a guess here
+# would turn "unknown" into "missing secret" — the exact overclaim this file's
+# sibling directive warns about.
+prerequisite-steps = [
+  "Probe whether fight can inspect the full gate",
+]
+
+[execution-taxonomy.notes]
+# What this taxonomy deliberately does NOT do.
+#
+# * Class 1 needs no entry: it is "no job exists", decided before any step.
+# * Billing refusal (`A-BILLING`) is a JOB ANNOTATION, not a step conclusion.
+#   With no step evidence the classifier reports `Unclassified (no step
+#   evidence)` — fail-closed — and hypatia's `scripts/ci-health/` owns that class.
+# * A tag/branch-pinned `uses:` under `sha_pinning_required` refuses at startup
+#   with zero jobs, so it is class 1, owned by squabble-core::startup and
+#   `squabble zero-job`, not by this file.
+# * Nothing here may be read as a verdict: no class in squabble-core::execution
+#   constructs a CheckRun, drops a required context, or reaches GateState::Green.

.machine_readable/descriptiles/STATE.a2ml

@@ -6,7 +6,7 @@
 [metadata]
 project = "cicd-squabbler"
 version = "0.1.0"
-last-updated = "2026-10-28"
+last-updated = "2026-10-31"
 status = "active"  # active | paused | archived
 
 [project-context]
@@ -36,6 +36,7 @@ milestones = [
   { name = "`squabble chains` (Phase A, read-only) — pure cross-repo chain analysis in squabble-core::chains (cycles + dead upstreams blocking; diamonds, pin skew, tag/branch pins warnings; landing order; max-plus longest chain), local + GitHub GraphQL sources (new squabble-forge crate, queries validated against a committed schema snapshot), `--follow N` upstream probing, exit 4 on blocking. Dogfooded offline on cicd-squabbler, standards, typed-wasm, rsr-template-repo; live GraphQL run pending a gh-authenticated host.", completion = 90 },
   { name = "Zero-job `startup_failure` attribution — a run that dies before any job exists creates no check run, so nothing shows on the PR. Two first-class classes with DISTINCT moves: moved coordinate (reusable owner renamed/transferred → `RepointToCanonical`, same pin) and allow-list admission required (canonical coordinate refused by the caller's `selected` allow-list → `AllowListAdmissionRequired`, exact `owner/repo@*`). `squabble zero-job <path>` reports per-run attribution (repo, workflow, coordinate as written, canonical target, required pattern) and exits 4 on any observed run; `squabble chains` resolves every upstream's canonical `full_name` through REST (names compared, never pins) to flag moved upstreams and canonical-grouped pin skew before a run proves it. Diagnosis only — no CheckRun is constructed, no postures edited, no green declared. Code complete; build/tests and a live `gh`-authenticated run pending a Rust toolchain (none installable in the authoring environment).", completion = 70 },
   { name = "Creusot complement for Rust (the twin of spark/): verification/squabble-creusot states the engine's load-bearing invariants as Creusot contracts with a stable-Rust mirror that tests the model against the real squabble-core; own workspace + rust-toolchain pin (nightly-2026-08-03 for Creusot v0.14.0) so the nightly-only LGPL proof library never enters the stable --locked build; estate gate wired via hyperpolymath/cicd-suite's creusot-gate.yml (enforce_hollow), plus scripts/install-toolchain.sh and just verify-{status,install,mirror,creusot,gate}. STATED, NOT PROVED: no obligation has been discharged; detect/theatre phases run clean on this tree, prove phase fails closed. Dev container now installs the Rust toolchains it was missing.", completion = 35 },
+  { name = "Execution-phase classification (estate CI diagnosis coverage) — squabble-core::execution distinguishes the five outcomes a report must not collapse: not started (deferred to startup/zero-job), preflight (runner setup/provisioning/lock, BEFORE any policy step), prerequisite missing (declared tool/credential/config), policy step failed (the policy was reached — the finding is read from its own report, never inferred), verified (job passed AND a policy step recorded success). Host-supplied step signatures in .machine_readable/bot_directives/execution_taxonomy.a2ml (no step name compiled in; exact match); fail-closed Unclassified with five reasons; Handoff names the decision owner. No CheckRun constructed, no Move proposed, no gate state reachable. Offline entry point `squabble phase <job.json>`. WIRED OFFLINE ONLY: `fight` does not yet fetch step evidence for red checks, so a preflight failure is still attributed by workflow shape in the planner — that is proposal P-1/P-2 in docs/reports/estate-integration/2026-10-31-ci-diagnosis-coverage.adoc. Tests written, NOT compiled or executed (no Rust toolchain in the authoring environment).", completion = 60 },
   { name = "RSR scaffolding customisation (identity, root-allow, A2ML manifests)", completion = 80 },
 ]
 
@@ -45,6 +46,7 @@ milestones = [
 
 [critical-next-actions]
 actions = [
+  "Compile and run the execution-phase suite on a host with a Rust toolchain (`just test`), then wire it into `fight` (proposals P-1/P-2 in docs/reports/estate-integration/2026-10-31-ci-diagnosis-coverage.adoc): fetch job step evidence for FAILED checks (fetch.rs already parses job ids out of check details_url but keeps greens only) and route a preflight/prerequisite failure to the provisioning owner instead of EscalateToExpert{DispatchFix}. Until then a setup failure is still attributed by workflow shape in the planner.",
   "Owner: decide the REUSE/dep5 declaration for crates/squabble-forge/graphql/github-schema.graphql (third-party GitHub schema; the Files: * default would mis-declare it MPL-2.0) — or drop the snapshot and fetch it in CI.",
   "Live-fire `squabble chains gh:… --follow 1` on a gh-authenticated host; then fetch reusable upstreams at their PINNED SHA (GraphQL object(expression:\"<sha>:.github/workflows\")) so diamonds carry basis=pinned-revision instead of scanned-revision.",
   "Enact the remaining self-wins under --apply: required-context reconcile and reusable-workflow re-pin both need the GitHub ruleset API / a target SHA (network), so they stay propose-only until that host capability exists. (`--apply` already enacts the path-filter strip, which is a pure local file edit.)",

CHANGELOG.adoc

@@ -10,6 +10,66 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning].
 
 ==== Added
 
+* `scripts/local-verify.sh` (and `just local-verify`) — runs every gate CI runs,
+  locally, and leaves one bundle (`SUMMARY.txt` inside a timestamped `$TMPDIR`
+  directory) carrying per-step status, the errors extracted from each log, the
+  toolchain identity and the before/after worktree state. It writes nothing into
+  the repository, and it delegates installation to `scripts/install-toolchain.sh`
+  so nothing it installs is unverified. Status vocabulary is the estate's:
+  `PASS`/`FAIL`/`VOID`/`SKIP`/`KNOWN`, where `VOID` ("no check was performed")
+  and `SKIP` are never passes, and a `KNOWN` pre-existing failure must be the
+  single failure in the run to be recognised at all. `--only <ids>` runs a subset
+  (deselected steps are recorded `SKIP`, never `PASS`) and `--check` reports the
+  toolchain and the plan without running a step or writing a ledger. Written
+  because the new modules below were authored without a reachable Rust toolchain.
+  They type-check on CI but have not been executed: `Cargo fmt` fails first, and
+  the `Cargo test` job does not start. That failure is **inherited**: `main` is
+  not fmt-clean, and the 7 unformatted workspace files it carries are repaired by
+  #144 (and identically by #143). None of the files this change adds or modifies
+  is unformatted. Merge one of those two first, rebase, and `fmt` passes on its
+  own — only then do `clippy` and the tests execute.
+* `tests/local_verify_test.sh` — 31 planted controls for the harness above: no
+  toolchain (`VOID`, exit 2), all-green (exit 0), a planted compile error (its
+  diagnostic and `file:line` extracted), a fmt diff, a failing assertion (both
+  sides extracted), `--only`, `--check`, a missing `jq` (`VOID`, never `PASS`), an
+  unchanged worktree, and exactly one documented status per ledger row. No Rust,
+  no network, no token: `bash tests/local_verify_test.sh`.
+  Two of its own first-draft cases were **wrong and were fixed, not worked
+  around**: the bare `PATH` fixture omitted `dirname`, so the script under test
+  resolved its repository root to `/` and two `VOID` cases passed for the wrong
+  reason; and one case piped the script into `grep -q`, which exits at the first
+  match and killed the writer with `SIGPIPE`, which `pipefail` then reported as
+  the plan being missing.
+* `squabble_core::execution` — the execution-phase classifier. `fight` knew only
+  *that* a check was red, so a job that died in runner setup or lock resolution
+  was attributed by the workflow's *shape* (a code fixer, a security scan, an
+  upstream owner) rather than as provisioning. The module classifies step
+  evidence into the five outcomes an estate report must keep distinct — not
+  started, preflight, prerequisite missing, policy step failed, verified — with
+  a fail-closed `Unclassified` carrying one of five reasons, and a `Handoff`
+  naming who must act. Signatures are **host-supplied** (no step name is
+  compiled in, preserving the standalone rule) and matched **exactly**, the
+  lesson `gate_triage.a2ml` 0.2.0 already paid for. It constructs no `CheckRun`,
+  proposes no `Move`, drops no required context and reaches no gate state, so
+  `squabble ≠ bypass` is untouched; `Verified` hands off to `NoClaim` and must
+  still be read with `polarity`.
+* `squabble phase <job.json> [--repo <path>] [--json]` — the offline entry point
+  for that classifier, over a jobs-API payload. Prints class, step, handoff
+  label, owner phrase and explanation, plus a permanent "NOT a gate verdict"
+  line. Exit `0` (a classification was produced) or `2` (tool failure): there is
+  deliberately no exit code that means green. Outside `squabble-contract/1.0.0`,
+  like `zero-job` and `chains`.
+* `.machine_readable/bot_directives/execution_taxonomy.a2ml` — the step-name
+  signatures, each with the workflow it was read from (2026-10-31), and an
+  explicit note that `cargo check --locked` is *not* a setup step: a
+  dependency-resolution error inside it is indistinguishable from a compile
+  failure at the step-conclusion evidence tier.
+* `docs/reports/estate-integration/2026-10-31-ci-diagnosis-coverage.adoc` — the
+  role/ownership map behind the above: the five outcomes, who diagnoses and who
+  remediates each (hypatia `ci-health`, standards' reusables, cicd-suite,
+  reposystem, proven-tests-and-benches, gitbot-fleet), eight concrete gaps, the
+  owner-handoff table for inaccessible settings, and six proposals kept separate
+  from what is implemented.
 * `.github/actions/squabble` — a composite action that installs the
   squabble v0.1.0 release binary for other workflows and, optionally, runs
   it. It refuses any download whose sha256 is not the pinned digest, or whose
@@ -98,9 +158,11 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning].
   verify-{status,install,mirror,creusot,gate}` install and run the toolchain,
   Creusot included via upstream's `./INSTALL` (not `cargo install`).
   **Stated, not proved**: no obligation has been discharged — the authoring
-  environment has no Rust toolchain at all, and this repository's `Rust CI`
-  currently ends as a zero-job `startup_failure`, so CI has not compiled the
-  workspace either. The estate gate's detect/theatre phases were run against
+  environment has no Rust toolchain at all, and this repository's `Rust CI` on
+  `main` has been ending as a zero-job `startup_failure` (four consecutive runs),
+  so pushes to `main` have not compiled the workspace. Pull requests *do* run it:
+  on PR #145 `Cargo check` passes and `Cargo fmt` fails, so the workspace is
+  type-checked but the Creusot prove job still has no green precedent. The estate gate's detect/theatre phases were run against
   this tree (obligations=true, claims=false, 10 contract attributes, T1/T2/T3
   clean) and its prove phase correctly reported "NO PROOF WAS PERFORMED".
 * The dev container now installs the Rust toolchains it was missing (stable for

Justfile

@@ -360,6 +360,15 @@ validate-coapt:
 # ═══════════════════════════════════════════════════════════════════════════════
 
 # Report which toolchains and provers are present (installs nothing)
+# Run every CI gate locally and leave one evidence bundle to hand back.
+# Writes nothing into the repository (default bundle: $TMPDIR/squabble-verify-*).
+local-verify *args:
+    @bash scripts/local-verify.sh {{args}}
+
+# Planted controls for the harness above (no Rust, no network, no token)
+local-verify-test:
+    @bash tests/local_verify_test.sh
+
 verify-status:
     @bash scripts/install-toolchain.sh --check
 

README.adoc

@@ -120,6 +120,32 @@ Both moves only let a check *start*. Neither drops a required context, weakens a
 check, nor edits settings: `squabble ≠ bypass` holds, and nothing here is a
 green. A missing or skipped check cannot be made green by a diagnosis.
 
+== Where a run stopped: preflight is not a finding
+
+A red check says *that* a run failed; it never says whether the policy ran. A job
+that dies in runner setup, provisioning or lock resolution is not a verdict on
+the code, and attributing it by the workflow's shape dispatches work nobody can
+do.
+
+[source,sh]
+----
+gh api repos/o/r/actions/jobs/12345 > job.json
+squabble phase job.json --repo .      # class · step · handoff · owner
+----
+
+`squabble phase` classifies step evidence into the outcomes an estate report must
+keep distinct — *not started* (zero jobs: attributed by `zero-job`/`chains`),
+*preflight*, *prerequisite missing*, *policy step failed* (where, never why: read
+the policy's own report), and *verified* (still subject to `polarity`'s vacuity
+check) — or refuses with a reason (`Unclassified`). Step names live in
+`.machine_readable/bot_directives/execution_taxonomy.a2ml`, never in the engine.
+No class constructs a check, drops a context or reaches green: `squabble ≠
+bypass` holds, and `phase` has no exit code that means green.
+
+The role, ownership map, gaps and handoffs across `cicd-suite`, `standards`,
+`reposystem`, `proven-tests-and-benches`, Hypatia and `gitbot-fleet`:
+`docs/reports/estate-integration/2026-10-31-ci-diagnosis-coverage.adoc`.
+
 == Rust deductive verification (Creusot)
 
 The estate requires its Rust to carry verification obligations, the twin of the