/proof-verify

name: proof-verify
description: Plan-based verification - freeze acceptance criteria before building, then verify after with an independent fresh-context agent (the builder must not verify their own work). For multi-stage work, seal accepted inputs with commit/tree, contract, input/output digests, and a fresh verdict so downstream stages do not reopen them. Use when - "verify against plan", "proof check", "independent review", "check the implementation", or confirming a feature built from a plan meets spec. Do NOT use for quick one-off checks with no plan, or for letting the builder self-verify.

Proof Verify

Plan-based verification: freeze acceptance criteria BEFORE building, verify AFTER with independent agents.

When to Use

• After completing a feature/fix that was built from a plan
• When you need independent confirmation that work meets spec
• When the builder should NOT verify their own work
• Trigger phrases: "verify against plan", "check the implementation", "proof check", "independent review"

The Pattern

PHASE 1: PLAN (before any code)
  Create .proof/PLAN.md with numbered acceptance criteria
  Each AC: testable, specific, has a verification command or check
  Plan is FROZEN - no changes during build

PHASE 2: BUILD (normal work)
  Implement against the plan
  Mark progress in .proof/PROGRESS.md
  Builder does NOT self-verify

PHASE 3: VERIFY (after build, independent agent)
  Fresh agent reads PLAN.md (never saw the build process)
  Walks through each AC, runs verification commands
  Writes .proof/VERDICT.md with PASS/FAIL per criterion
  If any FAIL → .proof/PROBLEMS.md with specific fixes

PHASE 4: FIX (if needed)
  Builder reads PROBLEMS.md, makes minimal fixes
  Back to PHASE 3 (re-verify)
  Loop until all PASS

Stage Ledger - only when proof feeds another stage

For a release, integration, migration, hardware, signer, or other multi-stage task, a green check is not enough. The next stage needs a stable input, not a summary that the previous stage once looked good.

1. Freeze the stage contract and its scope before building it. 2. Run the focused proof and obtain the fresh verdict as usual. 3. Write the stage to `.proof/stage-ledger.json` as `VERIFIED` or `SEALED`. A sealed stage records its source commit/tree, contract digest, named input and output digests, fresh verdict digest, and invalidation keys. 4. A downstream stage names the sealed parent and exact output digest it consumes. It must not consume a merely `VERIFIED` or `BLOCKED` stage. 5. If an external dependency is missing, record `BLOCKED` with the exact missing prerequisite. Do not invalidate the sealed upstream code. 6. If code, contract, or an input digest changes, add a `SUPERSEDED` successor and re-run proof for that successor; do not overwrite the old receipt.

Validate the ledger deterministically:

Resolve `<proof-verify-skill-dir>` to the directory containing the loaded `proof-verify` `SKILL.md`; do not assume that a project checkout has a `skills/development/` copy:

python <proof-verify-skill-dir>/scripts/validate_stage_ledger.py \
  .proof/stage-ledger.json

The ledger is not a signing ceremony for every edit. Use it only when an accepted result crosses a real project boundary. Full format, status semantics, and examples: `references/proven-stage-contracts.md`.

Phase 1: Create Plan

Create `.proof/PLAN.md` in the project root:

# Verification Plan

**Created:** YYYY-MM-DD HH:MM
**Task:** [one-line description]
**Builder:** [session ID or "current"]
**Status:** FROZEN

## Acceptance Criteria

### AC1: [short name]
**Description:** [what must be true]
**Verify:** [exact command or check to run]
**Expected:** [what success looks like]

### AC2: [short name]
**Description:** [what must be true]
**Verify:** [exact command or check to run]
**Expected:** [what success looks like]

### AC3: [short name]
...

## Out of Scope
- [explicitly what this plan does NOT cover]

## Constraints
- [time, resource, or technical constraints]

Rules for good ACs:

• **Testable** - there is a command or check that produces PASS/FAIL
• **Specific** - "function returns correct value" not "code works"
• **Independent** - each AC can be verified without the others
• **Sufficient** - use one criterion when one observable contract is all that

changed; split criteria only when their behavior, owner, or verification command is meaningfully independent

• **Frozen** - once written, do not modify during build

Phase 2: Build

Normal implementation. The only additions:

1. Create `.proof/PROGRESS.md` as you work:

# Build Progress

### AC1: [name]
- [x] Implemented in `src/foo.py:42`
- Files changed: `src/foo.py`, `tests/test_foo.py`

### AC2: [name]
- [x] Implemented in `src/bar.py:18`
- Files changed: `src/bar.py`
- Note: chose approach B because [reason]

2. After build is complete, write `.proof/EVIDENCE.md`:

# Evidence

### AC1: [name]
**Command:** `pytest tests/test_foo.py -v`
**Output:**
\```
tests/test_foo.py::test_returns_correct PASSED
tests/test_foo.py::test_handles_edge PASSED
\```
**Result:** PASS

### AC2: [name]
**Command:** `grep -c "TODO" src/bar.py`
**Output:** `0`
**Result:** PASS

Builder collects evidence but does NOT write the verdict. That is the verifier's job.

Phase 3: Verify (Independent Agent)

This is the critical phase. The verifier MUST be:

• A **fresh agent** (new session or subagent) that never saw the build
• Given ONLY: `PLAN.md` + access to the codebase
• NOT given: `PROGRESS.md`, `EVIDENCE.md`, or any build context

Verifier prompt template

You are an independent verifier. Your job is to check whether
the implementation meets the acceptance criteria in .proof/PLAN.md.

Rules:
1. Read .proof/PLAN.md first. This is your ONLY specification.
2. For each AC, run the verification command yourself.
3. Do NOT read .proof/PROGRESS.md or .proof/EVIDENCE.md
   (those are the builder's