feat(task-board): let a column say what it means

[viktormarinho]

What is this contribution about?

This is the piece @viktormarinho asked for in place of a status mapping: you tell each column what it means, once, instead of maintaining a translation between two vocabularies.

It also closes a hole I flagged in #6716 and would not want anyone to enable the flag over.

The hole

archive-merged.ts wrote { status: "archived" } directly. On a board whose columns are the org's own there is no such column — and nothing catches it:

• the sweep writes through storage, so assertBoardHasColumn never runs;
• board_column_org is null for those rows, so the foreign key sleeps.

The card would be filed under a column that does not exist: invisible, not archived. The board decides now, and a board with nowhere to retire a card leaves it in Done — wrong-but-visible beats right-but-gone.

/** Where the sweep retires a finished card, or null when this board has
 *  nowhere to retire one to. */
archiveColumn(): Promise<string | null>;

Same nullable shape as automationFor, for the same reason.

Roles

TASK_BOARD_COLUMN_ROLE_SET is how an org says which of its columns means what. A column mirrored from a tracker is a name and a position — nothing tells us "Code Review" is where review happens, or that "Arquivado" retires a card.

Two roles today (in_review, archived), because two are what automation actually reads. A column carries at most one, and most carry none — that stays the safe default for a column we did not invent.

Studio's own lanes are deliberately not configurable: they already mean what they say, and setRole finds no row to update on a board that has no rows, which the tool turns into a clear error rather than a silent no-op.

It rejects a role on a column the board does not have, for the same reason TASK_BOARD_AUTOMATION_UPSERT does — a rule that can never fire still reads as configured to whoever set it.

How did you verify your code works?

Real-Postgres cases in board-handler.integration.test.ts, one per board:

• Studio's board retires to archived, as it always did;
• an org board has nowhere to retire a card until someone says which column that is — asserted across the whole cycle: null, then set a role and it answers that column, then clear it and it goes back to null. The clear half matters because a role you cannot take back is a trap.

The existing archive-sweep integration tests keep passing — and one of them needed real work rather than a workaround: its context was built with only taskBoard, and the sweep now asks the board (which asks the org which board it is). I gave the test the storages instead of moving the lookup to dodge it, the same call as in #6710.

4200 pass / 72 fail across apps/api/src and the board's web tests — the same 72 pre-existing order-dependent failures measured against baseline earlier. Every *.integration.test.ts also run individually in find | sort order, the way CI runs them, all green. bun run check 0 errors, bun run lint at baseline, knip clean (it caught COLUMN_ROLES being exported for no one — narrowed), fmt:check clean.

Not verified, flagging honestly:

• No UI. Roles are set through the tool, and the debt is now three PRs deep: no screen for automations (feat(task-board): configure what a column runs, per column #6690), for the board mode (feat(task-board): a board whose columns are the org's own #6698), or for roles (here). At some point that stops being deferral and starts being a product with no controls.
• Only two roles. in_review is defined and settable but nothing reads it yet — the review-phase checks still compare to the literal "in_review". It is here because setting it is half of what makes the sync useful, but I want to be plain that it is inert today; archived is the one that does something.
• No e2e, and no live check of the archive sweep against an org board — there are no org boards with cards yet.

Screenshots/Demonstration

Not applicable — no visible change. Studio's own board answers exactly as before.

How to Test

1. On any org today, the archive sweep still retires merged Done cards to Archived.
2. On an org with org_board_columns on and some columns, confirm the sweep leaves finished cards in Done — it has nowhere to retire them.
3. TASK_BOARD_COLUMN_ROLE_SET { columnKey: "<one of theirs>", role: "archived" }, then confirm the sweep retires to that column.
4. Clear it with role: null and confirm it stops again.
5. Try a role on a column that does not exist, and on an org still using Studio's board — both should be refused with a message that says why.

Migration Notes

None. No schema change — task_board_columns.role has existed since #6698 and this is the first thing to write it.

Review Checklist

• PR title is clear and descriptive
• Changes are tested and working
• Documentation is updated (if needed)
• No breaking changes

---

Summary by cubic

Fixes the archive sweep so a finished card is never filed under a column the board doesn't have. The sweep now asks the board where to retire a card instead of writing the literal "archived" — a board with no column marked as such leaves merged cards in Done (wrong-but-visible) instead of filing them under a nonexistent column (invisible).

• Adds TASK_BOARD_COLUMN_ROLE_SET to mark one of the org's columns as archived or in_review, or clear it with null.
• Studio's own board keeps its fixed Archived lane; org boards have no archive column until the org says which one that is.

^{Written for commit 1544edd. Summary will update on new commits.}