mdBoard

Checks and guarantees

Checks are the mechanical part of the collaboration. They protect the human gates from being skipped by accident or convenience.

You usually ask the agent to run them; you do not need to run them yourself.

What mdBoard checks

Guarantee Why it matters
One open upstream iteration There is a single working truth.
One writer lease Two agents cannot race the same branch.
One active batch Implementation stays sequential.
One task working The agent is not doing hidden parallel work.
Roadmap limit The committed set stays reviewable.
Estimate before roadmap The roadmap total is meaningful.
All tasks done before handover Review sees a complete batch.
Independent review before completion The agent cannot self-approve.
Report and changelog on completion The outcome is explainable later.
No deletion; explicit terminal states History stays reconstructable.
Event journal append-only The audit trail is not rewritten.

The full invariant list is in Process model.

How the agent uses checks

Before a gated action, the agent checks the guard. Before a handover or merge, it runs the full board check:

Human: Is #0007 ready for handover?

Agent: Not yet. #0007-03 is still working. The batch must have all
          tasks done before handover. I will re-check when it is done.

If a check fails, the agent explains the finding and the legal options. It does not bypass the check.

What a human sees

Ask for a plain-language check:

Human: Check the board.

Agent: OK: one open iteration, one active batch, roadmap 3 of 5.
          No blocked batches, no error tasks.
          One pending meeting: handover review for #0008.
          The completed batch has a report and a changelog entry.

The JSON form is for automation; the agent should translate it for you.

Checks in CI

The agent or CI can run:

mdboard check --json
mdboard render --check

check validates the board and its invariants. render --check verifies that BOARD.md and ROADMAP.md are current. A red check stops the merge queue; it is not a suggestion.

::: info Alpha The 1.0 process check validates the board records and, with --git, the iteration, lease, current branch, dirty worktree and owner-only files (mdboard.toml, actors, roadmap override, LICENSE, NOTICE). :::

What checks do not do

  • They do not run your tests.
  • They do not prove that the code matches the intent; that is the human review.
  • They do not prove that a chat authorisation really happened.
  • They do not replace the branch protection on nightly and stable.
  • They do not validate third-party plugin execution; plugins are disabled in this alpha.

Human recovery

If a check blocks work, ask what the legal paths are:

Human: The check says “one active batch”. We need to start another.

Agent: Only one batch can be in breakdown or doing. We can finish the
          current batch, block it with a reason, or cancel it. We cannot
          start a second one.

The agent should never “make it pass” by editing a generated view or forcing a state. Fix the facts, then regenerate.

Next