# Proof Loop

> Run evidence-gated coding sprints with frozen ACs, separated builder/verifier roles, and durable proof artifacts.

- Skill: `leostehlik/proof-loop` (Agent Skill, multi-file: 47 files)
- Install (CLI): `npx get-skill add leostehlik/proof-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leostehlik/proof-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: LeoStehlik (https://skillmd.com/u/leostehlik)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/leostehlik/proof-loop

---

# Proof Loop

A sprint is not done until every acceptance criterion has a PASS verdict from a fresh verifier session.

Read `references/workflow.md` for the full loop spec.
Read `references/brief-template.md` for the agent brief format.
Read `references/artifacts.md` for the artifact schema.
Read `references/loopsmith-bridge.md` when deciding whether a repeated Proof Loop failure should become a Loopsmith eval case.


## Activation and Safety Boundaries

Use this skill only when the user explicitly asks for Proof Loop, proof artifacts, acceptance-criterion verification, fresh verifier separation, or an evidence-gated coding sprint. Do not activate it for ordinary code edits where the user did not request this protocol.

Proof Loop may create or update files under `.agent/tasks/<TASK_ID>/` in the current repository. Confirm the task id and repository root before creating artifacts. Do not publish artifacts, run remote validation, change repository permissions, moderate users, request full-access sandboxing, or touch credentials unless the user explicitly asks for that separate action in the current conversation.

Run helper scripts with the least privilege available. If a command could modify source files outside `.agent/tasks/<TASK_ID>/`, ask first and record the command in the evidence artifact.

## The Loop

```
spec freeze -> build -> evidence -> FRESH verify -> fix -> FRESH verify
                                         ^                      |
                                         |______________________|
                                         (repeat until all ACs = PASS)
```

## Four Roles — Always Separate

| Role | Does | Never |
|------|------|-------|
| **Spec-Freezer** | Writes spec.md with explicit ACs | Edits production code |
| **Builder** | Implements against frozen spec | Verifies own work |
| **Verifier** | Fresh session — verdicts each AC | Edits production code |
| **Fixer** | Minimal fix for what verifier flagged | Signs off on completion |

**The verifier is always a fresh session.** The agent that built cannot judge its own work.

## Acceptance Criteria Format

Every sprint brief must include explicit ACs before build starts:

```
AC1: [specific, testable condition — not a task description]
AC2: [specific, testable condition]
AC3: [specific, testable condition]
```

Good: "AC1: A German-locale user sees all prompt form field labels in German"
Bad: "AC1: Translate the form fields"

## Helper Scripts

Use these when the repository has the `proof-loop` folder available:

```bash
python3 scripts/init_task.py TASK_ID --title "Task title"
python3 scripts/check_task.py .agent/tasks/TASK_ID
```

`check_task.py` is the mechanical done gate. It returns success only when the verifier artifacts show every AC as PASS and no open problems remain.

## Sprint is DONE Only When

- Every AC has a PASS verdict in the verifier's `verdict.json`
- No problems remain in `problems.md`
- Full regression suite passes (if applicable)

## Artifacts (stored in repo)

```
.agent/tasks/<TASK_ID>/
  spec.md         -- frozen ACs + constraints + non-goals
  verdict.json    -- AC verdicts per phase (PASS/FAIL/UNKNOWN)
  problems.md     -- specific failures with file/line refs (if any)
```

See `references/artifacts.md` for schemas.

## Mechanical validation limits

The local helpers validate artifact structure and complete AC coverage against `spec.md`. They require a verify-phase verdict, recorded verifier identity, non-empty evidence, and an explicitly empty problems file. They cannot authenticate verifier independence or prove that recorded checks really ran; a human or independent verifier must inspect that evidence. Repository tests and demo fixtures are maintainer tools, not the skill’s writing or verification authority.

## Registry installs

Public examples are under `examples/*/tasks/`; real project tasks still use `.agent/tasks/`. ClawHub does not preserve executable bits, so run the unified CLI as `python3 bin/proof-loop` and shell wrappers with `bash`. The doctor checks runtime files, not GitHub CI metadata.

