Skip to content

Add corvid-stack template: CorvidLabs trust toolchain setup (language-agnostic)#427

Merged
0xLeif merged 3 commits into
mainfrom
feat/corvid-stack-template
Jun 24, 2026
Merged

Add corvid-stack template: CorvidLabs trust toolchain setup (language-agnostic)#427
0xLeif merged 3 commits into
mainfrom
feat/corvid-stack-template

Conversation

@0xLeif

@0xLeif 0xLeif commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a built-in corvid-stack template that scaffolds the CorvidLabs trust toolchain β€” fledge + spec-sync + augur + attest β€” as pure config. No language scaffolding: it's the "stack setup" layer you drop onto any repo.

Until now, wiring those four tools together meant hand-copying config from the integration guide. fledge templates init <name> -t corvid-stack does it in one shot.

What it scaffolds

File Purpose
fledge.toml Tasks + the verify lane (the single CI gate)
.specsync/{config.toml, registry.toml, .gitignore} spec-as-contract setup
.attest.json Attestation policy (canonical permissive shape from CorvidLabs/attest)
.github/workflows/trust.yml CI gate: fledge β†’ spec-sync β†’ augur β†’ attest β†’ AGENTS.md marker check
AGENTS.md Managed trust-toolchain rules block (the BEGIN marker trust.yml greps for); CLAUDE.md is a one-line pointer
README.md Setup + gate overview

Faithfulness

Rather than guess, the config is grounded in the real upstream sources:

  • trust.yml uses the actual composite actions β€” CorvidLabs/spec-sync@v4, CorvidLabs/augur@v0, CorvidLabs/attest@v0 β€” with their documented inputs (fetch-depth: 0, notes fetch, threshold: block, policy: .attest.json).
  • .attest.json matches the canonical schema dogfooded in CorvidLabs/attest.

Rendering

Files needing project variables carry a .tera extension (AGENTS.md.tera, README.md.tera, .specsync/registry.toml.tera). The workflow YAML and .attest.json are copied verbatim, so their literal ${{ }} / JSON survive Tera untouched (render = []).

Test Plan

  • Scaffolded a project (fledge templates init acme-svc -t corvid-stack): all 10 files render, .tera stripped, {{ project_name }} substituted, ${{ }} preserved, marker present, no leftovers
  • Scaffolded project runs fledge spec check (exit 0) and fledge lanes run verify (all 4 steps)
  • Updated built-in template count test (9 β†’ 10) + templates spec/README catalog
  • cargo test, cargo clippy -- -D warnings, cargo fmt --check all pass

πŸ€– Generated with Claude Code

…guage)

A language-agnostic built-in template that scaffolds the CorvidLabs trust
toolchain (fledge + spec-sync + augur + attest) as pure config β€” no source
code. Closes the gap from https://corvidlabs.xyz/integrate/ where wiring the
four tools together was a manual, copy-paste setup.

Scaffolds:
- fledge.toml β€” tasks + the `verify` lane (the single CI gate)
- .specsync/{config.toml, registry.toml, .gitignore} β€” spec-as-contract setup
- .attest.json β€” attestation policy (canonical permissive shape from CorvidLabs/attest)
- .github/workflows/trust.yml β€” fledge β†’ spec-sync β†’ augur β†’ attest gate, using
  the real composite actions (spec-sync@v4, augur@v0, attest@v0) with the right
  inputs (fetch-depth: 0, notes fetch, threshold: block)
- AGENTS.md β€” managed trust-toolchain rules block with the BEGIN/END marker the
  workflow greps for; CLAUDE.md is a one-line pointer
- README.md β€” setup + gate overview

Files needing project variables use a `.tera` extension; the workflow YAML and
.attest.json are copied verbatim so their literal `${{ }}` / JSON survive.

Verified by scaffolding a project and running `fledge spec check` (exit 0) and
`fledge lanes run verify` (all 4 steps) against it. Updated the built-in
template count test (9 β†’ 10) and the templates spec/README catalog.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@0xLeif 0xLeif requested a review from a team as a code owner June 24, 2026 00:18
@0xLeif 0xLeif requested review from 0xGaspar, Kyntrin and tofu-ux June 24, 2026 00:18

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new setup-only template, corvid-stack, which configures the CorvidLabs trust toolchain (fledge, spec-sync, augur, and attest) for language-agnostic projects. The review feedback highlights several key areas for improvement: preventing the root-level .gitignore from overwriting existing project files, correcting the min_fledge_version to ensure compatibility, resolving em-dash usage contradictions in AGENTS.md.tera, and optimizing the CI workflow by avoiding slow Homebrew installations on Ubuntu and dynamically calculating the git range for push and pull request events.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment on lines +1 to +6
# CorvidLabs trust toolchain
augur.json # per-run augur artifact β€” never commit

# OS / editor noise
.DS_Store
*.swp

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Since corvid-stack is designed as a "setup-only" layer to be dropped onto existing repositories, including a root-level .gitignore in the template is risky. The template rendering engine in fledge (src/templates.rs) overwrites existing files verbatim. If a user already has a .gitignore in their project, it will be completely overwritten and lost. Consider removing the root .gitignore from the template and instead instructing the user (e.g., in the README) to add augur.json to their existing .gitignore.

[template]
name = "corvid-stack"
description = "CorvidLabs trust toolchain (fledge + spec-sync + augur + attest) β€” language-agnostic stack setup, config only"
min_fledge_version = "1.0.0"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The min_fledge_version is set to "1.0.0". However, according to specs/templates/context.md, the current version of fledge is around v0.15.2. If min_fledge_version is enforced, setting it to "1.0.0" will make this template incompatible with current installations of fledge. Consider lowering it to a version that actually supports the required template features (e.g., "0.15.0" or "0.1.0").

Suggested change
min_fledge_version = "1.0.0"
min_fledge_version = "0.15.0"

Comment thread templates/corvid-stack/AGENTS.md.tera Outdated
- Keep specs in lockstep with code β€” update the `*.spec.md` in the same change.
- A block verdict from augur means stop and escalate, not merge.
- Do not commit `augur.json`.
- Do not use em-dash characters in authored content.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The rule states Do not use em-dash characters in authored content., but the template itself uses em-dashes (β€”) in multiple places (e.g., lines 5, 14, 16, 19, 21, 27, and 31). To maintain consistency and adhere to the rule, please replace the em-dashes in this file with hyphens or colons, or remove/modify this rule.

# spec-sync v4 configuration
# Docs: https://github.com/CorvidLabs/spec-sync
specs_dir = "specs"
source_dirs = ["src"]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Since corvid-stack is a language-agnostic template, the source code might not reside in a src directory (e.g., Go projects often use the root or other directories, Python might use a package name). Consider adding a comment to remind users to update source_dirs to match their project structure.

Suggested change
source_dirs = ["src"]
# Update this to match your project's source directories (e.g., ["lib"], ["app"], or ["."] for root)
source_dirs = ["src"]

Comment on lines +24 to +25
- name: Install fledge
run: brew install corvidlabs/tap/fledge

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using brew install on GitHub Actions ubuntu-latest runners can be extremely slow (often taking several minutes) because it may trigger a Homebrew update and potentially build from source if Linux bottles are not available. Consider using a direct binary download via curl from GitHub Releases, or caching cargo install fledge --locked to significantly speed up CI runs.

- name: Augur risk gate
uses: CorvidLabs/augur@v0
with:
range: origin/main..HEAD

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Hardcoding origin/main..HEAD as the range has two issues:

  1. On a push event to main, origin/main and HEAD will likely point to the same commit, resulting in an empty range.
  2. On a pull_request targeting a branch other than main, it will compare against the wrong base.

Consider dynamically setting the range using GitHub Actions expressions, for example:
range: ${{ github.event_name == 'pull_request' && format('origin/{0}..HEAD', github.base_ref) || format('{0}~1..{0}', github.sha) }}

          range: ${{ github.event_name == 'pull_request' && format('origin/{0}..HEAD', github.base_ref) || format('{0}~1..{0}', github.sha) }}

uses: CorvidLabs/attest@v0
continue-on-error: true
with:
range: origin/main..HEAD

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Hardcoding origin/main..HEAD here has the same issues as in the Augur step (empty range on push to main, incorrect base on non-main PRs). Consider using a dynamic range expression here as well.

          range: ${{ github.event_name == 'pull_request' && format('origin/{0}..HEAD', github.base_ref) || format('{0}~1..{0}', github.sha) }}

…quential job

Each tool now runs as its own job (fledge, spec-sync, augur, attest, rules), so
each surfaces as a distinct PR check and a failure points straight at the tool.
In verify form the tools are independent (none consumes another's output), so
parallel is correct; added a comment on when to add `needs:` if attest moves to
the augur-fed `sign` pipeline. No path filters by default (a trust gate should
score/verify every change; path filters also break required-check semantics).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ Corvin says...

      _
    <(;\  .oO(oh no...)
     |/(\
      \(\\
      " "\\

"I'm pecking through the errors..."

CI Summary

Check Status
Dependency Audit βœ… Passed
Integration (3 OS) ❌ cancelled
Lint (fmt + clippy) βœ… Passed
Spec Validation βœ… Passed
Tests (3 OS) βœ… Passed

Powered by corvid-pet

… hints

From the gemini-code-assist review on #427:
- trust.yml: replace the slow `brew install` on ubuntu with the curl-pipe
  prebuilt installer (install.sh)
- trust.yml: compute the augur/attest range dynamically instead of hardcoding
  origin/main..HEAD (empty on push to main, wrong base on non-main PRs):
  PR uses origin/<base_ref>..HEAD, push uses <sha>~1..<sha>
- Remove all em-dashes from template content (the managed AGENTS.md block bans
  them, so the template must not use them)
- .specsync/config.toml: comment that source_dirs should match the project layout
- README: note to merge (not replace) .gitignore/AGENTS.md when overlaying onto
  an existing repo

Kept min_fledge_version = "1.0.0" (fledge is at 1.6.0; the cited 0.15.2 is from a
stale companion doc) and the root .gitignore (templates init writes a fresh dir,
so nothing is overwritten, and augur.json must be ignored from day one).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@0xLeif

0xLeif commented Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Resolved in b1ba761:

Applied

  • brew install slow on ubuntu β†’ switched to the curl-pipe prebuilt installer (install.sh), which downloads a release binary instead of building/bottling.
  • Hardcoded origin/main..HEAD (augur + attest) β†’ now dynamic: origin/<base_ref>..HEAD on PRs, <sha>~1..<sha> on push. Fixes the empty range on push-to-main and the wrong base on non-main PRs. (Safe to add ${{ }} here since trust.yml is copied verbatim, not Tera-rendered.)
  • Em-dash contradiction β†’ removed every em-dash from the template content, so it no longer breaks its own managed rule.
  • source_dirs β†’ added a comment to set it to the project's layout.

Kept, with reasoning

  • min_fledge_version = "1.0.0" β€” the cited "~v0.15.2" is from a stale context.md; fledge is shipping 1.6.0, so a 1.0 floor is correct.
  • Root .gitignore β€” fledge templates init only writes into a freshly created dir (it bails if the target exists), so there's no existing file to overwrite; and augur.json must be gitignored from day one per the integration guide. Added a README note to merge rather than replace when overlaying onto an existing repo.

The Integration jobs showed cancelled (not failed) on the prior run β€” concurrency cancel from the rapid pushes; the re-run on this push should be clean.

@github-actions github-actions Bot dismissed their stale review June 24, 2026 00:45

Superseded by updated review.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ Corvin says...

      _
    <(;\  .oO(oh no...)
     |/(\
      \(\\
      " "\\

"Even the dumpster of code seems empty today."

CI Summary

Check Status
Dependency Audit βœ… Passed
Integration (3 OS) ❌ cancelled
Lint (fmt + clippy) βœ… Passed
Spec Validation βœ… Passed
Tests (3 OS) βœ… Passed

Powered by corvid-pet

@github-actions github-actions Bot dismissed their stale review June 24, 2026 01:09

Superseded by updated review.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

βœ… Corvin says...

      _
    <(^\  .oO(Caw! ^v^)
     |/(\
      \(\\
      " "\\

"Caw! Your code sparkles like a dropped french fry."

CI Summary

Check Status
Dependency Audit βœ… Passed
Integration (3 OS) βœ… Passed
Lint (fmt + clippy) βœ… Passed
Spec Validation βœ… Passed
Tests (3 OS) βœ… Passed

Powered by corvid-pet

@0xLeif 0xLeif merged commit 0c137d8 into main Jun 24, 2026
13 checks passed
@0xLeif 0xLeif deleted the feat/corvid-stack-template branch June 24, 2026 02:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant