--- title: "Proof-Carrying Workflows: knowing what was checked, and what needs checking again." url: "https://lindemann.design/work/proof-carrying-workflows/" description: "A workflow system for reviewing AI-assisted development: agreed scope, recorded evidence and checks that stay tied to the code they cover." --- # Proof-Carrying Workflows: knowing what was checked, _and what needs checking again._ An AI agent can finish a task without leaving a clear record of what it changed or checked. We are building Proof-Carrying Workflows to make that work easier to review. It connects the agreed scope, the changes and the evidence to a specific version of the code, then flags affected results when that code changes. In use - the flow ```text ┌ baseline git:8f4c2a1 │ the repository before the work │ ◇ authorization recorded outside PCW, before the work │ who may change what, bound to the baseline │ ◇ change set declared paths + evidence │ under an evidence contract; claims bound to the snapshot │ ◇ result git:b73d901 │ the repository after the work │ ◆ kernel one deterministic decision │ read-only, no dependencies; approval stays outside │ ├─ within authority structurally valid, claims current ├─ rejected change exceeds authority └─ invalidated a declared dependency changed technical outcomes; whether an audit or a release is complete is a separate, later decision ``` From agreed scope to a result someone else can verify. - pilot · claim invalidation ```text ◇ evidence run runner-owned container │ composer ci passed │ composer ci:full passed ◇ technical claim ci:full, retained, bound to snapshot │ declares dependency plugin-base ◆ later change plugin-base, in a disposable clone, verified │ matches dependency yes │ dependent claim invalidated technical pilot, not workflow adoption ``` A shared-code change makes an earlier result stale. - kernel · repository state ```text { "version": "1", "baselineSnapshot": "git:8f4c2a1", "resultSnapshot": "git:b73d901" } // four versioned JSON objects in, one decision out. // the kernel accepts data; it never acquires authority or facts. ``` A record of the code before and after the work. - .pcw/installation.json ```text { "format": "proof-carrying-workflows.installation", "version": "1", "source": { "kind": "workspace-checkout", "path": "workflows" }, "catalog": { "pathBase": "source-root", "path": "specifications/catalog.json" }, "profile": { "id": "craft-plugin", "package": "@proof-carrying-workflows/craft-plugin-profile", "adoptionPath": ".pcw/craft-plugin-adoption.json" } } ``` The proposed installation for the first adopter. - Adoption readiness ```text { "adoption": { "owner": "adopter", "authorityScope": "cross-workflow-pre-activation-work-queue", "grantsAuthority": false, "mayWriteLifecycleRecords": false, "mayActivate": false }, "target": { "installation": { "digest": "sha256:78959b81c3ef1674f687b20f4f1d659029f57b92cbea81bcfc32b66affb76802" }, "profile": { "digest": "sha256:7c4ec90d4b1715e4ede2e32483de623762ddf363c9a7553ac7863b042f729b3d" } }, "phase": { "adoption": "parked", "activation": "pre-activation" } } ``` A readiness record showing adoption is still pending. - Release adoption ```text { "id": "check-or-prepare-package", "phrases": [ "release prep", "start release", "validate release", "check compatibility", "prepare for release" ], "classificationRequired": true, "defaultMode": "package-release-preparation" } // what a person says, mapped to a workflow route. // classification first; the mode is chosen after. ``` Everyday requests mapped to the release workflow. - agent and CI surfaces ```text Portable Agent Skill repository-local destination Codex .codex/skills/proof-carrying-workflows/ Claude Code .claude/skills/proof-carrying-workflows/ installs nothing, grants nothing: it makes the pcw contract discoverable it does not let an agent mutate a run Offline CI verification .github/workflows/verify-existing-run.yml runs only pcw run verify --store --run no installs, no run start, no candidate commands, no provider, no keys ``` The same verification approach for agents and CI. Role Design, architecture and engineering Stack - Node 22, ESM - Git, Docker - Dependency-free kernel Status In development, public release planned Since 2026 to present 1. **Scope** check changes against what was agreed 2. **Evidence** keep results tied to the code that was checked 3. **Recheck** identify results affected by later changes The problem ## A finished task still leaves questions. This started with work on our plugin family. After an audit, translation review or release check, we needed to know which version had been checked, what the agent was allowed to change and where the results were recorded. A confident summary could leave those questions unanswered. We wanted a record that another person or an automated check could verify, including whether later changes had made an earlier result out of date. How it works ## Keep the agreement, the change and the evidence together. Each task starts with an agreed scope and a record of the code before the work. The submitted result identifies what changed and supplies evidence for the checks performed. A small verification core compares those records. It can reject changes outside the agreed scope or evidence that belongs to a different version. Results also declare which files or shared components they depend on. If a verified change touches one of those dependencies, the result becomes stale and needs checking again. PCW applies this approach to audits, documentation, localisation and releases. PCW commands ```bash pcw profile validate --profile pcw run start --profile --workflow --target --authority --store pcw run begin --store --run --implementer pcw run submit --store --run --implementer --result pcw run validate --store --run --validator --decision valid|invalid --report pcw run verify --store --run ``` Run records sit outside the project being checked. The command-line tool also requires different declared identifiers for the implementer and validator. The team adopting the system remains responsible for verifying who those people or agents are. Review and approval ## Evidence supports a decision. Someone still owns it. PCW verifies submitted work. It can refuse to certify a result, but it does not intercept every file edit or tool action. A team that needs to prevent unauthorised operations must provide those controls separately. Passing a technical check does not approve a release or close an audit. Those decisions stay with the people and workflow responsible for them. Developers, agents and CI can use the same records without being given that authority. Where it stands ## The mechanism works in a pilot. Adoption comes next. In a technical pilot, the real Redirect Manager checks ran in containers managed by PCW. The system retained the successful result. A later change to the shared base plugin, made in a disposable copy, correctly marked the dependent result as stale. PCW includes Git state capture, evidence collection, stored run verification, a Craft plugin profile and an initial agent integration. The plugin family is the planned first adopter; its everyday workflows have not switched to PCW yet. We are testing PCW locally and preparing it for public release. The next step is to complete the plugin migration and verify those workflows before the standalone release. Licensing, distribution and broader agent support are still being worked through. Designing the system ## One approach that can travel between projects. The verification core is independent of an AI vendor or a particular repository. Project profiles describe the files, checks and workflow rules for each adopter. Craft plugins are the first profile; other project types are planned. The design keeps the recorded facts, technical verification and approval decisions separate. That makes it easier for a reviewer to understand what a result establishes and what still needs their judgement.