Troubleshooting

Start with the collaboration, not the CLI. Most problems are a human gate, a board state or a agent that has lost the runbook.

Ask the agent for the board brief

Human: Give me the board brief and tell me what is blocking.

Agent: Upstream iteration 3 open. #0009 doing; #0009-02 working.
          #0008 handover review pending (you + reviewer).
          Roadmap 4 of 5. No blocked cards, no error tasks.
          One pending clarification for #0010.

If the brief is vague, ask for the specific card and the legal actions.

“I cannot start the next batch”

Only one batch can be in breakdown or doing. The agent should explain the active batch.

Human: Why can't we start #0010?

Agent: #0009 is still doing. mdBoard allows one active batch.
          We can finish #0009, block it with a reason, or cancel it.

Do not work around this by editing a card file or starting a second agent.

“The roadmap is full”

The default limit is 5 batches. The owner can:

remove a batch from the roadmap (unroadmap);
complete or cancel a batch;
create a temporary override with a reason and expiry.

Human: Raise the roadmap limit to 7 until Friday.

Agent: That is an owner-only override. I will record the reason and
          expiry. Do you confirm?

An expired override fails the check until it is renewed or cleared.

“The agent refuses to move the card”

That is usually correct. Ask what is legal:

Human: Move #0007 to completed.

Agent: Completion requires handover, an independent review and your
          accept. #0007 is in doing. The next legal move is handover when
          all tasks are done.

If the refusal is wrong, ask for the rule and the current state. Do not ask the agent to bypass it.

“The review is stuck”

The batch is in handover; it needs a human decision. Check:

is there at least one independent review artifact?
did a reviewer request changes?
is the owner accept recorded?
is the report draft missing?

Human: Why is #0008 still in handover?

Agent: One review artifact is accepted. A second reviewer has not
          submitted yet. The owner accept is also missing.

“A task is in error”

error is a task-level failure. The human decides:

recover the task to pending;
cancel the task;
block the batch if the failure needs a broader decision.

Agent: #0009-02 failed: the test fixture is missing.
          I recommend recover to pending after you provide the fixture.

“A batch is blocked”

blocked means waiting on a human or external decision. The agent should name the return state and the reason.

Human: The credential is available now.

Agent: I unblocked #0009 back to doing. #0009-02 continues.

“The merge is refused”

Only the owner merges. The agent can prepare the check, but the merge command must be run by a human. Common reasons:

an active batch is in breakdown, doing or handover;
a batch is blocked;
the worktree is dirty;
the merge check fails;
the agent tried to execute an owner command.

“There is a merge conflict”

With one writer, this should be rare. The agent must stop and reconstruct the timeline from the event journal. It should not choose a side.

Agent: I found a conflict in a card file. The event history shows two
          plausible transitions. I need a human decision before writing.

“The agent forgot the runbook”

Ask it to reload:

Human: Run `mdboard runbook` and `mdboard context` again, then restate
       your role and the next legal action.

If it still behaves outside the model, stop the session. Do not let it continue with stale instructions.

“The agent claims I approved something I did not”

This is the trust limitation of chat-only authorisation. Check the event journal:

who is recorded as authorised_by;
what statement was recorded;
what action was taken.

If the record is false, treat it as an incident. The model cannot cryptographically prevent a misbehaving agent with write access; see Security.

“The cost is zero”

The batch has no token estimate, or the cost model is not configured. Ask the agent to show the estimate and the [costs] settings.

“The meeting keeps appearing”

It is pending until accepted, deferred or dismissed. A deferred meeting returns on its due date. If it should not exist, dismiss it with a reason; do not ignore it silently.

When to use the CLI yourself

You usually do not need to. Use the CLI when:

you are the owner and must merge or release;
you need to inspect the event history;
you are recovering from a agent failure;
you are setting up the project.

The CLI reference is written for the agent; it is still the authoritative command list.