Skip to content
supersigil

CI Verification

Supersigil is most valuable when the same contract that guides local work is also enforced in CI. The goal is straightforward: catch broken references, missing evidence, and spec drift before a change lands.

The CI Workflow

Section titled “The CI Workflow”

  1. Run verification locally

    Terminal window
    supersigil verify

    verify is the graph-level check that enforces structural integrity, coverage, evidence, and tracked-file rules.

  2. Use tracked files for drift detection

    Add tracked file globs to the specs that should be reconsidered when code changes:

    <TrackedFiles paths="src/auth/**/*.rs, tests/auth/**/*.rs" />

    Now Supersigil can tell you when a pull request touched code that a spec claims to care about.

  3. Check only the current branch’s changes in CI

    Terminal window
    supersigil verify --since main --merge-base --committed-only

    This asks Supersigil to compare the branch against the merge-base with main and report specs whose tracked files changed.

  4. Use affected for triage when you do not need full verification

    Terminal window
    supersigil affected --since main --merge-base --committed-only

    This is useful in review tooling, dashboards, or scripts that want to know which specs need attention before deciding what to do next.

What CI Should Enforce

Section titled “What CI Should Enforce”
  • Broken references should always fail the build.
  • Missing verification evidence should fail once a document leaves draft.
  • Tracked-file drift should at least warn, and often fail in stricter repos.
  • Warnings-only runs should still be visible because they indicate contract debt.

Exit Codes

Section titled “Exit Codes”

supersigil verify uses exit codes to signal results: 0 for clean, 1 for errors, 2 for warnings only. See the Verification page for the full table. This makes it easy to gate merges or post review comments conditionally.

Example: GitHub Actions

Section titled “Example: GitHub Actions”
.github/workflows/specs.yml
name: Spec Verification


on:
  pull_request:
  push:


jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Supersigil
        run: cargo install supersigil
      - name: Verify Spec Graph
        run: supersigil verify --since main --merge-base --committed-only

Practical Policy

Section titled “Practical Policy”
  • Keep active work in draft while the structure is still moving.
  • Move a spec out of draft once missing evidence should block the branch.
  • Use affected when you want lightweight routing.
  • Use verify --since ... when you want actual CI enforcement.
Section titled “Related Reading”