aos-workflow-gate

Evidence-based workflow gate for CI, PR, scanner, and AI-agent signals.

This repository is the workflow layer around aos-kernel. Its job is to make a pull request or release gate explainable and replayable: collect workflow signals, apply an explicit policy, and produce a PASS, WARN, or BLOCK decision with evidence.

Start here (two minutes, zero config)

Self-Test Mode (zero-config) — an advisory self-test of your pipeline, without writing any bundle or policy. The action collects the completed check runs of the current commit, generates an explicit advisory policy over them, and writes a replayable decision record plus a Markdown summary to the job page. This is a complete workflow file — copy it as .github/workflows/aos-self-test.yml. No checkout is needed: Self-Test Mode reads check runs through the API and installs from the action itself:

name: AOS Self-Test

on:
  pull_request:

permissions:
  contents: read
  checks: read
  actions: read
  pull-requests: read
  statuses: read

jobs:
  self-test:
    runs-on: ubuntu-latest
    steps:
      # Pinned from actions/setup-python@v6 on 2026-07-03.
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
        with:
          python-version: "3.11"
      - name: AOS self-test (advisory)
        uses: RafineriaAI/aos-workflow-gate@v0.35.0

A permissions: block sets every unlisted scope to none. Zero-config uses checks: read for check runs, actions: read for workflow runs, pull-requests: read for the SHA-bound changed-file set, and statuses: read for legacy commit statuses. Public repositories may allow unauthenticated reads; declare every scope so the same workflow works on private repositories.

No required-checks input is needed: zero-config mode discovers the required status checks from your branch rules (classic branch protection included when the token can read it; an unreadable classic surface is recorded as unverifiable, never interpreted as zero requirements), enforces their app-bound identity, and waits briefly for them to stabilize. Name required-checks only to override the discovery; named checks become required (missing or failed means BLOCK), every other collected check is advisory. Set wait-for-checks: "120" to poll until the required checks complete (only required checks are waited for; a wait that ends incomplete fails closed and is recorded in the bundle's collection status). The generated bundle and policy are written to .aos-gate/ so the decision stays replayable. Workflows that never started are visible too: the gate reads the commit's check suites and workflow runs, and anything still queued or awaiting approval is recorded in the bundle instead of silently not existing.

What the job page answers, in under thirty seconds: the verdict (PASS, WARN, or BLOCK), the scope it covers (and expressly does not), the freshness of the observation, the effect (advisory or enforcing), the signal counts, at most three top gaps with one dominant problem, and exactly one Next step. An enforceably clean PASS is quiet — one screen, no tables. The step exposes outputs for downstream jobs: verdict, diagnosis, next-action, can-block, record, record-digest, and the state counters (required-total, required-successful, required-missing, required-pending, required-unverifiable, required-failed, advisory-warnings).

First diagnosis. Before the first gate run, probe what your token, environment, and target actually allow — read-only, with stable diagnostic codes and remediation, and no verdict (see docs/PREFLIGHT.md):

aos-workflow-gate preflight --pr https://github.com/OWNER/REPO/pull/N

Your evidence. The decision record, the collected bundle, the generated policy, and a static evidence.html view land in .aos-gate/ and are uploaded as the aos-gate-evidence artifact by default. GitHub artifacts expire per repository settings — attach the files to a release for permanence (this repository gates and attaches its own release evidence that way).

Replay it. Anyone holding the artifact can reproduce the decision offline:

pip install "git+https://github.com/RafineriaAI/aos-workflow-gate@v0.35.0"
aos-workflow-gate verify --input gate-decision.json --bundle bundle.json
aos-workflow-gate summarize --input gate-decision.json --html --out evidence.html

Enforce when ready. Advisory mode never fails the job. When the record shows the gate you want, set mode: "enforce" — a BLOCK verdict then fails the step, on your terms.

Public proof

Every verdict the gate can produce is committed to this repository as real, replayable evidence — PASS (examples/pr-evidence-record.json), WARN (examples/zero-required-record.json — the main aha case: GitHub's required status checks permitted the merge while zero checks were required at the gate), and BLOCK (the v0.11.0 incident counterfactual). Each triple replays offline with verify and is re-replayed by the test suite on every CI run.

Current status

Phase 2: the local evaluate CLI and the advisory GitHub Action are implemented. Phase 3 has started: the zero-config GitHub check-runs collector is implemented, so the action can gate a pull request without any hand-written input. The gate turns collected signals plus an explicit policy into a deterministic PASS, WARN, or BLOCK decision record that is replayable and tamper-evident. SARIF and Scorecard file adapters and starter policy packs are implemented; the GitLab collector is planned next.

Decision records carry UNSIGNED_NOT_OFFICIAL verification status: they are structure- and replay-checkable, not an official signed verdict.

No production, compliance, signing, SLSA, or security-audit claim is made by this repository at this stage.

Core idea

A normal CI dashboard tells you which checks passed. aos-workflow-gate is intended to answer a stricter question:

Given this exact PR, policy, commit, and set of workflow signals, why did the release gate decide PASS, WARN, or BLOCK?

That turns gate behavior from a scattered set of green and red checks into a replayable decision record.

Practical use case

A maintainer wants a release candidate to be blocked when required checks are missing, warned when non-blocking scanners report known risks, and passed only when required evidence is present.

Run the gate locally:

python -m pip install -e .
aos-workflow-gate evaluate \
  --input examples/github-pr-signal-bundle.json \
  --policy policies/default.yml \
  --out examples/gate-decision.json

This prints the verdict and writes a full decision record. For the committed example the verdict is WARN: the required check passed and one advisory scanner warning remains. The record preserves subject identity, policy identity and digest, input identities and digests, the explained reasons, and a self-digest for tamper detection. A committed copy is checked in at examples/gate-decision.json.

Verify a decision record has not been altered:

aos-workflow-gate verify \
  --input examples/gate-decision.json \
  --bundle examples/github-pr-signal-bundle.json

Instant merge-protection check for any pull request URL — a read-only observer that fetches the head SHA, the base branch's active rules, and the head's check runs, then evaluates a policy generated from the rules' required status checks (missing required checks fail closed to BLOCK; failing non-required checks are listed as counterfactual blockers; the bundle's rules_digest makes protection drift between two records detectable):

aos-workflow-gate check-pr https://github.com/OWNER/REPO/pull/N

Render a record as Markdown (the same summary the GitHub Action posts):

aos-workflow-gate summarize --input examples/gate-decision.json

Export a verified record as an unsigned in-toto Statement and sign it with your own keys (see docs/DECISION_PREDICATE.md):

aos-workflow-gate export \
  --input examples/aos-kernel-gate-decision.json \
  --out gate-statement.json
cosign sign-blob --yes gate-statement.json \
  --output-signature gate-statement.sig

The draft input and policy files are examples/github-pr-signal-bundle.json and policies/default.yml.

GitHub Action: full control

Further inputs: mode: "enforce" makes a BLOCK verdict fail the step (default advisory never fails the job); policy-pack: minimal-pr-gate selects a bundled starter policy (see docs/POLICY_PACKS.md); upload-artifact is "true" by default and uploads the record, the .aos-gate/ evidence, and evidence.html as the aos-gate-evidence artifact, even when an enforced BLOCK fails the evaluate step (set "false" to skip).

For full control, provide an explicit bundle and policy. The action is read-only, needs no repository secrets, writes a Markdown summary to the job page, and exposes the decision record for artifact upload:

permissions:
  contents: read

steps:
  # Pinned from actions/checkout@v5 on 2026-07-03.
  - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
    with:
      persist-credentials: false
  # Pinned from actions/setup-python@v6 on 2026-07-03.
  - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
    with:
      python-version: "3.11"
  - name: Run gate (advisory)
    id: gate
    uses: RafineriaAI/aos-workflow-gate@v0.35.0
    with:
      input: examples/github-pr-signal-bundle.json
  # Pinned from actions/upload-artifact@v7.0.1 on 2026-07-04.
  - name: Upload decision record
    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
    with:
      name: gate-decision
      path: gate-decision.json

Advisory mode never fails the job; the verdict is reported in the step summary and in the verdict output. Set enforce: "true" to make a BLOCK verdict fail the step. This repository runs the action on itself in .github/workflows/aos-workflow-gate-self.yml.

Pilots and design partners

Self-serve use is free (Apache-2.0, no feature gates). Evaluating a real release gate for your workflows? A guided pilot designs the policy for one real workflow and hands over measured, replayable results — the policy stays yours. A limited design-partner variant trades structured feedback for reduced scope fee. Not sure where you stand? The pilot readiness wizard runs entirely in your browser and drafts a Decision-Gap Report that prefills the scoping form. Request scoping → (commits neither side). Tried the gate? Two minutes of feedback shapes the roadmap.

Platform neutrality

The gate core is platform-neutral: plain Python, zero runtime dependencies, JSON in and out. GitHub Enterprise Server works out of the box, and GitLab CI or Jenkins can run the same evaluation on an explicitly provided bundle — see docs/CI_INTEGRATIONS.md. Only the check-runs collector and the Action are GitHub-specific by design.

What this is

• A deterministic gate over workflow evidence.
• A policy and evidence layer for CI, PR, scanner, and AI-agent signals.
• A practical bridge between aos-kernel verdict semantics and real repository workflows.
• A GitHub Action and local CLI that run in advisory mode before they block anything.

What this is not

• Not a claim that a repository is secure.
• Not a compliance certification system.
• Not a replacement for code review, testing, threat modeling, or release engineering.
• Not a runtime proof that workflow systems are correct.
• Not a signing or provenance authority.

Documentation map

• Scope defines claim boundaries and non-goals.
• Architecture defines the layers and what each phase implements.
• Use cases gives the first practical workflow scenarios.
• Adoption guide removes terminology and integration barriers.
• Standards compatibility maps planned integrations to SLSA, SPDX, CycloneDX, SARIF, in-toto, and OpenSSF Scorecard without claiming compliance.
• Decision record predicate defines the in-toto Statement export and operator-key signing recipe.
• CI integrations covers GitHub Enterprise Server, GitLab CI, and generic shell usage.
• Adapters defines the mechanical SARIF and Scorecard mapping contracts.
• Source contract defines the versioned source-v0 contract for external adapters: identity-completeness invariant, policy-owned classification, import via file or stdin, no plugin runtime.
• Agent action adapter defines the agent-action-v0 contract binding an agent's intent, action, parameters, and base state into validated evidence — states, not approvals.
• Benchmark harness defines the benchmark-case-v0 recorded-case format and bench-verify: digest bindings, chronology, offline replay, and an explicit verified-vs-unverifiable boundary — the harness runs nothing.
• Real-agent governance benchmark records real agent changes from this repository's own history — a real PASS, a real green-but-incomplete WARN, and the v0.11.0 incident as a BLOCK counterfactual on real signals — each replayable offline, with the dogfooding boundary stated first.
• Policy packs documents the starter policies under policies/packs/.
• Trust shows how to verify every claim yourself: read-only permissions, no telemetry, zero dependencies, tamper evidence, offline replay.
• Buyer FAQ answers security reviewers: data flows, permissions, free vs paid, vendor risk, platform coverage.
• Security readiness documents the private-repo data model and implemented input hardening, each with a negative test.
• User FAQ answers first-run questions and maps every failure symptom to its meaning and fix.
• Preflight diagnostics documents the read-only capability probes, the stable diagnostic code registry, and preflight's exit semantics.
• Value states what the gate is worth, only as far as the evidence reaches.
• Value metrics counts operational friction from the committed case studies — no ROI arithmetic, by design.
• Comparison maps what branch protection, OPA/conftest, in-toto attestations, and the gate each answer — a capability matrix, not a ranking.
• One-pager is the sendable summary: problem, product, proof, engagement paths.
• Guided pilot defines the paid assisted path and the design-partner variant.
• Funnel maps the no-contact path from discovery to scoping — a human enters exactly once, and only on request.
• Pilot package lists the evidence-led pilot deliverables file by file, with the handover checklist and report template.
• Marketplace listing holds the paste-ready listing copy and status.
• Real-repository replay case study runs the gate on real workflow signals at a pinned commit and replays the committed decision offline.
• Green, but incomplete shows a fully green dashboard hiding a control that never ran — and the gate recording it as a named, replayable WARN.
• Merge-ready with zero enforced evidence is the main aha case: GitHub permits the merge while zero checks are required at the gate, and the default first run answers WARN with the decision gap and both real failures named — replayable from committed files.
• Roadmap defines the phased plan.
• Release governance defines branch, ruleset, tag, and release policy.
• Draft signal bundle and draft policy make the first use case concrete.
• Security policy defines responsible reporting boundaries.
• Contributing defines contribution expectations.

Local check

Run the local hygiene checks with:

python -m ruff check .
python -m mypy
python -m pytest
python tools/check_public_surface.py

Or run only the public surface check with:

python tools/check_public_surface.py

This check validates the documentation index, bootstrap claim boundary, and draft example files. It is not a product audit.

Relationship to aos-kernel

aos-kernel remains the minimal public kernel and formal surface. aos-workflow-gate is the operational layer that will adapt real workflow signals into a gate decision record. Kernel correctness claims do not automatically extend to this repository.

License

Apache-2.0. See LICENSE.

The license covers this repository's source code only. It grants no rights to the "AOS", "AOS Kernel", or "RafineriaAI" names and marks, and no rights to the separate proprietary AOS Core technology. See NOTICE.