Engineering guide

When an agent silently breaks a requirement

A plausible patch can satisfy the latest request while breaking an older promise. The missing safeguard is often a persistent requirement and evidence chain that survives the agent's current task.

Start with the promise that must survive

Suppose an agent is asked to simplify payment retries. It removes a stored idempotency key because local tests still pass. The patch may be tidy while violating the approved rule that repeating a transaction must never create a second charge.

Illustrative case. The task is “simplify retry handling.” The governing requirement is “a repeated transaction ID produces at most one charge.” The review question is whether the new implementation preserves that promise under timeout, retry, and concurrent delivery.

Keep the requirement, its rationale, assumptions, and authority outside the transient task conversation. If the repository lacks a reliable specification, recover candidate intent from contracts, examples, tests, history, and observed failures. Existing behavior is evidence to examine, not automatic permission to preserve every accident.

Make the change's reach inspectable

Connect the approved requirement to its implementing functions, interface contracts, and verification cases. Trace impact can expose recorded dependents, but it cannot discover every unrecorded runtime interaction. Review relevant callers, configuration, and shared state alongside the graph.

proof review req SYS-REQ-042 --gate
proof review req SYS-REQ-042 --gate --run

The first command plans the requirement-focused gate. The second can execute affected tests and focused audit checks. A focused result helps iteration; use the full gate before treating it as final change evidence.

Test the old guarantee against the new implementation

For the retry example, use a test that submits the same transaction again after an ambiguous timeout and checks the resulting charge count. Include concurrent retries if they are in the operating scope. Preserve a reproducer if a defect is found, then verify that the repair changes the incorrect result while keeping valid behavior.

An annotation says which promise a test claims to examine. A passing run records an observation for particular code and inputs. Neither alone proves the requirement covers every important case. A model counterexample also needs investigation before it is called a product defect.

Prevent quiet changes to the acceptance bar

Review requirement edits, deleted tests, weakened assertions, narrowed scope, and new suppressions as part of the same change. Agents may author, recover, verify, and approve within applicable delegation policy; the implementation task itself must not silently grant authority to weaken approved intent.

proof review req SYS-REQ-042 --gate --run --full

A repository blocks merging only when its CI and branch policy require the applicable result for the candidate revision. Proof's default audit threshold is warn unless configured otherwise. The command does not configure merge protection by itself.

Continue from here

Review code impacts against intent. Build a requirement-aware CI gate.

Bring an agent-generated patch and one older requirement it must preserve. Bring a change to Proof.