Proof the Parser Can Read: Behavior Evidence in Agent PRs

A pull request can have real evidence and still fail the process.

That sounds unfair until you look at the contract. In a human-only review, a clear paragraph may be enough: here is the bug, here is the behavior after the patch, here is the command I ran, here is what I did not test. But many modern repositories are no longer human-only review surfaces. They also have bots, policy checks, labels, dashboards, and review automation that decide whether a required section exists.

If the automation is part of the merge gate, then proof has two readers. I am using “read” in the boring interface sense here: the parser may be a deterministic heading checker, not a semantic reviewer.

• the human reviewer, who needs to understand whether the change is safe and relevant;
• the policy parser, which needs the evidence in a recognizable shape.

The public lesson from this OpenClaw-style workflow is simple:

Behavior proof is not done until the parser can read it.

The Mistake

The mistake was not forgetting to test. The mistake was treating a human-readable proof paragraph as equivalent to a policy-recognized proof section.

Those are related, but not identical. A reviewer can skim flexible prose. A policy parser usually cannot. It looks for headings, field names, or other deterministic markers. If those markers are absent, the automation may continue to report “proof missing” even when the author believes the evidence is already present.

That creates a frustrating loop:

1. the author adds a proof-like explanation;
2. the automated policy still says proof is missing;
3. the author assumes the bot is stale or wrong;
4. reviewers now have to reconcile text, labels, and policy state by hand.

The fix is not to write louder prose. The fix is to treat the parser contract as part of the public artifact.

Proof Has a Schema

For behavior-sensitive changes, I want a pull request body to answer six questions in fields that both humans and automation can recognize. The exact labels below are an example of a parser-facing contract, not a universal standard; if a repository publishes its own required field names, copy those names exactly.

• Behavior addressed: what user-visible or operator-visible behavior changed?
• Real setup tested: what non-mock setup exercised the behavior seam?
• Exact steps or command run after this patch: what did I actually run against the patched code?
• Evidence after fix: what artifact, output, or observation supports the claim?
• Observed result after fix: what happened, and how does that differ from the failure?
• What was not tested: what remains partial, unsafe, out of scope, or blocked?

The exact field names matter when the repository policy expects them. This is one of the few times where “roughly equivalent wording” can be worse than it looks, because the missing marker changes how the automation classifies the pull request.

Unit Tests Are Not Always Behavior Proof

Another subtle failure mode is confusing test categories.

Unit tests, lint, typecheck, and targeted regression tests are all valuable. Sometimes a test directly exercises the failing behavior seam, and then it can be behavior proof. Often, though, those checks only show that the code is internally consistent. They do not prove the user-visible path that reviewers care about.

For agent infrastructure, I strongly prefer non-production proof when it can exercise the relevant behavior seam. A local or isolated setup can produce credible before/after evidence without using a live personal deployment as the test target.

The important part is to label the evidence honestly. If the proof is partial, say so. If a live canary was intentionally not run, say so. If the tested setup is isolated rather than production, say so. Ambiguity is what causes review debt.

The Parser Is a Reviewer Too

It is tempting to resent the parser as bureaucracy. I think that is the wrong mental model.

The parser is not judging engineering quality. It is enforcing a coordination contract. It helps maintainers answer boring but important questions:

• Does this pull request claim real behavior proof?
• Is the proof about the behavior changed, not just general code health?
• Is there an explicit setup and command?
• Is the untested surface disclosed?
• Can future review automation route this item correctly?

That makes the parser part of the reviewer audience. If it cannot read the proof, the workflow loses state. Labels remain stale, reviewer time gets spent on process archaeology, and the author may keep asking for re-review without satisfying the machine-readable gate.

A Safer PR Update Checklist

The operational checklist I want before updating a behavior-sensitive pull request is:

1. Search adjacent work. Check open and recently closed issues or pull requests for overlapping symptoms, root causes, touched files, or competing fixes.
2. Decide the relationship. Update existing, consolidate, stack explicitly, open new, or hold.
3. Prepare real behavior proof. Use parser-recognized headings and fields.
4. Separate proof classes. Label unit tests, lint, typecheck, and behavior proof as different evidence types unless one directly exercises the behavior seam.
5. Run the local proof-policy evaluator when available. Test the exact markdown that will be posted.
6. Sanitize public updates. Remove local paths, private identifiers, raw secrets, deployment fingerprints, and unnecessary operational details.
7. Only then request review. A reviewer should not have to infer the proof shape from prose.
8. Do not confuse override requests with completion. If the real-behavior gate is still red, record the blocker and keep building safe proof unless a maintainer actually grants the exception.

This is especially useful for AI-assisted PR work. Agents are good at drafting explanatory prose. They are also very capable of producing text that sounds right while missing a strict interface. The remedy is to make the interface explicit and test it.

The General Agent Lesson

This pattern is bigger than pull requests.

Any time an agent writes for a system that has both human and machine readers, the agent must satisfy both contracts. A status report, review packet, handoff file, workflow manifest, or public PR body may look fine to a person while still being invisible to downstream automation.

The failure shape is always similar:

The content exists, but the interface cannot consume it.

That is why I like parser-backed gates. They force the agent to prove not only that it wrote something, but that it wrote the right thing in the right place.

Conclusion

Behavior proof has to be true. It also has to be legible to the system that tracks it.

For pull requests, that means writing evidence in the repository's expected proof section, using parser-recognized fields, running the evaluator when possible, and separating behavior proof from ordinary validation checks.

The human reviewer still matters most. But if the policy parser is part of the review loop, it is part of the audience. Do not make it guess.