Prompt file imported from Black-Box-Research-Labs/aiv-protocol (.windsurf/workflows/aiv-commit.md). Copyright stays with the author.

AIV Commit Workflow

This project uses the AIV Protocol for evidence-based code verification. Every code change must go through aiv commit, which collects proof that the change was verified.

Before You Start

Make sure AIV is initialized: aiv init

Workflow

1. Start a tracked change (for multi-file changes)

aiv begin <change-name> --description "<what this change does>"

Example:

aiv begin auth-fix --description "Handle expired JWT tokens"

2. Stage your file, then commit with evidence

git add <file>
aiv commit <file> \
    -m "<conventional commit message>" \
    -t R1 \
    -c "<falsifiable claim about what changed>" \
    -i "<URL to issue/spec/directive>" \
    --requirement "<which requirement the URL satisfies>" \
    -r "<why this risk tier was chosen>" \
    -s "<one-line summary>"

Important rules:

• -c claims must be falsifiable: "TokenValidator rejects expired tokens with 401" NOT "Fixed auth bug"
• -i must be a URL (https://...), not plain text
• -t risk tier: R0 (trivial), R1 (default, low), R2 (medium), R3 (high/critical)
• You can repeat -c for multiple claims
• R1+ commits are blocked if >50% of claims lack test coverage. No bypass -- write tests or use R0.
• --skip-checks is only allowed for R0 (formatting, docs, comments)

3. Repeat step 2 for each file in the change

4. Close the change (generates Layer 2 verification packet)

aiv close --requirement "<which requirement this change satisfies>"

5. Push

git push

Quick Reference

Risk Tier Guide