Compare commits

...
1 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 00a64adca8 (03bdc76) Draw a symmetric relation once, and refuse the mirror, and bump to 0.32.1
`relate` refused a relation the ticket already held but never looked at what
the target held, so both ends of a `relates to` could store a line. `show` then
drew the same neighbour twice under the same label, since `RelatesTo` maps to
itself in `inverse_label`: one row from the stored line and one derived from the
far ticket's mirror of it, indistinguishable. Live on this board, where 8556048
and 8c8a520 each stored the other.

Both ends of the fix, because they do different jobs. `relation_rows` drops a
derived row that reads exactly like a stored one, which repairs the boards that
already hold both directions without an edit. `cmd_relate` refuses to store the
mirror in the first place, reporting no change since the edge is already
recorded at the far end, which stops it recurring. Neither alone closes it.

The dedupe keys on the **label** and the target, not the kind and the target.
Two tickets each blocking the other is two facts and the block has to say both,
`blocked by` from this end and `blocks` from the other; keying on the kind would
fold them into one row and lose half of what the ticket says. Only a symmetric
kind can collide with its own stored line, and `RelationKind::is_symmetric`
derives that from `label() == inverse_label()` rather than naming `RelatesTo`,
so a kind added later answers by construction. The same gate is what keeps the
refusal off a cycle: a target holding `blocked by <this>` is not a duplicate.

The stored row is the survivor, not the derived one, because it is the line
`relate --clear` can address. The consequence is worth knowing and is written
down: with both ends holding a line, clearing one leaves the other's, which then
draws as the derived row. Correct, since the far end still asserts the relation.

4179958 decided that `relates to` is symmetric and "written once, not onto both
files". Nothing enforced it until now.

The board's own data is left alone. 8556048 and 8c8a520 still both store the
line and the block now draws it once, which is what the criterion asked for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 12:41:49 +02:00
9 changed files with 274 additions and 6 deletions
+4
View File
@@ -182,6 +182,10 @@ and this file is for what someone changing worklane's own code needs.
- **`add` does not write the section.** The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A `_No relations._` block in every new ticket is noise in every `show`, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two
- **The full uuid is stored, not the seven characters `ls` prints.** It resolves without a scan and cannot turn ambiguous as the board grows. `show` renders the short id and the target's title instead: the file is the machine's copy, the output is the reader's
- **One direction is stored and the inverse is derived.** `blocked by` goes on the gated ticket rather than `blocks` on the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency. `relates to` is symmetric and is written once, on whichever end the caller ran it from. `RelationIndex::inbound` finds the far end by scanning, which is what keeps `relate` a single-file write
- **A derived row that reads exactly like a stored one is dropped, and the stored one is kept.** Both ends of a symmetric relation could hold a line, since nothing stopped it until 03bdc76, and the block then drew the same neighbour twice under the same label. The stored row survives because it is the line `relate --clear` can address; the derived one is on a file this ticket does not own
- **The dedupe keys on the label and the target, not the kind and the target.** Two tickets each blocking the other is two facts and the block says both, `blocked by` from this end and `blocks` from the other; keying on the kind would fold them into one row and lose half of what the ticket says. Only a symmetric kind can collide with its own stored line, and `RelationKind::is_symmetric` derives that from `label() == inverse_label()` rather than naming `RelatesTo`, so a kind added later answers by construction
- **`relate` also refuses to store the mirror, which is the other half of the same fix.** The dedupe repairs a board that already holds both directions; the refusal stops it recurring. `mirrored` in `cmd_relate` reads the target's own relations and reports no change, gated on `is_symmetric` because a target holding `blocked by <this>` is a cycle rather than a duplicate. 4179958 decided `relates to` is written once and not onto both files; for six months nothing enforced it
- **A symmetric edge is cleared from the end that stores it.** With both ends holding a line, `--clear` on one leaves the other's, which then draws as the derived row: correct, since the far end still asserts the relation, and the reason the dedupe keeps the stored row rather than the derived one
- **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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.32.0"
version = "0.32.1"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.32.0"
version = "0.32.1"
edition = "2024"
[dependencies]
+1 -1
View File
@@ -13,7 +13,7 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. `--status discarded` is exempt and reachable from anywhere, for a ticket that will not be done; leaving `discarded` is a backward move and needs `-f`. Discarding is refused while open tickets are blocked by the ticket, `-f` overrides. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f`. `--clear <kind> <target>` takes an edge off instead, repeatable, the kind spelled either way, `blocked-by` or `blocked by`. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused |
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning, and a derived row that reads exactly like a stored one is drawn once. `relates to` on a ticket whose target already stores it reports no change, since it is the same edge; `blocked by` and `regression of` read differently from the far end, so a mutual pair is two rows. `mv` refuses to move a ticket blocked by one that is not done, unless `-f`. `--clear <kind> <target>` takes an edge off instead, repeatable, the kind spelled either way, `blocked-by` or `blocked by`. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused |
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
+7
View File
@@ -226,6 +226,13 @@ clearing the same edge in one call is refused outright, the way `set` refuses a
is also replacing, and nothing is written. **Only one side is stored**, on the ticket you name, and `show` derives the other
end for the ticket at the far side, so never record both directions.
`relates to` reads the same from both ends, so recording it on the second ticket is
refused as no change: the edge is already there, from the far side. `blocked by` and
`regression of` are different: the far end reads as `blocks` and `regressed by`, so two
tickets each blocking the other is two facts and the block shows both. A symmetric edge
comes off with `--clear` at the end that stores it, since that is the only end holding a
line to remove.
`--blocked-by` is enforced: `mv` refuses to move a ticket while a ticket it is blocked by
is not in `done` or `discarded`, whichever move it is, and names every open blocker. `-f`
moves it anyway, beside the backward and skipping moves it already allows. It is enforced
+13 -3
View File
@@ -1219,9 +1219,19 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
let relation = Relation { kind, target: target_uuid };
requested.push(relation.clone());
// Already held, either in the file or earlier in this call. Recording it
// twice would read as two dependencies on one ticket.
if existing.contains(&relation) || items.contains(&relation.item()) {
// A symmetric relation the target already stores is already recorded, from
// the other end: `show` derives it onto this ticket by scanning, so a line
// here would be the same edge stored twice. 4179958 decided `relates to` is
// written once and not onto both files, and nothing enforced it until
// 03bdc76. Only the symmetric kind, since the target holding
// `blocked by <this>` is a cycle rather than a duplicate.
let mirrored = kind.is_symmetric()
&& parse_relations(&target, &target_title)?
.contains(&Relation { kind, target: uuid.clone() });
// Already held, either in the file, at the far end, or earlier in this call.
// Recording it twice would read as two dependencies on one ticket.
if existing.contains(&relation) || items.contains(&relation.item()) || mirrored {
continue;
}
+40
View File
@@ -7099,6 +7099,46 @@ mod tests {
}
}
/// One builder behind both views, so the dedupe 03bdc76 added lands on the board
/// without the overlay knowing about it. Criterion 2 names the board as well as
/// `show`, and this is the half that says so.
#[test]
fn a_relates_to_stored_at_both_ends_is_drawn_once_in_the_overlay() {
let dir = board_dir();
let holder = "11111111-0000-4000-8000-000000000000";
let target = "22222222-0000-4000-8000-000000000000";
// Both lines, which is the state a board recorded before `relate` refused the
// mirror. The section goes ahead of the metadata on the holder, where `relate`
// writes it and where the overlay has it on screen.
std::fs::write(
dir.join("backlog").join(format!("{holder}_a-holder.md")),
format!(
"# A holder\n\n## Description\nA description.\n\n## Relations\n\
- relates to {target}\n\n## Metadata\n\n- **ID**: {holder}\n\
- **Priority**: 2\n- **Status**: backlog\n"
),
)
.unwrap();
write_ticket(
&dir,
"reviewing",
target,
"The target",
&format!("\n## Relations\n- relates to {holder}\n"),
);
let mut board = one_board(&dir);
board.toggle_detail();
let body = board.detail.as_ref().expect("no detail").plain();
assert_eq!(
body.matches("relates to").count(),
1,
"the same edge is drawn twice in the overlay:\n{body}"
);
}
/// The body is no longer one string, so the clamp and the draw could measure two
/// different things. They take the same `Text`, and this is what says so: a ticket
/// whose relations run past the overlay scrolls to its last row.
+121
View File
@@ -2123,6 +2123,16 @@ impl RelationKind {
}
}
/// Whether the kind reads the same from both ends, which is `relates to` alone.
///
/// Derived from the two labels rather than listed, so a kind added later answers this
/// by construction. A symmetric kind is the only one whose derived row can collide
/// with its own stored line: `blocked by` from one end reads as `blocks` from the
/// other, and those are two different things to say about one pair of tickets.
pub fn is_symmetric(self) -> bool {
self.label() == self.inverse_label()
}
/// Every kind, so a caller can walk them without listing them a second time.
pub const ALL: [RelationKind; 3] = [
RelationKind::BlockedBy,
@@ -2569,10 +2579,30 @@ pub fn relation_rows(stored: &[Relation], index: &RelationIndex, uuid: &str) ->
})
.collect();
// How each stored row reads, which is what a derived row is checked against below.
// Collected first because the check cannot borrow `rows` while extending it.
let drawn: Vec<(&'static str, String)> =
rows.iter().map(|row| (row.label, row.uuid.clone())).collect();
rows.extend(
index
.inbound(uuid)
// A derived row that reads exactly like a stored one is not a second fact.
// Both ends of a symmetric relation can hold a line, since nothing stopped
// that until 03bdc76, and the block drew the same neighbour twice under the
// same label. The stored row is the one kept: it is the line `--clear` can
// address, where the derived one is on a file this ticket does not own.
//
// Keyed on the label and the target rather than the kind and the target,
// which is what keeps a mutual block as two rows: `blocked by` and `blocks`
// are different things to say about one pair, and only a symmetric kind,
// whose inverse label is its own, can collide with itself.
.into_iter()
.filter(|(kind, holder)| {
!drawn
.iter()
.any(|(label, target)| *label == kind.inverse_label() && *target == holder.uuid)
})
.map(|(kind, holder)| RelationRow {
kind,
label: kind.inverse_label(),
@@ -5655,6 +5685,97 @@ Plain line with **bold** and a [link](http://x.test/a).
}
}
/// `relates to` alone reads the same from both ends, and it is derived from the two
/// labels rather than listed, so a kind added later answers by construction.
#[test]
fn only_relates_to_is_symmetric() {
for kind in RelationKind::ALL {
assert_eq!(
kind.is_symmetric(),
kind == RelationKind::RelatesTo,
"{kind:?} claims symmetry it does not have, or has one it does not claim"
);
assert_eq!(kind.is_symmetric(), kind.label() == kind.inverse_label(), "{kind:?}");
}
}
/// Both ends of a symmetric relation can hold a line, since nothing stopped that
/// until 03bdc76, and the block drew the same neighbour twice under the same label.
/// The derived row goes and the stored one stays: it is the line `--clear` can
/// address, where the derived one lives on a file this ticket does not own.
#[test]
fn a_derived_row_that_reads_like_a_stored_one_is_drawn_once() {
let index = RelationIndex::new(vec![related(
TARGET,
"The neighbour",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
)]);
let stored = vec![relation(RelationKind::RelatesTo, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 1, "the same edge is drawn twice: {rows:?}");
assert_eq!(rows[0].label, "relates to");
assert_eq!(rows[0].uuid, TARGET);
// The stored one, which is what `--clear` addresses. Both ends carry the same
// label here, so the label cannot say which survived: the count is what does.
assert_eq!(
render_relations(&rows, false),
format!("relates to {RELATES_MARK} {} (b1b2c3d) The neighbour\n", smark("backlog"))
);
}
/// Only where the row would read the same. A pair of tickets each blocking the other
/// is two facts, and the block says both: `blocked by` from this end and `blocks`
/// from the other. Deduping on the kind rather than on the label would have folded
/// them into one and lost half of what the ticket says.
#[test]
fn a_mutual_relation_of_an_asymmetric_kind_keeps_both_rows() {
for kind in RelationKind::ALL.into_iter().filter(|kind| !kind.is_symmetric()) {
let index = RelationIndex::new(vec![related(
TARGET,
"The other one",
"backlog",
vec![relation(kind, SELF)],
)]);
let stored = vec![relation(kind, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 2, "{kind:?} lost a row: {rows:?}");
assert_eq!(rows[0].label, kind.label(), "{kind:?}");
assert_eq!(rows[1].label, kind.inverse_label(), "{kind:?}");
}
}
/// The dedupe is per target, not per kind: a second neighbour holding its own
/// `relates to` is a different edge and keeps its row.
#[test]
fn a_second_neighbours_derived_row_survives_the_dedupe() {
const OTHER: &str = "cccccccc-1111-4222-8333-444444444444";
let index = RelationIndex::new(vec![
related(
TARGET,
"The neighbour",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
),
related(
OTHER,
"Another one",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
),
]);
let stored = vec![relation(RelationKind::RelatesTo, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 2, "{rows:?}");
assert_eq!(rows[0].uuid, TARGET, "the stored row is not first: {rows:?}");
assert_eq!(rows[1].uuid, OTHER, "the other neighbour was dropped: {rows:?}");
}
/// Both directions of one kind carry the same mark, since the kind is what the mark
/// says and the label is what says which way it points.
#[test]
+86
View File
@@ -714,3 +714,89 @@ fn a_clear_with_one_value_is_a_usage_error() {
assert_eq!(out.status.code(), Some(2), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}
/// The far end already stores it, so the edge is already recorded: `show` derives it onto
/// this ticket by scanning. A line here would be the same edge on two files, which
/// 4179958 decided against and nothing enforced until 03bdc76.
#[test]
fn a_relates_to_the_target_already_stores_is_not_stored_again() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", BLOCKER, "--relates-to", GATED]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--relates-to", BLOCKER]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before, "the mirror was stored anyway");
// Still shown, since it was recorded at the other end.
let shown = stdout(&run(&temp, &["show", GATED]));
assert_eq!(shown.matches("relates to").count(), 1, "{shown}");
}
/// A board that already holds both directions draws the edge once. The refusal above
/// stops it recurring; this is what repairs a ticket that already has it, without an edit.
#[test]
fn a_relates_to_stored_at_both_ends_is_drawn_once() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
// Both lines written directly, which is the state a board recorded before the refusal
// is in. The CLI will not produce it any more, so nothing else can set this up.
for (holder, target) in [(GATED, BLOCKER), (BLOCKER, GATED)] {
let path = find(&worklane, holder);
let content = fs::read_to_string(&path).unwrap().replace(
"## Metadata",
&format!("## Relations\n- relates to {target}\n\n## Metadata"),
);
fs::write(&path, content).unwrap();
}
let shown = stdout(&run(&temp, &["show", GATED]));
assert_eq!(shown.matches("relates to").count(), 1, "the edge is drawn twice:\n{shown}");
assert_eq!(shown.matches(&BLOCKER[..7]).count(), 1, "{shown}");
// And from the other end, which stores its own line and derives this one.
let far = stdout(&run(&temp, &["show", BLOCKER]));
assert_eq!(far.matches("relates to").count(), 1, "{far}");
}
/// Only where the row reads the same. Two tickets each blocking the other is two facts,
/// and the block says both: `blocked by` from this end, `blocks` from the other.
#[test]
fn a_mutual_block_is_still_drawn_from_both_ends() {
let temp = TempDir::new().unwrap();
board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", BLOCKER, "--blocked-by", GATED]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(
!stdout(&out).contains("No changes"),
"the second was refused: {}",
stdout(&out)
);
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("blocked by"), "{shown}");
assert!(shown.contains("blocks"), "the derived direction was dropped:\n{shown}");
}
/// The same for the other asymmetric kind, whose inverse label also differs from its own.
#[test]
fn a_mutual_regression_is_still_drawn_from_both_ends() {
let temp = TempDir::new().unwrap();
board(&temp);
run(&temp, &["relate", GATED, "--regression-of", BLOCKER]);
run(&temp, &["relate", BLOCKER, "--regression-of", GATED]);
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("regression of"), "{shown}");
assert!(
shown.contains("regressed by"),
"the derived direction was dropped:\n{shown}"
);
}