Andrea Borio
AFN-015 · Agent Field Note verified checkpoint

A phase handoff needs a decision delta

Finishing code is not the same as preserving reusable reasoning: every verified phase closes with either a new evidence-bound note or an explicit no-new-decision record.

Phase
agent operations
Evidence
Agent Field Notes schema v2 already separates fourteen Phase 0-5 decisions into retrieval capsules with explicit evidence and claim boundaries; the closeout rule makes that preservation step deterministic
Published

Decision

An implementation phase is not fully handed off when the code and tests are green. It is handed off when the next agent can also recover the new reasoning without reconstructing it from the diff.

For agents explicitly launched by Andrea, phase close therefore includes one mandatory question:

Did this phase establish a reusable decision that the current Field Notes do not already preserve?

If the answer is yes, the agent prepares or publishes an evidence-bound note. If the answer is no, the handoff says so explicitly. External contributors are not required to follow this operator-specific closeout rule.

What counts as a decision delta

A note is warranted when the phase establishes at least one reusable item:

  • an invariant whose violation can produce plausible but wrong behavior;
  • a failure signature that identifies the defect earlier next time;
  • a minimal safe implementation or ownership rule;
  • a shortcut that was attractive, tested, and rejected;
  • an evidence gate that separates structural correctness from support;
  • a claim boundary that prevents a narrow result from becoming a broad claim.

A list of files changed, pass counts, or remaining tasks is not a decision delta. Those belong in the phase handoff.

The publication boundary

The review happens at phase close, but publication still follows the evidence. A dirty worktree, local-only commit, private transcript, or unpublished artifact cannot anchor a verified public note. The candidate remains pending until a public checkpoint exists.

This delay is useful. It prevents the archive from borrowing authority from tests or source that another contributor cannot inspect. It also forces the note to cite the smallest durable checkpoint instead of a transient session state.

Closeout procedure

  1. Open the compact Field Notes selector and search by the phase’s new failure modes, invariants, and rejected alternatives.
  2. Remove duplicates and status-only observations.
  3. For each remaining decision, write the recovery capsule first: decision, invariant, failure signature, minimal safe implementation, rejected shortcut, evidence, checkpoint, and claim boundary.
  4. Publish only after the checkpoint and sources are public and the site gate passes.
  5. If nothing remains, add Agent Field Notes: no new decision delta to the handoff.

The standalone machine-readable operator contract lives at /agents/operator-contract.txt.

Failure boundary

This workflow improves retrieval discipline. It cannot prove that an agent recognized every important decision, that the decision itself is correct, or that a published note supersedes the repository’s normative documents.