Files
worklane/docs/relations.md
T
Ansho ReiandClaude Opus 5 a017f9002e (c680e24) Write a warning through a second stream on the sink, and bump to 0.33.2
check_blockers reported a blocker the board does not hold with eprintln!,
the one print site fa5662a left behind: a helper had no sink to reach, and
what it wrote was stderr rather than stdout. Harmless while main was the
only caller, and since 53ffb94 the command prompt runs the same handlers,
where stderr is the alternate screen with the columns on it. ratatui does
not repaint a cell it believes is unchanged, so the fragment stayed until
something else redrew them.

Sink carries two writers instead of one, because the CLI's two streams are
two: Sink::std hands the answer to stdout and an aside to stderr, so a
shell reads the same line on the same stream, and the integration test now
asserts that stderr whole rather than searching it. Sink::buffer holds its
warnings instead, and Board::run reads them back with Sink::warnings and
puts them above the answer on both outcomes -- a mv that warns about a
dangling blocker and is then refused by a real one wrote the aside first,
and it says why the refusal names one blocker and the ticket records two.

check_blockers and check_dependents both take the sink now, so their
refusals take the colour from it as well, rather than asking the process
about a stdout the board is not writing to.

no_handler_or_helper_reaches_a_print_macro walks src for the next print
site, each file cut at its own test module, since the rule is about every
future site rather than the one that broke.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-10 11:53:10 +02:00

21 KiB
Raw Permalink Blame History

Relations

Recording an edge between two tickets, and drawing the block that reports them.

Relating Tickets

  • The Relations section is relate's alone. RELATIONS is in the section table but deliberately out of section_args, so set and append cannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer
  • relate --clear <kind> <target> is the removal, and it is on relate rather than on set for the same reason the section is absent from section_args: one writer owns both directions, the way chown owns setting an owner and clearing one. It names the target and not just the kind, because a ticket can hold several relations of one kind and emptying all of them is not what anybody is asking for. That is also why it is not spelled like set --clear, which names a field and empties the whole of it
  • The two values are one flag, so clap cannot type them apart. num_args = 2 is per occurrence, which is what makes an odd number a usage error and every chunk a full pair; RelateArgs::cleared splits the pairs and parses the kind, so a bad kind is refused before the ticket is resolved. It exits 1 rather than clap's 2, which is the price of a two-value flag and the reason RelationKind::parse_value names the three in its message
  • Both spellings of the kind are accepted, blocked-by from the flag and blocked by from the label. Both are in front of the reader: the flag is what recorded the relation and the label is what show prints and what the file stores, so refusing the printed form would be a trap for anyone clearing a row they just read. RelationKind::flag is a match rather than label().replace(' ', "-"), so the flag, the --clear value and the completion list cannot drift apart
  • find_relation searches the ticket's own edges before the board, and that order is the feature. A dangling edge is the case most likely to need clearing, and no search of the board can reach a target whose ticket is gone, so the id-prefix tier over the stored targets is the only one that finds it. MIN_ID_SEARCH is the floor resolve_in puts under its own id tier and the comparison is case insensitive for the same reason. Two stored targets under one prefix name the candidates rather than guessing, which is what an ambiguous ticket search already does
  • An edge the ticket does not hold reports no change; a target naming nothing at all is an error. The two are different facts: the first is the state the caller asked for, and the second is a typo that reporting no change would swallow. The resolver's own reason is carried through, so an ambiguous search says so instead of being reported as nothing found
  • Recording and clearing the same relation in one call is refused, and the check runs on what was asked for. items drops the additions already in the file, so comparing against that would let --blocked-by X --clear blocked-by X quietly remove an existing X. requested is the full list for exactly that reason. The refusal is set --clear's: nothing is written rather than one direction silently winning
  • Removals rewrite the section and additions are appended to the result, in that order. Two passes rather than one rebuild, so a call with no --clear takes exactly the path it always took and append_section_body goes on deciding where a new line lands. Rewriting from the parsed relations is lossless because a line that is not a relation is already an error. The last edge leaves clear_section_body's placeholder, which is the line append treats as no content, so the next relate replaces it instead of writing under it
  • A relation is not logged, either direction. relate writes no history entry and neither does --clear, which keeps the two consistent; per the history rule, an edge that matters enough to explain gets a comment. Do not add an entry for the removal alone: a log that recorded only the destructive half would read as though the additions had never happened
  • 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
  • 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 warning goes through the sink check_blockers is handed, which is why a guard that says nothing on the happy path takes one at all: the same helper runs from the board's command prompt, where the process's stderr is the alternate screen. See The Command Prompt. 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

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
  • Cell is the unit both renderers take: a run of text, the colour it is drawn in and the modifier it carries, None for the default foreground and for text drawn as it stands. The same trick as the palette itself, where Color::ansi() and From<Color> for ratatui::style::Color keep one colour from existing for one renderer and not the other, and Modifier is that trick a second time for the styles that are not colours
  • Modifier is the first style on a cell that is not a colour, and it is an enum with one variant for the reason the palette is one: Modifier::ansi() is SGR 9 and From<Modifier> for ratatui::style::Modifier is CROSSED_OUT, so a style that exists for one renderer and not the other is a compile error. Bold is not in it, because bold rides inside Color::Magenta.ansi() and span_from adds it back from the colour alone; a second modifier goes here beside the strike. It is independent of the colour, so a struck run keeps whatever colour its column already gave it
  • Cell::struck is a builder, not a third constructor. The strike is decided a whole row at a time and the cells of that row are built by the layout that already chose their colours, so relation_cells maps it over the row it has just finished rather than threading the decision through every cell it makes
  • RESET is a constant both writers share. paint opens a colour and paint_cell may open a modifier ahead of one, and a reset that only knew about the colour would leave the strike running to the end of the line
  • Body::push_cell merges on the whole style, not the colour alone. Nothing outside the relations block carries a modifier today, and a merge keyed on the colour would silently strike a plain run through the moment one did
  • reference_cells is the one spelling of a cross reference. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was a reference_cell beside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone
  • A row carries two marks, kind then status: what sort of edge this is, then how far the ticket at the other end has got. blocked by × ◐ (6ce2c47) Title. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
  • The status went through one bad shape first. It was a rising bar, ▁▄▆█, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
  • Both directions of a kind carry one mark. blocked by and blocks are the same edge read from two ends, and the label is what says which end you are on. both_directions_of_a_kind_carry_one_mark pins it
  • × is BLOCKED_MARK, the same constant a held-up card draws, in the same brightred. On a card it says this ticket is held up and in the block it says this edge is what holds one, which is one word, so one glyph and one definition. It lives in util.rs for that reason, not in tui.rs where the card is
  • The kind marks stay out of the priority vocabulary, which owns ●◐○·, and no_relation_mark_is_a_priority_glyph pins that against every level. They are the arrows the footer already draws, so they render wherever it does
  • The status marks are those very circles, and what keeps them from reading as a level is width: the meter is always two cells and a status mark is one. the_status_mark_is_one_cell_where_the_meter_is_two pins both halves. A card carries the meter and never a status mark, and the block carries the status mark and never a meter, so the two never sit in one column
  • Both marks go ahead of the id, where they describe the target rather than the row. Every row carries both, so nothing is pushed out of line the way the card's blocked mark would have been, which is why that one sits after the id and these before it
  • The kind mark survives a target the board cannot find and the status mark cannot, since a kind is read from the ticket's own file and a status from the board. ? holds the column so the id does not move, and _missing_ in grey is what says the target is gone
  • Committed and reviewing are told apart by colour alone, both being ◐, so a pipe cannot tell them apart: should_use_colors is false and both read as under way. Accepted, because ● and ○ are the two answers usually wanted and show on the target settles the rest, and assets/SKILL.md says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
  • RelationTarget carries the title and the status in one Option, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
  • show and the board carry the same mark, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
  • Resolved.relations is rows, not a rendered block, and Resolved.campaign is cells for the same reason. An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing in Resolved can arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, since content_parts paints nothing at all
  • BodyPart splits the body rather than building it twice. It is Cells or Relations: everything outside the block is laid out once, by content_parts, and content_trim is that run through paint_cells while the board is the same cells run through span_from. Body is the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in places
  • Detail.body is a Text, and it is the only thing measured. last_offset and the Paragraph both take it, so the clamp cannot wrap the body differently from the draw. Detail::plain() flattens it for the suite and is #[cfg(test)]: a second representation carried alongside the spans is a second thing to disagree
  • detail_body closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end. It now splits per cell rather than per part, since a Cells part holds many runs and a newline can fall inside any of them
  • The whole overlay body is coloured now, and content_parts paints nothing. The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the same Cell treatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout that show paints and the board styles. Do not reintroduce a paint call in content_parts: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes
  • colored still reaches content_parts, and it no longer means paint. It says whether this renderer can carry a colour at all, and one thing turns on it: **bold** gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passes true, content_trim passes the CLI's decision, and a piped show still reads its markers. Nothing else in the body consults it
  • Magenta means bold, and span_from is where the board learns that. Color::Magenta.ansi() is \x1b[1;35m, so the CLI draws every bold run bold as well as magenta, and From<Color> can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent
  • The conversion is pinned from both ends. show_prints_the_same_body_it_printed_before_the_cells_conversion holds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite. the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it is the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence
  • The history block arrives as segments too, so nothing in the overlay is flat. history_parts splits the entries into flow runs and quoted runs in one walk; history_cells is their flatten, which is what makes the CLI's bytes a property of the segmentation rather than a second walker free to drift from it, and the board reads the same parts and lays each out itself. Pinned from both ends the way the body is: the pins over format_history hold the flatten byte for byte, and the_block_splits_into_flow_and_quoted_parts pins which runs are whose