Dev Qualification Patrol

status: preview period: ongoing theme: dev-qualification-patrol doc_type: architecture-and-usage source_level: local-files confidence: high sensitivity: public evidence_grade: A review_state: self-reviewed last_reviewed: 2026-08-03 ai_provenance: model_family: GPT-5 product: Codex generated_at: 2026-08-03 visible_context: Existing Buildchain Shifu Gate receipts, Kungfu Dev Patrol, Alpha preflight, candidate patrol, and GitHub failed-job rerun semantics. invisible_context_boundary: No credentials, private logs, or private configuration were used.

Buildchain provides a reusable controller for repositories whose development branch advances faster than a heavy cross-platform qualification workflow can settle. The controller keeps no external queue. On every wakeup it derives the only pending item from the current source-branch head and maintains these states:

qualified: the current source SHA already has a successful Dev run;
running: one Dev run is active, with a different current SHA retained as the implicit latest pending item;
waiting-preflight: the current SHA has not passed its lightweight exact-SHA preflight;
waiting-priority: a declared Alpha or release workflow is queued or active;
dispatch-ready: the latest SHA is preflight-qualified and no Dev or priority run is active;
retry-ready: the latest exact-SHA Dev run failed only at a classified external boundary and remains inside the attempt limit; or
blocked: the failure was deterministic, unknown, or exhausted its bounded retry policy.

This is an event-driven, coalescing controller rather than a FIFO build queue. If ten commits arrive during one slow Dev run, the next reconciliation observes only the newest branch head. Intermediate unqualified SHAs are superseded without consuming the shared native runners.

Exact-source and priority contract

Call .github/workflows/dev-qualification-patrol.yml from a thin consumer workflow after the lightweight preflight, Dev Patrol, and declared priority workflows complete. Add an offset schedule as recovery for delayed or missed GitHub events. Repeated wakeups are idempotent.

The controller requires a successful preflight whose head_sha equals the current source head. It dispatches the heavy workflow on the source branch and adds a controller-owned source-sha input. The consumer must reject the run before qualification if that input differs from the workflow event SHA. This closes the race where the branch advances between observation and workflow startup. The heavy reusable Gate workflow then receives the exact SHA as its source-ref, so every platform receipt remains source-bound.

priority-workflows-json is a JSON array of workflow paths. Any queued, waiting, pending, requested, or in-progress run in those workflows prevents a new Dev dispatch or automatic retry. This lets Alpha and release work keep priority on shared self-hosted runners. A successful current Dev result remains qualified even when priority work is active; priority only governs new heavy work.

Bounded local retry

The controller uses GitHub’s failed-jobs rerun endpoint, not a fresh workflow dispatch, for classified transient failures. Successful matrix jobs and their exact-source receipts remain in the same workflow-run transaction. Failed jobs and dependent aggregation run again. The Shifu Gate profile uploads platform, diagnostic, aggregate, and controller artifacts with overwrite enabled so a later attempt can replace only the same-run artifact names.

Automatic retry is deliberately narrow:

whole-run cancelled, timed_out, or startup_failure conclusions qualify;
checkout, setup, toolchain, download, upload, environment exposure, and runner-workspace reset steps qualify;
Gate execution, Gate enforcement, aggregation, and controller-receipt failures never qualify; and
an unknown failing step fails closed.

max-attempts counts the original attempt. The default 2 therefore permits at most one automatic failed-jobs rerun. This policy reduces retry friction for network, runner, and provider failures without laundering a product or Gate failure into an infrastructure retry.

Permission and mutation boundary

The reusable workflow always performs observe with Actions and contents read permissions. The separate mutate job runs only when the observation proposes dispatch or rerun-failed-jobs, mutation-authorized is true, and dry-run is false. Before writing, it re-resolves the branch and all workflow state and requires the action and source SHA to match the read-only observation. A race fails closed and the next event recomputes from current truth.

Start a consumer in dry-run mode. Its observation and mutation decisions are retained as exact-source artifacts with a canonical decision root. Enabling mutation requires a repository token that can write Actions; no contents, pull-request, tag, release, package, or publication permission is used.

The controller does not merge a PR, publish an Alpha, create a tag, create a release, or settle a Release Passport. Once Dev and Alpha preflight evidence both succeed for one SHA, the separate Dev to Alpha Candidate Patrol may select it.

Dev Qualification Patrol