RunProof

Make AI prove it works.

RunProof is a verification engine for AI-driven development.

It prevents agents from claiming work is complete without real execution evidence.

If a command didn’t run — or failed — the system blocks progress.

---

Why not existing SDD frameworks?

Feature	RunProof	Spec-Kit	OpenSpec	BMAD	Agent Teams
Spec-driven workflow	✅	✅	✅	✅	⚠️ Partial
Structured artifacts	✅	✅	✅	✅	⚠️ Partial
Persistent state (on disk)	✅	❌	⚠️ Partial	⚠️ Partial	❌
Execution verification	✅	❌	❌	❌	❌
Blocks fake completion	✅	❌	❌	❌	❌
Command execution evidence	✅	❌	❌	❌	❌
Checksum validation	✅	❌	❌	❌	❌
Enforced workflow transitions	✅	⚠️ Soft	⚠️ Soft	⚠️ Soft	❌
CI / Git hook enforcement	✅	❌	❌	❌	❌
Anti-hallucination guarantees	✅	❌	❌	❌	❌

⚠️ Partial = supported conceptually but not enforced or persisted

---

🚫 The problem

AI says:

"Done"

Reality:

npm test
# FAIL

---

✅ With RunProof

runproof verify --require-execution-evidence

Result:

BLOCKED: command failed (exit_code=1)

The system forces real execution before accepting completion.

---

Why It Exists

AI coding agents are excellent at producing code. They are much weaker at:

• remembering why a decision was made after the chat scrolls away
• proving that tests ran, rather than saying they did
• keeping specs in sync when behavior changes

RunProof turns "the agent said it passed" into structured, checksummed evidence stored in your repository. No lock-in. No operating-system lock-in. The workflow state is explicit, versioned, and repository-native in .runproof/state.json.

---

Try It Now (30 seconds, no setup)

Runs the full Golden Path in a temp directory and cleans up after itself:

npx -y runproof-cli@latest demo

What you will see:

── Step 1/7: runproof init
   ✓ Initialized .runproof/ (adapters, agents, profiles, schemas, skills, specs)
── Step 2/7: runproof new demo-harden-login --profile quick
   ✓ Created .runproof/changes/demo-harden-login/ (proposal.md, tasks.md, verification.md)
   ✓ Phase automatically recorded → propose
── Step 3/7: Agent fills proposal.md → status: ready
── Step 4/7: Agent closes tasks.md → status: ready
── Step 5/7: runproof transition demo-harden-login task
   ✓ Phase recorded in .runproof/state.json → task
── Step 6/7: runproof verify --command 'echo all-tests-pass'
   ✓ Command executed; output checksummed → .runproof/evidence/
   ✓ verification.md updated automatically → status: verified
── Step 7/7: runproof transition archive  &&  runproof archive
   ✓ Change closed → .runproof/archive/2026-05-05-demo-harden-login/
── runproof validate
   ✓ Repository governance passed — zero errors

---

Install

uv tool install runproof-cli

Or with pipx:

pipx install runproof-cli

Or via the Node wrapper:

npm install -g runproof-cli

Or one-shot:

npx -y runproof-cli@latest version

Or from source (requires Python 3.11+):

uv tool install runproof-cli --from git+https://github.com/sebamar88/RunProof.git

---

User Guide

Detailed bilingual user guides live in Notion:

• RunProof User Guide

The guide includes:

• Quick Start for Engineers
• Team Workflow Guide
• Production Rollout Guide

Each guide is split into EN and ES subpages.

---

Golden Path: Guard A Real Change

1) Initialize your repository

runproof init --root my-app
runproof validate --root my-app

2) Open a governed change

runproof run harden-login-rate-limit --profile standard --title "Harden login rate limits" --root my-app

Result: .runproof/changes/harden-login-rate-limit/ with six artifacts — proposal.md, delta-spec.md, design.md, tasks.md, verification.md, archive.md.

run creates the change if needed, reads the artifact state, names the current phase, and tells the agent the next allowed action.

3) Give the agent a repository contract

Instead of "fix login security", point the agent at the change folder:

Run `runproof run harden-login-rate-limit --root .` before each handoff.
Follow the phase it reports.
After each completed artifact phase, record it with `runproof transition`.
Do not archive until `runproof run` reports `sync-specs` or `archive`.

The agent now has a repository contract, not just a chat instruction.

4) Block fake completion

runproof check harden-login-rate-limit --root my-app

Open tasks or missing evidence will surface here. The change cannot close cleanly.

5) Record state, verify, sync, and archive

runproof transition harden-login-rate-limit specify --root my-app
runproof transition harden-login-rate-limit design --root my-app
runproof transition harden-login-rate-limit task --root my-app
runproof verify harden-login-rate-limit --command "pytest -q" --root my-app
runproof transition harden-login-rate-limit archive-record --root my-app
runproof transition harden-login-rate-limit sync-specs --root my-app
runproof sync-specs harden-login-rate-limit --root my-app
runproof archive harden-login-rate-limit --root my-app
runproof validate --root my-app

Outcome: the code change, specs, executed verification evidence, state transitions, checksums, and archive record all stay in the repo.

---

Orchestrator API (Python)

The CLI is not the only binding layer. The Python core exposes a strict workflow object for tools, adapters, and IDE integrations:

from runproof import SDDWorkflow, WorkflowPhase

workflow = SDDWorkflow("my-app")

result = workflow.run(
    "harden-login-rate-limit",
    profile="standard",
    title="Harden login rate limits",
)

if result.state.phase == WorkflowPhase.PROPOSE:
    print(result.state.next_action)

transitioned = workflow.transition("harden-login-rate-limit", WorkflowPhase.SPECIFY)
verified = workflow.verify(
    "harden-login-rate-limit",
    commands=["pytest -q"],
    require_command=True,
)

transition(), verify(), sync_specs(), and archive() refuse invalid phase order. verify executes commands and stores reproducible logs under .runproof/evidence/ with SHA-256 checksums. That is the difference between SDD helpers and SDD enforcement.

---

WorkflowEngine — Agent Execution Loop

WorkflowEngine.next_step() gives agent integrations everything they need in a single call — no N+1 lookups:

from runproof import WorkflowEngine

engine = WorkflowEngine("my-repo")
step = engine.next_step("harden-login-rate-limit")

# EngineStep(
#   phase=WorkflowPhase.TASK,
#   next_action="Complete tasks.md, close all task checkboxes, and set status to ready.",
#   suggested_command="runproof transition harden-login-rate-limit task",
#   allowed_commands=[],
#   blocking_findings=[],
# )

# Agent-driven loop:
while not step.is_complete and not step.is_blocked:
    agent_do_work(step.next_action)
    run_command(step.suggested_command)
    step = engine.next_step("harden-login-rate-limit")

engine.guard(change_id, "archive") checks the phase gate only. engine.execute(change_id, "archive") checks the gate and executes. engine.allowed_commands(change_id) returns the gated commands that would pass right now.

---

Hard Enforcement

RunProof can enforce governance at git/CI boundaries:

runproof guard --root my-app --require-active-change --strict-state
runproof guard --root my-app --require-execution-evidence
runproof install-hooks --root my-app

guard fails when:

• the repository foundation is invalid
• a workflow is blocked
• an archived delta was not synced into living specs
• the policy requires an active .runproof/changes/* record and none exists
• strict state finds stale artifact checksums
• execution evidence is required but missing

install-hooks writes a pre-commit hook that runs:

runproof guard --require-active-change --strict-state

That makes ungoverned commits fail locally. CI can run the same guard command server-side.

---

Reference

Command Guide

runproof version
runproof demo
runproof init --root <path>
runproof validate --root <path>
runproof status --root <path>
runproof new <change-id> --profile <profile> --title "Human intent" --root <path>
runproof run <change-id> --profile <profile> --title "Human intent" --root <path>
runproof transition <change-id> <phase> --root <path>
runproof verify <change-id> --command "pytest -q" --root <path>
runproof guard --require-active-change --strict-state --root <path>
runproof install-hooks --root <path>
runproof check <change-id> --root <path>
runproof sync-specs <change-id> --root <path>
runproof archive <change-id> --root <path>
runproof phase <change-id> --root <path>
runproof log <change-id> --root <path>

Add --trace to any command for component-level diagnostic output:

runproof --trace transition my-change specify --root .
# [TRACE] REGISTRY     → transition my-change → specify
# [TRACE] REGISTRY     → require_phase my-change expected=propose
# [TRACE] INFERENCE    → workflow_state my-change

---

Current Status

Current release: v0.28.1

Production-ready:

• contract-tested modular architecture
• execution-verified workflows with checksummed evidence
• strict guard enforcement for CI and git hooks
• --trace mode for component-level debugging
• Golden Path demo and CLI tooling

---

Influences And Attribution

RunProof is original work, informed by MIT-licensed workflow ideas from:

• GitHub Spec Kit
• OpenSpec
• Agent Teams Lite
• BMAD-METHOD

Attribution and compatibility notes are in NOTICE.md.

License

RunProof is released under the MIT License.