docs(board): the merge does not move the board — move it yourself

[wenzowski]

The previous PR (#398) changed the tracker's merged-event mapping from Done to
In Review and updated mem:workflow/board-states and AGENTS.md to say the
merge writes that column for you.

Measured on #398 itself, and it does not. Merged 06:27:05, all eight
required checks green. CLOUD-192 still read In Progress at 06:35:26 —
8m21s later — with no In Review entry anywhere in its state history.

Not lag, and not any of the obvious causes:

• The key travelled. Branch claude/cloud-192-implementation-9l6mcg carries
  cloud-192, and linear-code[bot] commented on the PR at 06:12:20 and
  attached it to CLOUD-192. Linear had the issue and had the link.
• The setting is live. The settings page was re-read after the merge and
  still showed "On PR merge, move to… In Review". A dropdown selected but
  never saved is ruled out by measurement, not assumed away.
• The merge is visible to GitHub. state: MERGED, mergedAt set, and the
  timeline carries merged + closed. A fast-forward landing is not invisible.

So the contract this repo shipped one PR ago is wrong, and wrong in the
expensive direction: an agent reading it waits for a board move that never
comes, and the board silently understates what has landed. The claim was mine;
this retracts it.

Also a probe

This PR's body carries a closing keyword (Closes CLOUD-192) where #398
carried only a Refs: trailer, and CLOUD-192 was moved back to In Progress
first so the transition is observable. That tests Linear's closing vs
contributing split — the one explanation still standing.

• If CLOUD-192 lands in In Review on merge, the cause is the keyword, and the
  fix is repo-side: land/issue-guard emit the closing form, shipped with a
  gate.
• If it does not, the merged-event rule does not reach this workspace's PRs at
  all, and the hand-move this PR documents is the answer rather than a stopgap.

Either result is recorded on the issue. done-check (landed in #398) holds the
other end regardless — a Done that shipped in no release is already a failing
check.

Closes CLOUD-192

[linear-code]

CLOUD-192 The board transitions to Done on merge, not on release — In Review is never occupied

Why. The board is the observability surface, and its states are defined against a trunk-based model: In Review = landed on main, under post-merge review, pre-release; Done = released. Observed on CLOUD-168, the integration collapses both into one transition fired by the merge.

Measured. PR #103 merged at 19:29; CLOUD-168's state history is Backlog -> In Progress -> Done with Done set at 19:29:03 — merge time. The release (v0.0.15, which does contain the commit) was not cut until 19:31:56, ~3 minutes later. So the issue read Done for three minutes while unreleased, and In Review was never occupied at any point.

The end state converged here only because release-plz happened to release promptly. The transition is keyed on the wrong event, so the failure is latent rather than absent:

• A release that fails, is delayed, or is held leaves issues sitting in Done while unreleased — the exact "done means landed-and-verified" drift Batten exists to prevent, on Batten's own board.
• In Review having no occupants means the post-merge review window the trunk-based model depends on has no board representation. Per AGENTS.md we review after merge, before release; a column that is structurally never entered cannot surface that work.

This also supersedes a recorded observation in mem:workflow/board-states, which states "the merge-side transition did not fire" (measured when #100 merged and CLOUD-178 stayed In Progress). It now fires — and overshoots. That memory needs correcting either way, since an agent reading it today will expect to hand-move a landed issue that the integration has already moved.

Acceptance.

• Merging a PR moves its issue to In Review, not Done.
• Done is set by the release, not the merge — an issue whose commit is on main but not in any published release is never Done.
• A test or documented probe demonstrates the two-step path on a real issue (state history shows In Progress -> In Review -> Done).
• mem:workflow/board-states is updated to record the current, measured behaviour, replacing the "did not fire" note.

Implementation, 2026-08-13.

Re-measured before touching anything. The defect is still live and unchanged from the original CLOUD-168 observation: CLOUD-499's state history reads Todo -> In Progress -> Done, with Done set at 05:13:12 — merge time. Last tag v0.0.62, main 50 commits past it, so ~1.5 days of landed work read as released.

The two halves have different owners, and only one is code.

• merge -> In Review is a workspace setting — the team's GitHub integration maps the merged event to a status. No repo code and no Linear MCP tool can change it, so nothing in the tree can hold it. It was flipped from Done to In Review (Workflows & automations -> Pull request automations -> "On PR merge, move to…"). The setting alone did not produce the transition — see the probe below. This bullet stays open.
• release -> Done has no automation available at all, and this is not a gap that a setting closes. Per mise-tasks/released's header: the integration triggers on PR events, and "a release tag now contains this commit" is not one. Performing it needs a Linear credential the repo deliberately does not have.

So the repo ships the half it can hold: the consequence. mise-tasks/done-check refuses a Done that no v* tag reaches — CLOUD-N Done -> In Review, exit 1. It is landed-check's terminal twin (both name In Review, one for a board behind git, one for a board ahead of the release) and composes with released running the other way. It only ever refutes a Done, never confirms one: refs come from commit messages, so a ref inside a tag is weak evidence while a ref nowhere near one is conclusive. A skipped promotion is now a failing check rather than silent drift.

The board was corrected rather than grandfathered. Piping the full Done closure (159 issues) exited 1 and named five: CLOUD-404, CLOUD-484, CLOUD-491, CLOUD-495, CLOUD-499 — each landed, each in no tag. All five moved to In Review, graph-check-adjudicated on their PR attachments first. The same closure now exits 0 (27 not judged, the unlanded channel). That before/after pair is the gate demonstrating it can fail on real data, not only on fixtures.

Fewer than the 50 unreleased commits would suggest, because an issue is judged by its most-released ref: work carrying several PRs, some shipped, passes. That is CLOUD-468's question and this gate deliberately does not answer it.

Notes. If the integration cannot key Done on a release event, the fallback is to stop it at In Review and let the release step promote — a correct-but-manual last transition beats an automatic wrong one, since graph-check already gates In Review => a linked PR attachment.
The probe FAILED, and that is the finding. This issue's own PR (#398) was the demonstration. It merged at 06:27:05 by fast-forward, main at bd99948, all eight required checks green. Read at 06:29:48, 06:35:26 — 8m21s after the merge — the issue was still In Progress with updatedAt unchanged from an edit made before the PR existed. The state history shows no In Review entry at any point.

The automation is not simply slow: mem:workflow/board-states records the open-side transition firing eight seconds after gh pr create, and this same PR's open-side fired normally — linear-code[bot] commented on it at 06:12:20 and attached #398 to this issue. So Linear received the PR, linked it, and did not act on the merge.

What that rules in and out:

• Not a missing key. The branch was claude/cloud-192-implementation-9l6mcg, carrying cloud-192, and the attachment proves the link resolved to this issue.
• Not a missing setting, re-confirmed after the fact rather than assumed. The settings page was re-opened and screenshotted at 11:34 local — after the merge, not before it — and "On PR merge, move to…" still read In Review. So the value persisted and was live when feat(done-check): key Done on the release, and refuse a Done no tag contains #398 merged. The obvious explanation, that a dropdown was selected but never saved, is ruled out by measurement.
• Not the fast-forward merge being invisible. GitHub reports the PR MERGED with mergedAt set, and the timeline carries merged + closed events.

The untested hypothesis is Linear's closing vs contributing PR distinction, which the settings page names in its own copy. #398's body carries Refs: CLOUD-192 and no closing keyword, so it may be registered as contributing — linked, but not driving status. That would also explain why the transition is reachable at all in this workspace while being unreachable for the PRs this repo actually produces, since issue-guard requires the key and nothing requires a closing keyword.

It is not settled by the earlier counter-evidence in the memory (#131 completing on merge with only a Refs: trailer), because that was measured against the old Done mapping; whether the two rows classify PRs the same way is exactly the open question.

Next step, and it is cheap: land any PR whose body carries a closing keyword for its issue and read the state history. If it moves to In Review and a Refs:-only PR does not, the fix is a repo-side one — issue-guard/land emit the closing form — and it ships with a gate. If neither moves, the merged-event rule is not reaching this workspace's PRs at all and the fallback in the Notes below is the answer: stop at In Review by hand, with done-check (landed) holding the line on the other end.

This issue is moved to In Review by hand, which is the truthful column for landed-and-unreleased work and is precisely the hand-move the mechanism was supposed to make unnecessary.

Review in Linear

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[wenzowski]

/fast-forward