Proof-Carrying Change

Prove what an agent changed by binding intent, authorization, observed effects, architecture delta, and independent verification.

Writing code is not the same as proving the requested change is complete. Proof-Carrying Change (PCC) gives one source-changing task a durable record of why it started, what was allowed, what actually happened, how architecture changed, and what independent verification concluded.

The shortest useful loop

Start with an adopted project or workspace and a current Goal:

npx workspai goal "Improve retry behavior without breaking clients" --json
npx workspai change begin --json

change begin pins the active Goal, Workspace Model, Knowledge Graph, and live input generation. That lease prevents a later operation from silently proving a different system state.

Discover the same durable change from another terminal, IDE, or CI job:

npx workspai change list --json
npx workspai change status --change <change-id> --json

Directory order is not lifecycle truth. Consumers should use change list instead of guessing which .workspai/changes directory is current.

Prediction is guidance, not proof

An agent may describe the architecture effects it expects:

npx workspai change predict --change <change-id> --file prediction.json --json

Prediction is explicitly noncanonical and proof-ineligible. After execution, Workspai derives the actual Graph overlay from fresh evidence and reports matched, missing, and surprising operations. A confident prediction cannot verify itself.

Authorize and observe effects

A person grants only the effect classes needed for this change:

npx workspai change authorize --change <change-id> --effects filesystem,command --granted-by maintainer --json

The agent, extension, or CLI integration records each observed effect through a typed, idempotent receipt:

npx workspai change effect record --change <change-id> --file effect-receipt.json --json

Authorization is not evidence that an effect occurred. An observed effect is not evidence that the Goal passed. The Decisions ledger keeps those transitions separate and digest-linked.

Deleted artifacts use validated tombstones rather than references to files that no longer exist. If a deleted path later reappears, capsule validation fails. When aggregate and nested project labels point to the same contained physical file, Workspai reconciles that identity without demanding duplicate receipts.

Re-observe, verify, and seal

npx workspai change verify --change <change-id> --strict --json
npx workspai change capsule validate --change <change-id> --json
npx workspai change capsule export --change <change-id> --output .workspai/exports/<change-id>.json --json

Verification refreshes canonical architecture, derives the actual delta, checks effect coverage, and records Workspace Verify against the exact post-effect generation. Goals with additional release, security, or coverage criteria may also require an exact-generation domain receipt:

npx workspai change verification record --change <change-id> --file verification-receipt.json --json

A capsule can be open, blocked, verified, sealed, or aborted. A sealed capsule means the immutable Goal criteria have passing post-effect receipts. It does not upgrade unsupported external claims into truth.

Durable blockers and human decisions

A blocked change keeps its event history. A person can resume it into an allowed state with a recorded reason:

npx workspai change resume --change <change-id> --to authorized --reason "Add receipts for generated files" --json

Resume appends intent; it does not erase or fork history. Terminal transactions cannot accept later effects. Optimistic compare-and-append protects the ledger from concurrent writers.

What owns each claim

Claim	Authority
Intent, scope, and acceptance criteria	Goal Pack
Lifecycle, authorization, effects, and causal order	Decisions ledger
Architecture baseline and actual delta	Workspace Model and Knowledge Graph
Engineering verdict	Workspace Verify and domain verifiers
Portable assurance summary	Proof-Carrying Change capsule
Execution activity	Live activity plane, observational only

The capsule composes references to these owners. It does not replace them or copy prompts, responses, secrets, absolute paths, or unbounded command output.

Contract trail

The command catalog exposes every change operation from the synchronized runtime inventory.