[matthewtsmith]

Two fixes found while a litart task sat on Needs you for no reason.

Unblock no longer re-blocks the task at once

Bug: #268 was blocked after a failed validation. The owner unblocked it, a builder pushed a fix, and seven seconds later foreman blocked it again with the same reason, before anything had looked at the new commit.

Cause: applyUnblock removed blocked from the issue but left validator:failed on the PR. The fix-round count is still spent (the README documents that as intentional), so as soon as the issue was back In Review, blockActions matched again.

Fix: Unblock now also removes reviewer:changes and validator:failed from the issue's PR, as the README's manual unblock steps already said. It finds the PR on the stored board, so there is no extra GitHub read. The fix-round count is unchanged: the next verdict on the new commit has to be an approval, or the task is blocked again.

Approving a plan merges its plan PR and applies it at once

Before: Approve plan only added plan-approved. The plan PR still had to be merged by hand, and until then apply_plan logged approved plan file not on origin/main on every tick. apply_plan also ran only on ticks with nothing to claim, so an approval waited behind every review and validation.

Now: applyPlanActions (src/phase.ts) runs ahead of the pick, because none of these actions start a session. For each approved epic whose plan has not been applied:

• Plan PR open with green or no checks: emits merge_plan (squash merge), then apply_plan in the same tick.
• Checks pending: waits for the next tick.
• Red checks or a conflict: emits plan_pr_stuck. That posts one comment on the epic per head commit, and the epic gets a "Fix a plan PR" row on Needs you, counted in the badge.
• No plan PR open (merged by hand): emits apply_plan, as before.

The plan PR is found by the title planner.md prescribes: docs(plan): phase NN plan (#<epic>).

New ledger line, informational and not terminal, added to the README grammar list next to ci rerun and unblocked:

plan PR #<pr> cannot merge at <sha>: <reason>. Fix it or merge it by hand (foreman@<host>)

Also fixed: an approved epic whose plan was not applied yet still has needs-owner. ownerItems read that as a sign-off and offered Sign off, which closes the epic before it has any tasks. Such an epic now offers only Pause, and its row says what it is waiting on. Waiting on shows the pending plan PR as a CI wait.

OwnerItem gains planPr (nullable, default null), so older state.json files still parse.

Test plan

• pnpm lint && pnpm typecheck && pnpm test: 707 tests pass, with new tests for every branch above (phase, state ordering, ledger, loop execute, owner, waiting, attention, needs-you)
• foreman -p litart next against the live repo: reads correctly with the new build
• Checked all four instances: every open approved epic already has a plan applied comment, so none loses its Sign off button
• After deploy: approve litart epic #274 and confirm plan PR merged appears once in foreman.log, with consecutiveFailures staying at 0

🤖 Generated with Claude Code

https://claude.ai/code/session_01JrFSqr3eJsNihHcgYph1hB