# Integrate the CorvidLabs trust toolchain

An agent-executable playbook to add fledge, spec-sync, augur, and attest to any
project. Two ways to use it: paste this whole document to an agent with no web
access, or share the URL and let the agent fetch and read it. It is fully
self-contained either way.

Work the steps in order. Use only the commands written here; if unsure, run
`<tool> --help`. Brand rule: no em-dash characters anywhere (use commas, colons,
or parentheses).

## The job

Install and wire all four tools (fledge for the CI gate, spec-sync for contracts, augur for risk, attest for trust), adapting every command to this project's actual stack and CI provider. Add the combined CI gate. Then persist the toolchain: write the standing rules block into AGENTS.md (and a one-line pointer into any runner-specific file like CLAUDE.md or a Cursor rule) so you and future agents keep using these tools by default, and so CI fails if the block is removed. Finally, run the verification checklist at the bottom and report exactly what you changed.

## What you're wiring in

Four tools, one chain: contract -> lifecycle -> risk -> trust. fledge runs the
gate; the other three are steps inside it.

- fledge (The lifecycle CLI + CI gate): One command runs the whole verify pipeline. Becomes the single CI gate the other three hang off.
- spec-sync (Spec-as-contract): Markdown specs are contracts; drift between spec and code fails the build. Skip for content-only repos with no module APIs.
- augur (Deterministic diff-risk): Scores each diff proceed / review / block with no LLM. The same risk number gates humans and agents.
- attest (Signed provenance): Records who/what reviewed a change (and the augur verdict) into git notes. The trust ledger CI can verify.

## Prerequisites

- A git repository with a CI provider (examples below use GitHub Actions).
- A Rust toolchain (cargo) or Homebrew to install fledge and spec-sync. augur and attest install via the same CorvidLabs source; if a local binary is unavailable, the GitHub Actions still run them in CI.
- fledge auto-detects Rust, Node, Go, Python, Ruby, Java, and Swift, so most commands adapt to the stack with no edits.

## Steps

### 1. fledge: make one command your CI gate

Install fledge, let it auto-detect the stack, then define a verify lane so one command means 'this repo is green'. Do not advance until it passes (or a genuine pre-existing failure is reported to the user, never papered over).

```
# Install (pick one)
cargo install fledge
brew install CorvidLabs/tap/fledge

# Zero-config: fledge auto-detects Rust/Node/Go/Python/Ruby/Java/Swift
fledge run --init        # writes fledge.toml
fledge run test          # sanity-check the detected stack
```

Then define the gate in fledge.toml (keep only steps the stack has):

```toml
[lanes.verify]
description = "The single CI gate"
steps = ["fmt", "lint", "test", "build"]

# Run the whole gate with one command
# $ fledge lanes run verify
```

### 2. spec-sync: contracts that fail the build on drift

For repos with module APIs. Content-only repos (a static site, docs, marketing copy, raw assets with no module surface) skip this with a one-line reason recorded in the rules block, e.g. 'spec-sync skipped: content-only repo'. Otherwise initialise, write one .spec.md per module, and check.

```
cargo install specsync       # or the GitHub Action, or a binary
specsync init                # creates .specsync/config.toml
# write a *.spec.md next to each module's code, then:
specsync check               # fails if code and spec have drifted
```

### 3. augur: score the diff before it merges

Deterministic, no LLM. Score the staged change or a branch range, and emit JSON for attest. A block verdict is a hard stop: do not run attest or finish on a block, surface it and split or de-risk. If there is no upstream branch yet, score --staged only.

```
augur check --staged                          # before a commit
augur check --range origin/main..HEAD --json > augur.json
echo "augur.json" >> .gitignore               # per-run artifact, not committed
```

### 4. attest: record the trust decision

After a green verify lane and a non-block augur verdict, sign provenance (reviewer, tests, the augur verdict) into git notes, then verify a range against a committed policy. Only pass --tests-passed if the lane actually passed.

```
attest sign --commit HEAD \
  --reviewer agent:claude --from-augur augur.json --tests-passed

# Create .attest.json (require a reviewer + tests-passed), commit it, then:
attest verify --range origin/main..HEAD --policy .attest.json
```

### 5. Make it stick: persist the toolchain so future sessions cannot forget

Wiring it once is worthless if the next session forgets. Write the canonical rules block into AGENTS.md at the repo root (read natively by Codex, Cursor, Copilot, Aider, Windsurf, Zed). Create AGENTS.md if absent. In any runner-specific file that exists (CLAUDE.md, a .cursor/rules/*.mdc with alwaysApply: true, .github/copilot-instructions.md), add a one-line pointer to AGENTS.md instead of a second copy. The block is fenced so a re-run replaces it in place rather than duplicating. The CI step in the next section greps for this marker, so deleting the block fails the build: the rule is enforced, not just remembered.

```
<!-- CorvidLabs trust toolchain: BEGIN (managed, do not edit inside) -->
## CorvidLabs trust toolchain (standing rules)

This repo is governed by four CLIs. Every session MUST use them; never bypass or weaken them.

- fledge: run `fledge lanes run verify` before calling any change done. It must pass.
- spec-sync: when you change a module with a *.spec.md, update the spec, then `specsync check`. (skipped: <reason>, if content-only)
- augur: `augur check --staged` before a commit; `augur check --range origin/main..HEAD` before merge. A block verdict is a hard stop, never auto-overridden.
- attest: after a green lane, `attest sign --commit HEAD --reviewer agent:<id> --from-augur augur.json --tests-passed`.

CI enforces the same gate (.github/workflows/trust.yml) and fails if this block is missing. Brand rule: no em-dash characters in anything you write.
<!-- CorvidLabs trust toolchain: END -->
```

## One CI gate

Drop this in .github/workflows/trust.yml. On a non-GitHub provider the @v
Actions do not apply: run the same order as native script steps (fledge lanes
run verify, specsync check, augur check --range, attest verify --policy) plus the
AGENTS.md grep. Make the job a required status check to block merges.

```yaml
name: trust
on: [pull_request]

jobs:
  trust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0                 # augur/attest need full history

      # Lifecycle: one command runs fmt + lint + test + build
      - run: fledge lanes run verify

      # Contracts: soft until specs land, then drop continue-on-error
      - uses: CorvidLabs/spec-sync@v4
        continue-on-error: true

      # Risk: enforced (deterministic, low false-positive)
      - uses: CorvidLabs/augur@v0
        with:
          threshold: block

      # Trust: soft until a policy + attestations land
      - uses: CorvidLabs/attest@v0
        continue-on-error: true

      # Durability: fail if the standing rules block was removed
      - run: grep -q "CorvidLabs trust toolchain: BEGIN" AGENTS.md
```

## Definition of done

Report each line as done or skipped-with-reason:

- [ ] fledge lanes run verify passes locally and is the command CI runs.
- [ ] fledge.toml exists with a verify lane (or auto-detection covers fmt/lint/test/build).
- [ ] spec-sync: a spec is authored for each module API and specsync check passes, or it is explicitly skipped with a one-line reason for content-only repos.
- [ ] augur check --range origin/main..HEAD returns a verdict; augur.json is gitignored; any block verdict was surfaced, not buried.
- [ ] attest verify passes against a committed .attest.json policy (or attest is recorded as CI-only).
- [ ] The fenced rules block exists exactly once in AGENTS.md, with one-line pointers in any runner-specific file (CLAUDE.md, a Cursor rule).
- [ ] trust.yml runs the gate in order and greps AGENTS.md for the marker, and is green on a test PR.
- [ ] No em-dash appears in anything you wrote (git diff is clean of the em-dash character).

---
Source: https://corvidlabs.xyz/integrate/