ApprovalPack

Decision-ready approval packets for agent work.

Turn scattered agent run artifacts into compact, evidence-backed approval packets that a human can review in 2 minutes instead of 20.

Quick Start

pip install -e ".[dev]"

# Scaffold a starter spec
approvalpack init --title "Approve auth migration" --id auth-merge-checkpoint --out spec.yaml

# Validate it
approvalpack lint examples/specs/auth-checkpoint.yaml

# Build a packet from a passing bundle
approvalpack build examples/specs/auth-checkpoint.yaml examples/bundles/auth-good --out packets/auth-good

# Record a decision
approvalpack decide packets/auth-good/packet.json --decision approved --reviewer "Jane Doe" --note "Schema unchanged; safe to merge."

# Build a packet from a failing bundle
approvalpack build examples/specs/auth-checkpoint.yaml examples/bundles/auth-blocked --out packets/auth-blocked

Why

Agents generate long, scattered artifacts — traces, diffs, test outputs, logs, JSON summaries. When a senior engineer needs to approve a checkpoint, they have to reconstruct what happened from raw files.

ApprovalPack does the reconstruction for you:

• Indexes the evidence bundle
• Runs deterministic approval gates
• Maps claims to evidence
• Surfaces what the reviewer still must decide
• Emits a compact packet: JSON for machines, markdown for humans

Mental Model

Approval Spec (YAML)  +  Evidence Bundle (directory)
                      ↓
              approvalpack build
                      ↓
            Approval Packet (JSON + MD)
                      ↓
              Human reviews packet
                      ↓
              approvalpack decide
                      ↓
            Decision Record (JSON)

Five concepts:

1. ApprovalSpec — the committed source of truth for one checkpoint
2. EvidenceBundle — a directory of artifacts from an agent run
3. GateResult — the result of one deterministic check
4. ApprovalPacket — the generated review document (the product)
5. DecisionRecord — a human decision attached to a packet

Status Model

Packet status:

• review_ready — required evidence present, all blocker gates passed
• blocked — missing evidence or failed blocker gates

Decision values:

• approved
• rejected
• needs_info

Example Spec

version: "0.1"
id: auth-merge-checkpoint
title: Approve auth migration checkpoint
audience: senior_ic
goal: Decide whether this run is safe to merge.

required_evidence:
  - id: junit
    kind: file
    path: artifacts/junit.xml
  - id: schema
    kind: file
    path: artifacts/schema_diff.json

gates:
  - name: tests-green
    type: junit_no_failures
    file: artifacts/junit.xml
    blocker: true
  - name: schema-unchanged
    type: json_equals
    file: artifacts/schema_diff.json
    field: changed
    value: false
    blocker: true

claims:
  - name: tests-passed
    statement: Required auth tests passed.
    evidence_refs: [junit]
    gate_refs: [tests-green]

questions:
  - name: compatibility-review
    prompt: Do the changed auth behaviors remain acceptable?
    evidence_refs: [schema]

Gate Types (v0.1)

Type	What it checks
exists	File is present in bundle
json_equals	JSON field equals expected value
json_lte	JSON field is ≤ threshold
text_contains	File contains pattern
text_not_contains	File does not contain pattern
junit_no_failures	JUnit XML has zero failures/errors
trace_event_present	JSONL trace contains event type

Review-Ready vs Blocked

Review-ready (auth-good bundle):

• All evidence present
• Tests green, schema unchanged, no critical warnings
• Reviewer still asked: "Are the behavior changes acceptable for existing clients?"

Blocked (auth-blocked bundle):

• 3 test failures, schema changed, critical warning in summary
• Packet status: blocked
• Cannot approve until blockers are resolved

This contrast is the core product: ApprovalPack narrows human judgment instead of replacing it.

What ApprovalPack Is Not

• Not a tracing dashboard
• Not an eval platform
• Not a workflow runtime
• Not an auto-approval engine

It does one thing: make human approval fast, legible, and auditable.

Intentionally Not Built Yet

• Hosted service or dashboard
• Live vendor integrations (LangSmith, OpenAI, Anthropic)
• LLM summarization or semantic grading
• GitHub App / sticky PR comments
• Signed approvals or workflow callbacks
• HTML rendering

Roadmap

• Vendor-specific bundle importers
• Richer evidence parsers
• HTML packet rendering
• GitHub PR check-run integration
• Policy presets for common checkpoints
• Semantic assistance for summary/question drafting

Development

pip install -e ".[dev]"
pytest
approvalpack --help

License

MIT