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.
What a receipt is
When an agent changes project files, in the AI chat or through an MCP write tool, Penstock records:
- what changed: each file with a SHA-256 before and after, and the diff in the diagram's own terms;
- the Check result before and after, with the new findings called out by rule and element id;
- the scenarios run on the changed diagram, against the previous run;
- whether auto layout was applied;
- the connections and secrets findings the change introduced;
- a verdict: verified, has new findings, or not verified with the reason.
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.
| Part | Plan |
|---|---|
| The verdict and the counts for every change | Free |
The full receipt, stored receipts, --write | Pro, Team in a pipeline |
| Auto-repair | Pro |
check --require-receipt | Pro 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/
attempts | How many times the agent is handed the new errors. 3 by default, 0 turns it off. |
keepReceipts | Write each receipt to .penstock/receipts. Off by default. |
requireReceipt | In a pipeline, penstock check fails when a change made by an agent has no matching valid receipt. The same as --require-receipt. |
agentPaths | Folders 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. |
agents | The 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
receipt verify <file...>makes a receipt without an agent: the files that changed against a git ref (HEADunless--against).--writekeeps it in.penstock/receipts. Exit 0 when the change is verified, 1 when it has new findings or could not be verified.receipt check <receipt.json>confirms that the stored hashes still match the files. It does not run the check again. Exit 1 when a file changed, is missing or should not exist.penstock check --require-receiptfails when a change made by an agent has no matching valid receipt.
What a receipt never runs on its own
A receipt never runs what an agent wrote without a person's say.
- The saved scenarios of a change run only on an engine marked
deployment.forTests. - They do not run when the change adds or changes content that runs (a script, a listener, an expression, a service call), or touches
penstock.yamlor the test files. The receipt then says scenarios not run and is not fully verified.penstock receipt verify --run-scenariosruns them on request. - Anything Penstock could not fully inspect (too many files, a file too large or unreadable, a changed decision, form, template or case that a run would deploy) holds the scenarios back the same way, and limits the check to the built-in rules.
- An MCP write runs the scenarios only with
scenarios: true. - The check in a receipt uses the built-in rules only when the change touches the lint configuration, a rules folder, a plugin,
penstock.yamlorpackage.json, or when the project is not trusted (penstock trust). The receipt says so.
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 runpenstock receipt verify --run-scenariosif 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 withpenstock receipt verify.