(2c95d38) Gate a blocker by the column it is in, not by whether it is done, and bump to 0.33.1

check_blockers refused every move while a blocked by target was still open, so a
dependent sat in backlog until its blocker landed even when the blocker was in
reviewing and its code was there to build on. The way out was -f, which also waives
the backward and skipping guard, on every move for as long as the pair existed.

The rule is now the columns: a ticket may stand level with what it waits on but never
ahead of it, so a blocker in reviewing lets the dependent be committed and reviewed
and gates only done. util::blocks_move is the one place it is decided, taking the
status moved into and the blocker's own, and mv passes the target through. A finished
blocker still holds up nothing, answered through is_open, and a target of discarded
is answered by name rather than by its place in Status::ALL, where it sits last.

The refusal now names the status moved into and only the blockers still behind it: a
dependent told to wait for work already ahead of it has nothing to act on. The board
asks the same function about the column one stage ahead, so the blocked mark means the
card cannot advance rather than that a dependency was ever recorded, which also takes
it off cards in the two terminal columns.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-09-10 11:38:17 +02:00
co-authored by Claude Opus 5
parent 9c224fb768
commit ead3c4340d
15 changed files with 409 additions and 90 deletions
+5 -3
View File
@@ -23,9 +23,11 @@ Recording an edge between two tickets, and drawing the block that reports them.
- **A line in the section that is not a relation is an error naming the ticket**, not a line quietly dropped. Nothing but `relate` writes there, so a bad line means a hand-edited file. The TUI is the deliberate exception: `detail_of` falls back to no block, since one corrupt ticket must not take the whole board down
- **The block is built outside `content_trim` and passed in.** Half of it comes from other tickets and `content_trim` has only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show
- `ensure_section` inserts against `SECTION_ORDER`, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten `## Notes` between the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to
- **The blocker check runs on every move**, after the already-in-that-status return and behind `force`. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused. `-f` now bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true
- **A blocker that is not on the board warns and allows the move.** Refusing would wedge the ticket with no way out but `-f`, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names **every** open blocker, since clearing the one that happened to be printed would leave the ticket blocked
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See [The Board View](tui-board.md)
- **A dependent may stand level with its blocker but never ahead of it.** `blocks_move` is the rule: the move is refused exactly when the status moved into is further down `Status::ALL` than the blocker's own, so a blocker in reviewing lets the dependent be committed and reviewed and gates only done. The first shape of this refused every move while a blocker was not done, which read as one rule rather than a table of transitions but stopped the work it was meant to order: a pair is usually built and reviewed together, and waiting for the blocker to land cost a `-f` on every move and left the rule enforcing nothing
- **A finished blocker is answered by `is_open`, and a discard target by name.** Done landed and discarded never will, so neither holds anything up, and that is the one place the board decides what finished means. Discarded is last in `Status::ALL` for the stamp rule's sake, so a comparison of positions alone would read a discard as the furthest move of all: `blocks_move` returns false for it outright, since abandoning a ticket is not carrying it along the flow and owes nothing to what it waits on. A status that is not one of the five holds up every move, the direction `is_open` already takes with such a value: a fault surfaces rather than quietly letting a dependent past
- **The blocker check runs on every move**, after the already-in-that-status return and behind `force`, with the target status passed in as what decides the answer. A move to the status the ticket is already in is not a move, so it is not refused. A backward move never is either, being at or behind everything, and it needs `-f` for its own reason anyway. `-f` bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true
- **A blocker that is not on the board warns and allows the move.** Refusing would wedge the ticket with no way out but `-f`, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names **every** blocker still behind the move and the status it was for, since advancing the one that happened to be printed would leave the ticket held up, and a ticket refused the next stage after moving once is otherwise told nothing about what changed. A blocker further along than the move is left out of the list entirely: a dependent told to wait for work already ahead of it has nothing to act on
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. It asks `blocks_move` about the status one stage ahead of the column the card is in, so the mark means the card cannot advance and not that a dependency was ever recorded. See [The Board View](tui-board.md)
## The Relations Block
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
+2 -2
View File
@@ -19,8 +19,8 @@ What a ticket file holds, how the statuses move it, and how a search finds it.
- **`Status::ALL` is every directory that can hold a ticket, and that is the only list left.** It is what the tree walkers want: `status_dirs`, `RelationIndex::load`, `collect_ticket_items`' callers, `cmd_tags`, `list_ids`, the resolver, the digest and the board's own columns all have to see a discarded ticket or it becomes unaddressable. There was a second list, `FLOW`, the four stages work moves through, which used to be what the board drew from; a136d13 drew the discarded column behind a visibility prefix instead, which took FLOW's last reader away, so it is gone. Hiding is decided by `Visibility`, never by leaving a status out of the walk: what is drawn changes, what is read does not. The prefix property survives on the order alone — done and discarded are deliberately the last two in `ALL` — and `the_terminal_columns_are_last_in_the_order_drawn` pins it
- **Discarding is not a stage, so the walk rules do not apply to entering it.** `mv --status discarded` is allowed from any status with no `-f`, because a backlog ticket that turns out to be a duplicate should not have to be walked through committed and reviewing to be abandoned. Leaving it needs `-f`, which comes free from the backward-move rule
- **The two dependency guards look opposite ways, and `mv` picks by direction.** `check_blockers` asks what this ticket waits on and gates work moves; `check_dependents` asks who waits on this ticket and gates the discard. A ticket being abandoned owes nothing to its own blockers, but the tickets blocked *by* it recorded a dependency on work that is about to be declared never-happening, so those plans get a look before the ground moves. `-f` is the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded
- **Discarded satisfies a block the way done does.** There is nothing left to wait for, and whether the dependent still makes sense was asked at discard time by the guard above, which is what makes it safe to pass here rather than a second place to re-ask
- **The two dependency guards look opposite ways, and `mv` picks by direction.** `check_blockers` asks what this ticket waits on and gates work moves, refusing the ones that would put it ahead of a blocker; `check_dependents` asks who waits on this ticket and gates the discard. A ticket being abandoned owes nothing to its own blockers, but the tickets blocked *by* it recorded a dependency on work that is about to be declared never-happening, so those plans get a look before the ground moves. `-f` is the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded; `check_blockers` also skips a blocker already further along than the move being made
- **Discarded satisfies a block the way done does.** There is nothing left to wait for, and whether the dependent still makes sense was asked at discard time by the guard above, which is what makes it safe to pass here rather than a second place to re-ask. It is also why `blocks_move` answers a discard by name and not by position: discarded is last in `Status::ALL`, so comparing positions alone would read the two terminal statuses as the furthest stages of the flow rather than the ends of it
- **Both terminal statuses are hidden by default and counted anyway.** `ls` leaves done and discarded out of the decorated listing and keeps them in the summary counts, and `--ids` and the status positional still reach both: a ticket nobody will work still has to be nameable by a completion or a script
- **A campaign counts a discarded member as finished.** The work was decided out of the campaign rather than left in it, and counting it outstanding would hold a campaign open forever over a ticket nobody will ever do
- **`mv` creates the target directory before moving into it.** A board made before a status existed has no directory for it, and the first move into one is the wrong place to refuse. `init` gets all five from `status_dirs()`
+1 -1
View File
@@ -102,7 +102,7 @@ The TUI: the columns, the cards, the frame, the pickers and the footer.
- **`digest` watches the campaigns directory** as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
- `tags` is a field on `TicketItem`, filled in `collect_ticket_items` through `parse_tags`, for the reason the criteria count is. `parse_tags` splits the comma-separated field into whole trimmed values, so a caller asking for `bug` is not answered by `bugfix`, and reads absent, `_None_` and empty as the same answer
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket its blocker has not moved out of the way of looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. The mark is `mv`'s own rule asked one column ahead, so it says this cannot advance rather than that a dependency was ever recorded: a card in committed whose blocker is in reviewing is unmarked, because reviewing is where it may go, and the same card is marked once it sits in reviewing and only done is left. The two terminal columns have no next stage and nothing in them is drawn blocked. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
- **The mark goes after the id, not before it.** Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
- **A blocker the board does not hold marks nothing**, the answer `mv` already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception `detail_of` makes for the same reason: `show` and `mv` are where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure