mdBoardReports and changelog
A completed batch leaves two human-readable artifacts: a report and a dated changelog entry.
The report
When a batch is completed, the agent writes .mdboard/reports/R0007.md. It contains:
- the accepted intent and scope;
- the task list and each task’s commit;
- the review rounds and artifacts;
- tests and evidence;
- residual risks and out-of-scope items;
- the estimated cost;
- links to the batch, tasks and reviews.
The report is the first thing to read when you want to understand a completed batch without replaying the whole conversation.
The changelog
The root CHANGELOG.md gets one bullet per completed batch, grouped by date:
## 2026-10-24
- CSV export for the report table ([#0007 report](.mdboard/reports/R0007.md))
- Owner-only usage summary ([#0008 report](.mdboard/reports/R0008.md))
Rules:
- one date heading per day;
- one bullet per completed batch;
- the bullet ends with a report link;
- canceled batches do not add a changelog entry.
The agent appends to an existing date section rather than creating a duplicate.
How to ask for a report
Human: Summarize #0007 for me.
Agent: #0007 delivered owner-only CSV export for the report table.
Three tasks, one review round, one rework task, all done.
Tests: API and filter coverage. Risk: the stream boundary is
fixed at 1,000 rows. Estimated cost: €0.0027.
Full report: .mdboard/reports/R0007.md.
The summary should be understandable without opening the code.
Reports are evidence, not marketing
A report is written for the next maintainer, not for a release page. It should state what changed, what did not, and what a reviewer should know. If the batch left a known limitation, the report says so.
Event history
The report is a narrative. The event journal is the audit trail:
- every state transition;
- who executed it;
- who authorised it;
- the reason;
- the commit.
The agent uses the event journal when a conflict or an ambiguous card state needs reconstruction.
Release notes and conflict reports
A successful owner release writes .mdboard/releases/v<version>.md on stable, commits it, and tags the release. It lists the nightly/stable commits and the completed batches with their reports.
A failed merge writes .mdboard/reports/conflict-<timestamp>.md. The merge is aborted, the working tree is left clean, and a human decides the resolution; the agent never picks a side automatically.
No separate report indexes
The report and changelog are the two durable outcomes. If you want a retrospective, make it a new spark.