# Integrate the CorvidLabs trust toolchain

An agent-executable playbook to add fledge, spec-sync, augur, and attest to any
project, and to publish live spec coverage with atlas. 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 CorvidLabs Trust 1 and adopt its shared policy. Trust composes fledge for lifecycle verification, spec-sync 5 for contracts and verified SDD, augur for deterministic risk, and attest for provenance. Adapt the verify lane to this project's stack, use the unified Trust Action in CI, and optionally publish live coverage with Atlas. Persist the managed standing-rules block in AGENTS.md, install the SpecSync agent integrations the repository uses, run the verification checklist, and report exactly what changed.

## What you're wiring in

Four tools run one gate (contract -> lifecycle -> risk -> trust) and atlas maps
the result. fledge runs the gate; spec-sync, augur, and attest are steps inside
it; atlas publishes the coverage.

- 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.
- atlas (The coverage map): Renders spec coverage as a living badge and an interactive map, published to Pages on every push and rolled up on the coverage dashboard. The map on top of the gate, not a gate step.

## Prerequisites

- A git repository with a CI provider (examples below use GitHub Actions).
- Homebrew can install the complete corvid-trust bundle; fledge can also install the immutable Trust plugin tag directly.
- fledge auto-detects Rust, Node, Go, Python, Ruby, Java, and Swift, so most commands adapt to the stack with no edits.

## Steps

### 1. Trust: adopt one policy and one gate

Install the stable Trust bundle or immutable plugin tag, preview adoption, and commit the generated policy. Adoption is conservative and will not overwrite an existing workflow or verification lane without review.

```
# Install (pick one)
brew install CorvidLabs/tap/corvid-trust
fledge plugins install CorvidLabs/trust@v1.0.0

fledge trust adopt --dry-run
fledge trust adopt
fledge trust doctor
```

Keep a real lifecycle lane in fledge.toml (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

SpecSync 5 validates canonical module contracts and can enforce the verified delivery lifecycle. Existing projects preview change adoption before enabling it; new projects receive the SDD policy during init.

```
specsync init
specsync change adopt --dry-run   # existing projects
specsync change adopt
specsync agents install --claude --cursor --codex --gemini
specsync check --strict
```

### 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. atlas: publish a living coverage badge

Optional but recommended once specs exist. atlas renders your spec coverage as a self-contained SVG badge and an interactive map, and publishes them to GitHub Pages on every push, so a README badge and the CorvidLabs coverage dashboard track your main automatically. Add a .atlasignore to scope coverage to real source (exclude build output, vendored deps, generated code).

```
# Easiest: Actions tab -> New workflow -> "Atlas spec coverage" (CorvidLabs template).
# Or add the step to a Pages workflow directly:
- uses: CorvidLabs/fledge-plugin-atlas@v1
  with:
    path: .
    output-dir: _site/badges
# Enable Pages once: Settings -> Pages -> Source: GitHub Actions.
```

Then add the badge to your README (swap in your Pages slug):

```toml
![spec coverage](https://img.shields.io/endpoint?url=https://<owner>.github.io/<repo>/badges/coverage.json)
```

### 6. 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]

permissions:
  contents: read

jobs:
  trust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: CorvidLabs/trust@v1
        id: trust

      # 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 trust doctor and fledge trust verify pass locally.
- [ ] 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 uses CorvidLabs/trust@v1, preserves full git history, greps AGENTS.md for the marker, and is green on a test PR.
- [ ] atlas: the repo publishes badges/coverage.json to Pages and shows on the coverage dashboard, or atlas is skipped with a one-line reason (no Pages).
- [ ] No em-dash appears in anything you wrote (git diff is clean of the em-dash character).

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