The Completion Protocol

A task is not finished when the code works. It is finished when the work is recorded in a form the next agent can read. The Completion Protocol is the set of fields an agent populates before it moves a task to in_review.

What "done" requires

When an agent completes a task, it writes the full payload in one update:

• executionRecord is a short narrative of what was built: the approach, the key functions, the file paths. The next agent reads this instead of re-discovering the work. See Execution records.
• decisions is one line per technical choice, in the form choice plus why. These are the constraints a later task needs to respect.
• files lists every path the work touched. For a task that changed no repo files (research, a decision-only task, a Piyaz-only refinement), the agent passes an empty array on purpose, which is the positive answer to "what changed?", not a missing one.
• Evaluated acceptance criteria. The agent walks each criterion and marks it satisfied or not. It does not auto-check everything; an honest false is more useful than an optimistic true.
• A PR. If the work changed code, the agent opens a pull request, detecting the project's template and using the [<taskRef>] bracket form so Piyaz can track the PR's status. Research, decision-only, and Piyaz-only tasks skip the PR.

Every field appends; none overwrite. A destructive overwrite would lose prior work with no recovery.

The handoff, not the finish

Populating the payload moves a task to in_review, not to done. The agent's terminal write is in_review; the human operator finalizes in_review → done after the PR is approved. Agents never promote their own work. See Human in the loop.

A change that does not propagate did not happen

Recording the payload is half the protocol. The other half is propagation. After any status change, the agent (or orchestrator) checks the task's edges and its downstream dependents, then updates, adds, or retires edges so the graph reflects what actually shipped. Skip it once and the graph lies: tasks look ready that are not, blockers point at finished work, and the next session picks the wrong thing.