@motir/cli 0.5.0 → 0.5.1

package/README.md

@@ -220,6 +220,66 @@ that has no direct edge, or when you want the review hop on the record. An
 illegal flip surfaces the server's own allowed-targets error verbatim. A merged
 **session** PR closes out in bulk with `motir done --session <branch>`.
 
+## The repair — `motir fix` (MOTIR-5465)
+
+```sh
+motir fix <key> [--agent <cmd>] [--report-log]
+```
+
+**When to use it.** A work item's pull requests are failing, or its merge did not
+land for a reason the CODE could answer, and the run that opened them has ended.
+That is a card at **Implemented** whose checks went red later or whose branch
+conflicts, or a card back at **In Review** after the merge queue threw it out for a
+failed or timed-out check (it waits there for a fresh approval, and `motir fix` is
+the answer when the failure is real). A merge blocked by a repository SETTING, or a
+pull request somebody took out of the queue by hand, is refused: no code change
+fixes either. The item page's Development block offers this command, ready to copy.
+
+**What it does:**
+
+1. **Claims the repair** (`POST /api/v1/work-items/{key}/repair`). Only one
+   repair runs on a card at a time. The claim is an open `fix` run, and it never
+   changes the card's status or assignee. A refusal is printed in words and
+   exits non-zero:
+   - somebody is already fixing it, and they are named;
+   - the card is not waiting on a repair (neither Implemented, nor In Review after
+     a merge-queue ejection);
+   - its merge did not land for a reason no code change fixes — a setting, or a
+     hand removal from the queue — and the refusal names what would help instead;
+   - the pull requests belong to the parent's run, and the key to fix instead is
+     named;
+   - the card has no pull requests;
+   - its checks are still running;
+   - nothing is failing.
+2. **Checks out each red pull request's own branch**, as a worktree beside that
+   repository's checkout (`<repo>-fix-<key>-<number>`). The worktree is on the
+   branch, not a detached HEAD, so a push updates the same pull request. A
+   repository with no local checkout is refused. A resumed repair reuses its
+   worktree.
+3. **Runs the same fix loop `motir run` ends with**, using the same prompt and
+   the same limit of five attempts. When the failing set spans several
+   repositories, the prompt lists every checkout.
+
+   **A pull request the merge queue ejected counts as failing**, even when its
+   own checks are green (the queue failed on its merge commit, not on the branch
+   alone). The prompt says why it left the queue and names the queue's failing
+   check. A conflict is told to merge the base and resolve it. If the agent
+   pushes nothing, because there was nothing to change, the repair stops after
+   that ONE attempt and tells you to press **Queue again** on the card.
+
+4. **Closes the run** on every exit path:
+   - green → completed, exit 0;
+   - the sixth red → halted, exit 1, naming each failing check, its repository
+     and the attempt count (the queue's check, for an ejected pull request);
+   - an ejected pull request the agent pushed nothing to → failed, exit 1,
+     pointing at _Queue again_;
+   - Ctrl-C → interrupted, exit 130.
+
+   The page shows a repair as in progress for as long as its run is open.
+
+It opens no pull request and links nothing. The build moves the card to
+**In Review** when the checks pass, exactly as it does after `motir run`.
+
 ## The loop — `motir auto` (7.9.4)
 
 ```sh