Cold-reviewer Path

If you want to see CORE govern code in CI without installing anything locally, the shortest path is to add CORE as a GitHub Action and open a pull request.

One honest prerequisite, stated up front: the Action audits your repo against the .intent/ constitution in that repo (see below). If your repo doesn't have one yet, scaffold it first — then come back here.

Govern your own repo (BYOR — Bring Your Own Repository). Two commands bootstrap a fitted constitution into your repo. Both are core-cli commands (pip install core-cli) that talk to a running CORE API — the API needs Postgres + Qdrant behind it (ADR-146). There is no offline onboard today; the BYOR quickstart covers standing the API up.

Step 1 — Deliver the machinery floor (schemas, taxonomies, enforcement config):

core project onboard <path-to-your-repo> --write

Step 2 — Induce and ratify rules (LLM reads your source, proposes candidates, you confirm each):

core project scout <path-to-your-repo> --write

project scout requires an LLM resource. Without one it presents a curated menu of four universal rules for you to accept, reject, or adjust — ratification is always required. Dry-run (no --write) previews what would be written in either command. Once both steps are done, add the workflow below and open a pull request.

Already have a .intent/? A ready-made rule pack needs no API: pip install core-runtime, then core-admin project adopt-pack core/starter-python --write inside the repo.

To run the full loop locally on CORE itself in one command, see Getting Started (./install-core.sh).

For verifying CORE's claims about itself (single gateway, no bypass, no untracked mutation), see the Proof Index instead — that page assumes a running CORE.

What you'll see

CORE reads the .intent/ directory in your repo, runs the constitutional rules declared there against your src/ (or whichever paths your rules scope), and posts findings inline on the pull request as GitHub annotations. A failing severity threshold blocks the check; merge protection is yours to configure.

No daemon runs. No database is provisioned. The action is the stateless audit path — Audit tier per ADR-086 D1.

Minimum setup

Your repository needs a .intent/ directory at the root. If you don't have one, scaffold it with core project onboard (see above) before adding the workflow.

Add this workflow at .github/workflows/core-audit.yml:

name: CORE constitutional audit

on:
  pull_request:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DariuszNewecki/CORE@main
        with:
          severity: block

Open a pull request that touches a file your rules scope. The check runs, annotates findings on the diff if any exist, and exits with verdict=PASS or verdict=FAIL.

Inputs

Input	Default	Notes
`intent-path`	`.intent/`	MVP supports the default only. Custom paths exit with a clear error.
`severity`	`block`	One of `block`, `high`, `medium`, `low`, `info`. Findings below this threshold are suppressed.
`format`	`github-annotations`	One of `github-annotations`, `json`, `text`. Other formats are useful when piping the action's logs.

The action emits one output:

verdict — PASS (no findings at severity, every blocking rule evaluated), DEGRADED (no findings, but one or more blocking rules could not be evaluated offline — compliance for those is unknown, not passed; exit 1), FAIL (findings present), or ERROR (internal failure, or the audit produced no recognisable verdict). The verdict is derived from the audit's JSON result, never from the exit code alone.

Ref stability

The example above pins to @main because the audit-engine version bundled in tagged releases lags the latest published core-runtime on PyPI; @main tracks the most recent pin. Once a release tag lands carrying the current pin, prefer pinning to that tag (e.g. @v2.7.0) instead of @main for reproducible CI.

Plain `docker run` (no CI required)

If you'd rather observe the audit in your local terminal without setting up a GitHub workflow, pull the published image and mount your repository at /workspace:

docker run --rm \
  -v "$PWD:/workspace" \
  ghcr.io/dariusznewecki/core-audit-gate:latest

Output defaults to plain text. Override CORE_SEVERITY or CORE_FORMAT as env vars:

docker run --rm \
  -e CORE_SEVERITY=high \
  -e CORE_FORMAT=json \
  -v "$PWD:/workspace" \
  ghcr.io/dariusznewecki/core-audit-gate:latest

The image is the same binary as the GitHub Action; the only difference is the output format default (text vs github-annotations) and the workspace mount point (/workspace vs /github/workspace). Exit codes are identical.

Known limits

intent-path other than .intent/ is rejected; file an issue if you need a non-default path.
github-annotations output renders cleanly only inside GitHub's UI. If you run the action's logic outside CI, override format to text or json.

What this proves

A successful CORE audit on your repo demonstrates three structural claims simultaneously:

The rules declared in your .intent/ were loaded, parsed, and evaluated by named engines (ast_gate, glob_gate, etc.).
Findings, if any, name the rule that produced them — not a generic linter category.
The exit code is deterministic from the result: severity threshold met → fail; a blocking rule not evaluated → degraded (never reported as pass); no findings and full blocking coverage → pass; internal failure → error. No silent passes.

This is the same evaluation path the Proof Index claims hold for; this page just lets you observe it without standing up the full runtime.