Skip to content

Plan Auditor documentation

Plan Auditor turns "the agent says it is done" into a checkable fact. A step is verified only when a deterministic check, executed in a fresh subprocess by a separate process, actually passed — and the result is appended to a hash-chained evidence log that later audits re-verify.

Nothing on this site requires an LLM, a GPU, or a network connection.

Start here

If you want to… Read
See a verified task end to end in five minutes Quick start
Look up a command or exit code CLI reference
Understand the supervision layers Architecture
Understand step DAGs and requirement coverage Dependency graph
Understand what is and is not provable Formal planning
Know the limits before relying on it Threat model
Isolate against a deliberately hostile agent Deployment isolation
Wire it into a host or CI Integrations
Run the shipped example end to end examples/fib/ in the repository
Know what the tool writes into your repository Workspace artifacts
Know what is published where, and what is attested Release status
Know what can actually be measured here What is measurable
Contribute a check type or fix a doc Contributing guide

Release status, stated once

2.6.3 is the current release on both PyPI and npm, and this site describes that release. PyPI artifacts carry PEP 740 provenance; npm tarballs carry Sigstore SLSA provenance through the trusted publisher. 2.4.0 and 2.4.1 were defective and cannot be withdrawn, because npm versions are immutable; see the README's release-status section for what each one shipped.

A 2.4.2 wheel ships the Python packages supervisor and scripts, and additionally ships the Agent Skill assets (SKILL.md, references/, hooks/ and the Node launcher) namespaced under plan_auditor_skill/; scripts/ stays a top-level Python package. It does not ship docs/ or examples/. CI asserts that every wheel it builds contains the runtime files and the skill assets, via .github/scripts/check_dist_assets.py.

The five rules

  1. No deterministic evidence, no completion. Every step needs at least one run, pytest, or exec check.
  2. Requirements are host-owned. The request contract is sealed before work starts; the agent cannot rewrite what you asked for.
  3. Evidence is append-only and hash-chained, and evidence that claims completion must be HMAC-authenticated. plan-auditor evidence verify re-checks the chain, including rotated archives. A chain without a configured HMAC key is tamper-evidence only — it can be rebuilt identically by anyone with write access — so the gate refuses to treat it as proof. Set PLAN_AUDITOR_HMAC_KEY (or PLAN_AUDITOR_HMAC_KEY_FILE, outside the workspace) and run plan-auditor integrity init . before the audit you intend to claim.
  4. Sealed criteria only tighten. Post-approval, criteria may be added but never removed or weakened.
  5. Unprovable is a failure, not a pass. Unknown resolves to FAIL or UNKNOWN, never to success.

Concepts in one paragraph each

Request contract — A JSON document you write that states the task and its requirements with deterministic acceptance checks. Activating it computes a digest; the supervisor refuses to pass a plan whose requirements drifted from it.

Plan — .plan-auditor/plan.json (plus any .plan-auditor/plans/<name>.json). Requirements, steps, covers bindings, dependencies, named outputs, and verify checks. Every active plan must pass; a passing default plan cannot hide an unfinished named plan.

Seal — A hash over the full verification contract: requirements, coverage, the dependency DAG, output contracts, every check, and the supervisor profile/mode/policy fingerprint. plan verify creates it; later audits detect any attempt to weaken it.

Evidence — An append-only JSONL log where every record carries the SHA-256 of the previous one. Tampering with a past record breaks the chain. Without a configured HMAC key every record carries "auth": {"alg": "none"}, the chain still verifies, and it is still not authentication: the completion gate requires an authenticated chain because a keyless one is rebuildable by anyone with write access to the workspace.

Fresh full audit — plan-auditor audit re-runs every check in a new subprocess while the workspace is frozen, and fails if the workspace changed during the run. It is the only command whose exit code 0 means "complete".

The 30-second mental model

you (host)                agent                    supervisor (separate process)
    |                        |                              |
    |-- request-source.json ->|                              |
    |-- plan.json ----------->|-- implements step ----------->|
    |                        |-- "done!" ---------> run checks in fresh subprocess
    |                        |                              |--> append hashed evidence
    |                        |<-- non-zero until proven -----|
    |                        |                              |
    |<---------------- audit . (exit 0) --------------------|

Scope and non-goals

Plan Auditor is not an OS sandbox and does not claim kernel isolation; in a default install the agent and the verifier run as the same OS user. It is tamper-evident, not tamper-proof. See Threat model and Deployment isolation for the boundary and for what to change when the agent is assumed hostile.