Review and acceptance

Review is the human bottleneck in the collaboration. That is intentional: implementation is fast, understanding is not.

mdBoard reviews the batch as a whole at handover. It does not ask you to approve every task.

The handover

A batch enters handover when:

• all tasks are done;
• no task is in error;
• the agent has a report draft.

The agent opens a handover review meeting and asks the reviewers to look at the batch. The batch does not move to completed automatically.

What you review

Review the intent and the outcome, not the agent’s keystrokes:

• Does the batch match the accepted idea and the acceptance criteria?
• Are the tests and evidence sufficient?
• Are the risks and out-of-scope items explicit?
• Is the report understandable without reading every commit?
• Is the cost estimate consistent with what was delivered?
• Are docs and changelog updated?

The agent can show the task list, commits, tests and report draft on request.

The review artifact

Each reviewer writes or dictates a review artifact for the round:

id: RV-0007-01-01
batch: "#0007"
round: 1
reviewer: reviewer
authored_by: reviewer
transcribed_by: agent
verdict: changes-required
findings:
  - id: F1
    text: "The stream closes before the final row."
created_at: 2026-10-24T15:00:00Z

• authored_by is the human whose verdict it is.
• transcribed_by is set when the agent writes down a chat review.
• The provenance is part of the record. The agent does not silently impersonate a reviewer.

If review independence matters more than convenience, write the artifact yourself in the HTML board instead of dictating it in chat.

Multiple reviewers

Reviewers can work in parallel. Each artifact is independent. This is the only place where mdBoard deliberately supports parallelism: human review is the bottleneck, so add reviewers, not feature branches.

The owner makes the final acceptance decision. If any reviewer requests changes, the owner either:

• requests changes, returning the batch to doing; or
• records an explicit override reason in the event.

Request changes

Human: I reviewed #0007. The stream closes before the final row.
       Request changes and create a rework task.

Agent: I recorded a changes-required artifact from you, returned
          #0007 to doing, and created #0007-04 from finding F1.
          The other tasks are still done.

The batch goes handover → doing. Rework is a new task linked to the review artifact. done tasks are not reopened; the history stays clean.

When the rework is done, the batch enters handover again with a new review round.

Accept

Human: I accept #0007. Complete it.

Agent: I recorded your owner accept, wrote the final report,
          appended the changelog entry, and closed #0007 as completed.

Completion requires:

• at least one independent review artifact;
• the owner’s accept;
• the report at .mdboard/reports/R0007.md;
• the changelog bullet in the root CHANGELOG.md.

One-human projects

If there is only one human, the owner may self-review with an explicit override reason. The event records it. This is a pragmatic alpha rule, not a claim of independent review.

What happens after completion

completed is final. If the batch turns out to be wrong or incomplete:

• start a new spark for the follow-up;
• do not reopen a completed batch.

A defect in released code is new intent, not a quiet edit to history.

Review checklist

Use this in the handover review:

Next

• Meetings
• Reports and changelog
• Roles and authority