{"id":51140674,"url":"https://github.com/corvidlabs/augur","last_synced_at":"2026-07-07T22:00:29.463Z","repository":{"id":363697104,"uuid":"1264141040","full_name":"CorvidLabs/augur","owner":"CorvidLabs","description":"🔮 Graded trust for code changes. Deterministic risk scoring (proceed, review, block) for humans and agents. No API key, no LLM.","archived":false,"fork":false,"pushed_at":"2026-07-07T17:34:10.000Z","size":753,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T19:12:53.024Z","etag":null,"topics":["ai-agents","ci","cli","code-review","developer-tools","fledge","git","risk-scoring","sarif","swift"],"latest_commit_sha":null,"homepage":"https://corvidlabs.xyz/augur","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CorvidLabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-09T15:44:41.000Z","updated_at":"2026-07-07T17:34:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CorvidLabs/augur","commit_stats":null,"previous_names":["corvidlabs/augur"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/CorvidLabs/augur","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorvidLabs%2Faugur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorvidLabs%2Faugur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorvidLabs%2Faugur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorvidLabs%2Faugur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CorvidLabs","download_url":"https://codeload.github.com/CorvidLabs/augur/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorvidLabs%2Faugur/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ci","cli","code-review","developer-tools","fledge","git","risk-scoring","sarif","swift"],"created_at":"2026-06-25T22:30:28.860Z","updated_at":"2026-07-07T22:00:29.359Z","avatar_url":"https://github.com/CorvidLabs.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# augur\n\n**Graded trust for changes.** A deterministic change-risk verdict for every diff: `proceed`,\n`review`, or `block`. No API key, no LLM.\n\n[![augur](https://img.shields.io/endpoint?url=https://corvidlabs.github.io/augur/badge.json)](https://corvidlabs.github.io/augur/)\n[![CI](https://github.com/CorvidLabs/augur/actions/workflows/ci.yml/badge.svg)](https://github.com/CorvidLabs/augur/actions/workflows/ci.yml)\n[![spec coverage](https://img.shields.io/endpoint?url=https://corvidlabs.github.io/augur/badges/coverage.json)](https://corvidlabs.github.io/augur/)\n[![Docs](https://img.shields.io/badge/docs-corvidlabs.github.io%2Faugur-blue)](https://corvidlabs.github.io/augur/)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"site/public/demo.gif\" alt=\"augur check assesses a working-tree change and returns a REVIEW verdict\" width=\"760\"\u003e\n\u003c/p\u003e\n\n`augur` reads a diff and tells you how risky it is, and whether a human should look, as a\ndeterministic, scriptable verdict: `proceed`, `review`, or `block`. macOS and Linux.\n\n## Quickstart\n\n### Install\n\nThe fastest way is Homebrew (macOS); on Linux, build from source (below):\n\n```sh\nbrew install corvidlabs/tap/augur\n```\n\nPrefer to build from source? Drop the release binary on your `PATH` (needs Swift 6 and `git`):\n\n```sh\nswift build -c release\ninstall -m 0755 .build/release/augur /usr/local/bin/augur\n# or, with fledge:\nfledge run install\n```\n\nOther options:\n\n```sh\nmint install CorvidLabs/augur\n# or\nswift package experimental-install\n```\n\n### Try it instantly (no setup)\n\nEvery script in [`examples/`](examples/README.md) builds the binary and runs against a\nthrowaway `/tmp` repo, so you get a real verdict in seconds:\n\n```sh\nbash examples/01-check.sh\n```\n\nSee [`examples/README.md`](examples/README.md) for the full catalog (gate exit codes,\ncoverage, SARIF, the `augur → attest` trust loop, and more).\n\n### The core commands\n\n`augur check` reports a verdict over a range (it always exits `0`):\n\n```\n$ augur check --range main..HEAD\n\naugur · main..HEAD\n\n  verdict     [!] REVIEW\n  risk        [#######             ]  37/100\n  confidence  63/100\n  calibration prior-only (0 incidents / 7 commits)\n\n  files (2), riskiest first:\n    !    36  src/auth/token.swift\n          · sensitivity: matches sensitive category 'auth'\n    !    35  db/migrations/001_add_secrets.sql\n          · sensitivity: matches sensitive category 'secrets'\n\n  → an agent should request human review before merging\n```\n\n`augur gate` exits **non-zero** when the verdict meets or exceeds a threshold, so a CI step\nor agent escalates instead of merging blind:\n\n```\n$ augur gate --range main..HEAD --threshold review\naugur gate · review (risk 37)\n$ echo $?\n1\n```\n\n`augur check --json` is the agent-friendly path (sorted-key JSON):\n\n```\n$ augur check --range main..HEAD --json | jq .verdict\n\"review\"\n```\n\nIn human reports, `confidence` is a display inverse of risk (`100 - riskScore`).\nThe engine's primary output is still `riskScore` plus the derived verdict; the\nseparate `calibration.confidence` field only says how much history backs the\nincident signal.\n\n### Where next\n\n- [Docs site](https://corvidlabs.github.io/augur/): the rendered guides.\n- [`docs/cli.md`](docs/cli.md): every command, flag, exit code, and the JSON shape.\n- [`docs/configuration.md`](docs/configuration.md): the full `.augur.toml` reference.\n- [`examples/README.md`](examples/README.md): every runnable example, simplest first.\n\n## Why it exists\n\nIt's built for the world where agents write most of the code: humans can't hand-review the\nvolume, and agents have no native sense of \"I'm out of my depth here, escalate.\" `augur` is\nthat missing primitive. It's language-agnostic, CI-agnostic, and **requires no API key and no\nLLM**. AI is optional and additive.\n\nAgents made code cheap to produce. The scarce resource is now *trust*. `augur` turns the\nsenior-engineer instinct (\"this part is fine, that part needs a careful look\") into a\ndeterministic artifact that both humans and agents can act on.\n\n- **Humans** use it to triage: spend review attention on the risky 10% of a 40-file PR.\n- **Agents** use it to gate: `augur gate` exits non-zero so an agent escalates instead of\n  merging blind.\n\n## How it scores\n\nEvery signal is derived from `git` history and the filesystem. No model, no network:\n\n| Signal | What it catches |\n|--------|-----------------|\n| **sensitivity** | Touches secrets, auth, crypto, payments, migrations, infra, CI, or dependency manifests. |\n| **test-gap** | Code changed with no test in the changeset, *or*, with a coverage report, the fraction of changed lines left uncovered. Never fires on documentation/prose files. |\n| **churn** | Hot files that change constantly are fragile. |\n| **coupling** | A file's usual co-change partner is *absent* from the change. |\n| **diff-shape** | Large single-file edits are harder to review. |\n| **ownership** | Bus-factor (single author) or diffuse ownership (many authors). |\n| **incident** | The file's own history of reverts / hotfixes. |\n| **codeowners** | A changed file with no declared owner in the repo's `CODEOWNERS` (neutral when there is no `CODEOWNERS` file). |\n\nScoring has two layers:\n\n1. A **transparent heuristic prior** with documented weights. It always applies, even on a\n   brand-new repo.\n2. A **history calibration** that scales the incident signal by how much the repository's\n   own revert/hotfix record backs it. Every assessment reports `calibration`\n   (`prior-only` → `weak` → `history-backed`) so you know whether a score is guessing or\n   grounded. The longer `augur` watches a repo, the sharper it gets.\n\nThe primary score is `riskScore` (`0...100`), and verdict thresholds are applied to that\nrisk. Human and markdown reports also show `confidence`, but it is just the inverse\n(`100 - riskScore`) for readability. Do not confuse that with `calibration.confidence`,\nwhich is the separate `0...1` measure of how much repository history backs the incident\nsignal.\n\n## Usage\n\n```sh\naugur check                         # assess working-tree changes\naugur check --range main..HEAD      # assess a range (range-first)\naugur check --staged                # assess staged changes (pre-commit)\naugur check --json                  # machine-readable, sorted-key JSON\naugur check --markdown              # GitHub-flavored markdown (PR comments / job summaries)\naugur check --sarif                 # SARIF 2.1.0 for GitHub code scanning\naugur check --sarif-out augur.sarif # write SARIF to a file (implies --sarif)\naugur check -v                      # show every contributing signal\n\naugur gate --threshold review       # exit 1 if verdict \u003e= review (CI / agent loops)\naugur explain                       # optional AI explanation via fledge\n\naugur calibrate                     # cache the history model to .augur/cache.json\naugur check --cached                # reuse the cache instead of re-walking git log\n\naugur check --config ./my.toml      # use an explicit .augur.toml\naugur check --no-config             # ignore any .augur.toml; use built-in defaults\n\naugur check --coverage lcov.info    # sharpen test-gap with a coverage report (LCOV/Cobertura/JaCoCo/Go)\naugur check --no-coverage           # disable coverage auto-detection\n\naugur check --exclude 'vendor/**'   # drop vendored/generated paths from the assessment (repeatable)\naugur check --no-exclude            # ignore [exclude] paths from .augur.toml\n\naugur check --no-codeowners         # disable CODEOWNERS-aware ownership scoring\n\naugur check --color auto            # color when stdout is a TTY (default)\naugur check --color always          # force color (e.g. for screenshots / pagers)\naugur check --color never           # plain output\n```\n\n### Output \u0026 color (`--color`, `NO_COLOR`)\n\nThe human-readable `check` report is colorized **only when it's safe**: by default\n(`--color auto`) color is emitted only when stdout is an interactive terminal *and* the\n[`NO_COLOR`](https://no-color.org) environment variable is unset. Piped, redirected,\n`--json`, and `--sarif` output is always plain, so scripts and CI capture clean text.\nUse `--color always` to force it (handy for screenshots) or `--color never` to disable it.\n\nThe color scheme is semantic and intentionally restrained:\n\n- **Verdict:** `proceed` green, `review` amber/yellow, `block` bold red.\n- **Risk meter:** a `█`/`░` gradient bar tinted by level (green → amber → red).\n- **Headers / labels:** bold; secondary and signal detail are dim/gray.\n- **File paths:** cyan; each per-file row is tinted by that file's own verdict.\n- **Confidence \u0026 calibration:** cyan.\n\n### Coverage-aware test-gap (`--coverage`)\n\nBy default the **test-gap** signal is a coarse heuristic: did the changeset touch any\ntest file? Supply a line-coverage report and it becomes precise. It scores the fraction\nof the change's *added* lines that are actually covered:\n\n```sh\naugur check --coverage lcov.info      # LCOV\naugur check --coverage coverage.xml   # Cobertura XML\naugur check --coverage jacoco.xml     # JaCoCo XML (Kotlin/Java)\naugur check --coverage cover.out      # Go coverprofile (go test -coverprofile)\n```\n\nFour formats are supported, all parsed in `AugurKit` with Foundation only (no third-party\ndependency):\n\n| Format | Typical name | How a line is instrumented / covered |\n|--------|--------------|--------------------------------------|\n| **LCOV** | `lcov.info` | `DA:\u003cline\u003e,\u003chits\u003e`. Covered when `hits \u003e 0`. |\n| **Cobertura** | `coverage.xml` | `\u003cline number hits\u003e`. Covered when `hits \u003e 0`. |\n| **JaCoCo** | `jacoco.xml` | `\u003cline nr mi ci\u003e` under `\u003cpackage\u003e\u003csourcefile\u003e`. Covered when `ci` (covered instructions) `\u003e 0`; path is `package@name`/`sourcefile@name`. |\n| **Go coverprofile** | `cover.out` | `path:start.col,end.col stmts count` blocks; every line in `start…end`. Covered when *any* covering block has `count \u003e 0`. |\n\naugur also **auto-detects** a report at the repo root when `--coverage` is absent, trying these\nnames in order and using the **first** that exists (logged to stderr): `lcov.info`,\n`coverage.xml`, `jacoco.xml`, `cover.out`, `coverage.out`. Pass `--no-coverage` to disable\nthat, or `--coverage \u003cpath\u003e` to point elsewhere. The format is detected by extension (`.info`\n→ LCOV, `.out` → Go, `.xml` → Cobertura/JaCoCo) then by content (JaCoCo is distinguished from\nCobertura by its `\u003creport\u003e`/`\u003csourcefile\u003e` markers; a Go profile by its leading `mode:` line).\n\nPrecise behavior, per non-test, non-binary code file:\n\n- **Has instrumented changed lines** → `risk = 1 − (covered ÷ instrumented)`, with a detail\n  like `2/3 changed lines covered (67%)`.\n- **Entirely absent from the report** → high risk (`0.7`, \"not in coverage report\").\n- **No changed line was instrumented** (e.g. only comments/blank lines changed), or no\n  per-line data is available → falls back to the heuristic.\n- **No coverage supplied at all** → the original heuristic test-gap behavior, unchanged.\n\nAdded line ranges come from `git diff --unified=0`; only the file's *added* lines are scored\n(not context or deletions).\n\n**Path-matching limitation.** Diff paths and coverage paths often disagree on a leading\nprefix (`Sources/App/Service.swift` vs `/build/checkout/Sources/App/Service.swift`), so\naugur matches by **normalized longest common suffix** at path-component boundaries. This\ntolerates prefix differences, but if two distinct files share an identical trailing suffix\n(`a/util.swift` and `b/util.swift` against a bare `util.swift`) the match is ambiguous and\nresolved deterministically (shorter then lexicographically-smaller path), so it may not be the\nfile you intended. Prefer emitting coverage with repo-relative paths.\n\n### SARIF for GitHub code scanning (`--sarif`)\n\n`augur check --sarif` emits a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)\nlog so augur's risk findings can be uploaded to GitHub code scanning and annotate a pull\nrequest **inline**: each changed file gets an annotation at its first added line.\n\n```sh\naugur check --range main..HEAD --sarif                  # SARIF to stdout\naugur check --range main..HEAD --sarif-out augur.sarif  # SARIF to a file\n```\n\n`--sarif` and `--json` are mutually exclusive; `--sarif-out \u003cpath\u003e` implies `--sarif`. The\noutput is generated entirely in `AugurKit` with Foundation `Codable` (no third-party SARIF\ndependency) and is deterministic (sorted keys).\n\naugur emits a **single** rule, `augur/change-risk`, and **one result per assessed file**.\nEach result's severity `level` is mapped from the file's verdict:\n\n| Verdict | SARIF level |\n|---------|-------------|\n| `block` | `error` |\n| `review` | `warning` |\n| `proceed` | `note` |\n\nThe `message.text` summarizes the verdict, risk score, and top contributing signals; the\nlocation points at the file with a `region.startLine` of its first added line (when added\nlines are known); and `riskScore` / derived `confidence` (`100 - riskScore`) / `verdict`\nare carried in `result.properties`.\n\nA runnable end-to-end demo is in [`examples/07-sarif.sh`](examples/07-sarif.sh), and a\ncopy-paste CI workflow that uploads the SARIF is in\n[`examples/workflows/sarif.yml`](examples/workflows/sarif.yml):\n\n```yaml\n- run: augur check --range \"origin/${{ github.base_ref }}..HEAD\" --sarif --sarif-out augur.sarif\n- uses: github/codeql-action/upload-sarif@v3\n  with:\n    sarif_file: augur.sarif\n    category: augur\n```\n\n**Honest caveat (GHAS on private repos).** Uploading SARIF to GitHub code scanning via\n`github/codeql-action/upload-sarif` requires **GitHub Advanced Security (GHAS)** when the\nrepository is **private**; without it the upload step returns a `403`. It works out of the\nbox once the repo is **public**, or with GHAS enabled on a private repo. The example\nworkflow marks the upload `continue-on-error: true` so the job stays green until GHAS/public\nis in place; remove that once it is. Generating the SARIF file itself needs nothing special.\n\n### Configuration (`.augur.toml`)\n\nDrop an `.augur.toml` at the repo root and `augur` discovers it automatically (override\nwith `--config \u003cpath\u003e`, ignore with `--no-config`). Every section is optional; an absent\nfile means built-in defaults, so configuration is strictly additive. It is parsed in the\nCLI layer only; the engine library stays dependency-free.\n\n```toml\n# Verdict cutoffs (0...100). score \u003e= block -\u003e block; \u003e= review -\u003e review; else proceed.\n# Defaults: review = 35, block = 65.\n[thresholds]\nreview = 35\nblock = 65\n\n# Signal weights for the heuristic prior. Only listed keys are overridden.\n[weights]\nsensitivity = 0.25\ntest_gap = 0.20\ncodeowners = 0.08   # weight of the CODEOWNERS ownership signal\n\n# Set true to use ONLY the custom rules below; default false MERGES them onto the built-ins.\n[sensitivity]\nreplace_defaults = false\n\n# Custom sensitivity rules: flag paths containing any fragment with the given risk (0...1).\n[[rules]]\nlabel = \"internal-api\"\nrisk = 0.7\nfragments = [\"internal/\", \"private/\"]\n\n# Drop generated/vendored/lockfile paths from the assessment entirely (glob-matched).\n[exclude]\npaths = [\"vendor/**\", \"node_modules/**\", \"**/*.generated.swift\", \"**/Package.resolved\"]\n```\n\nA worked, commented config and runnable scripts live in [`examples/`](examples/).\n\n### Excluding generated \u0026 vendored files (`[exclude]` / `--exclude`)\n\nVendored dependencies, generated code, and lockfiles add noise to a risk verdict. A\n9,000-line `vendor/` drop or a churny `Package.resolved` is not something a reviewer\nshould be scored on. List globs under `[exclude] paths` (or pass `--exclude \u003cglob\u003e`,\nrepeatable) and `augur` removes matching files **before** scoring: they appear in neither\nthe verdict nor any signal, and are reported as `excluded: N files` (and in JSON's\n`excludedPaths`). If *every* changed file is excluded, `augur` treats the change as clean.\n\nGlobs are whole-path anchored and support three wildcards:\n\n| Token | Matches | Example |\n|-------|---------|---------|\n| `*`   | any characters **except** `/` (one path segment) | `src/*.swift` → `src/a.swift`, not `src/x/a.swift` |\n| `**`  | any characters **including** `/` (zero or more segments) | `vendor/**` → `vendor`, `vendor/a/b.c` |\n| `?`   | exactly one character | `file?.txt` → `file1.txt`, not `file.txt` |\n\n```sh\naugur check --exclude 'vendor/**'                 # vendored dependencies\naugur check --exclude '**/*.generated.swift'      # generated sources, anywhere\naugur check --exclude '**/Package.resolved'       # lockfiles\naugur check --exclude 'vendor/**' --exclude 'node_modules/**'  # repeatable\n\naugur check --no-exclude    # ignore [exclude] from .augur.toml (ad-hoc --exclude still applies)\n```\n\nCLI `--exclude` globs are *added* to any `[exclude] paths` from `.augur.toml`; `--no-exclude`\ndrops the configured ones while keeping any passed on the command line.\n\n### CODEOWNERS-aware ownership (`codeowners`)\n\nIf your repo has a `CODEOWNERS` file, `augur` uses it to flag review-routing gaps. A changed\nfile with **no declared owner** raises the `codeowners` signal (risk `0.6`, \"no CODEOWNERS\nowner\"); an **owned** file neutralizes it (risk `0`, detail lists the owners). When there is\n**no `CODEOWNERS` file at all**, the signal contributes `0`; repos without one are never\npenalized.\n\n`augur` auto-discovers `CODEOWNERS` at the standard locations (`.github/CODEOWNERS`,\n`CODEOWNERS`, `docs/CODEOWNERS`; first found wins) and follows GitHub semantics (**the last\nmatching pattern wins**), reusing the same glob engine as `--exclude`:\n\n```text\n# .github/CODEOWNERS\n*            @platform        # catch-all\n/src/        @backend-team    # overrides for src/\n/src/auth/   @security        # overrides again, more specific\n*.md         @docs-team\n```\n\nThe owner is surfaced in the signal detail (human `-v` output and JSON). Pass\n`--no-codeowners` to disable, or tune its weight via `.augur.toml [weights] codeowners`.\n\n### Calibrate \u0026 cache\n\n`augur calibrate` walks git history once and writes a serializable model to\n`.augur/cache.json` (pinned to the current `HEAD`), reporting the backing volume and\ncalibration band. `augur check --cached` then reuses that model instead of re-running\n`git log`, which is ideal for tight agent loops. If `HEAD` has moved since calibration, `check\n--cached` prints a staleness warning to stderr but stays usable; with no cache it falls\nback to live computation. `.augur/` is git-ignored and never committed.\n\n```sh\naugur calibrate           # -\u003e .augur/cache.json (HEAD-pinned)\naugur check --cached      # fast path; warns on stderr if stale\n```\n\n### In CI\n\n```yaml\n- run: augur gate --range origin/main..HEAD --threshold block\n```\n\n#### GitHub Action (`CorvidLabs/augur`)\n\nThis repo ships a composite GitHub Action (\"augur gate\") you can drop into **any** repo. It\ninstalls a prebuilt `augur` for the runner (macOS universal or Linux x86_64) from the matching\nrelease, then runs `augur gate` against your checkout — no Swift toolchain required. On other\nplatforms it falls back to building augur from its own source (which needs Swift on the runner).\n\n```yaml\njobs:\n  gate:\n    runs-on: ubuntu-latest        # or macos-latest\n    steps:\n      - uses: actions/checkout@v4\n        with: { fetch-depth: 0 }  # gate needs history for the range\n      - uses: CorvidLabs/augur@v0\n        with:\n          range: origin/main..HEAD\n          threshold: block\n          coverage: lcov.info       # optional\n```\n\nPin to the moving `@v0` tag to track the latest 0.x release, or to an exact tag\n(e.g. `@v0.3.0`) to lock a specific version.\n\n| Input | Default | Description |\n|-------|---------|-------------|\n| `range` | `origin/main..HEAD` | Git range to assess (needs full history). |\n| `threshold` | `block` | Fail at or above this verdict (`proceed` / `review` / `block`). |\n| `coverage` | *(none)* | Optional path to a coverage report (LCOV `.info`, Cobertura/JaCoCo `.xml`, or Go `.out` coverprofile). |\n| `working-directory` | `.` | Repository root to run in. |\n| `version` | *(action ref)* | augur release to install (`v0.3.0` or `latest`); defaults to the pinned tag, else `latest`. |\n\n| Output | Description |\n|--------|-------------|\n| `verdict` | The computed verdict (`proceed` / `review` / `block`). |\n| `risk` | The computed risk score (0–100). |\n| `binary` | Path to the augur binary used. |\n\nPrebuilt binaries cover **GitHub-hosted macOS and Linux x86_64 runners**. Other runners (e.g.\n`windows-latest`, Linux arm64) need a Swift toolchain so the action can build from source.\n\n### For agents\n\n```sh\nverdict=$(augur check --range main..HEAD --json | jq -r .verdict)\n[ \"$verdict\" = \"proceed\" ] || echo \"escalating to a human\"\n```\n\n## JSON shape\n\n```json\n{\n  \"scope\": \"main..HEAD\",\n  \"riskScore\": 45.0,\n  \"verdict\": \"review\",\n  \"calibration\": { \"confidence\": 1.0, \"totalCommits\": 500, \"incidentCommits\": 156 },\n  \"thresholds\": { \"review\": 35.0, \"block\": 65.0 },\n  \"files\": [\n    { \"path\": \"src/auth/token.swift\", \"riskScore\": 45.0, \"signals\": [ /* ... */ ] }\n  ],\n  \"excludedPaths\": [ \"vendor/lib/huge.swift\" ]\n}\n```\n\n## Development\n\n```sh\nfledge run check     # build + test + spec check\nfledge run test\nfledge run spec      # spec-sync alignment\nfledge run selfcheck # dogfood: run augur on its own changes\n```\n\nThe engine (`AugurKit`) has **zero third-party dependencies** and is fully testable without\n`git` via the `RepositoryProbe` protocol. The CLI uses `swift-argument-parser`.\n\n## Trust layer (augur → attest)\n\nA verdict from `augur` is *ephemeral*: it lives for one CI run and is gone. Its sibling\n[`attest`](https://github.com/CorvidLabs/attest) makes it durable: `attest` records *who or\nwhat reviewed a change, and at what confidence* as a signed-or-unsigned provenance note\nkeyed to the commit SHA (stored in git notes), and gates CI / agent loops on a policy.\n**augur scores the risk; attest records the trust.** They compose over a pipe and never\nlink to each other.\n\n```sh\naugur check --json | attest sign --from-augur -        # record the trust\nattest verify --policy .attest.json                     # gate on it\n```\n\n`attest sign --from-augur -` copies augur's `verdict` and maps its `riskScore` (0...100) to\na trust-record confidence (`1 − riskScore/100`). A worked, end-to-end run is in\n[`examples/06-trust-pipeline.sh`](examples/06-trust-pipeline.sh): an agent attests a `review`\nchange, a policy that demands human approval for `review`+ verdicts FAILs, then a human\nsigns off and it PASSes.\nVerified output (real exit codes):\n\n```\n== 3) augur check --json | attest sign --from-augur - (agent records trust) ==\nattest · recorded agent:claude on f0ec5e6256\n\n== 5) attest verify: agent-only record FAILS the policy ==\n  policy: requireHumanApprovalWhenVerdictAtLeast = review\nattest verify · [x] FAIL (1 commit checked)\n  violations:\n    x f0ec5e6256  requireHumanApprovalWhenVerdictAtLeast: verdict is at least review on this commit but no attestation is human-approved\n  attest verify -\u003e exit 1   (only an agent attested a 'review' change)\n\n== 6) a human signs off, then attest verify PASSES ==\nattest · recorded human:leif on f0ec5e6256\nattest verify · [ok] PASS (1 commit checked)\n  attest verify -\u003e exit 0   (human approval now satisfies the policy)\n```\n\nThe policy clears as soon as **any** human-approved attestation exists on the commit: the\nhuman signs off with a plain `--human-approved` and need not restate the verdict.\n\n### Reusable CI workflow\n\n[`examples/workflows/trust.yml`](examples/workflows/trust.yml) is a copy-paste GitHub Actions\nworkflow other CorvidLabs repos can adopt. On `pull_request` it builds augur and runs\n`augur gate --range origin/\u003cbase\u003e..HEAD --threshold block`, with commented-out steps showing\nexactly where `attest sign` / `attest verify` slot in.\n\n### Pre-commit hook\n\n[`examples/hooks/pre-commit`](examples/hooks/pre-commit) runs `augur gate --staged\n--threshold block` and refuses the commit on a `block` verdict (set `AUGUR_THRESHOLD=review`\nto also stop on review-grade changes). Install it from the repo root:\n\n```sh\nln -s ../../examples/hooks/pre-commit .git/hooks/pre-commit\n# or copy it: install -m 0755 examples/hooks/pre-commit .git/hooks/pre-commit\ngit commit --no-verify   # deliberately bypass for one commit\n```\n\n**Honest scope.** `AugurKit` and the CLI build and run on **macOS and Linux**; CI exercises\nboth (full build + test on each, via GitHub-hosted runners). Homebrew ships a prebuilt\nmacOS binary; on Linux, build from source with Swift 6. The dogfooding workflows here\nbuild augur (and attest) *from a checkout*. **Cross-repo tool packaging** (installing a\nprebuilt binary into a foreign repo without a Swift toolchain) remains a deferred step.\n\n## Documentation\n\nIn-depth docs live in [`docs/`](docs/):\n\n- [Architecture](docs/architecture.md): `AugurKit` vs the CLI, the signal pipeline, two-layer scoring + calibration, and the zero-dependency invariant.\n- [Signals](docs/signals.md): every signal, what it catches, its weight, and how to tune it.\n- [Configuration](docs/configuration.md): the full `.augur.toml` reference (thresholds, weights, rules, exclude, codeowners) plus `--config` / `--no-config`.\n- [CLI reference](docs/cli.md): every command and flag (`check`, `gate`, `calibrate`, `explain`) with examples, glob syntax, exit codes, and JSON shape.\n- [Coverage](docs/coverage.md): supported formats (LCOV / Cobertura / JaCoCo / Go), auto-detection, and path-matching caveats.\n- [CI integration](docs/ci-integration.md): self-hosted macOS, the `augur-gate` action, SARIF upload (GHAS caveat), the pre-commit hook, and the augur → attest trust pipeline.\n- [Dogfooding](docs/dogfooding.md): the proof that augur scores augur, with real captured output for a PROCEED on its own change *and* a caught risky change (non-zero gate), plus an honest note on calibration.\n\n## Dogfooding (proof)\n\naugur runs augur on its own changes. The release binary assesses every change in\nCI and gates on a block-level self-change, and [`examples/dogfood.sh`](examples/dogfood.sh)\nis a committed, runnable demo that proves **both** outcomes with real exit codes:\na low-risk **PROCEED** on augur's own latest change, and a **REVIEW** verdict\n(with a `sensitivity: secrets` signal and a genuinely non-zero `gate` exit) on a\ncontrolled risky change. The captured output and an honest note on augur's own\n`prior-only` calibration are in [docs/dogfooding.md](docs/dogfooding.md).\n\n```sh\nfledge run dogfood          # build release + assess \u0026 gate augur's last commit\n./examples/dogfood.sh       # the full PROCEED + caught-risky-change proof\n```\n\n## Roadmap\n\n- [x] `augur calibrate`: cache the history model; report backing volume (`check --cached`).\n- [x] Configurable sensitivity rules, weights, and verdict thresholds (`.augur.toml`).\n- [x] Coverage-report ingestion (lcov/cobertura) for per-line test-gap precision (`--coverage`).\n- [x] Reusable GitHub Action (\"augur gate\") for any repo: installs a prebuilt binary\n  (macOS universal / Linux x86_64) and gates the caller's checkout — `uses: CorvidLabs/augur@v0`.\n- [x] **`attest`**: signed provenance records keyed to commit SHAs, a verifiable trail of\n  *what reviewed a change and at what confidence*. `augur` scores change risk; `attest`\n  records the resulting trust claim. See [Trust layer](#trust-layer-augur--attest) above and\n  [`examples/06-trust-pipeline.sh`](examples/06-trust-pipeline.sh).\n- [x] Cross-repo tool packaging: prebuilt augur binaries (macOS universal, Linux x86_64) so\n  foreign repos gate without a Swift toolchain. (`attest` and `trust.yml` still build from a\n  checkout today.)\n\n## License\n\nMIT © CorvidLabs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorvidlabs%2Faugur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorvidlabs%2Faugur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorvidlabs%2Faugur/lists"}