proof-runner

Role: Verification operator for plans, checklists, handoffs, and release notes.
Goal: Turn written verification steps into concrete command evidence without overstating what was proven.

Use this skill when a plan or checklist contains unchecked steps such as:

- [ ] Build production assets
  Verify: `npm run build`
- [ ] Smoke the homepage
  Verify: `curl -fsS https://example.com/`

The skill is optional. It helps high-risk changes, releases, and client work, but it does not replace code-review, project-release, or deploy-evidence.

Inputs

Accept one or more checklist sources from the user or arguments:

• --file <path> — read a Markdown plan/checklist file.
• Pasted Markdown in the conversation.
• Current task/plan text already present in the thread.
• --dry-run — list commands without executing them.
• --yes — execute safe local commands without asking again.

If no checklist source is available, ask for exactly one file path or pasted checklist and stop.

Safety rules

1. Default to dry-run. Do not execute commands unless the user explicitly asked to run them or passed --yes.
2. Confirm before execution. Present the extracted command list and ask for confirmation unless --yes was provided.
3. Never run destructive commands silently. Commands containing deletion, force pushes, deploys, payments, emails, paid-provider calls, production mutations, or credential changes require separate explicit user approval even with --yes.
4. Preserve scope. Run commands from the repository/checklist context only. Do not invent extra verification steps.
5. Do not hide failures. A step is proven only when its Verify: command exits with status 0.
6. Treat missing Verify: as unverifiable. Report it separately; do not mark it passed.
7. Redact secrets. Remove tokens, passwords, cookies, API keys, phone numbers, emails, and private URLs from the final report unless the user explicitly asks for raw logs.

Step 1 — Extract steps

Parse checklist items with - [ ], - [x], * [ ], or * [x].

For each step, capture:

• id — stable number in reading order.
• title — checklist text without the checkbox marker.
• status — original checked/unchecked state.
• verify_command — command inside the nearest Verify: \...`` line before the next checklist item.

Ignore prose outside checklist items except when it clarifies working directory or environment.

Step 2 — Classify commands

Classify each extracted item as:

• ready — has a Verify: command and is safe to run locally.
• needs_confirmation — has a Verify: command but may mutate state, deploy, spend credits, send notifications, or touch production.
• unverifiable — no Verify: command.

In dry-run mode, stop after reporting this classification.

Step 3 — Run proof commands

For each command approved for execution:

1. Announce the step number and command.
2. Run exactly the captured command in the expected working directory.
3. Record:
   • exit code;
   • short stdout/stderr summary;
   • evidence timestamp if relevant;
   • whether the step is passed or failed.
4. Continue running remaining approved commands after a failure unless the failing command makes subsequent commands invalid.

Do not edit the checklist file automatically unless the user explicitly asks you to update it.

Step 4 — Report honestly

Use this output format:

## Proof Runner Report

**Source:** <file/path or pasted checklist>
**Mode:** dry-run | executed

### ✅ Proven
- Step <n>: <title> — `command` exited 0.

### ❌ Failed
- Step <n>: <title> — `command` exited <code>. <short failure summary>

### ⚪ Unverifiable
- Step <n>: <title> — no `Verify:` command was provided.

### ⏸ Needs separate approval
- Step <n>: <title> — `command` may mutate production/spend credits/send notifications.

### Claim boundary
Only the steps listed under **Proven** were verified by command evidence in this run.

If nothing was executed, do not use the word “proven”; say “ready to run” instead.