(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
+30 -26
View File
@@ -490,59 +490,63 @@ fn move_ticket_file(
.map_err(|e| anyhow!("Could not move ticket '{}' to {}: {}", title, dest.display(), e))
}
/// Refuse a move while a ticket it is `blocked by` is not done.
/// Refuse a move that would put a ticket ahead of one it is `blocked by`.
///
/// Every move, not only the one into committed: 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. Called before anything is written, so a refusal leaves no
/// rename, no rewritten field and no half moved ticket.
/// Every move is asked, and `target` is what decides the answer: a ticket may stand
/// level with what it waits on, so a blocker in reviewing lets the dependent be
/// committed and reviewed and refuses only done. The rule and why it is this one are in
/// [`blocks_move`]. Called before anything is written, so a refusal leaves no rename, no
/// rewritten field and no half moved ticket.
///
/// A target the board does not have warns and allows the move. Refusing there would
/// wedge the ticket behind a bookkeeping fault with no way out but `--force`, and a
/// dangling uuid is not a dependency.
fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()> {
let blockers: Vec<Relation> = parse_relations(content, title)?
fn check_blockers(worklane_dir: &Path, content: &str, title: &str, target: Status) -> Result<()> {
let edges: Vec<Relation> = parse_relations(content, title)?
.into_iter()
.filter(|relation| relation.kind == RelationKind::BlockedBy)
.collect();
if blockers.is_empty() {
if edges.is_empty() {
return Ok(());
}
let index = RelationIndex::load(worklane_dir)?;
let mut open: Vec<String> = Vec::new();
let mut behind: Vec<String> = Vec::new();
for blocker in &blockers {
match index.get(&blocker.target) {
// Discarded satisfies a block the way done does: there is nothing left to
// wait for. Whether the dependent still makes sense was asked when the
// blocker was discarded, which is `check_dependents`' refusal.
Some(target) if !is_open(&target.status) => {}
Some(target) => open.push(format!(
for edge in &edges {
match index.get(&edge.target) {
// A blocker level with the move, or ahead of it, is not in the way. Neither
// is a discarded one: whether the dependent still makes sense was asked when
// the blocker was discarded, which is `check_dependents`' refusal.
Some(blocker) if !blocks_move(target, &blocker.status) => {}
Some(blocker) => behind.push(format!(
" ({}) {} [{}]",
color_text(short_id(&target.uuid), Color::Red),
target.title,
color_text(&target.status, Color::Orange),
color_text(short_id(&blocker.uuid), Color::Red),
blocker.title,
color_text(&blocker.status, Color::Orange),
)),
None => eprintln!(
"Warning: ticket '{}' is blocked by {}, which is not on the board.",
title,
short_id(&blocker.target),
short_id(&edge.target),
),
}
}
if open.is_empty() {
if behind.is_empty() {
return Ok(());
}
// Every open blocker, not the first: a ticket waiting on three of them is not
// unblocked by clearing the one the message happened to name.
// Every blocker still behind the move, not the first: a ticket waiting on three of
// them is not freed by advancing the one the message happened to name. The status
// moved into is named too, since a ticket that moved once already and is refused the
// next stage is otherwise told nothing about what changed.
Err(anyhow!(
"Cannot move '{}' while it is blocked by:\n{}\nUse --force (-f) to move it anyway.",
"Cannot move '{}' to {} while it is blocked by:\n{}\nA ticket cannot move ahead of what it waits on. Use --force (-f) to move it anyway.",
color_text(title, Color::Green),
open.join("\n"),
color_text(target.as_str(), Color::Orange),
behind.join("\n"),
))
}
@@ -691,7 +695,7 @@ pub fn cmd_mv(args: &MvArgs, start: &Path, sink: &mut Sink) -> Result<()> {
if !force {
match discarding {
true => check_dependents(&worklane_dir, &parse_ticket_field(&resolved, "ID"), &title)?,
false => check_blockers(&worklane_dir, &resolved, &title)?,
false => check_blockers(&worklane_dir, &resolved, &title, *target)?,
}
}
+54 -19
View File
@@ -307,7 +307,8 @@ fn project_name(dir: &Path) -> String {
pub struct Card {
pub ticket: TicketItem,
pub project: Option<String>,
/// Whether a ticket this one is `blocked by` is on the board and not done.
/// Whether a ticket this one is `blocked by` would refuse its move out of this
/// column, which is `mv`'s rule asked one stage ahead. See `mark_blocked`.
///
/// Decided at reload like `project`, and for a stronger reason: the answer lives on
/// two tickets at once, so no card can reach it alone and asking per draw would mean
@@ -3283,7 +3284,13 @@ fn campaign_of(ticket: &TicketItem, campaigns: &CampaignIndex) -> Option<Cell> {
Some(campaign_label(&campaign.uuid, campaign.codename.as_deref()))
}
/// Set `blocked` on every card whose ticket waits on one that is not done.
/// Set `blocked` on every card that cannot move out of the column it is in.
///
/// The mark is `mv`'s answer to the move the card would make next, so the question is
/// asked of the status one stage ahead: a card in committed whose blocker is in
/// reviewing is not marked, 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.
///
/// Two walks of what `columns_of` has just read, not a lookup per relation: the status
/// of a blocker is on another card, so the pass builds the uuid to status map once and
@@ -3307,9 +3314,14 @@ fn mark_blocked(columns: &mut [Column]) {
.collect();
for column in columns.iter_mut() {
// Nothing moves forward out of done or discarded, so nothing there is held up.
let Some(next) = Status::from_name(column.status).and_then(Status::next_in_flow) else {
continue;
};
for card in column.cards.iter_mut() {
card.blocked = card.ticket.blockers.iter().any(|blocker| {
matches!(status_of.get(blocker.as_str()), Some(status) if is_open(status))
matches!(status_of.get(blocker.as_str()), Some(status) if blocks_move(next, status))
});
}
}
@@ -8190,8 +8202,9 @@ approach";
run_line(&mut board, "relate 1111111 --blocked-by 2222222");
assert!(board.prompt.is_none(), "relate was refused: {:?}", refused(&board));
// `mv` names every open blocker on a line of its own and then says what `-f` does,
// which is three lines and the reason none of them may be dropped.
// `mv` names every blocker in the way on a line of its own and then says what the
// rule is and what `-f` does, which is three lines and the reason none of them may
// be dropped.
run_line(&mut board, "mv 1111111 --status committed");
let notice = board.notice.as_ref().expect("the refusal said nothing");
assert!(notice.failed, "a refused move was reported as a success");
@@ -9458,12 +9471,12 @@ approach";
.collect()
}
/// The one thing on a card that says do not start this. Without it a ticket whose
/// blocker is still open reads exactly like one that is ready.
/// The one thing on a card that says this cannot advance. Without it a ticket its
/// blocker has not moved out of the way of reads exactly like one that is ready.
#[test]
fn a_card_waiting_on_an_open_ticket_carries_the_blocked_mark() {
fn a_card_its_blocker_has_not_moved_ahead_of_carries_the_blocked_mark() {
let dir = board_dir();
write_ticket(&dir, "committed", BLOCKER, "The blocker", "");
write_ticket(&dir, "backlog", BLOCKER, "The blocker", "");
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
let board = one_board(&dir);
@@ -9478,6 +9491,26 @@ approach";
);
}
/// The mark is the move the card would make next, not the dependency itself: a
/// blocker a stage ahead leaves the next column open, so the card is not held up
/// until it stands level with it again.
#[test]
fn a_card_whose_blocker_is_a_stage_ahead_carries_none() {
let dir = board_dir();
write_ticket(&dir, "reviewing", BLOCKER, "The blocker", "");
write_ticket(&dir, "committed", WAITER, "The waiter", &blocked_by(BLOCKER));
assert!(!marked_blocked(&one_board(&dir), "The waiter"));
// The same pair once the waiter has caught up: only done is left, and that is
// the stage the blocker still has to reach first.
let caught_up = board_dir();
write_ticket(&caught_up, "reviewing", BLOCKER, "The blocker", "");
write_ticket(&caught_up, "reviewing", WAITER, "The waiter", &blocked_by(BLOCKER));
assert!(marked_blocked(&one_board(&caught_up), "The waiter"));
}
/// The mark is the state of the dependency, not a note that one was ever recorded.
#[test]
fn a_card_whose_blockers_are_all_done_carries_none() {
@@ -9492,13 +9525,13 @@ approach";
assert!(!screen.contains(BLOCKED_MARK), "a cleared blocker still marked:\n{screen}");
}
/// One open blocker out of two is still a reason not to start, the rule `mv` applies
/// when it names every open blocker rather than the first.
/// One blocker out of two still in the way is still a reason not to start, the rule
/// `mv` applies when it names every blocker behind the move rather than the first.
#[test]
fn a_card_is_marked_while_any_one_of_its_blockers_is_open() {
fn a_card_is_marked_while_any_one_of_its_blockers_is_in_the_way() {
let dir = board_dir();
write_ticket(&dir, "done", BLOCKER, "The blocker", "");
write_ticket(&dir, "reviewing", ELSEWHERE, "The other blocker", "");
write_ticket(&dir, "backlog", ELSEWHERE, "The other blocker", "");
write_ticket(
&dir,
"backlog",
@@ -9513,9 +9546,9 @@ approach";
/// A discarded blocker holds nothing up, the answer `mv` gives it: there is nothing
/// left to wait for.
///
/// The board and `mv` share `is_open` for this, which is what keeps them from
/// The board and `mv` share `blocks_move` for this, which is what keeps them from
/// drifting now that the blocker arrives in the map: `columns_of` builds every
/// status, so a rule written as `!= DONE` would mark these cards while `mv` kept
/// status, so a rule of the board's own would mark these cards while `mv` kept
/// letting them move. The fixture writes the directory directly, the way a board
/// that predates a discard would hold one.
#[test]
@@ -9526,8 +9559,10 @@ approach";
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
assert!(!marked_blocked(&one_board(&dir), "The waiter"));
assert!(!is_open(DISCARDED), "the rule the board and mv share");
assert!(is_open("backlog") && is_open("committed") && is_open("reviewing"));
assert!(
!blocks_move(Status::Committed, DISCARDED) && !blocks_move(Status::Committed, DONE),
"the rule the board and mv share"
);
}
/// The answer `mv` gives a dangling uuid: a bookkeeping fault, not a dependency.
@@ -9566,7 +9601,7 @@ approach";
#[test]
fn a_column_too_narrow_for_the_mark_drops_it() {
let dir = board_dir();
write_ticket(&dir, "committed", BLOCKER, "The blocker", "");
write_ticket(&dir, "backlog", BLOCKER, "The blocker", "");
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
let board = one_board(&dir);
@@ -9593,7 +9628,7 @@ approach";
#[test]
fn the_blocked_mark_follows_a_card_onto_the_merge() {
let (first, second) = (board_dir(), board_dir());
write_ticket(&first, "committed", BLOCKER, "The blocker", "");
write_ticket(&first, "backlog", BLOCKER, "The blocker", "");
write_ticket(&first, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
write_ticket(&second, "backlog", ELSEWHERE, "Elsewhere", &blocked_by(BLOCKER));
+179 -6
View File
@@ -2422,7 +2422,8 @@ pub fn parse_relations(content: &str, title: &str) -> Result<Vec<Relation>> {
pub struct RelatedTicket {
pub uuid: String,
pub title: String,
/// The directory it sits in, which is what decides whether a blocker is still open.
/// The directory it sits in, which is how far along a blocker stands and therefore
/// which moves it holds up.
pub status: String,
/// The relations it stores, and therefore where an inverse is derived from.
pub relations: Vec<Relation>,
@@ -3144,6 +3145,78 @@ impl Status {
Status::Discarded => "discarded",
}
}
/// The status a directory name or a `Status` field names, and nothing for a value
/// that is not one of the five.
///
/// The inverse of [`Status::as_str`], derived from [`Status::ALL`] rather than
/// matching the five names a second time, so a status added to the list is
/// recognised here without a second edit. Callers reading a status off disk hold a
/// string, and this is where they turn it back into something the flow order can be
/// asked about.
pub fn from_name(name: &str) -> Option<Status> {
Status::ALL.into_iter().find(|status| status.as_str() == name)
}
/// This status's place in the flow, which is its index in [`Status::ALL`].
///
/// Read rather than spelled, for the reason `mv` reads the same list to decide
/// whether a move goes forward: two orders of the five statuses could disagree, and
/// there is only one flow.
pub fn flow_position(self) -> usize {
Status::ALL
.iter()
.position(|status| *status == self)
.expect("Status::ALL holds every variant")
}
/// The status the flow moves into from here, and nothing at the end of it.
///
/// The three working statuses each have a successor; the two terminal ones have
/// none. Discarded follows done in [`Status::ALL`] only so that leaving it reads as
/// a backward move, so it is nothing's successor even though it sits after one, and
/// nothing moves forward out of done either.
pub fn next_in_flow(self) -> Option<Status> {
match self {
Status::Done | Status::Discarded => None,
_ => Status::ALL.get(self.flow_position() + 1).copied(),
}
}
}
/// Whether a blocker sitting in `blocker` holds up a move into `target`.
///
/// The rule is the columns: a ticket may stand level with what it waits on but never
/// ahead of it, so the move is refused exactly when `target` is further down the flow
/// than the blocker. Level is allowed, which is what lets a pair be committed together
/// and reviewed together; only the last stage still waits for the blocker to land,
/// which is the gate that carries the meaning anyway.
///
/// A finished blocker holds up nothing, and [`is_open`] is where the board decides what
/// finished means. Answered by name rather than by a place in [`Status::ALL`]: discarded
/// sits last there for the stamp rule's sake, and a block that rested on that would
/// change meaning the day the list is reordered.
///
/// Takes the blocker's status as a string because that is what the callers hold, the
/// directory the ticket was found in. A value that is not a status at all holds up every
/// move, the direction [`is_open`] takes with the same value: a fault surfaces instead of
/// quietly letting a dependent past.
pub fn blocks_move(target: Status, blocker: &str) -> bool {
if !is_open(blocker) {
return false;
}
// Abandoning a ticket is not carrying it along the flow, so it owes nothing to what
// it waits on. `mv` asks `check_dependents` on that move rather than this, and the
// answer here agrees so no caller has to route around a wrong one.
if target == Status::Discarded {
return false;
}
match Status::from_name(blocker) {
Some(blocker) => target.flow_position() > blocker.flow_position(),
None => true,
}
}
pub fn status_dirs() -> Vec<&'static str> {
@@ -3174,9 +3247,9 @@ pub const DISCARDED: &str = Status::Discarded.as_str();
///
/// The two terminal statuses do not: done landed and discarded never will, so in both
/// cases there is nothing left to wait for and nothing left to plan around. One spelling
/// for all three readers, because `mv` refuses a move on it, refuses a discard on it and
/// the board draws its blocked mark from it, and two views disagreeing about what counts
/// as open would be the difference nobody can explain later.
/// for every reader, because `mv` refuses a discard on it and [`blocks_move`] answers a
/// finished blocker with it, and two views disagreeing about what counts as open would be
/// the difference nobody can explain later.
///
/// Takes the status as a string because that is what the callers hold: the directory a
/// ticket was found in, not a parsed [`Status`]. An unrecognised value reads as open,
@@ -3282,8 +3355,8 @@ pub struct TicketItem {
///
/// Read here for the reason `criteria` is: the board marks every held-up card on
/// every tick, and asking per card would re-read every ticket body on every draw.
/// The uuids only, never the answer: whether a blocker is still open is a fact
/// about another ticket, so it belongs to whoever holds the whole board.
/// The uuids only, never the answer: how far along a blocker stands is a fact about
/// another ticket, so it belongs to whoever holds the whole board.
///
/// A Relations section that cannot be parsed reads as no blockers rather than as a
/// ticket that cannot be listed. `show` and `mv` still refuse it, which is where a
@@ -6449,4 +6522,104 @@ Plain line with **bold** and a [link](http://x.test/a).
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains("not a directory"), "{error}");
}
// ------------------------------------------------- what a blocker holds up --
/// The column rule over every pair of working statuses: the move is refused exactly
/// when it would land further down the flow than the blocker stands. Level is
/// allowed, which is the whole of it — a pair can be committed together and reviewed
/// together, and only done still waits for the blocker to land.
#[test]
fn a_blocker_holds_up_only_the_moves_ahead_of_it() {
let flow = [
Status::Backlog,
Status::Committed,
Status::Reviewing,
Status::Done,
];
for blocker in [Status::Backlog, Status::Committed, Status::Reviewing] {
for target in flow {
assert_eq!(
blocks_move(target, blocker.as_str()),
target.flow_position() > blocker.flow_position(),
"a blocker in {} against a move to {}",
blocker.as_str(),
target.as_str(),
);
}
}
}
/// A finished blocker holds up nothing, whichever way it finished: done landed and
/// discarded never will, so in both cases there is nothing left to wait for.
#[test]
fn a_done_or_discarded_blocker_holds_up_nothing() {
for blocker in [DONE, DISCARDED] {
for target in Status::ALL {
assert!(
!blocks_move(target, blocker),
"a {blocker} blocker held up a move to {}",
target.as_str(),
);
}
}
}
/// Abandoning a ticket is not a stage of work, so its own blockers have no say. The
/// question `mv` asks on that move is the other one, about the tickets waiting on it.
#[test]
fn abandoning_a_ticket_is_not_held_up_by_its_blockers() {
for blocker in Status::ALL {
assert!(
!blocks_move(Status::Discarded, blocker.as_str()),
"a blocker in {} held up a discard",
blocker.as_str(),
);
}
}
/// A value that is not one of the five is a bookkeeping fault, not a stage, and it
/// surfaces by holding the dependent where it is rather than quietly letting it past.
#[test]
fn a_status_that_is_not_one_holds_up_every_move_along_the_flow() {
for target in [
Status::Backlog,
Status::Committed,
Status::Reviewing,
Status::Done,
] {
assert!(blocks_move(target, "in-progress"), "{}", target.as_str());
}
}
/// Each working status has a successor and the two terminal ones have none, discarded
/// included: it follows done in `Status::ALL` for the stamp rule's sake, not because
/// the flow moves into it.
#[test]
fn only_the_working_statuses_have_a_next_stage() {
assert_eq!(Status::Backlog.next_in_flow(), Some(Status::Committed));
assert_eq!(Status::Committed.next_in_flow(), Some(Status::Reviewing));
assert_eq!(Status::Reviewing.next_in_flow(), Some(Status::Done));
assert_eq!(Status::Done.next_in_flow(), None);
assert_eq!(Status::Discarded.next_in_flow(), None);
}
/// The name a status is stored under reads back as that status, and nothing else
/// reads back as one: the directory a ticket was found in is the caller's only
/// handle on it.
#[test]
fn a_status_name_round_trips_and_nothing_else_resolves() {
for status in Status::ALL {
assert_eq!(Status::from_name(status.as_str()), Some(status));
assert_eq!(
status.flow_position(),
Status::ALL.iter().position(|s| *s == status).unwrap()
);
}
for name in ["Backlog", "", "in-progress", "backlog "] {
assert_eq!(Status::from_name(name), None, "{name:?} resolved as a status");
}
}
}