Motir

The server-assembled dispatch prompt tells an agent how to do the work. It says nothing about how to REPORT the outcome — neither "I finished" nor "this card cannot be done as specified". Both are signals the loop needs and neither exists today: motir auto infers completion from a process exit code, which only means the process ended, not that the work landed.

⚠️ CORRECTED 2026-08-07. This card first said the agent should move a refused card to blocked. That is wrong and would not have worked: blockedness is decided by the dependency EDGES, so the blocked status changes a label and nothing else — the card stays ready, stays in the pickable set, and gets re-dispatched on the next run. The agent moves it to Planning (in the in_progress category, MOTIR-2425), which removes it from the pickable set structurally.

Why the PROMPT is the only place this can live

motir auto runs claude --dangerously-skip-permissions in a sandbox against the user's OWN key (BYOK). There is no wrapper, no policy layer and no second channel — the prompt is the entire contract with the agent. Whatever is not in it does not happen.

The two signals

FINISHED — set the card to in_review over MCP. A positive act, not an inference. The loop then has two independent confirmations (the process exited, the card moved) and can tell "the agent finished" from "the agent died quietly".

THE CARD IS WRONG — record the finding, submit it as a plan, stop. When the premise is false, a precondition it names has not shipped, or an acceptance criterion is unsatisfiable:

1. Revert first. Restore the tree to the state it was dispatched in; commit nothing.

2. Do not improvise. No adjacent change, no widening the card's scope to make it satisfiable, no creating or editing work items — a plan is PROPOSALS awaiting human approval, and the agent must not do the approving by writing cards itself.

3. Comment the finding on the card — what is false, with the evidence.

4. Move the card to Planning over MCP. Not blocked: readiness comes from the edges, so blocked would leave the card in the pickable set and it would be handed out again. Planning is in the in-progress category, which is what actually removes it — and it is the truthful word, because the card is not blocked, it is being re-planned.

5. Submit it as a plan, naming the exact invocation:

   motir plan --detach <KEY> "<the findings>"
   

   Anchored at the card's key, because an unanchored thread produces a project-wide plan about one card's defect. --detach because the agent must not sit waiting on a planner.

6. Never retry the submit. A submit SPENDS the token owner's AI credits; a blind retry-on-timeout in an unattended loop costs real money twice.

7. Exit.

⚠️ ONE CARD, ONE COMMIT — and that commit message IS the pull request

motir auto runs every card onto one session branch and opens one pull request at close-out, whose body is assembled from the commits on the branch (11.5.27). So the prompt must tell the agent two things about its commit:

• Exactly one commit for the card. The branch's legibility rests on it — a reviewer reads the pull request as the list of cards it delivers. An agent that got halfway before discovering a defect and committed anyway puts a change in that pull request with no card behind it, which is worse than either finishing or stopping.
• The message is written for a REVIEWER WHO WAS NOT THERE, because it is the only per-card narrative that reaches them. Nobody reading the pull request opens the card. Subject: what changed. Body: why, and what someone needs in order to decide whether to merge — including whatever surfaced during the work that the card could not have known. A message that restates the card's title tells the reviewer nothing they could not already see, and a one-liner leaves the pull request with a subject and no reasoning under it.

Scope BOUNDARY

The prompt's assembly and its tests. It does NOT create the Planning status (MOTIR-2425, which blocks it). It does NOT change motir auto's loop — reading the signals, stopping, and the close-out are 11.5.26's; assembling the body from the commits is 11.5.27's. It does NOT add a prompt MODE or a new parameter: every instruction here is unconditional, because a human-driven motir run agent should report the same way. It does NOT change the planning endpoints, motir plan, or the CLI.

Acceptance criteria

• The assembled prompt carries both signals in both per_item_pr and session_lineage variants — asserted for each, because a section added to one branch of a two-branch assembler is the classic half-shipped prompt change.
• The FINISHED signal names the transition explicitly (in_review) and says it is required, not optional — an agent that treats it as a nicety leaves the loop unable to distinguish success from a quiet death.
• The defect signal names Planning, and the prompt does NOT mention blocked — asserted on the assembled text, because blocked is the intuitive word and an agent offered both will reach for it.
• The revert-first instruction comes FIRST in the defect section: an agent that reads "record the finding" before "commit nothing" has already had four steps in which to commit.
• The exact motir plan command form appears verbatim, with the key substituted, so an agent never has to infer the anchoring or the flag. An agent told to "submit your findings for re-planning" will invent an invocation, and the likely invention is an unanchored thread.
• The prompt states that the commit message becomes the pull request body, and says what that asks of it: written for a reviewer who has not read the card, with the reasoning in the body.
• The prompt states that a plan is proposals awaiting approval, and that the agent must not create or edit work items itself.
• The prompt states the no-retry rule with its reason (credits), not as a bare prohibition.
• An assembled prompt for a real item is asserted end-to-end, not a fragment — PLACEMENT matters (an outcome protocol after the git workflow reads as an afterthought).
• No change to any endpoint, response shape or contract version.

Context refs

• lib/services/dispatchPromptService.ts — the assembler and its two workflow variants.
• MOTIR-2425 — the Planning status this instruction depends on.
• packages/cli/src/commands/plan.ts — parsePlanArgs (leading keys are the anchor set), submitOneShot (append then submit), --detach; the command form this prompt names already ships.
• MOTIR-2213 — the prompt is a pure READ that never claims or transitions; this card does not change that.
• 11.5.26 — the loop half: reads both signals, stops on a submission, and closes out on every exit path.
• 11.5.27 — assembles the pull request body from these commits; the reason the message instruction is here.
• Story: MOTIR-1855.