Penstock

Guide / Draw and edit

AI receipt and auto-repair

Whenever an agent changes your files, Penstock records what changed, what the check says before and after, what the scenarios say, and gives a verdict. When the change brings new errors, Pro hands them back to the agent to fix.

Free A free preview of the verdict and the counts is shown for every change. The full receipt, auto-repair and stored receipts are Pro. The pipeline gate is Team in a pipeline.

What a receipt is

When an agent changes project files, in the AI chat or through an MCP write tool, Penstock records:

A receipt holds names, hashes and ids. It never holds file contents or secret values. Its format is published as penstock-receipt.schema.json.

The chat shows the receipt as a card under the answer, for example Verified: 0 new problems, 3 scenarios pass, with chips. The Chat tab shows the full receipt. MCP tool results carry it in a receipt field. A free preview, the verdict and the counts, is shown for every change.

PartPlan
The verdict and the counts for every changeFree
The full receipt, stored receipts, --writePro, Team in a pipeline
Auto-repairPro
check --require-receiptPro on a developer machine, Team in a pipeline

Auto-repair

Pro

When a change introduces new Check errors, Penstock hands the findings back to the agent in the same chat turn, or in the tool result for MCP. It does this up to ai.verify.attempts times: 3 by default, 0 turns it off, at most 10. The receipt records each attempt.

Keeping receipts

A receipt is written to .penstock/receipts/<timestamp>-<name>.json only when ai.verify.keepReceipts is true, and then atomically. Nothing is written silently.

ai:
  verify:
    attempts: 3
    keepReceipts: true
    requireReceipt: false
    agentPaths:
      - generated/
attemptsHow many times the agent is handed the new errors. 3 by default, 0 turns it off.
keepReceiptsWrite each receipt to .penstock/receipts. Off by default.
requireReceiptIn a pipeline, penstock check fails when a change made by an agent has no matching valid receipt. The same as --require-receipt.
agentPathsFolders whose files count as made by an agent for the gate, besides commits with an Assisted-by trailer or a Co-authored-by trailer naming an agent.
agentsThe names that make a Co-authored-by trailer count as an agent.

ai.verify is in the configuration schema and in penstock doctor. See penstock.yaml.

From the command line

penstock receipt verify processes/order.bpmn --against origin/main
penstock receipt check .penstock/receipts/20261028T100000Z-order.json

What a receipt never runs on its own

A receipt never runs what an agent wrote without a person's say.

Common problems

The receipt says "scenarios not run".
The change adds content that runs, or the engine is not marked deployment.forTests. Read the change, then run penstock receipt verify --run-scenarios if you accept it.
No file appears in .penstock/receipts.
Set ai.verify.keepReceipts: true, or use --write. Both need Pro.
The pipeline fails on a missing receipt.
A commit with an agent trailer, or a file under agentPaths, has no matching valid receipt. Make one with penstock receipt verify.