Compare commits

..
21 Commits
Author SHA1 Message Date
Ansho Rei b439ad9c41 (7f772a7) Repair a Status field that lags its directory on mv, and bump to 0.32.6 2026-08-25 16:14:05 +02:00
Ansho Rei 455f04d136 (3ca1d0c) Record the tag picker's design in the Board View section 2026-08-25 16:13:38 +02:00
Ansho Rei cac21a94f5 (8f650fc) Refuse a tab in a tag annotation, and bump to 0.32.5 2026-08-25 15:26:08 +02:00
Ansho Rei 8c599440e5 (8020e48) Quote a comment behind a gutter bar that survives wrapping, and bump to 0.32.4 2026-08-25 15:19:01 +02:00
Ansho Rei a92dbf552f Teach the skill to assume WORKLANE_ACTOR and reserve --actor for another's action 2026-08-25 13:57:36 +02:00
Ansho Rei b93b8e1b81 (d447e04) Render each comment behind a grey bar spanning its length, and bump to 0.32.3 2026-08-25 13:56:55 +02:00
Ansho ReiandClaude Opus 5 f0f88025f3 (938a887) Colour the footer's keys and merge them into their words, and bump to 0.32.2
Every key hint on the board was one flat grey string, `←→ column   ↑↓ card
/ search   y copy id   enter detail   d show done (3)   q quit`, so nothing
separated a key from what it does and a reader looking for one read the row word
by word. frig and pantop both colour the key, and the three are read side by
side.

`key_hint` is the only thing that draws a hint now: the key cyan and bold, the
description in the terminal's default foreground, one span each. The three
footer states, the prompt's two keys, the picker's row and the `q board` on the
frame's border all go through it, so the shape is learnt once and cannot drift
between rows. Cyan here and magenta in pantop is the rule and not an
inconsistency: one accent per tool, the one that tool already uses.

**A key that is its description's first letter is merged into it.** `q quit` is
drawn `quit` with the `q` coloured, `c campaign` is `campaign`, `t tag` is
`tag`. `y copy id`, `ctrl-c quit`, `d show done (2)` and every arrow row stay
split, so the row carries both forms at once, which is what the two cells are
worth on a row already at its width naming eight keys. The prefix test is case
sensitive, and that is not fussiness: a row naming both `r` and `R` would draw
one word for the two of them, and the merged form can only say which key it is
while the letter it colours is that key. frig has such a pair and needs it.

`enter` is written `↵` everywhere it is named, which is the other two cells.

The rows are lists of `(key, description)` pairs rather than format strings, so
the tab slot, the two filter keys and the `d` slot come and go by pushing a pair
or not. They were fragments carrying their own trailing spaces, spliced into
three format strings that had to agree about the spacing between them.

The frame's border hint is measured over its spans instead of one string, since
it is three of them now. It still drops the indicator first and then itself,
whole either way.

The grey was argued for in comments, and the argument is reversed rather than
deleted: the row is still chrome, but a key nobody can pick out of it is chrome
that has to be read word by word to be used. What that costs is on the prompt,
where the query now sits in the same foreground as the descriptions beside it.
The cursor is what says which half is an input, and it does that in a terminal
with no colour at all.

**The footer tests read cells, not text.** Three of the guards that keep
1b78a24 out were `!contains("q quit")`, and once `q quit` is spelled `quit`
every one of them passes whatever the row says, because the split `ctrl-c quit`
contains the merged form. `keys_on` answers with how many cells the word opens
with in the key colour: `Some(1)` is `q` quitting, `Some(0)` is the word sitting
in the tail of `ctrl-c quit`, and `None` is a key the row does not name at all.
`!contains("enter detail")` on the frame row would have joined them the moment
the spelling changed, and is now `↵ detail`.

AGENTS.md carries the rule, the merge and the case sensitivity, and the palette
gains the one colour it spends on something that is not a value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 13:11:31 +02:00
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
Ansho ReiandClaude Opus 5 0f0767ac00 (8556048) Take a relation off with relate --clear, and bump to 0.32.0
`relate` only added. A `--blocked-by` pointed at the wrong ticket was on that
ticket forever, refusing every move it made until the target was done or `-f`
was passed again, and a target that was deleted did not clean up either: the
board carried a dead edge that nothing could clear and every later read of the
ticket paid for.

`--clear <kind> <target>` takes one off. It is on `relate` rather than on `set`
for the reason `RELATIONS` is out of `section_args`: a relation names a target
that has to be resolved first, so 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 the way `set --clear` is, which names a field and empties it whole.

Both spellings of the kind are taken, `blocked-by` from the flag and
`blocked by` from the label: both are in front of the reader, the flag being
what recorded the relation and the label what `show` prints and the file
stores, so refusing the printed form would trap anyone clearing a row they had
just read. `RelationKind::flag` is a match rather than a `replace` on the
label, so the flag, the `--clear` value and the completion list cannot drift.

`find_relation` searches the ticket's own edges by id prefix before it searches
the board, and that order is the feature rather than an optimisation: no search
of the board reaches a target whose ticket is gone, so the stored-target tier
is the only thing that can clear a dangling edge, which is the case most likely
to need clearing. Two stored targets under one prefix name the candidates
instead of guessing, as an ambiguous ticket search already does.

An edge the ticket does not hold reports no change, and 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 a no-op would swallow. The
resolver's own reason is carried through, so an ambiguous search says it is
ambiguous rather than 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 and not on what would be written. A relation
already in the file is not among the additions, so comparing against those
would have let `--blocked-by X --clear blocked-by X` quietly remove it.

Removals rewrite the section from what is left and additions are appended to
that, in that order and in two passes: a call with no `--clear` then takes
exactly the path it always took. The last edge leaves the placeholder, which is
the line `append` treats as no content, so the next `relate` replaces it rather
than writing underneath it.

The two values are one flag, so clap cannot type them apart. `num_args = 2` is
per occurrence, which makes an odd number a usage error and every chunk a full
pair, and `cleared` parses the kind before the ticket is resolved. Nothing is
logged, in either direction, since `relate` never has: a log recording only the
destructive half would read as though the additions had never happened.

`chowns_clear_is_completed_with_tickets_and_sets_is_not` found the first rule
carrying `-l clear` and there are now three, on three commands, each taking
something different. It is `each_clear_flag_is_completed_for_its_own_command`,
scoped per command, and `relate --clear` offers the kinds rather than a board
listing, since tickets where the kind goes would be candidates it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 12:13:37 +02:00
Ansho ReiandClaude Opus 5 7994d98913 (76d10d7) Strike through a relation to a discarded ticket, and bump to 0.31.5
The relations block marked a target `○ ◐ ●` or `?`, and none of those can say
the target was discarded: the status mark is one cell in a column of five
states, and `●` in grey against `●` in green is a colour a pipe does not get.
A row pointing at abandoned work therefore read as a live dependency, which is
exactly what it is not.

The row is struck through instead, the whole of it, gutter and padding
included, so the line runs unbroken from the label to the end of the title.
The relation stays recorded, for completeness and for the case the target is
moved back out of discarded, and reads at a glance as no longer standing for
anything. The mark column is untouched: 451fb83 already gave a discarded
target the full circle of done in the grey of the untouched pile, and the
strike is additive on top of that.

`Cell` learns a modifier, the first style on it that is not a colour. Same
trick as the palette, one step further: `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 stays
out of it, because bold rides inside `Color::Magenta.ansi()` and `span_from`
adds it back from the colour alone; a second modifier goes beside this one.

`paint_cell` opens the modifier ahead of the colour and closes both with one
reset, which is why the reset is now a constant the two writers share rather
than a literal in `paint`. `span_from` takes the modifier too and has no early
return for the uncoloured case any more: a struck plain run is a styled span
with no foreground. `Cell::struck` is a builder, because the strike is decided
a whole row at a time by the layout that already chose the colours.

`Body::push_cell` merges on the whole style rather than 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.

The strike is under the same flag every other escape is, so a piped `show`
carries none of it. That is the bargain committed and reviewing already take
for being told apart by colour alone, and `assets/SKILL.md` says so outright
rather than leaving an agent to infer that a plain-looking row may point at
abandoned work.

Tests are paired both ways, and both halves are load bearing: a renderer that
struck nothing fails the presence, and one that struck every row fails the
absence. `the_status_marks_are_pinned` had never listed discarded, so it does.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 11:53:45 +02:00
Ansho ReiandClaude Opus 5 d1a0f0ee27 (2a83bd4) Frame the tag-filtered board with the tag's annotation, and bump to 0.31.4
A board filtered to a tag now says which tag, the way a board filtered to a
campaign says which campaign. The frame slot above the columns is shared, not
doubled: one filter is on at a time, per `Filter`, so the row and the geometry
`Chrome` computes stay as they are and only what is drawn into them changes.

`FrameContent` is what the two are told apart into, and `frame_content` is the
one place they are told apart at all. Everything below it is the campaign
frame's: the borders, the colour, `q board`, the page indicator, the scroll,
the focus and `enter`. A second match on the filter under there is how the two
frames would come to behave differently in a way nobody decided.

The tag goes on the top border as `#tag`, in the colour a card draws it in,
because `~v1` against `#bug` is what says at a glance which filter emptied the
columns. How many tickets carry it goes on the bottom right where the standing
goes, counted off every column, drawn or not. The annotation fills the prose
rows, wrapped and scrolled the way ebad2fa made the description.

An undeclared tag draws `NO_ANNOTATION` in grey rather than a blank row, which
is also the frame saying the word was never agreed on. The vocabulary file's
own placeholder and not the description section's, so the frame and `tags.md`
say the same thing about the same tag.

Nothing in the geometry is named after campaigns any more. `Chrome::campaign`
is `Chrome::frame`, `CAMPAIGN_ROW` is `FRAME_ROW`, and `Chrome::campaign_rows`
is `Chrome::frame_rows` — which collided with the free `frame_rows` that lays
out the whole screen, so that one is `screen_rows`.

`y` on a tag frame copies the tag, since a tag is its own id and the hash the
border draws is not part of what `--tag` matches. The footer's tag span and its
`q board` slot are gone: 0fd1ddc put them there for want of a frame to say it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 11:41:35 +02:00
Ansho ReiandClaude Opus 5 45b513bdce (2733b10) Colour the history block, and indent a comment's body deeper, and bump to 0.31.3
The block shipped with three painted things: the heading, the kind label
and the actor with its timestamp as one cyan span. Every value in it was
plain, so a status entry drew two status names in no colour while the
same names are orange in the metadata table three lines above, and a tags
entry drew its tags without the slots every other view gives them.

The kind label is now grey, as chrome that names a row. It was orange,
which means Status everywhere else, so an `owner` or `tags` label claimed
a meaning belonging to the value beside it. `From` on a comment's author
line goes grey for the same reason.

Each value takes the meaning its field carries in the metadata table:
status orange, tags through the same `tag_cells` the Tags field uses, a
campaign codename through `tag_color` bare the way `Codename` is, an
owner plain, and `_Not set_`, `_None_` and `_missing_` grey. The
separator is a constant beside `change`, with `split_change` next to it,
so the writer and the reader cannot disagree about what divides the two
halves.

The actor is drawn through `tag_color`, so one writer is one colour in
every entry it wrote, and cyan goes back to meaning the timestamp alone.

A comment's body moves to four spaces and the author line stays at column
0, so an indented line is somebody's own words and a line of values at
column 0 is the tool reporting itself.

The padding is still measured on the unpainted label, now pinned with the
alignment test running both ways.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 10:54:36 +02:00
Ansho Rei ab337ca7f8 (1f1b321) Record a move's reason in its history entry, and bump to 0.31.2 2026-08-25 10:38:04 +02:00
Ansho Rei 60b43a682e (a136d13) Draw the discarded column behind a three-state visibility rotation, and bump to 0.31.1 2026-08-25 03:33:38 +02:00
Ansho ReiandClaude Fable 5 5bf0fd1bfe (451fb83) Add a discarded status for work that will not be done, and bump to 0.31.0
The flow ended at done, so a ticket that turned out to be a duplicate or
obsolete had nowhere to go: it sat in the backlog or was deleted by hand,
which destroyed the record and left every relation to it dangling. Discarded
is a fifth status with its own directory, keeping the invariant that the
filename, the Status field and the directory agree, and keeping done meaning
the work landed.

Entering it is allowed from any status without -f, because discarding is not
a stage of work. Discarded sits last in Status::ALL, which is what makes the
rest fall out rather than needing cases: nothing follows it, so a discard
clears no stamp and a ticket abandoned from reviewing keeps the journey it
made, and every move out is a backward move, so un-discarding needs -f.

The two dependency guards now look opposite ways. check_blockers asks what a
ticket waits on and gates work moves; check_dependents asks who waits on it
and gates the discard, because those plans depended on work about to be
declared never-happening. Both skip targets that are themselves terminal.

Status::FLOW is the four stages the board draws, so a discarded column on
screen stays a136d13's ticket and done stays the last drawn column. Every
tree walker keeps using Status::ALL, or a discarded ticket would be
unaddressable.

util::is_open replaces three spellings of "not done and not discarded",
across mv, ls and the campaign standing. The board's blocked mark goes
through it as well: that path was only accidentally correct, since a
discarded blocker is absent from the FLOW columns, and drawing the column
later would have diverged it from what mv allows.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 19:44:14 +02:00
Ansho ReiandClaude Fable 5 c03f47c52d (f774a33) Record a campaign move in the history log, and bump to 0.30.0
assign was the only field writer without an entry: a ticket could leave one
campaign for another with nothing recording it. Kind gains Campaign, assign
gains the --actor flag the other four writers carry, and the entry is written
after the save and behind the no-change return, the rule every writer follows.

The entry records Campaign::name, the codename or failing that the title,
settled when the entry is written so a rename cannot change what an old entry
means. The uuid the field holds says nothing in a log line, and a before-uuid
the board no longer has reads _missing_, the way the Campaign field itself
renders a dangling one.

campaign is the longest mechanical label, so LABEL_WIDTH widens from 6 to 8
and every mechanical row moves two columns right, a deliberate output change
that makes this a minor alongside the new flag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 15:49:50 +02:00
Ansho ReiandClaude Fable 5 9d17f55860 (f3e099e) Colour the history block in the detail overlay, and bump to 0.29.1
The board appended the block as a pre-rendered string with colour off, the
last flat piece of a body e4d0bb7 had fully styled. history_cells lays the
block out once: format_history is those cells painted for the CLI, and
detail_of pushes the same ones as a Cells part, so the overlay styles them
and no escape can enter. The CLI's output is pinned byte for byte, and the
overlay test pairs the presence of the colours with the absence of escapes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 14:49:24 +02:00
Ansho ReiandClaude Opus 5 f454d212a4 (d4ce964) Record status, owner and tag changes in a history log, and bump to 0.29.0
The comments directory was already an append-only log with one event
kind. It is now .worklane/history/<uuid>/, with the kind in the entry
and in the filename after the stamp, so a ticket says how it got where
it is and not only what was said about it.

mv, chown and set --tags each write an entry after their own save and
behind their own no-change return, so a refused or no-op edit records
nothing. --actor is on all four writers now. An old comments directory
is adopted on first access and a file with no marker reads as the
comment it is, so nothing is migrated or rewritten.

The log moves to src/history.rs, out of util.rs and handlers.rs, and
the card's counter counts comments only: a ticket that has moved three
times has not been talked about.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 13:19:09 +02:00
Ansho ReiandClaude Opus 5 a1bdb5df49 (87862df) Attribute an entry to WORKLANE_ACTOR, not to the git user, and bump to 0.28.0
Every comment the CLI wrote was attributed to the git user, so a board
several agents write to read as a list of things one human had done.
resolve_actor is now the single source: flag, then WORKLANE_ACTOR, then
get_git_user(), then unknown.

comment --owner is renamed to --actor with no alias, since it names the
writer of the entry and not the ticket's assignee, which is chown's.
add --owner and campaign add --owner still default to the git user.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 12:34:51 +02:00
Ansho Rei c2ee165108 (e4d0bb7) Colour the whole detail overlay body, not just its relations, and bump to 0.27.3
The block was the only coloured part because it arrived as rows while
everything else arrived as a painted string, and the board had to ask for
the unpainted one: an escape in a ratatui paragraph is drawn as literal
bytes.

content_parts now paints nothing. BodyPart::Text becomes
BodyPart::Cells, so content_trim is the cells through paint_cells and the
board is the same cells through span_from. push_heading, ordered_cells,
inline_cells, metadata_cells, metadata_value_cells and tag_cells replace
the painters they were. Resolved.campaign is cells too, which made
reference_cell dead at its last caller.

The colored flag still reaches content_parts and 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.

Color::Magenta.ansi() is \x1b[1;35m, so span_from adds the bold modifier
on the board's side, since From<Color> carries only the colour and the
same cell must not be painted two ways.

show's output is pinned byte for byte against what it printed before,
both by a fixture holding one of every painted run and by diffing the
old binary against the new one over every ticket and campaign on this
board, coloured and piped.
2026-08-24 11:57:25 +02:00
Ansho Rei 407cb14fe6 (e6e3a1b) Guard the README command table against a missing row
The campaign and assign rows landed with 528566d. What was left was the
checking, done here against the built binary rather than against the
ticket that added them.

The campaign ls row was incomplete: the listing also prints the derived
state, [open] until every member is done and [done] after, and reads
"no members" with no state for a campaign nothing has been filed
against, which is neither. Corrected.

every_subcommand_has_a_row_in_the_readme_command_table walks clap's own
subcommands, one level of nesting included, against the table's rows.
Two commands hid behind an otherwise complete table for two minor
versions because the only thing walking it was somebody remembering to.
The tag subcommands are named in a PENDING list rather than skipped,
since f7dd1a1 rewrites that row.
2026-08-24 11:28:32 +02:00
27 changed files with 6744 additions and 1042 deletions
+127 -47
View File
@@ -7,6 +7,7 @@
- `src/handlers.rs` - one `cmd_*` per subcommand
- `src/util.rs` - the ticket format, resolution, rendering and the palette
- `src/campaign.rs` - the campaign file format, its resolution, its index and its members
- `src/history.rs` - the history log: the path, the kinds, the reader, the writer, the card's counter and the block `show` and the board both render
- `src/tui.rs` - board state, the change digest, and the ratatui draw
- `src/clipboard.rs` - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
- `src/install.rs` - the embedded agent assets and the compare-and-refuse install
@@ -16,23 +17,33 @@
- `assets/ADMIN.md` - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against `PLAN.md` in both directions: this one decides the vocabulary, that one applies it
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `history.rs` and `tui.rs`
- Ticket files stored as `.md` in `.worklane/<status>/` directories
- History entries stored as `.md` in `.worklane/history/<ticket_uuid>/`, one file per entry, beside the status directories for the reason campaigns are
- Campaign files stored as `.md` in `.worklane/campaigns/`, which is beside the status directories and deliberately not in `status_dirs()`
## Ticket File Format
- Filenames: `<uuid_v4>_<slug>.md`
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Discarded On`, `Campaign`, `Status`. The last five are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The four stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **`Discarded` is last in `Status::ALL`, and that placement is what makes the stamp rule fall out right.** Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps `Committed On` and `Submitted On`, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs `-f` without a rule of its own. `Discarded On` is its stamp, and `Completed On` stays untouched, because a discarded ticket was never done
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- Format: `**Field Name**: value`
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
- History entries stored in `.worklane/history/<ticket_uuid>/<stamp>_<kind>.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`, `**Campaign**`), then the body, then `**Author**` and `**Time**`. See The History Log
## Status Workflow
`backlog` → `committed` → `reviewing` → `done`
`backlog` → `committed` → `reviewing` → `done`, and `discarded` off to one side
- **`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
- **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()`
**How to use worklane is in `assets/SKILL.md`, not here.** That document is what
`worklane install-skill` ships, so it is the one place the flow, the move-as-you-work
@@ -43,7 +54,7 @@ and this file is for what someone changing worklane's own code needs.
## Testing
- Run: `cargo test`
- Tests use `assert_cmd` and `assert_fs` for CLI testing
- `setup_worklane()` creates temp `.worklane/` with all four status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it
- `setup_worklane()` creates temp `.worklane/` with the four flow status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it. **The fixtures deliberately do not create `discarded/`**, so every discard test runs against a board that predates the status and `mv_creates_the_discarded_directory_on_a_board_that_predates_it` is not the only thing exercising the on-demand creation
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
- **Every unit-test fixture directory goes through `util::Fixture`, and nothing calls `remove_dir_all` at the end of a test.** `Fixture::new(prefix)` makes a uuid-named directory under the system temp dir and its `Drop` removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: `/tmp` reached 18363 of these and filled the disk, failing a link step and then a `git add` with "No space left on device", an error naming neither the tests nor what they left behind
- **`Fixture` derefs to `Path` and also implements `AsRef<Path>`**, because the two reach different call sites: a parameter typed `&Path` is a coercion site and one bound by `impl AsRef<Path>` is not. `Fixture::child(name)` points the fixture at a directory inside itself while still removing the parent, which is the tree `project_tree` needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than `assert_fs::TempDir` — that names its directories `.tmpXXXXXX`, which says nothing about whose they are
@@ -160,9 +171,21 @@ and this file is for what someone changing worklane's own code needs.
### 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
@@ -175,7 +198,7 @@ and this file is for what someone changing worklane's own code needs.
- **A campaign's state is derived, never stored.** Open until every member is done, computed by `Standing` from the members. A `Status` field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no `campaign mv` and no forward-only ruleset beside `mv`'s
- **A campaign with no members is neither open nor done.** `Standing::state()` returns `None` there, and both callers print `no members`. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
- **Membership is one field on the member**, `Campaign` in the ticket Metadata, written only by `assign`. The member list is deliberately *not* on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So `add` has no `--campaign` and `set` has no `--campaign`, the same rule as Owner and Status
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cell` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cells` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **`add` does not write the field.** Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of `add` means one path that is always exercised rather than two. Same reasoning as the Relations section
- `set_or_insert_metadata_field()` is the upsert, and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no `## Metadata` heading is an **error, not an insertion**: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
- **The four tiers are `resolve_in()`, shared by tickets and campaigns.** A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. `Found.dir` is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
@@ -224,12 +247,15 @@ and this file is for what someone changing worklane's own code needs.
- The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back
- Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top. The index is shared and clamps permanently when a shorter column pulls it down, so a column you return to follows the selection to where it now sits rather than holding your old place
- **The footer names only keys that work.** It read `↑↓ scroll` when nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete
- **A hint is a key and what pressing it does, and `key_hint` is the only thing that draws one.** The key is cyan and bold, the description takes the terminal's default foreground, and the row keeps its three-space gaps. Everything that names a key goes through it: the three footer states, the prompt's two keys, the picker's row and the `q board` on the frame's border, so a reader learns the shape once. Same division in frig and pantop, each in its own accent colour, cyan here and magenta there — the three tools are read side by side and used to look like three programs
- **A key that is its description's first letter is merged into it**, so the board draws `quit`, `campaign` and `tag` with the letter coloured and no letter in front, while `y copy id`, `ctrl-c quit`, `d show done (2)` and every arrow row stay split. Two cells back on a row already at its width naming eight keys, and the coloured letter *is* the key either way. The prefix test in `key_hint` is case sensitive for exactly that reason: a row naming both `r` and `R` would otherwise draw one word for the two of them, and the merged form can only say which key it is while the letter on screen is that key. It also means the row carries both forms at once, which is the cost of the two cells
- **What the row is cannot be read off its text any more, so the tests read its cells.** `footer_cells`, `footer_at`, `keys_on` and `footer_style` in the test module: `keys_on(.., "quit")` is `Some(1)` where `q` quits and `Some(0)` on a row whose only `quit` is the tail of `ctrl-c quit`. A `contains("q quit")` cannot tell those apart, and three of the guards that keep 1b78a24 out were written that way
- **`q` and `esc` are one key: close what is open, quit when there is nothing left to close.** `q` used to set `should_quit` outright, so a reader who pressed it to put a ticket away lost the board instead, which is not what `q` does anywhere else that lays a document over a list. One match arm in `main.rs`, not two: two arms carrying one rule is how a later edit changes it for one key and not the other
- **The rule is `Board::dismiss`, not the match arm.** The dispatch in `main.rs` is not reachable from a test, so anything decided there is undecidable by the suite. The arm is the line that names the keys and nothing else. `the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quitting` scans `main.rs` for what the arm cannot say for itself, over whitespace-collapsed source so rustfmt cannot fail it
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on saying `q quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on drawing the merged `quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do. `ctrl-c quit` is split by the same rule that merges the other, being no word's first letter
- **The overlay names its ticket on the border, not at the head of the paragraph.** `Board::detail` is a `Detail` carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: `content_trim` drops the `# ` heading on purpose, since `cmd_show` prints it, and anything in the paragraph scrolls away
- `detail_title` cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
- The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason
- The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_history_with` take the colour decision for the CLI's side of the same layouts
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
@@ -237,63 +263,70 @@ and this file is for what someone changing worklane's own code needs.
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
- **`corner_line`'s right side is a group, single-spaced, and it gives up its items from the front.** The item nearest the edge is what the corner is *about*; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an `Option`. The spacing between the items lives in `corner_line` with the gap arithmetic rather than in a caller, for the reason `column_areas` is shared: geometry reproduced by hand drifts from the draw. `due_span` returns a `Span` and not an `Option<Span>` now, since the `Option` only ever existed to satisfy the old signature and the function cannot fail
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The comments live outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_comments` applies, and no body is read, because a count needs none of them. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the comments of another. `comments_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The history lives outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_history` applies, and no body is read, because a count needs none of them. **It counts comments and not entries**, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. `history_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
- **The count is cyan and the mark is `COMMENT_MARK`, U+275E, a Dingbat.** It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where `spans_width` counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the comments directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the history directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cells` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `column_count` and the copy key all keep working unchanged
- **A campaign filter is a uuid on the tab, not on the `Board`.** `Tab::filter` is a `Filter`, and a campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::frame` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign or a tag, because both heights have to be measured the same way by everything that measures the board. `screen_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `FRAME_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to. **Nothing in the geometry is named after campaigns**, because the slot is the tag filter's too: `Chrome::frame` says how tall the frame is and never which filter filled it, so a measurement of the board never has to ask
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **`FRAME_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::frame_rows` takes the height because of this, and `screen_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `FRAME_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
- **The frame slot is shared between the two filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what the two are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the two frames come to behave differently in a way nobody decided
- **A tag frame draws the annotation, which is the payoff for declaring a tag.** Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in `tags.md`, which they would have to know to open. An undeclared tag draws `NO_ANNOTATION` in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
- **A tag has no id, so `y` on its frame copies the word.** A tag *is* its name, matched whole by `ls --tag`, so there are no seven characters to shorten and the `#` the border draws is not part of it — `--tag "#bug"` matches nothing. The footer says `y copy tag` there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
- **The count on a tag frame is every column's, drawn or not**, the rule the standing holds. With the filter on, those columns *are* the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no `[open]` to be in
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with either filter on the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no filter is on is the one state that must never exist — `select_filter` and `reload` are what keep it from arising, off `Filter::is_whole` rather than off which filter it is, since either draws a frame to hold it
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
- **The toggle re-clamps the frame offset, through `scroll_frame(0, screen)`.** A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next `pgup` counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows, and measured over its spans rather than one string since it is a key hint like any other. Drawn through `key_hint` and not as grey chrome: it is the one key on the board named anywhere but the footer, and a reader who has learnt to look for the cyan letter should not need a second convention to find it. The indicator beside it stays grey, having no key in it
- **`c` and `t` are named in the footer only on a closed board with nothing filtered**, which is where a reader has to find them. Over an open ticket and on a filtered board they are left out: the frame's border then says how to put the filter away, and the row has no cells to spare. The tag used to be drawn on that row in its own colour, for want of a frame to draw it in, and 2a83bd4 took that away rather than saying it twice. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `↵ expand` or `↵ collapse`, the two scroll keys and `y copy id` — `y copy tag` on a tag frame — and leaves out `←→` because they do nothing there. It has to say which way `↵` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
- **`t` opens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it.** Every tag the board declares or carries, matched whole and case sensitively the way `ls --tag` matches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesy `c` pays a campaign-filtered board, and a board carrying no tag gets the same `Notice` a board with no campaigns gets
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
- **One picker serves both lists, and `PickerRow::key` is what keeps it one.** A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead `PickerKind` decides only which list is built and what the answer filters, and everything between the keypress and the filter runs once against the key — a campaign is keyed by its uuid and a tag by itself, both strings the tab can be filtered by. Picking either clears the other without either setter remembering to, because `select_filter` replaces one `Filter`: one field, which is the same reason the frame slot is shared
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
- **The tag sections are declared above undeclared, and truncate neither.** The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too: `tags.md` is what the board intends, and the vocabulary the listing reports is the one the picker offers. `campaign` and `campaigns` would have sat one under the other here, in different sections, the day the second was invented
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
- **A heading is drawn only over rows that exist**, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
- **`open` and `completed`, not `open` and `done`.** The split is taken from `Standing::state`, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not *in* done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
- **Headings and the truncation line take no number: the highlight moves over campaigns only.** `stepped_picker_row` walks past the chrome rather than stopping on it, since a highlight resting on a heading gives `enter` nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though `--tag` is not, because matching a tag is the filter and searching for one is a reader typing. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
- **The highlight follows its campaign, not its row number.** `place_picker` takes a uuid, the answer `Tab::campaign` already gives for the filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted uuid before the lists are rebuilt and puts it back after
- **The highlight follows its row, not its row number.** `place_picker` takes a key — a uuid or a tag, whichever list is open — the same string `Tab::filter` holds for either filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted key before the lists are rebuilt and puts it back after
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
- **`digest` watches the campaigns directory** as well as the statuses and the comments. 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
- **`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
- **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 four 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
- **`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
- **The merge carries the flag rather than recomputing it.** `relate` resolves its target inside one `.worklane`, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no
- `project_label` takes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had; `the_project_label_leaves_the_row_inside_the_column` pins it
- `due_date` cuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"
- **Done is hidden until `d` asks for it.** Not a new opinion: `ls` already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done directory and `digest` still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` actually sits rather than assuming the last slot, and `the_done_column_is_last` pins the assumption. A status inserted after done would otherwise hide two columns in silence
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted
- **The terminal columns are hidden until `d` asks for them, one step at a time.** Not a new opinion: `ls` already counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. So `d` rotates three states — hide both, show done, show both, and back around — through the `Visibility` enum on `Board`, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the *next* press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done and discarded directories and `digest` still watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` and `DISCARDED` actually sit rather than assuming positions, and `the_terminal_columns_are_last_in_the_order_drawn` pins the assumption. A status inserted after discarded would otherwise hide two columns in silence
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
- **Assert a column heading against the top border row, not the whole screen.** The footer names done too, so `screen.contains("done (0)")` passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; `headings()` and `footer()` exist so the next one does not. `headings()` locates the row through `board_area()` rather than taking row zero, since the tab row sits above it when more than one board is monitored
@@ -306,7 +339,7 @@ and this file is for what someone changing worklane's own code needs.
- Id and title only, per 3b16540, both lowercased. The title has to be case insensitive to be worth typing, and giving the id the same treatment lets a pasted id match whatever case it was copied in. An empty or all-space query matches **nothing** rather than everything
- **The jump goes through `select_at`, the tail `select_card` already used.** `follow_selection` scrolls the column the card is in, and the offsets are per column and on the `Tab`, so a jump across columns moves the right one; `refresh_detail` keeps an open overlay on the ticket the selection names. A second version of either is how a jump comes to scroll differently from the arrow keys
- **A hit closes the prompt and a miss keeps it open**, marked, with the selection untouched. The query can then be corrected in place instead of retyped from `/`. Doing nothing visible is what makes a reader retype a query that was already right
- **The prompt takes the whole footer row**, because the key list it replaces describes nothing that currently works while every key is going into the buffer. The typed query is drawn in the default foreground and the keys in grey: one is content, the other is chrome. `no match` is brightred beside the query it is about, since grey chrome is what a reader skips
- **The prompt takes the whole footer row**, because the key list it replaces describes nothing that currently works while every key is going into the buffer. Its two keys are drawn as every other key is, cyan on the key and the default foreground on the word. That the query then sits in the same foreground as the descriptions is what the house style costs on this row, and the cursor is what says which half is an input — which it does in a terminal with no colour at all. `no match` stays brightred beside the query it is about, being the one thing on the row that is neither a key nor what was typed
- **The real terminal cursor goes after the query**, not a glyph standing in for one. ratatui shows the cursor only for a frame that asked for it, so `set_cursor_position` is also what says "you are typing" while the query is still empty. Clamped to the row, so a query longer than the terminal leaves it on the last cell
- Both closed footers name `/`, since the jump works with a ticket open as well: it moves the selection and the overlay follows
- Out of scope on purpose, each its own ticket once the input mode exists: `n` and `N` for the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
@@ -327,8 +360,12 @@ and this file is for what someone changing worklane's own code needs.
### 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 and the colour it is drawn in, `None` for the default foreground. 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
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
- **`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
@@ -340,11 +377,15 @@ and this file is for what someone changing worklane's own code needs.
- **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.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
- **`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
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
- `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
### Finding the Board
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
@@ -357,16 +398,42 @@ and this file is for what someone changing worklane's own code needs.
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
- Two paths inside one project resolve to the same `.worklane` and are monitored once. `projects()` dedupes on the resolved directory, not on the argument
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `show_done` stays on the board because it is a preference about the flow rather than about a project
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `visibility` stays on the board because it is a preference about the flow rather than about a project
- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so `Board::new` builds the tab list once and `reload` only refills each tab's columns. `reload` clamps **every** tab, and `select_tab` clamps again on arrival, because done may have been hidden while another tab was in view
- The merge tab goes **first** and is where the view opens: it is the reason to monitor several boards at once. It is materialised in `reload`, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in `collect_ticket_items`
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `frame_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `screen_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
- `digest_of` hashes each board's `digest` into one value, so a change in any of them redraws. Do not watch only the first
### Who Wrote an Entry
- **Identity is supplied, not detected.** Every option that needs no cooperation fails: a harness variable such as `CLAUDECODE` names the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor is `WORKLANE_ACTOR`, set once per session, with `--actor` as the per-call override
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** `resolve_actor` is the only caller of `get_git_user` for an entry's author, and every entry the CLI writes goes through it. The two halves are separate pure functions, `session_actor` and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
- **The session half is cached in a `OnceLock`, the way `should_use_colors` is:** neither the variable nor the git user can change mid-run, and the fallback costs a `git config` subprocess. `session_actor` takes the git user as a closure so that subprocess is not run when the variable already answered
- An **empty `WORKLANE_ACTOR` counts as unset**, the convention `colors_wanted` follows for `NO_COLOR`, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one
- **The actor is free text, checked against nothing**, like the `chown` user: there is no registry of actors, and the same reason `ls --tag` refuses to validate a tag
- **It was `comment --owner`, renamed with no alias.** Owner is the ticket's assignee and has one writer, `chown`; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splitting `set` and `chown` avoided. `the_owner_flag_is_gone` pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
- **`add --owner` and `campaign add --owner` still default to the git user, deliberately.** Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported
- **An entry does not record whether the call had a terminal.** It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
- **Set it in the agent's configuration, not per call.** `env` in `~/.claude/settings.json` reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no `env` block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around `opencode`. Both are documented in `assets/SKILL.md` rather than assumed
### The History Log
- **The log is the comments directory with the kind named in it.** It was already an append-only log with one event kind: one file per entry under `.worklane/history/<uuid>/`, stamped to the microsecond and written with `create_new`. Adding `status`, `owner` and `tags` beside `comment` needed no new mechanism, which is why there is no separate journal file and no database
- **What is not logged, deliberately:** ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
- **`--clear` is logged, since it is the same field going somewhere.** `chown --clear` and `set --clear tags` write an entry whose after-value is the sentinel the ticket now holds, `_Not set_` or `_None_`. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does
- **The kind is read from the file and only counted from the filename.** `parse_entry` matches the leading marker; `kind_from_stem` splits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader
- **A file with no marker is a comment**, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command: `entry_content(Kind::Comment, ..)` is byte for byte what `cmd_comment` wrote before this module, so nothing is rewritten and either version can read the other's board
- **The old directory is adopted, not migrated.** `adopt_comments` renames `comments` to `history` on the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. **A board holding both is refused**, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it
- **An entry is written after the edit it describes, never before.** A refused move, a refused chown and a failed save log nothing, which is what `a_refused_move_writes_nothing` and `a_failed_edit_writes_nothing` pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it
- **A no-op edit writes nothing either, and `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them
- **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it
- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `campaign` being the longest of the four, so the bodies line up under each other
- **A campaign entry records `Campaign::name`, the codename or failing that the title, never the uuid the field holds.** Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A `before` uuid the board no longer has reads `_missing_`, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from `_Not set_` (f774a33)
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
### Shipping the Agent Assets
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
@@ -394,11 +461,12 @@ and this file is for what someone changing worklane's own code needs.
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
### Color and Output
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
- **`color_text()` is for the CLI's own printing only. Anything reachable from `content_trim` takes the decision as an argument and calls `paint()`**, because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. `nothing_the_body_renders_asks_the_terminal_for_the_colour_decision` scans this file and fails on a new caller; the allowlist is `ambiguous`, which builds a failed-search message for stderr
- A function that takes an `enabled` flag must use it all the way down. `colorize_inline` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
- A function that takes an `enabled` flag must use it all the way down. The inline pass honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag: `ordered_cells` and `metadata_value_cells` return the colour rather than a decision about it
- **A test that asserts an absence has to be paired with one that asserts the presence.** The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so `should_use_colors()` was false and the leaking branch was never taken. The pair is now `content_trim(.., false)` has no escape and `content_trim(.., true)` still colours, which pins the flag as the only thing that decides
- **The palette is the `Color` enum, not a string.** `Color::ansi()` gives the CLI its SGR sequence and `From<Color> for ratatui::style::Color` gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how `magenta` came to be undefined
- Reset color with `\x1b[0m` after colored text
@@ -414,9 +482,16 @@ and this file is for what someone changing worklane's own code needs.
- Unknown values (`_None_`, `_Not set_`) → grey (38;5;8)
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `●` discarded, grey `?` for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The *pair* is what has to be unique, which is the same bargain the two half circles already take, and `every_status_has_a_mark` pins it against `status_dirs`. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
- **Relation row to a discarded target → struck through, the whole row.** The one thing in the palette that is not a colour, and it is here because the status mark cannot carry it: that mark is one cell in a column of five states, so a row pointing at abandoned work reads as a live dependency, which is exactly what it is not. The strike says the relation no longer stands for anything while the row stays on the ticket, for completeness and for the case the target is moved back out of discarded. Only discarded: a done target still stands for the fact that it was a blocker, and a `_missing_` one says something different again, that the row cannot be resolved at all. Gutter and padding included, so the line runs unbroken from the label to the end of the title, and every cell opens its own SGR 9 since each is closed by its own `RESET`
- **The strike is under the colour flag, like every other escape.** A piped `show` carries none of it, the same bargain committed and reviewing already take for being told apart by colour alone, and the board draws it as a style instead. Do not answer the pipe by changing the glyph in the mark column: the pair there has to stay unique, and `every_status_has_a_mark` is what says so
- Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the `relates to` mark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, because `show` prints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line
- Chrome → grey. The footer's key names, a rendered `[ ]`, and the overlay's page indicator. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
- Chrome → grey. A rendered `[ ]`, the overlay's page indicator and the frame's. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
- **A key name → cyan, and bold; what pressing it does → the default foreground.** The one place the palette spends a colour on something that is not a value: a key is what a reader is hunting for on a row they otherwise skip, and with the key merged into its description the colour is the only thing saying which letter to press. Not a second meaning for the timestamp's cyan in any place the two could be confused — nothing on the footer, the prompt or a border hint holds a value at all — and it is the accent frig draws the same row in, which is the point. Grey stays on the chrome around it: the page indicator, and the row's gaps
- Chrome → grey, in the history block too: the kind label at the head of a mechanical row, and the `From` on a comment's author line. Both name their row rather than holding a value, which is what grey already says. The label was orange, which means Status everywhere else, so an `owner` or `tags` label claimed a meaning belonging to the value beside it
- **A value in the history block takes the colour it has in the metadata table three lines above.** A status is orange, a tags entry goes through the same `tag_cells` the Tags field does, a campaign codename takes `tag_color` bare the way `Codename` does, and `_Not set_`, `_None_` and `_missing_` are grey. An owner stays plain: a person's name is the one value the palette has no meaning for, and spending a colour on the field that needs it least is how a colour stops meaning anything. The block's job is to be scanned, and it is not worth scanning if it has a palette of its own to learn first
- History actor → its name through `tag_color`, the way a campaign codename is. Not a new meaning for a reserved colour but the existing use of the tag slots, a name that groups rows: one writer is one colour in every entry it wrote, so a reader sees who has been working a ticket without reading the same name four times. `claude`, `opencode` and a person each get their own
- History timestamp → cyan, and its own span. It shared one with the actor while the two were formatted as `name (time)`, which spent the timestamp's colour on a name. The parentheses are plain: they are punctuation, not chrome with something to say
- Campaign label → its codename through `tag_color`, bold, marked `~`. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view because `tag_color` is a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not `#`, or the row would read as a list of tags with a stranger in it, and not `@`, which reads as a person on every board anyone has used. `Codename` in a metadata table takes the colour without the mark, since the field name has already said what it is
- Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a `TAG_COLORS` slot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
@@ -427,14 +502,19 @@ and this file is for what someone changing worklane's own code needs.
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
### Code Organization
- Colorization functions (`colorize_ordered`, `colorize_inline`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
- **`colorize_inline` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- **`change` and `split_change` are a pair, and they live beside each other in `history.rs`.** The mechanical body is stored as one string, `before → after`, so painting the halves means splitting it, and the separator is a constant the writer and the reader share. A renderer with its own copy of the spacing would go on splitting on a separator the writer no longer emits, and would say so by drawing a whole body as one half. The split is `split_once`, so a value carrying the arrow itself keeps it
- **The history block quotes who is talking.** Every line of a comment's body draws behind a grey bar spanning the whole run, paragraph breaks included, the way quoted text is drawn — d447e04, taking the review of 2733b10's answer over that ticket's uniform prefix and b304b17's per-line indent, both of which left the continuation at column 0. The reason under a mechanical row draws the same bar. The author line stays at column 0 and is told from a mechanical row by its `From` and its colour instead; the rule a reader learns is that a barred line is somebody's own words and a line of values at column 0 is the tool reporting itself. With colour off the glyph goes but the width it occupied stays, as spaces derived from the drawn form in `quoted_cells`, so a pipe keeps the column without an escape byte
- **A quote is one segmentation, two shapes, and the shapes split on wrapping.** The CLI prefixes each stored line — `quoted_cells`, which is why a terminal soft-wrapping a wide line draws continuations bare: a pipe has no width to honour, and `show` does not wrap by hand. The board quotes as geometry instead (8020e48): a `HistoryPart::Quoted` run becomes an overlay section laid out as two columns, a two-cell gutter holding the grey bar top to bottom and the body beside it, so a row the prose wraps onto inherits the mark from the gutter rather than from its own first characters. `Detail` holds sections for this reason — flow stretches full width, quotes beside their gutters — and the clamp sums the sections' wrapped heights, so scroll and draw measure one total. The newline history writes after every quote is consumed by the section builder rather than drawn: it used to close the quote's last line and the section boundary does that now, so drawing it would bank a blank row no entry ever had. `QUOTE_BAR` lives in `util.rs` because both renderers draw it, not because they draw it the same way
- **`history.rs` owns the log end to end**: the path, the kinds, the parse, the write, the count and the render. It came out of `util.rs` and `handlers.rs`, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way `campaign.rs` and `tag.rs` answer their own questions
- The body's painters return cells, not strings: `ordered_cells`, `inline_cells`, `metadata_cells`, `metadata_value_cells`, `tag_cells` and `push_heading`. `content_trim_colored` is the CLI entry point and `paint_cells` is the only thing that writes an escape. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
- **`inline_cells` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
- `show` renders the Metadata section as a two column table via `metadata_cells`, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
- `resolve_ticket()` scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
- `parse_ticket_field()` handles extracting metadata values from markdown format
- `move_ticket_file()` stages the updated content in a temp file under `.worklane/`, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the next `mv` corrects
- **A move whose target equals the directory the file already sits in repairs a Status field that disagrees with it, instead of refusing as a no-op.** `resolve_ticket` reads the current status off the directory, so the old comparison was the directory agreeing with itself and could never see the field; a hand-moved file was stuck with moving it away and back to fix it. Now the field is compared first: agreement is the ordinary already-in-status report with nothing written, disagreement rewrites the field alone through the same in-place save every edit uses, and reports it as a correction rather than a move. It is gated on neither `-f` nor the dependency guards behind them, because it is not a transition; it writes no stamp, since presence still answers how far the work got and the work arrived nowhere new; and it logs nothing, because an entry shaped like a transition would record a journey the ticket never took. The mirror case is unchanged: a field ahead of its directory after a crash mid-move is corrected by the next real `mv`, because there the target is a status the ticket is not sitting in
- Field lookup, read and write, is scoped to the lines under the `## Metadata` heading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead. `set_status_field()` carries the same scoping
### Ticket Resolution
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.27.2"
version = "0.32.6"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.27.2"
version = "0.32.6"
edition = "2024"
[dependencies]
+19 -10
View File
@@ -5,23 +5,23 @@ Worklane is a local Kanban flow for agentic software development.
## Commands
| Command | Description |
|---------|-------------|
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories |
| `worklane` or `worklane tui [path...]` | Opens the board: one column per status, redrawn when the tree changes. Read only. Opens with done and discarded hidden, their counts in the footer; `d` rotates hide both, show done, show both, and back around. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done, discarded directories |
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
| `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 |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
| `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` |
| `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 |
| `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 |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion |
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
@@ -29,6 +29,14 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
## Environment
| Variable | Effect |
|----------|--------|
| `WORKLANE_ACTOR` | Who every entry the CLI writes is attributed to: a comment, and the `status`, `owner` and `tags` entries `mv`, `chown` and `set --tags` record. Set it once, in the environment an agent runs in, and every call it makes is attributed to it instead of to the git user of whoever's machine it is on. `--actor` overrides it per call, an empty value counts as unset, and with neither supplied the author is the git user and then `unknown`. Free text, checked against nothing |
| `NO_COLOR` | Set and non-empty turns colour off, whatever the value, per no-color.org. Colour is also off when output is not a terminal, and when `TERM` is `dumb` or empty |
| `XDG_CONFIG_HOME` | Where `install-tool` looks for opencode's config root, `$XDG_CONFIG_HOME/opencode`, defaulting to `~/.config`. `install-skill` does not follow it: `~/.claude` is not an XDG path |
## Completions
```sh
@@ -43,10 +51,11 @@ asks worklane for the one thing only the board knows:
```
worklane show <TAB> every ticket, id and title, done included
worklane mv <TAB> the same, then --status <TAB> for the four
worklane mv <TAB> the same, then --status <TAB> for the five
worklane chown alice <TAB> the ticket, which is the second argument here
worklane chown --clear <TAB> the ticket, which the flag carries here
worklane relate x --blocked-by <TAB>
worklane relate x --clear <TAB> the three kinds, not a ticket: the kind comes first
worklane campaign show <TAB> the campaigns, from `campaign ls --ids`
worklane assign <TAB> the same, since a campaign comes first here
worklane ls --campaign <TAB> and again
+14 -6
View File
@@ -233,17 +233,25 @@ two exceptions below are files no command owns, and they are marked as such.
first check `worklane ls done`. If it is there and should not be, its file has been moved
into the wrong directory by hand or by a restore.
The repair is two moves, not one:
`mv` reads the current status from the *directory*, so one move puts both halves right:
move the ticket to the status it belongs in and the field travels with it.
```
worklane mv 1b78a24 --status reviewing -f
worklane mv 1b78a24 --status done -f
```
`mv` reads the current status from the *directory*, so moving it to the status the
directory already says it is in is refused as a no-op and the field stays wrong. Moving it
away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line
is read from the file rather than from where it sits.
If the file is where it belongs and only the `Status` field inside is stale — a hand move
that forgot the field, or a half-finished restore — name the directory the file actually
sits in: a move there finds the field disagreeing with the directory and rewrites just
the field, reporting the correction instead of refusing as a no-op.
```
worklane mv 1b78a24 --status done
```
That repair changes only the field: no stamp is written and no history entry either,
because the work went nowhere. Check either repair with `worklane show 1b78a24`, whose
`Status` line is read from the file rather than from where it sits.
### A command says the id matches several tickets
+151 -26
View File
@@ -1,15 +1,15 @@
---
name: worklane
description: Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the four statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.
description: Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the five statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.
---
# worklane
A kanban board as files. Every ticket is one markdown file in `.worklane/<status>/`,
named `<uuid>_<slug>.md`, and comments live in `.worklane/comments/<uuid>/`. The CLI is
the only thing that writes there: do not hand-edit or hand-place a file, because the
filename, the `Status` field and the directory have to agree and the commands are what
keep them agreeing.
named `<uuid>_<slug>.md`, and its history lives in `.worklane/history/<uuid>/`, one file
per entry. The CLI is the only thing that writes there: do not hand-edit or hand-place a
file, because the filename, the `Status` field and the directory have to agree and the
commands are what keep them agreeing.
Commands walk up from the working directory to find the nearest `.worklane`, so **run
`worklane` inside the repo the ticket belongs to**. Which directory you run it in is
@@ -20,7 +20,7 @@ a person, not for you: it takes over the screen and does not return until quit.
## The flow
`backlog` → `committed` → `reviewing` → `done`
`backlog` → `committed` → `reviewing` → `done`, with `discarded` off to one side
**Move the ticket as you work it, not afterwards.** `worklane mv <id> --status committed`
before writing any code, and `--status reviewing` once it is done and the tests pass. The
@@ -35,11 +35,39 @@ skipping move, for correcting a mistake.
A move is also refused while the ticket is blocked by one that is not done yet, see
[Relating tickets](#relating-tickets).
`mv` stamps the time as it goes: `Committed On`, `Submitted On` and `Completed On`, one
field for the status the ticket is in now, shown by `show` among the rest of the
metadata. Only the current one is kept, so the stamp says how long the ticket has been
where it is, not how long each earlier stage took. Nothing else writes them, and moving
a ticket back removes the stamp of the status it left.
`mv` stamps the time as it goes: `Committed On`, `Submitted On`, `Completed On` and
`Discarded On`, shown by `show` among the rest of the metadata. They **accumulate**, so a
ticket that walked the whole flow carries all of them side by side and the journey is
legible; presence means it got that far and has not been sent back past it, not that it
is there now, which is what `Status` says. Moving a ticket back drops the stamps of every
stage after where it lands.
## Discarding a ticket
`worklane mv <id> --status discarded` is where a ticket goes that will not be done: a
duplicate, something obsolete, something that turned out to be wrong. It keeps the record
and the relations, which deleting the file by hand would destroy.
```
worklane mv 1b78a24 --status discarded
```
Reachable from any status and needs no `-f`, because discarding is not a stage of work: a
backlog ticket does not have to be walked through `committed` to be abandoned. **Say why
in a comment before you discard it.** The status records that it will not happen and
nothing records what was decided, and that is the question somebody asks in six months.
What it means everywhere else:
- `ls` leaves it out of the listing and keeps it in the counts, the way it treats `done`.
`ls discarded` and `--ids` still reach it
- A campaign counts a discarded member as **finished**: the work left the campaign rather
than sitting in it unfinished
- A discarded ticket **blocks nothing**, so a ticket waiting on it can move
- Discarding a ticket that open tickets are blocked by is **refused**, naming them: their
plans depended on this work, so they need a look first. `-f` says you looked
- Getting it back is a backward move, so it needs `-f`:
`worklane mv 1b78a24 --status backlog -f`
## Reading the board
@@ -48,13 +76,13 @@ worklane ls # every status, counts then tickets
worklane ls backlog # one status
worklane ls --priority 1 # only the most urgent
worklane ls --tag bug # only the tickets carrying that tag
worklane show 1b78a24 # one ticket, body and comments
worklane show 1b78a24 # one ticket, body and history
```
`ls` prints a seven-character id per ticket. That is what you address it by.
`worklane ls --ids` prints the same tickets as an id, a tab and a title, one per line and
unstyled, with done included and the filters still applying. That is the form to parse
unstyled, with done and discarded included and the filters still applying. That is the form to parse
when you want the ids themselves: `worklane ls --ids | cut -f1`. The decorated listing is
for reading, not for cutting up.
@@ -99,6 +127,11 @@ is never left half-marked. A criterion already in the state you asked for is rep
unchanged rather than refused, and a call that would change nothing writes nothing. Both
apply to `uncheck` exactly as they do to `check`.
**Say why on the unusual moves:** `worklane mv 1b78a24 --status backlog -f --reason "the
first plan was wrong"`. The reason is recorded inside the history entry beside the
transition it explains and rendered indented under its row, in `show` and on the board.
Optional on every move; a refused or no-op move records nothing even with one.
## Filing a ticket
```
@@ -159,7 +192,7 @@ one command here that does not start with the ticket. The user is free text and
checked against nothing. Swap the two and the call fails, because the username has to
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
`worklane init` creates `.worklane/` with the four status directories and the campaigns
`worklane init` creates `.worklane/` with the five status directories and the campaigns
directory beside them, for a repo that has no board yet.
## Relating tickets
@@ -168,17 +201,43 @@ directory beside them, for a repo that has no board yet.
worklane relate 1b78a24 --blocked-by 4179958 # this one waits on that one
worklane relate 1b78a24 --regression-of 6d327df # this one broke that one's fix
worklane relate 1b78a24 --relates-to 7bfb9fc # neighbours, no dependency
worklane relate 1b78a24 --clear blocked-by 4179958 # take that edge off again
```
One flag per kind, and each repeats. The ticket comes first and the flag says what it is
to the target, so read the call as a sentence: `relate A --blocked-by B` means A waits
on B. **Only one side is stored**, on the ticket you name, and `show` derives the other
on B.
**`--clear` is how an edge comes off, and it names the kind and the target**, because a
ticket can hold several relations of one kind and emptying all of them is rarely what is
wanted. Repeat the flag for more. The kind is spelled either way, `blocked-by` as the flag
records it or `blocked by` as `show` prints it. `set --clear` does not reach relations:
`relate` is the only writer of the section, so it owns both directions.
The target is resolved against the edges the ticket already holds first, by id prefix,
and only then as an ordinary ticket search. That order is what lets you clear an edge
whose target has been **deleted**, which is the case most likely to need it: `show` draws
it as `_missing_` with a `?` mark and `mv` warns about it on every move, and no search of
the board can reach a ticket that is gone.
An edge the ticket does not hold reports no change. A target that names nothing at all is
an error rather than a no-op, so a mistyped id does not read as success. Recording and
clearing the same edge in one call is refused outright, the way `set` refuses a field it
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`, whichever move it is, and names every open blocker. `-f` moves it
anyway, beside the backward and skipping moves it already allows. The other two kinds are
reference data and never refuse anything.
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
from the other end too: discarding a ticket that open tickets are blocked by is refused,
naming them. The other two kinds are reference data and never refuse anything.
Recording a relation the ticket already holds reports no change. A ticket cannot relate
to itself, and a target that later disappears shows as `_missing_` rather than silently
@@ -187,15 +246,19 @@ going away.
`show` marks each row twice, kind then status. The kind is `×` for `blocked by` and
`blocks`, `→` for `relates to`, `←` for `regression of` and `regressed by`; both
directions of one kind carry one mark, and the label is what says which end you are on.
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done, and
`?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done or
discarded, and `?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
that is finished and `blocked by × ○ (1b78a24)` is one nobody has started. The board
draws the same block.
Colour is what tells committed from reviewing, since both are `◐`, and **your output is a
pipe, so you do not get the colour**. Read `◐` as under way, and if it matters which
stage, `worklane show` on that target says so in its Status field. `●` and `○` are
unambiguous without it, which are the two answers usually being asked for.
Colour is what tells committed from reviewing apart, and done from discarded, since each
pair shares a glyph, and **your output is a pipe, so you do not get the colour**. Read
`◐` as under way and `●` as nothing left to do, and if it matters which of the two,
`worklane show` on that target says so in its Status field. `○` is unambiguous without it.
A row pointing at a **discarded** target is struck through on a terminal, since a
relation to abandoned work otherwise reads as a live dependency. That is a style rather
than a character, so a pipe does not get it either: ask the target's Status field.
## Campaigns
@@ -270,6 +333,65 @@ existing ticket will have been written from a different angle.
- Related but not the same: file it, and record it with `relate <new> --relates-to <old>`
rather than only mentioning the id in prose.
## What the board records about your work
`show` ends with a HISTORY block: every comment on the ticket and every change to its
status, owner, tags or campaign, oldest first, each naming who made it. You do not write
these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call
that changes nothing records nothing. A campaign move is recorded by codename, or by
title for a campaign that has none, not by the uuid the field holds.
```
HISTORY
────────────────────
status backlog → committed claude (2026-08-24 12:45:00)
From claude (2026-08-24 13:10:22)
The offset was never passed to the widget.
owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04)
campaign _Not set_ → v1 claude (2026-08-24 13:12:30)
```
Nothing else is logged: ticking a criterion, and editing the title, description, plan,
priority or due date, leave no entry. **When one of those matters, say so in a comment.**
An implementation plan rewritten because the first one was wrong is worth a sentence; the
edit itself is not recorded and nobody can reconstruct why from the file.
Read the block before picking a ticket up: it says whether somebody has already had it in
`committed` and sent it back, which the current status alone does not.
## Who your entries are attributed to
Every entry carries an author, and yours comes from `WORKLANE_ACTOR`, which your harness
sets before you run anything. **Assume it is set for you, and never spell yourself out on
a call** — a plain `worklane comment` is already attributed to you, which is what keeps a
board several agents write to saying which of them said what. It is configured once,
where your session's environment lives: `env` in `~/.claude/settings.json` for Claude
Code, and the environment opencode is started with for opencode, since it passes its own
environment to the tools it runs.
**Reach for `--actor` only when the entry is somebody else's action**: the person asked
you to move a ticket, or to put words on the board as their comment, so name them on the
flag — the move was theirs and the words are theirs, and an entry carrying your name
reads later as though you decided both. Otherwise leave it off, unless your instructions
say to use it. It is spelled the same on every command that writes an entry: `comment`,
`mv`, `chown`, `set` and `assign`.
```
worklane mv 1b78a24 --status done --actor "Ansho Rei"
```
Under a missing or empty variable the author falls back to the git user of the machine —
the human whose checkout it is — and with neither, `unknown`. It is free text, checked
against nothing: whatever name you pass, make it one a person reading the board will
recognise.
On `chown`, `--actor` is not the user argument: `worklane chown alice 1b78a24` makes alice
the ticket's owner, and `--actor` says who made that change.
## Shell completions
```
@@ -300,8 +422,8 @@ the candidates and exits 1 rather than guessing.
`--print is supported` is stored, not parsed as a flag. The cost is that a genuinely
mistyped flag there lands as content instead of failing, so read back what you wrote
with `worklane show`.
- `--due`, `--priority`, `--tags`, `--owner` and `--status` do *not* accept one, so a
mistyped flag on those is a usage error and nothing is written.
- `--due`, `--priority`, `--tags`, `--owner`, `--actor` and `--status` do *not* accept one,
so a mistyped flag on those is a usage error and nothing is written.
- A ticket argument that starts with a hyphen needs the flags first and a separator:
`worklane mv --status committed -- -leading-title`.
- A comment body of exactly `--` needs its own separator:
@@ -309,4 +431,7 @@ the candidates and exits 1 rather than guessing.
- An empty value for a scalar is a usage error, not a way to clear the field: use
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
the section either, and an all-blank one is refused with the `--clear` for it named.
- **`comment` has no `--owner`.** Owner is the ticket's assignee, which `chown` writes;
the author of a comment is `--actor` or `WORKLANE_ACTOR`. The old spelling is a usage
error, not an alias.
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
+26 -6
View File
@@ -187,7 +187,7 @@ export const ls = tool({
export const show = tool({
description:
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and comments.",
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and the history: every comment on it and every change to its status, owner or tags.",
args: {
id: tool.schema
.string()
@@ -219,6 +219,10 @@ export const mv = tool({
.boolean()
.describe("Force move (allows non-sequential moves like done -> backlog). Use with caution.")
.optional(),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
@@ -229,6 +233,7 @@ export const mv = tool({
}
const cmd: string[] = ["mv", args.ticket, "--status", args.status];
if (args.force) cmd.push("--force");
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
@@ -247,9 +252,9 @@ export const comment = tool({
body: tool.schema
.string()
.describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."),
owner: tool.schema
actor: tool.schema
.string()
.describe("Comment author. If omitted, defaults to the git user.")
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
@@ -261,7 +266,7 @@ export const comment = tool({
}
const cmd: string[] = ["comment", args.ticket, args.body];
if (args.owner) cmd.push("--owner", args.owner);
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
@@ -306,6 +311,10 @@ export const set = tool({
.string()
.describe("New priority level, 1 (most urgent) to 5 (least)")
.optional(),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
@@ -330,8 +339,12 @@ export const set = tool({
if (args.tags) cmd.push("--tags", args.tags);
if (args.due) cmd.push("--due", args.due);
if (args.priority) cmd.push("--priority", String(args.priority));
// Last, and not counted as a field: the length check below is what refuses a call
// that names nothing to change, and an actor alone changes nothing.
const fields = cmd.length;
if (args.actor) cmd.push("--actor", args.actor);
if (cmd.length === 2) {
if (fields === 2) {
return "Error setting fields: give at least one field to change";
}
@@ -405,6 +418,10 @@ export const chown = tool({
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
actor: tool.schema
.string()
.describe("Who the entry is attributed to, which on this command is not the same as user: user becomes the ticket's owner, actor is who made the change. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\".")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.user) {
@@ -414,8 +431,11 @@ export const chown = tool({
return "Error changing owner: ticket is required";
}
const cmd: string[] = ["chown", args.user, args.ticket];
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(["chown", args.user, args.ticket], context);
return await run(cmd, context);
} catch (err: any) {
return `Error changing owner: ${err.message}`;
}
+27 -8
View File
@@ -50,6 +50,21 @@ pub struct Campaign {
pub content: String,
}
impl Campaign {
/// The name a reader knows the campaign by: the codename, or the title for a
/// campaign filed without one.
///
/// What the history log records for a campaign move. The field holds a uuid, which
/// says nothing in a log line, and resolving at read time would let an entry change
/// meaning when a campaign is renamed, so the name is settled when the entry is
/// written. The codename over the title because it is the word the board and the
/// command line already use for the campaign, and a log row holds two of these
/// around an arrow.
pub fn name(&self) -> &str {
self.codename.as_deref().unwrap_or(&self.title)
}
}
/// The campaigns directory as [`resolve_in`] takes it.
///
/// The name is empty because a campaign has no status: it is what makes the ambiguity
@@ -173,30 +188,30 @@ impl CampaignIndex {
/// target does, rather than as the bare value the file stores: the value is a full
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
/// gone.
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
pub fn campaign_cells(content: &str, index: &CampaignIndex) -> Vec<Cell> {
let Some(uuid) = parse_campaign(content) else {
return String::new();
return Vec::new();
};
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
reference_cells(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()))
}
/// The parts [`content_trim`] cannot render from the ticket file alone.
///
/// Both halves read the tree beside the ticket, so they are gathered in one place
/// rather than at each call site.
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
pub fn resolved_for(content: &str, worklane_dir: &Path) -> Result<Resolved> {
Ok(Resolved {
relations: relations_for(content, worklane_dir)?,
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
campaign: campaign_cells(content, &CampaignIndex::load(worklane_dir)?),
})
}
/// The members of a campaign, grouped by status in flow order.
/// The members of a campaign, grouped by status in flow order, discarded last.
///
/// Read through `collect_ticket_items`, the source `ls` and the board already use, so
/// there is no second parser and the rows print the way every other listing does.
/// Empty groups are kept: a campaign's shape is the four statuses, and a caller that
/// Empty groups are kept: a campaign's shape is the statuses, and a caller that
/// wants only the filled ones can say so.
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
let mut grouped = Vec::new();
@@ -236,9 +251,13 @@ pub struct Standing {
impl Standing {
pub fn of(grouped: &[(&'static str, Vec<TicketItem>)]) -> Self {
Self {
// Discarded counts as finished: the work was decided out of the campaign,
// not left in it, and one abandoned ticket must not hold a campaign open
// forever. The same predicate `mv` gates on, so "nothing outstanding" means
// one thing across the tool.
done: grouped
.iter()
.filter(|(status, _)| *status == DONE)
.filter(|(status, _)| !is_open(status))
.map(|(_, items)| items.len())
.sum(),
total: grouped.iter().map(|(_, items)| items.len()).sum(),
+147 -12
View File
@@ -162,24 +162,43 @@ fn tag_value(raw: &str) -> Result<String, String> {
Ok(value.to_string())
}
/// Reject an annotation line that would be read back as a tag of its own.
/// Reject an annotation the vocabulary file or the listing cannot carry.
///
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
/// starting with the section marker would split the annotation and declare whatever
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
/// a different line.
/// followed. A tab anywhere in the value is refused for the listing's sake rather than the
/// file's: `tags ls` prints one tag, its count and the annotation's opening line as three
/// tab-separated fields, so an annotation holding a tab reads as the start of a fourth
/// field and everything after it is silently gone.
///
/// Both are refused at parse time, where nothing has been written, rather than escaped on
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking
/// for a different line.
fn annotation_line(raw: &str) -> Result<String, String> {
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
true => Err(format!(
if raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
return Err(format!(
"an annotation line cannot start with '{}', which is how the vocabulary file \
starts a tag",
crate::tag::SECTION
)),
false => Ok(raw.to_string()),
));
}
if raw.contains('\t') {
return Err(
"an annotation cannot contain a tab, which is how `tags ls` separates its fields"
.to_string(),
);
}
Ok(raw.to_string())
}
/// What `--actor` says on every command that writes a history entry.
///
/// One string, so the five spell it the same: a flag documented differently on each
/// command reads as five flags.
const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing";
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
@@ -221,6 +240,14 @@ pub enum Command {
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
force: bool,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
/// Why the ticket moved, recorded in the history entry beside the transition
/// it explains. Prose, so it takes a leading hyphen
#[arg(long, allow_hyphen_values = PROSE)]
reason: Option<String>,
},
/// Replace fields on an existing ticket
@@ -267,9 +294,10 @@ pub enum Command {
#[arg(allow_hyphen_values = PROSE)]
body: String,
/// Owner
#[arg(short, long)]
owner: Option<String>,
/// Named after the writer of the entry, not after the ticket's assignee, which
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
/// Group tickets that have to be finished together
@@ -292,6 +320,9 @@ pub enum Command {
/// Ticket UUID or title
ticket: String,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
/// The tag vocabulary: what the board carries, and what each tag means
@@ -728,6 +759,11 @@ pub struct SetArgs {
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
/// Only reaches the entry `--tags` writes, since that is the one field of this
/// command's that is logged
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
}
impl SetArgs {
@@ -773,6 +809,11 @@ pub struct ChownArgs {
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
/// Not the same as `user`, which is the ticket's new assignee: this is who made the
/// change. Both are on this command because it writes both.
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
}
impl ChownArgs {
@@ -824,12 +865,17 @@ pub struct AppendArgs {
/// Each flag repeats, so several relations of one kind land in a single call. The
/// targets are ticket searches, resolved by the same three tiers every other ticket
/// argument is, and stored as the target's uuid.
///
/// `--clear` is the other direction, and it is here rather than on `set` for the reason
/// Relations is absent from `section_args`: a relation names a target that has to be
/// resolved first, so its one writer owns both adding and removing, the way `chown` owns
/// both setting an owner and clearing one.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("relation_kinds")
.required(true)
.multiple(true)
.args(["blocked_by", "regression_of", "relates_to"])
.args(["blocked_by", "regression_of", "relates_to", "clear"])
))]
pub struct RelateArgs {
/// Ticket UUID or title
@@ -846,6 +892,18 @@ pub struct RelateArgs {
/// Ticket this one is merely related to. Symmetric, so it is recorded once
#[arg(long, value_parser = non_empty)]
pub relates_to: Vec<String>,
/// Take a relation off: the kind, then the ticket it points at. Repeat the flag
///
/// Two values rather than one, because a ticket can hold several relations of one
/// kind and emptying every `blocked by` on it is not usually what is wanted. That is
/// also why this is not `set --clear`, which names a field and empties the whole of
/// it: the "value" here is one edge among several, so the target has to be named too.
///
/// A `Vec<String>` because clap cannot type the two values of one flag apart.
/// [`RelateArgs::cleared`] is where the pairs are split and the kind is parsed.
#[arg(long, num_args = 2, value_names = ["KIND", "TARGET"], value_parser = non_empty)]
pub clear: Vec<String>,
}
impl RelateArgs {
@@ -858,6 +916,18 @@ impl RelateArgs {
(RelationKind::RelatesTo, &self.relates_to),
]
}
/// The relations asked to be taken off, as a kind and the search naming the target.
///
/// `num_args = 2` is per occurrence, so clap has already refused an odd number of
/// values and every chunk is a full pair. A kind that is not one of the three is
/// refused here, before the ticket is resolved and long before anything is written.
pub fn cleared(&self) -> anyhow::Result<Vec<(RelationKind, &str)>> {
self.clear
.chunks(2)
.map(|pair| Ok((RelationKind::parse_value(&pair[0])?, pair[1].as_str())))
.collect()
}
}
/// `check` and `uncheck` are separate commands rather than one verb with a flag,
@@ -881,3 +951,68 @@ pub struct CheckArgs {
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
pub criteria: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;
/// The command names as the README table would have to spell them: `campaign add`
/// for a nested one, the bare name for a top level one. `help` is clap's own and
/// documents nothing.
fn documented_names() -> Vec<String> {
let cli = Cli::command();
let mut names = Vec::new();
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
names.push(sub.get_name().to_string());
for nested in sub.get_subcommands() {
if nested.get_name() == "help" {
continue;
}
names.push(format!("{} {}", sub.get_name(), nested.get_name()));
}
}
names
}
/// Every subcommand has a row in the README's command table.
///
/// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and
/// the `--campaign` flag went with them, because the only thing walking the table
/// was somebody remembering to. This is what walks it. A command whose row is
/// missing is a command a reader of the README cannot discover at all, which is a
/// worse failure than a row that is merely out of date.
#[test]
fn every_subcommand_has_a_row_in_the_readme_command_table() {
// The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row
// once the vocabulary work above it has landed. Listed rather than skipped, so
// emptying this is part of closing that ticket rather than something to
// rediscover.
const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"];
let readme = include_str!("../README.md");
let table: String = readme.lines().filter(|line| line.starts_with('|')).collect();
let missing: Vec<String> = documented_names()
.into_iter()
.filter(|name| !PENDING.contains(&name.as_str()))
.filter(|name| !table.contains(&format!("`worklane {}", name)))
.collect();
assert!(
missing.is_empty(),
"no row in the README command table for {missing:?}. A new command is not \
shipped until the table lists it: that table is the only place a reader \
discovers one, and two commands hid behind an otherwise complete table \
for two minor versions."
);
}
}
+56 -14
View File
@@ -22,7 +22,7 @@ use clap::{CommandFactory, ValueEnum};
use clap_complete::Shell;
use crate::install::SKILLS;
use crate::util::Status;
use crate::util::{RelationKind, Status};
/// Subcommands whose first positional is a ticket.
///
@@ -98,6 +98,11 @@ fn fish_dynamic() -> String {
let ticket_commands = TICKET_COMMANDS.join(" ");
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
let ticket_flags = flag_list(&TICKET_FLAGS);
let relation_kinds = RelationKind::ALL
.iter()
.map(|kind| kind.flag())
.collect::<Vec<_>>()
.join(" ");
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
.iter()
@@ -188,6 +193,14 @@ complete -c worklane \
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
-x -a '(worklane ls --ids)'
# `--clear` is the one flag here whose first value is not a ticket, so it is not in
# `TICKET_FLAGS`: it takes the kind and then the target, and offering a board listing where
# the kind goes would be offering values it refuses. The kinds come from `RelationKind`
# rather than being spelled again. The target gets no rule at all, deliberately: fish
# completes the value after the flag, and the case this flag exists for is a target whose
# ticket is gone, which no listing of the board can offer.
complete -c worklane -n '__worklane_command_is relate' -l clear -x -a '{relation_kinds}'
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
# argument, `campaign show`'s only one, and `ls --campaign`.
complete -c worklane \
@@ -464,22 +477,51 @@ mod tests {
}
}
/// `chown --clear` takes a ticket, so it is completed like one, and only under
/// `chown`: `set --clear` is the same flag name carrying a field.
/// Three commands carry a `--clear` and each one takes something different: `chown`
/// takes the ticket, `relate` takes the kind and then the target, and `set` takes a
/// field name clap already offers. So each rule is scoped to its own command, and a
/// bare search for `-l clear` cannot tell them apart, which is what this used to do.
#[test]
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
fn each_clear_flag_is_completed_for_its_own_command() {
let script = fish_dynamic();
let rule = script
.lines()
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
.expect("chown --clear has a rule of its own");
assert!(rule.contains("__worklane_command_is chown"), "{rule}");
assert!(rule.contains("worklane ls --ids"), "{rule}");
let chown = command().find_subcommand("chown").expect("chown exists").clone();
let cli = command();
let rule_for = |name: &str| {
let scope = format!("__worklane_command_is {name}");
script
.lines()
.find(|line| {
line.starts_with("complete")
&& line.contains("-l clear")
&& line.contains(&scope)
})
.unwrap_or_else(|| panic!("no --clear rule for {name}:\n{script}"))
};
let has_clear = |name: &str| {
cli.find_subcommand(name)
.unwrap_or_else(|| panic!("no such subcommand: {name}"))
.get_arguments()
.any(|arg| arg.get_long() == Some("clear"))
};
// `chown --clear` names the ticket in the flag, so the flag completes tickets.
assert!(has_clear("chown"), "`chown` has no --clear for the rule to complete");
assert!(rule_for("chown").contains("worklane ls --ids"), "{}", rule_for("chown"));
// `relate --clear` takes the kind first, so it offers the kinds and not a board
// listing: tickets there would be candidates the flag refuses. The target, the
// second value, is deliberately left uncompleted.
assert!(has_clear("relate"), "`relate` has no --clear for the rule to complete");
let relate = rule_for("relate");
for kind in RelationKind::ALL {
assert!(relate.contains(kind.flag()), "{kind:?} is not offered: {relate}");
}
assert!(
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
"`chown` has no --clear for the rule to complete"
!relate.contains("worklane ls --ids"),
"tickets offered where the kind goes: {relate}"
);
assert!(
!TICKET_FLAGS.contains(&"clear"),
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
@@ -568,7 +610,7 @@ mod tests {
status.as_str()
);
}
assert!(script.contains("-a 'backlog committed reviewing done' -d status"));
assert!(script.contains("-a 'backlog committed reviewing done discarded' -d status"));
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
assert!(script.contains(shell), "the shell positional is never offered {shell}");
}
+366 -164
View File
@@ -10,6 +10,7 @@ use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
};
use crate::history::{Kind, change, format_history, read_history, write_entry};
use crate::install;
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
use crate::util::*;
@@ -112,11 +113,12 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
println!(" [{}] {} {}", status.to_uppercase(), count, label);
}
// Show all tickets except done grouped by status. Over `Status::ALL` rather
// than the names, because each column is ordered by its own entry stamp and the
// comparator is keyed on the status, not on the directory it was read from.
// Show all tickets except the two terminal statuses, grouped by status. Over
// `Status::ALL` rather than the names, because each column is ordered by its own
// entry stamp and the comparator is keyed on the status, not on the directory it
// was read from.
for status in Status::ALL {
if status.as_str() == DONE {
if !is_open(status.as_str()) {
continue;
}
let status_path = worklane_dir.join(status.as_str());
@@ -351,99 +353,12 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
Ok(())
}
/// Public for the TUI's detail view, which shows the same comments `show` does.
pub fn read_comments(comments_dir: &Path) -> Result<Vec<(String, String, String, String)>> {
if !comments_dir.exists() {
return Ok(vec![]);
}
let mut comments: Vec<(String, String, String, String)> = Vec::new();
for entry in fs::read_dir(comments_dir)? {
let entry = entry?;
let path = entry.path();
if path.extension().is_some_and(|e| e == "md") {
let content = fs::read_to_string(&path)?;
let filename = path
.file_stem()
.map(|s| s.to_string_lossy().to_string())
.unwrap_or_default();
let author = content
.lines()
.find(|l| l.starts_with("**Author**"))
.and_then(|l| l.split_once("**Author**:"))
.map(|(_, value)| value)
.map(|s| s.trim().to_string())
.unwrap_or_else(|| "unknown".to_string());
let time = content
.lines()
.find(|l| l.starts_with("**Time**"))
.and_then(|l| l.split_once("**Time**:"))
.map(|(_, value)| value)
.map(|s| s.trim().to_string())
.unwrap_or_else(|| "unknown".to_string());
let body = if let Some(after_comment) = content.strip_prefix("**Comment**\n") {
if let Some(end) = after_comment.find("\n\n**Author**") {
after_comment[..end].trim()
} else {
after_comment.trim()
}
} else {
""
};
comments.push((filename, author, time, body.to_string()));
}
}
comments.sort_by(|a, b| a.0.cmp(&b.0));
Ok(comments)
}
/// Write a comment under the first free name derived from `stem`.
///
/// `create_new` rather than `fs::write`: a name that already exists means another
/// comment landed in the same microsecond, and truncating it is exactly the data
/// loss this guards against. The suffix is zero padded so the names keep sorting
/// in the order they were written.
fn write_new_comment(comments_dir: &Path, stem: &str, content: &str) -> Result<String> {
for attempt in 0..100 {
let filename = match attempt {
0 => format!("{}.md", stem),
n => format!("{}_{:02}.md", stem, n),
};
match fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(comments_dir.join(&filename))
{
Ok(mut file) => {
file.write_all(content.as_bytes())?;
return Ok(filename);
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e.into()),
}
}
Err(anyhow!(
"No free comment filename for '{}' in {}",
stem,
comments_dir.display()
))
}
pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
let (_status, title, content) = resolve_ticket(search, worklane_dir)?;
let ticket_uuid = parse_ticket_field(&content, "ID");
// Read before anything is printed, so a board that cannot be read fails instead of
// half printing a ticket.
let resolved = resolved_for(&content, worklane_dir, should_use_colors())?;
let resolved = resolved_for(&content, worklane_dir)?;
// The only title in the output: content_trim_colored used to print it a second
// time from the file content. Green per the colour guideline, and the rule is
@@ -453,9 +368,8 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
println!("\n{}", content_trim_colored(&content, &resolved));
if ticket_uuid != "_Not set_" {
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
let comments = read_comments(&comments_dir)?;
let formatted = format_comments(&comments);
let entries = read_history(worklane_dir, &ticket_uuid)?;
let formatted = format_history(&entries);
println!("{}", formatted);
}
@@ -611,7 +525,10 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
for blocker in &blockers {
match index.get(&blocker.target) {
Some(target) if target.status == DONE => {}
// 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!(
" ({}) {} [{}]",
color_text(short_id(&target.uuid), Color::Red),
@@ -639,12 +556,71 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
))
}
/// Refuse discarding a ticket while open tickets are blocked by it.
///
/// The mirror of [`check_blockers`], asked at the other end of the edge: those tickets
/// recorded a dependency on work that is about to be declared never-happening, so their
/// plans need a look before the ground moves. `-f` is the caller saying they looked.
///
/// Tickets already done or discarded do not hold it up: a dependency that was satisfied
/// or abandoned is nobody's plan anymore.
fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str) -> Result<()> {
let index = RelationIndex::load(worklane_dir)?;
// Every open dependent, not the first, for the reason `check_blockers` names them
// all.
let waiting: Vec<String> = index
.iter()
.filter(|ticket| is_open(&ticket.status))
.filter(|ticket| {
ticket
.relations
.iter()
.any(|relation| relation.kind == RelationKind::BlockedBy && relation.target == uuid)
})
.map(|ticket| {
format!(
" ({}) {} [{}]",
color_text(short_id(&ticket.uuid), Color::Red),
ticket.title,
color_text(&ticket.status, Color::Orange),
)
})
.collect();
if waiting.is_empty() {
return Ok(());
}
Err(anyhow!(
"Cannot discard '{}' while open tickets are blocked by it:\n{}\nUse --force (-f) to discard it anyway.",
color_text(title, Color::Green),
waiting.join("\n"),
))
}
/// A status is a [`Status`] rather than a string, so an unknown one is clap's to refuse
/// and nothing here has to check. What is left is the order of the flow, which is
/// `Status::ALL`.
pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Result<()> {
pub fn cmd_mv(
ticket_id: &str,
target: Status,
force: bool,
actor: &Option<String>,
reason: &Option<String>,
start: &Path,
) -> Result<()> {
let target_status = target.as_str();
// A reason is one fact on one line, which is how the renderer draws it, so a
// newline smuggled in through the shell collapses with the whitespace around it.
// All blank means none, rather than an empty field in the log.
let reason = reason
.as_deref()
.map(str::split_whitespace)
.map(|words| words.collect::<Vec<_>>().join(" "))
.unwrap_or_default();
let worklane_dir = find_worklane_dir(start)?;
let (current_status, title, resolved) = resolve_ticket(ticket_id, &worklane_dir)?;
@@ -654,7 +630,13 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
.unwrap();
let target_idx = Status::ALL.iter().position(|status| *status == target).unwrap();
if !force && target_idx < current_idx {
// Discarding is not a stage of work, so the walk rules below do not apply to
// entering it: a ticket is abandoned from wherever it stands. They do apply to
// leaving it, which with discarded last in `Status::ALL` is always a backward move,
// so un-discarding needs `-f` with no rule of its own.
let discarding = target == Status::Discarded;
if !force && !discarding && target_idx < current_idx {
return Err(anyhow!(
"Cannot move backward from {} to {}. Use --force (-f) to allow.",
color_text(&current_status, Color::Orange),
@@ -662,15 +644,48 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
));
}
if !force && target_idx != current_idx + 1 && target_idx != current_idx {
if !force && !discarding && target_idx != current_idx + 1 && target_idx != current_idx {
return Err(anyhow!(
"Can only move one stage forward at a time. Use --force (-f) to skip stages."
));
}
if current_status == target_status {
// `current_status` is read off the directory, so this comparison is the field's
// only chance to be seen. A ticket whose file sits here and whose Status field
// says something else is a hand-moved file or a partial restore, and refusing it
// as a no-op left a repair nobody could reach without moving the file away and
// back; the mirror case, where the field leads the directory after a crash in
// move_ticket_file, is what the next real mv corrects.
let recorded = parse_ticket_field(&resolved, "Status");
if recorded == target_status {
println!(
"Ticket is already in '{}' status.",
color_text(target_status, Color::Orange)
);
return Ok(());
}
// The repair is not a move, so none of what gates one applies: not `-f`, which
// overrides transitions, and not the dependency guards behind it. Only the field
// is rewritten — no stamp, because the work arrived nowhere new, and no history
// entry, because an entry shaped like a transition would record a journey the
// ticket never took.
let corrected = set_status_field(&resolved, target_status, &title)?;
save_ticket(
&worklane_dir,
&current_status,
&parse_ticket_field(&resolved, "ID"),
&title,
None,
&corrected,
)?;
println!(
"Ticket is already in '{}' status.",
"Corrected Status field on '{}': said {}, but the file sits in {}.",
color_text(&title, Color::Green),
color_text(&recorded, Color::Orange),
color_text(target_status, Color::Orange)
);
return Ok(());
@@ -678,14 +693,25 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
// After the no-op above, so a ticket is never refused for a move it is not making,
// and behind `force`, which is where the other two overrides of a rule the board
// keeps true already live.
// keeps true already live. The two guards look opposite ways: a ticket being worked
// must not run ahead of what it waits on, and a ticket being abandoned owes nothing
// to its own blockers but must not be pulled out from under the tickets waiting on
// it.
if !force {
check_blockers(&worklane_dir, &resolved, &title)?;
match discarding {
true => check_dependents(&worklane_dir, &parse_ticket_field(&resolved, "ID"), &title)?,
false => check_blockers(&worklane_dir, &resolved, &title)?,
}
}
let current_path = worklane_dir.join(&current_status);
let target_path = worklane_dir.join(target_status);
// A board created before a status existed has no directory for it, and the first
// move into one is the wrong place to refuse. Idempotent for every board that has
// it.
fs::create_dir_all(&target_path)?;
// Updated before the file is even located, so a ticket without a Status field is
// refused for that reason rather than for whatever the lookup notices first.
let content = set_status_field(&resolved, target_status, &title)?;
@@ -712,6 +738,18 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
&title,
)?;
// After the move, never before: an entry for a move that was refused would be a log
// of things that did not happen. The no-op above returns without one for the same
// reason, and without its --reason with it.
write_entry(
&worklane_dir,
&parse_ticket_field(&resolved, "ID"),
Kind::Status,
&change(&current_status, target_status),
&resolve_actor(actor.as_deref()),
&reason,
)?;
println!(
"Moved ticket '{}' from {} to {}",
color_text(&title, Color::Green),
@@ -725,7 +763,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
pub fn cmd_comment(
ticket_id: &str,
body: &str,
owner: &Option<String>,
actor: &Option<String>,
start: &Path,
) -> Result<()> {
if body.is_empty() {
@@ -740,29 +778,14 @@ pub fn cmd_comment(
return Err(anyhow!("Could not determine ticket ID."));
}
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
fs::create_dir_all(&comments_dir)?;
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
let author = match owner {
Some(o) => o.clone(),
None => get_git_user().unwrap_or_else(|| "unknown".to_string()),
};
let comment_content = format!(
"**Comment**\n\
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n\
",
let filename = write_entry(
&worklane_dir,
&ticket_uuid,
Kind::Comment,
body,
author,
Local::now().format(TIMESTAMP_FORMAT)
);
let filename = write_new_comment(&comments_dir, &stem, &comment_content)?;
&resolve_actor(actor.as_deref()),
"",
)?;
println!("Comment added to '{}' ({})", title, filename);
Ok(())
@@ -996,6 +1019,24 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
save_ticket(&worklane_dir, &status, &uuid, &title, renamed, &content)?;
// Tags alone, of everything `set` writes. The other fields change often enough that a
// log of them is noise, and `apply` is what decides this: a field it did not record as
// changed was already what the call asked for. Emptying the field counts, since
// `--clear tags` is the same field going somewhere.
if changed.contains(&"tags") || cleared.contains(&"tags") {
write_entry(
&worklane_dir,
&uuid,
Kind::Tags,
&change(
&parse_ticket_field(&original, "Tags"),
&parse_ticket_field(&content, "Tags"),
),
&resolve_actor(args.actor.as_deref()),
"",
)?;
}
let shown = args.title.clone().unwrap_or(title);
if !changed.is_empty() {
report(&changed, &shown, "Updated");
@@ -1040,6 +1081,20 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
// Behind the no-change return above, so a chown to the owner a ticket already has
// records nothing, and after the save, so a failed write logs nothing.
write_entry(
&worklane_dir,
&uuid,
Kind::Owner,
&change(
&parse_ticket_field(&original, "Owner"),
&parse_ticket_field(&content, "Owner"),
),
&resolve_actor(args.actor.as_deref()),
"",
)?;
let verb = match user {
Some(_) => "Updated",
None => "Cleared",
@@ -1083,16 +1138,97 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
/// The kinds are a flag each rather than a `--kind` value, so an unknown kind is a
/// usage error at the door instead of a line written into the file and refused on the
/// way back out.
/// The stored relation a `--clear` names, or `None` when the ticket does not hold it.
///
/// Two tiers, in this order. A uuid prefix against the targets this ticket already
/// stores, which is the only tier that can reach a dangling edge: the target's ticket is
/// gone, so no search of the board resolves it, and that is the case most likely to need
/// clearing. Then the ordinary ticket search, so a title or a prefix of a live ticket
/// works here the way it does in every other argument.
///
/// The prefix tier is the ticket's own relations and not the board, so it stays cheap and
/// cannot be made ambiguous by a ticket somewhere else. `MIN_ID_SEARCH` is the same floor
/// `resolve_in` puts under its id tier, and the comparison is case insensitive for the
/// same reason: an id typed back off a listing has to resolve in whatever case it was
/// read.
///
/// A search that reaches neither tier is an error, not a no-op. A relation the ticket does
/// not hold reports no change, which is what the caller asked for either way, but a search
/// naming nothing at all is a typo and reporting no change for it would swallow it.
fn find_relation(
existing: &[Relation],
kind: RelationKind,
search: &str,
title: &str,
worklane_dir: &Path,
) -> Result<Option<Relation>> {
let held: Vec<&Relation> = existing.iter().filter(|held| held.kind == kind).collect();
let wanted = search.to_lowercase();
let by_prefix: Vec<&Relation> = held
.iter()
.copied()
.filter(|held| {
search.chars().count() >= MIN_ID_SEARCH
&& held.target.to_lowercase().starts_with(&wanted)
})
.collect();
match by_prefix.as_slice() {
[only] => return Ok(Some((*only).clone())),
// Named rather than guessed at, the way an ambiguous ticket search is: the
// candidates are printed and nothing is written.
[_, _, ..] => {
return Err(anyhow!(
"'{}' matches {} '{}' relations on '{}': {}. Name more of the id",
search,
by_prefix.len(),
kind.label(),
title,
by_prefix
.iter()
.map(|held| short_id(&held.target))
.collect::<Vec<_>>()
.join(", ")
));
}
[] => {}
}
match resolve_ticket(search, worklane_dir) {
Ok((_status, _target_title, target)) => {
let target_uuid = parse_ticket_field(&target, "ID");
Ok(held.into_iter().find(|held| held.target == target_uuid).cloned())
}
// The resolver's own reason is carried through, so an ambiguous search says it is
// ambiguous rather than being reported as nothing at all.
Err(reason) => Err(anyhow!(
"No '{}' relation on '{}' matches '{}': {}",
kind.label(),
title,
search,
reason
)),
}
}
pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(&args.ticket, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
let existing = parse_relations(&original, &title)?;
// Every target resolved and every refusal raised before a byte is written, so a
// call naming one good ticket and one bad one records neither.
// Every target resolved, every kind parsed and every refusal raised before a byte is
// written, so a call naming one good ticket and one bad one records neither.
let asked = args.cleared()?;
let mut items: Vec<String> = Vec::new();
let mut changed: Vec<&str> = Vec::new();
// Every addition the call asked for, whether or not it is one to write. `items` drops
// the ones already held, and a contradiction has to be caught on what was *asked*: a
// relation already in the file is not in `items`, so comparing against that would let
// `--blocked-by X --clear blocked-by X` quietly remove it.
let mut requested: Vec<Relation> = Vec::new();
for (kind, targets) in args.requested() {
for search in targets {
@@ -1114,10 +1250,21 @@ 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;
}
@@ -1128,15 +1275,74 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
}
if items.is_empty() {
let mut dropped: Vec<Relation> = Vec::new();
let mut cleared: Vec<&str> = Vec::new();
for (kind, search) in asked {
let Some(relation) = find_relation(&existing, kind, search, &title, &worklane_dir)? else {
continue;
};
// Both directions in one call, the way `set --clear` refuses a field it is also
// replacing: nothing is written rather than one of the two silently winning.
if requested.contains(&relation) {
return Err(anyhow!(
"--{} and --clear {} name the same relation to '{}', so nothing was written",
kind.flag(),
kind.flag(),
short_id(&relation.target)
));
}
if dropped.contains(&relation) {
continue;
}
dropped.push(relation);
if !cleared.contains(&kind.label()) {
cleared.push(kind.label());
}
}
if items.is_empty() && dropped.is_empty() {
report(&[], &title, "Recorded");
return Ok(());
}
let content = append_section_body(&ensure_section(&original, &RELATIONS), &RELATIONS, &items)?;
// Removals first, by rewriting the section from what is left, then additions appended
// to that. Two passes rather than one rebuild of the whole section: a call with no
// `--clear` then takes exactly the path it always took, and `append_section_body` goes
// on deciding where a new line lands.
let mut content = original.clone();
if !dropped.is_empty() {
let kept: Vec<String> = existing
.iter()
.filter(|held| !dropped.contains(held))
.map(|held| held.item())
.collect();
// The placeholder rather than an empty body when the last edge goes, which is the
// line `add` writes and the line `append` treats as no content, so the section can
// be written to again without it being left above what follows.
content = match kept.is_empty() {
true => clear_section_body(&content, &RELATIONS)?,
false => set_section_body(&content, &RELATIONS, &kept)?,
};
}
if !items.is_empty() {
content = append_section_body(&ensure_section(&content, &RELATIONS), &RELATIONS, &items)?;
}
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
report(&changed, &title, "Recorded");
if !changed.is_empty() {
report(&changed, &title, "Recorded");
}
if !cleared.is_empty() {
report(&cleared, &title, "Cleared");
}
Ok(())
}
@@ -1565,7 +1771,12 @@ pub fn cmd_campaign_show(search: &str, worklane_dir: &Path) -> Result<()> {
///
/// No-op detection compares the whole file, the way `set` and `chown` do, so assigning
/// a ticket to the campaign it already names writes nothing.
pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Result<()> {
pub fn cmd_assign(
campaign_search: &str,
ticket_id: &str,
actor: &Option<String>,
start: &Path,
) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(campaign_search, &worklane_dir)?;
let (status, title, original) = resolve_ticket(ticket_id, &worklane_dir)?;
@@ -1584,6 +1795,27 @@ pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Resul
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
// Behind the no-change return above and after the save, the rule every writer
// follows. The entry records `Campaign::name`, not the uuid the field holds: what
// the reader should see is settled here, when the entry is written. A campaign the
// board no longer has reads `_missing_`, the way the Campaign field itself renders
// a dangling uuid.
let before = match parse_campaign(&original) {
None => NOT_SET.to_string(),
Some(old) => CampaignIndex::load(&worklane_dir)?
.get(&old)
.map(|was| was.name().to_string())
.unwrap_or_else(|| MISSING.to_string()),
};
write_entry(
&worklane_dir,
&uuid,
Kind::Campaign,
&change(&before, campaign.name()),
&resolve_actor(actor.as_deref()),
"",
)?;
println!(
"Assigned '{}' to campaign '{}'",
color_text(&title, Color::Green),
@@ -1857,33 +2089,3 @@ pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
/// The collision path cannot be provoked from the CLI, since two processes
/// will not share a microsecond, but it is the whole point of the guard.
#[test]
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
let dir = Fixture::new("worklane-test");
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
let third = write_new_comment(&dir, "20260820_143012_123456", "third").unwrap();
assert_eq!(first, "20260820_143012_123456.md");
assert_eq!(second, "20260820_143012_123456_01.md");
assert_eq!(third, "20260820_143012_123456_02.md");
// Nothing was truncated on the way through
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
// read_comments sorts on the stem, so the names must sort in write order
let mut names = vec![second.clone(), third.clone(), first.clone()];
names.sort();
assert_eq!(names, vec![first, second, third]);
}
}
+1136
View File
File diff suppressed because it is too large Load Diff
+6 -5
View File
@@ -489,10 +489,10 @@ mod tests {
///
/// The domain examples are the first thing an edit would quietly drop, since every
/// other skill here is written around this repo, and dropping them leaves a document
/// that teaches a household board to file `cli` tickets. The two-step repair is the
/// second: it looks like a typo until you have watched `mv` refuse the one-step
/// version, which is why the ticket for this skill demanded every repair be run rather
/// than reasoned about.
/// that teaches a household board to file `cli` tickets. The one-move correction is
/// the second: it is the repair `mv` actually performs since it learned to fix a
/// Status field that lags its directory, and an edit back to the old two-step recipe
/// would be teaching a workaround for a bug that no longer exists.
#[test]
fn the_admin_skill_stays_domain_neutral_and_keeps_its_verified_repairs() {
for required in [
@@ -500,7 +500,8 @@ mod tests {
"product strategy", //
"worklane tags add", // the vocabulary is declared through the CLI
"--tags` replaces the whole field", // the destructive one, restated where it bites
"two moves, not one", // the repair `mv` cannot do in one step
"reporting the correction instead of refusing as a no-op", // the repair `mv` does in one step
"no stamp is written and no history entry", // because the work went nowhere
"do not edit a ticket file",
"File exception", // and the three places that rule does not reach
"worklane-plan", // the boundary against the sweep document
+16 -6
View File
@@ -6,6 +6,7 @@ mod clipboard;
mod command;
mod completions;
mod handlers;
mod history;
mod install;
mod tag;
mod tui;
@@ -56,15 +57,21 @@ fn main() -> Result<()> {
let worklane_dir = find_worklane_dir(&start)?;
cmd_show(&id, &worklane_dir)
}
Some(Command::Mv { ticket, status, force }) => cmd_mv(&ticket, status, force, &start),
Some(Command::Mv {
ticket,
status,
force,
actor,
reason,
}) => cmd_mv(&ticket, status, force, &actor, &reason, &start),
Some(Command::Set(args)) => cmd_set(&args, &start),
Some(Command::Append(args)) => cmd_append(&args, &start),
Some(Command::Relate(args)) => cmd_relate(&args, &start),
Some(Command::Chown(args)) => cmd_chown(&args, &start),
Some(Command::Check(args)) => cmd_check(&args, true, &start),
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
Some(Command::Comment { ticket, body, owner }) => {
cmd_comment(&ticket, &body, &owner, &start)
Some(Command::Comment { ticket, body, actor }) => {
cmd_comment(&ticket, &body, &actor, &start)
}
Some(Command::Campaign { command }) => match command {
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
@@ -79,7 +86,9 @@ fn main() -> Result<()> {
cmd_campaign_show(&campaign, &worklane_dir)
}
},
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
Some(Command::Assign { campaign, ticket, actor }) => {
cmd_assign(&campaign, &ticket, &actor, &start)
}
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
// group existed and the fish completion still calls it that way, so the two
// spellings cannot be allowed to drift into two behaviours.
@@ -233,8 +242,9 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// columns took hjkl and the arrows.
KeyCode::Tab => board.select_tab(1, screen),
KeyCode::BackTab => board.select_tab(-1, screen),
// Free of the other bindings, and the footer names it in both states.
KeyCode::Char('d') => board.toggle_done(screen),
// Free of the other bindings, and the footer names what the next press
// does in every state of the rotation.
KeyCode::Char('d') => board.rotate_visibility(screen),
// An ordinary single-shot action like the rest: it opens the prompt, and
// from the next keypress on `search_key` above has the keyboard. A `/`
// typed into an open prompt is taken there as a character, and one pressed
+2008 -464
View File
File diff suppressed because it is too large Load Diff
+1017 -236
View File
File diff suppressed because it is too large Load Diff
+40
View File
@@ -1703,3 +1703,43 @@ fn a_campaign_with_no_description_section_is_refused() {
assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written");
}
}
/// A discarded member counts as finished. The work was decided out of the campaign
/// rather than left in it, and counting it as outstanding would hold the campaign open
/// forever over a ticket nobody will ever do.
#[test]
fn a_discarded_member_counts_as_finished() {
let temp = TempDir::new().unwrap();
let _worklane = board(&temp);
run(&temp, &["assign", "v1 release", MEMBER]);
run(&temp, &["assign", "v1 release", OTHER]);
// Two members, one done and one in the backlog: open and half finished.
let listing = stdout(&run(&temp, &["campaign", "ls"]));
assert!(listing.contains("v1 release | 1/2 done [open]"), "{listing}");
let discarded = run(&temp, &["mv", MEMBER, "--status", "discarded"]);
assert!(discarded.status.success(), "{}", stderr(&discarded));
let listing = stdout(&run(&temp, &["campaign", "ls"]));
assert!(listing.contains("v1 release | 2/2 done [done]"), "{listing}");
}
/// `campaign show` groups the members by status, and a discarded one has a group to
/// land in rather than dropping out of the campaign it belongs to.
#[test]
fn campaign_show_lists_a_discarded_member() {
let temp = TempDir::new().unwrap();
let _worklane = board(&temp);
run(&temp, &["assign", "v1 release", MEMBER]);
assert!(
run(&temp, &["mv", MEMBER, "--status", "discarded"])
.status
.success()
);
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
assert!(shown.contains("The member"), "the discarded member is gone: {shown}");
}
+1 -1
View File
@@ -314,7 +314,7 @@ fn check_leaves_nothing_behind() {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect();
assert_eq!(strays, Vec::<String>::new());
+1 -1
View File
@@ -77,7 +77,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect()
}
+150 -30
View File
@@ -41,6 +41,24 @@ fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
uuid
}
/// The one comment on a ticket, which every author test writes exactly one of.
fn only_comment(worklane_dir: &Path, uuid: &str) -> String {
let files: Vec<_> = fs::read_dir(worklane_dir.join("history").join(uuid))
.unwrap()
.filter_map(|e| e.ok())
.collect();
assert_eq!(files.len(), 1, "expected one comment");
fs::read_to_string(files[0].path()).unwrap()
}
/// A git config file holding nothing but a `user.name`, for the tests that need the
/// fallback to answer something known instead of whatever the machine is configured with.
fn git_config_naming(temp: &TempDir, name: &str) -> PathBuf {
let path = temp.path().join("gitconfig");
fs::write(&path, format!("[user]\n\tname = {}\n", name)).unwrap();
path
}
#[test]
fn comment_creates_file_with_valid_ticket_uuid() {
let temp = TempDir::new().unwrap();
@@ -55,9 +73,9 @@ fn comment_creates_file_with_valid_ticket_uuid() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
assert!(comments_dir.exists());
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
assert!(history_dir.exists());
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -107,8 +125,8 @@ fn comment_includes_git_user_and_body() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -131,8 +149,8 @@ fn comment_stored_in_timestamped_file() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -142,14 +160,14 @@ fn comment_stored_in_timestamped_file() {
}
#[test]
fn comment_creates_comments_directory() {
fn comment_creates_the_history_directory() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "reviewing", "Dir Test");
let comments_dir = worklane.join("comments").join(&uuid);
assert!(!comments_dir.exists());
let history_dir = worklane.join("history").join(&uuid);
assert!(!history_dir.exists());
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
@@ -158,36 +176,138 @@ fn comment_creates_comments_directory() {
.assert()
.success();
assert!(comments_dir.exists());
assert!(history_dir.exists());
}
#[test]
fn comment_uses_owner_flag_when_provided() {
fn comment_uses_actor_flag_when_provided() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Owner Test");
let uuid = create_ticket(&worklane, "backlog", "Actor Test");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.arg("comment")
.args([&uuid, "Test comment with owner"])
.arg("-o")
.arg("TestUser")
.args([&uuid, "Test comment with actor"])
.args(["--actor", "TestUser"])
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
assert!(only_comment(&worklane, &uuid).contains("**Author**: TestUser"));
}
/// The flag it was, which named the ticket's assignee and not the writer of the entry.
/// Renamed without an alias, so the old spelling is a usage error rather than something
/// that half works.
#[test]
fn the_owner_flag_is_gone() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Gone Test");
for flag in ["--owner", "-o"] {
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.arg("comment")
.args([&uuid, "A body"])
.args([flag, "TestUser"])
.assert()
.failure();
}
assert!(
!worklane.join("history").join(&uuid).exists(),
"a comment was written despite the usage error"
);
}
/// The variable is the case an agent runs in: set once by its configuration and
/// inherited by every call, where a flag can be forgotten on the fortieth one.
#[test]
fn comment_takes_the_author_from_the_actor_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Variable Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.filter_map(|e| e.ok())
.collect();
let content = fs::read_to_string(files[0].path()).unwrap();
assert!(content.contains("**Author**: TestUser"));
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.arg("comment")
.args([&uuid, "Written by an agent"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: claude"));
}
#[test]
fn comment_falls_back_to_git_user_when_owner_omitted() {
fn the_actor_flag_overrides_the_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Override Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.arg("comment")
.args([&uuid, "Written by the other one"])
.args(["--actor", "opencode"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: opencode"));
}
/// An empty variable counts as unset, the convention `NO_COLOR` follows, so a wrapper
/// script can clear an inherited one and get the git user back.
#[test]
fn an_empty_actor_variable_falls_through_to_the_git_user() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Empty Variable Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "")
.env("GIT_CONFIG_GLOBAL", git_config_naming(&temp, "Configured User"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written by a person"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: Configured User"));
}
/// The last resort. Reached with a git that has no `user.name`, which is why the config
/// files are redirected: the machine running the suite has one.
#[test]
fn the_author_is_unknown_when_nothing_names_one() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Unknown Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env_remove("WORKLANE_ACTOR")
.env("GIT_CONFIG_GLOBAL", temp.path().join("no-such-gitconfig"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written by nobody in particular"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: unknown"));
}
#[test]
fn comment_falls_back_to_git_user_when_actor_omitted() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
@@ -200,8 +320,8 @@ fn comment_falls_back_to_git_user_when_owner_omitted() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -228,8 +348,8 @@ fn comments_added_back_to_back_are_both_kept() {
.success();
}
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -263,7 +383,7 @@ fn comment_accepts_a_body_that_begins_with_a_hyphen() {
.success();
}
let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid))
let bodies: String = fs::read_dir(worklane.join("history").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
@@ -318,7 +438,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("<BODY>"), "unclear error: {stderr}");
assert!(
!worklane.join("comments").join(&uuid).exists(),
!worklane.join("history").join(&uuid).exists(),
"a comment was written despite the error"
);
@@ -328,7 +448,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
.assert()
.success();
let stored: String = fs::read_dir(worklane.join("comments").join(&uuid))
let stored: String = fs::read_dir(worklane.join("history").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
+2 -2
View File
@@ -62,10 +62,10 @@ fn no_other_shell_gets_the_fish_half() {
#[test]
fn fish_is_offered_every_status() {
let out = script("fish");
for status in ["backlog", "committed", "reviewing", "done"] {
for status in ["backlog", "committed", "reviewing", "done", "discarded"] {
assert!(out.contains(status), "fish is never offered {status}");
}
assert!(out.contains("-a 'backlog committed reviewing done' -d status"));
assert!(out.contains("-a 'backlog committed reviewing done discarded' -d status"));
}
#[test]
+44
View File
@@ -903,3 +903,47 @@ fn ls_ids_prints_the_same_order_the_listing_does() {
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
/// Discarded is the other terminal status, so the decorated listing leaves it out the
/// way it leaves done out: it is counted in the summary and not listed. The positional
/// and `--ids` still reach it, since a ticket nobody will work still has to be nameable.
#[test]
fn ls_hides_discarded_but_counts_and_can_name_it() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
temp.child(".worklane")
.child("discarded")
.create_dir_all()
.unwrap();
create_ticket_with_id(
&worklane,
"backlog",
"Still open",
"aaaaaaa1-0000-0000-0000-000000000001",
"bug",
);
create_ticket_with_id(
&worklane,
"discarded",
"Abandoned",
"ccccccc3-0000-0000-0000-000000000003",
"bug",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls");
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Still open"), "{stdout}");
assert!(!stdout.contains("Abandoned"), "discarded was listed: {stdout}");
assert!(stdout.contains("DISCARDED"), "discarded is not counted: {stdout}");
// Nameable both ways, the way done is.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
assert!(get_stdout(&mut cmd).contains("Abandoned"));
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "discarded"]);
assert!(get_stdout(&mut cmd).contains("Abandoned"));
}
+346 -1
View File
@@ -474,7 +474,7 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect();
@@ -1144,3 +1144,348 @@ fn mv_does_not_restamp_a_no_op_move() {
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
}
/// A ticket whose file sits in one status directory while its Status field says another
/// is a hand-moved file or a partial restore. Moving it to the status it already sits in
/// is the repair: the field is rewritten to agree with the directory and reported as a
/// correction rather than refused as a no-op.
#[test]
fn mv_repairs_a_lagging_status_field_instead_of_refusing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "done");
let drifted = ticket_at(&worklane, "done", &filename)
.replace("- **Status**: done", "- **Status**: backlog");
fs::write(worklane.join("done").join(&filename), &drifted).unwrap();
let out = move_ticket(&temp, "cccc3333", "done", false);
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(out.status.success(), "{stderr}");
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Corrected Status field"), "{stdout}");
assert!(stdout.contains("backlog"), "{stdout}");
// Not a move: nothing was relocated and only the field changed, byte for byte.
assert!(worklane.join("done").join(&filename).exists());
assert_eq!(md_files(&worklane.join("backlog")), Vec::<String>::new());
assert_eq!(
ticket_at(&worklane, "done", &filename),
drifted.replace("- **Status**: backlog", "- **Status**: done")
);
}
/// The repair corrects bookkeeping rather than moving work, so it stamps nothing and
/// logs nothing: an entry shaped like a transition would record a journey the ticket
/// never took.
#[test]
fn a_repair_writes_no_stamp_and_no_history_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
// A real move first, so the ticket carries the stamp and the log entry that a
// repair has to leave alone.
let out = move_ticket(&temp, "cccc3333", "committed", false);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let history = worklane
.join("history")
.join("cccc3333cccc3333cccc3333cccc3333cccc");
assert_eq!(md_files(&history).len(), 1);
let content = ticket_at(&worklane, "committed", &filename);
assert!(content.contains("Committed On"), "{content}");
let drifted = content.replace("- **Status**: committed", "- **Status**: done");
fs::write(worklane.join("committed").join(&filename), &drifted).unwrap();
let out = move_ticket(&temp, "cccc3333", "committed", false);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let repaired = ticket_at(&worklane, "committed", &filename);
assert!(repaired.contains("Committed On"), "{repaired}");
assert!(!repaired.contains("Submitted On"), "{repaired}");
assert_eq!(md_files(&history).len(), 1, "the repair logged an entry");
}
/// The mirror drift, a field ahead of its directory from a crash mid-move, repairs the
/// same way when the caller keeps the ticket where it sits rather than moving it on to
/// where the field claims.
#[test]
fn mv_repairs_a_field_ahead_of_its_directory_too() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
let drifted = ticket_at(&worklane, "backlog", &filename)
.replace("- **Status**: backlog", "- **Status**: done");
fs::write(worklane.join("backlog").join(&filename), &drifted).unwrap();
let out = move_ticket(&temp, "cccc3333", "backlog", false);
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(out.status.success(), "{stderr}");
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Corrected Status field"), "{stdout}");
assert!(worklane.join("backlog").join(&filename).exists());
assert!(
ticket_at(&worklane, "backlog", &filename).contains("- **Status**: backlog"),
"{}",
ticket_at(&worklane, "backlog", &filename)
);
}
// ---------------------------------------------------------------- discarded --
/// Discarding is not a stage of work, so it is reachable from wherever the ticket
/// stands and needs no `-f`: a backlog ticket that turns out to be a duplicate should
/// not have to be walked through committed and reviewing to be abandoned.
#[test]
fn mv_discards_from_every_status_without_force() {
for from in ["backlog", "committed", "reviewing", "done"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, from);
let out = move_ticket(&temp, "cccc3333", "discarded", false);
assert!(
out.status.success(),
"discarding from {from}: {}",
String::from_utf8_lossy(&out.stderr)
);
assert!(
worklane.join("discarded").join(&filename).exists(),
"the ticket did not land in discarded from {from}"
);
assert_eq!(md_files(&worklane.join(from)).len(), 0, "left behind in {from}");
}
}
/// The fixture board has the four directories the tool shipped with. The first discard
/// on a board that predates the status creates the fifth rather than refusing.
#[test]
fn mv_creates_the_discarded_directory_on_a_board_that_predates_it() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
assert!(
!worklane.join("discarded").exists(),
"the fixture already had the directory"
);
let out = move_ticket(&temp, "cccc3333", "discarded", false);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(worklane.join("discarded").join(&filename).exists());
}
/// Leaving discarded is a backward move, which is the rule that already needs `-f`.
/// Un-discarding is a correction rather than a stage, so it is allowed under it.
#[test]
fn leaving_discarded_needs_force() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
assert!(
move_ticket(&temp, "cccc3333", "discarded", false)
.status
.success()
);
let refused = move_ticket(&temp, "cccc3333", "backlog", false);
assert!(!refused.status.success());
assert!(
String::from_utf8_lossy(&refused.stderr).contains("--force"),
"{}",
String::from_utf8_lossy(&refused.stderr)
);
assert!(worklane.join("discarded").join(&filename).exists());
let forced = move_ticket(&temp, "cccc3333", "backlog", true);
assert!(forced.status.success(), "{}", String::from_utf8_lossy(&forced.stderr));
assert!(worklane.join("backlog").join(&filename).exists());
}
/// The guard looks the other way round from `check_blockers`: a ticket being abandoned
/// owes nothing to what it waits on, but the tickets waiting on *it* recorded a
/// dependency on work that is about to be declared never-happening.
#[test]
fn mv_refuses_to_discard_a_ticket_open_tickets_are_blocked_by() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_gated_pair(&worklane, &temp, "backlog");
let out = move_ticket(&temp, "bbbb2222", "discarded", false);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("Gated Task"), "the dependent is not named: {stderr}");
assert!(stderr.contains("--force"), "{stderr}");
assert!(
!worklane.join("discarded").exists(),
"a refused discard made the directory"
);
}
/// `-f` is the caller saying they looked at the dependents.
#[test]
fn mv_discards_a_blocked_from_ticket_with_force() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_gated_pair(&worklane, &temp, "backlog");
let out = move_ticket(&temp, "bbbb2222", "discarded", true);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
}
/// A dependent that is itself finished or abandoned is nobody's plan, so it does not
/// hold up the discard.
#[test]
fn a_done_or_discarded_dependent_does_not_hold_up_a_discard() {
for status in ["done", "discarded"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_gated_pair(&worklane, &temp, "backlog");
assert!(
move_ticket(&temp, "aaaa1111", status, true).status.success(),
"the dependent could not be moved to {status}"
);
let out = move_ticket(&temp, "bbbb2222", "discarded", false);
assert!(
out.status.success(),
"a {status} dependent held up the discard: {}",
String::from_utf8_lossy(&out.stderr)
);
}
}
/// A discarded blocker satisfies the block the way a done one does: there is nothing
/// left to wait for. Whether the dependent still makes sense was asked when the blocker
/// was discarded, which is the refusal above.
#[test]
fn a_discarded_blocker_does_not_block() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = create_gated_pair(&worklane, &temp, "backlog");
assert!(
move_ticket(&temp, "bbbb2222", "discarded", true)
.status
.success()
);
let out = move_ticket(&temp, "aaaa1111", "committed", false);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(worklane.join("committed").join(&filename).exists());
}
/// Entering discarded clears no stamp, which is what discarded being last in
/// `Status::ALL` buys: a ticket abandoned from reviewing keeps the journey it made, so
/// the log still says how far it got before it was dropped.
#[test]
fn discarding_keeps_the_stamps_the_ticket_already_had() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
assert!(
move_ticket(&temp, "cccc3333", "committed", false)
.status
.success()
);
assert!(
move_ticket(&temp, "cccc3333", "reviewing", false)
.status
.success()
);
let before = ticket_at(&worklane, "reviewing", &filename);
let committed_on = field(&before, "Committed On").expect(&before);
let submitted_on = field(&before, "Submitted On").expect(&before);
assert!(
move_ticket(&temp, "cccc3333", "discarded", false)
.status
.success()
);
let after = ticket_at(&worklane, "discarded", &filename);
assert_eq!(
field(&after, "Committed On").as_deref(),
Some(committed_on.as_str()),
"{after}"
);
assert_eq!(
field(&after, "Submitted On").as_deref(),
Some(submitted_on.as_str()),
"{after}"
);
assert!(field(&after, "Discarded On").is_some(), "no discard stamp: {after}");
assert!(
field(&after, "Completed On").is_none(),
"a discard claimed the ticket was done"
);
}
/// The other end of the same rule: a forced move back out of discarded truncates the
/// journey at the target the way every backward move does.
#[test]
fn un_discarding_drops_the_discard_stamp() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
assert!(
move_ticket(&temp, "cccc3333", "discarded", false)
.status
.success()
);
assert!(
move_ticket(&temp, "cccc3333", "committed", true)
.status
.success()
);
let content = ticket_at(&worklane, "committed", &filename);
assert!(field(&content, "Discarded On").is_none(), "{content}");
assert!(field(&content, "Committed On").is_some(), "{content}");
}
/// Prose takes a leading hyphen, so a reason that reads like a flag is stored as the
/// content it is rather than refused or swallowed. The cost of that bargain is that a
/// genuinely mistyped flag here lands in the log too.
#[test]
fn a_reason_takes_a_leading_hyphen_as_content() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(
&worklane,
"backlog",
"Hyphen Reason",
"Prose trap.",
"bbbb2222",
"alice",
"_Not set_",
"",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args([
"mv",
"bbbb2222",
"--status",
"committed",
"--reason",
"-not-a-flag",
])
.assert()
.success();
let dir = worklane.join("history").join("bbbb2222");
let entry = fs::read_dir(&dir)
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
.collect::<Vec<_>>()
.join("\n");
assert!(entry.contains("**Reason**: -not-a-flag\n"), "{entry:?}");
}
+412
View File
@@ -388,3 +388,415 @@ fn a_line_that_is_not_a_relation_is_an_error() {
assert!(stderr.contains("is not a relation"), "{stderr}");
assert!(stderr.contains("The gated one"), "{stderr}");
}
// --------------------------------------------------------------- clearing --
/// Two blockers, one taken off by name. The other survives, which is the whole reason
/// `--clear` names the target and not just the kind: a ticket can hold several of one
/// kind, and emptying all of them is not usually what is wanted.
#[test]
fn a_relation_is_taken_off_by_its_kind_and_its_target() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--blocked-by",
FIXED,
],
);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("Cleared blocked by"), "{}", stdout(&out));
let content = ticket(&worklane, GATED);
assert!(
!content.contains(BLOCKER),
"the cleared relation is still there: {content}"
);
assert!(
content.contains(&format!("- blocked by {}", FIXED)),
"the other one went too: {content}"
);
}
/// Both spellings of the kind, because both are in front of the reader: `blocked-by` is
/// the flag that recorded it and `blocked by` is what `show` prints and what the file
/// stores. Refusing the form the tool itself prints would be a trap.
#[test]
fn the_kind_takes_the_flag_spelling_and_the_label_spelling() {
for kind in ["blocked-by", "blocked by", "Blocked-By"] {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", kind, BLOCKER]);
assert!(out.status.success(), "{kind}: {}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{kind} did not clear it");
}
}
/// The target is a ticket argument like any other, so it resolves by title too.
#[test]
fn a_cleared_target_resolves_by_title() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "blocker"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER));
}
/// A relation the ticket does not hold is the state the caller asked for, so it reports
/// no change rather than failing. The target resolves; the edge is simply not there.
#[test]
fn clearing_a_relation_the_ticket_does_not_hold_reports_no_change() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
// A kind it does not hold at all, and a target it holds under another kind.
for args in [["relates-to", BLOCKER], ["blocked-by", FIXED]] {
let out = run(&temp, &["relate", GATED, "--clear", args[0], args[1]]);
assert!(out.status.success(), "{args:?}: {}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("No changes"), "{args:?}: {}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before, "{args:?} wrote something");
}
}
/// A search naming nothing at all is a typo, not a state to report. Reporting no change
/// for it would swallow it, which is the one thing the no-change rule must not do.
#[test]
fn clearing_a_target_that_names_nothing_is_an_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "9999zzzz"]);
assert!(!out.status.success(), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}
/// The inverse is derived by a scan rather than stored, so taking the stored line off is
/// what takes it off both ends. The other ticket's own file was never touched either way.
#[test]
fn the_derived_inverse_goes_with_the_stored_line() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let untouched = ticket(&worklane, BLOCKER);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let shown = stdout(&run(&temp, &["show", BLOCKER]));
assert!(shown.contains("blocks"), "the inverse was never derived: {shown}");
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let after = stdout(&run(&temp, &["show", BLOCKER]));
assert!(!after.contains("blocks"), "the inverse outlived the stored line: {after}");
assert_eq!(ticket(&worklane, BLOCKER), untouched, "the other ticket was written to");
}
/// The case most likely to need clearing, and the only one no search of the board can
/// reach: the target's ticket is gone, so the prefix tier over the stored targets is what
/// finds it. `show` renders it as `_missing_` until it is cleared, and `mv` warns about it
/// on every move.
#[test]
fn a_dangling_relation_can_be_cleared() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
fs::remove_file(find(&worklane, BLOCKER)).unwrap();
assert!(
stdout(&run(&temp, &["show", GATED])).contains("_missing_"),
"the fixture is not dangling"
);
// By the short id, which is all a reader has once the title is gone.
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", &BLOCKER[..7]]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{}", ticket(&worklane, GATED));
assert!(!stdout(&run(&temp, &["show", GATED])).contains("_missing_"));
}
/// A prefix short enough to reach two stored targets names the candidates rather than
/// guessing, the way an ambiguous ticket search does, and writes nothing.
#[test]
fn an_ambiguous_prefix_over_the_stored_targets_names_the_candidates() {
const ONE: &str = "aaaa1111-0000-4000-8000-000000000000";
const TWO: &str = "aaaa2222-0000-4000-8000-000000000000";
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
create_ticket(&worklane, "backlog", "Twin one", ONE);
create_ticket(&worklane, "backlog", "Twin two", TWO);
run(&temp, &["relate", GATED, "--blocked-by", ONE, "--blocked-by", TWO]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "aaaa"]);
assert!(!out.status.success(), "{}", stdout(&out));
// The stored-target tier and not the board search, which would find the same two
// tickets by their own uuid prefix and report them the same way. The wording is what
// tells the two apart, so it is what this asserts.
let reason = String::from_utf8_lossy(&out.stderr);
assert!(
reason.contains("'blocked by' relations on"),
"the board answered instead: {reason}"
);
assert!(reason.contains(&ONE[..7]) && reason.contains(&TWO[..7]), "{reason}");
assert_eq!(ticket(&worklane, GATED), before);
}
/// The last edge leaves the placeholder `add` writes, not an empty body, so the section
/// can be written to again without the placeholder ending up above what follows it.
#[test]
fn clearing_the_last_relation_leaves_the_placeholder() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(
content.contains(
"## Relations
_No relations._
"
),
"{content}"
);
// And it is written to again without the placeholder being left behind.
run(&temp, &["relate", GATED, "--relates-to", FIXED]);
let again = ticket(&worklane, GATED);
assert!(again.contains(&format!("- relates to {}", FIXED)), "{again}");
assert!(
!again.contains("_No relations._"),
"the placeholder outlived the edge: {again}"
);
}
/// The same file surgery `relate` already does, so the tick, the handwritten section and
/// the prose survive a clear the way they survive a record.
#[test]
fn clearing_leaves_everything_it_was_not_asked_about_alone() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(content.contains("- [x] Crit one"), "the tick was lost: {content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"the unknown section was lost: {content}"
);
assert!(content.contains("1. Step one"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(content.contains("- **Status**: backlog"), "{content}");
}
/// One call does both, and each half reports itself in its own words.
#[test]
fn one_call_records_and_clears_different_relations() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(
&temp,
&[
"relate",
GATED,
"--clear",
"blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let reported = stdout(&out);
assert!(reported.contains("Recorded relates to"), "{reported}");
assert!(reported.contains("Cleared blocked by"), "{reported}");
let content = ticket(&worklane, GATED);
assert!(!content.contains(BLOCKER), "{content}");
assert!(content.contains(&format!("- relates to {}", FIXED)), "{content}");
}
/// Recording and clearing the same relation in one call is refused outright, the way
/// `set` refuses a field it is also replacing: nothing is written rather than one of the
/// two silently winning.
///
/// It has to be caught on what the call *asked* for and not on what it would write. A
/// relation already in the file is not among the additions, so comparing against those
/// would let this call quietly remove one.
#[test]
fn recording_and_clearing_the_same_relation_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--clear",
"blocked-by",
BLOCKER,
],
);
assert!(!out.status.success(), "{}", stdout(&out));
assert!(
String::from_utf8_lossy(&out.stderr).contains("nothing was written"),
"{}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(ticket(&worklane, GATED), before, "the relation was removed anyway");
}
/// A kind that is not one of the three is refused before the ticket is resolved, so
/// nothing is written. Exit 1 rather than clap's 2: the value is one of a pair clap
/// cannot type apart, so the kind is parsed by `RelateArgs::cleared`.
#[test]
fn an_unknown_kind_in_a_clear_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "depends-on", BLOCKER]);
assert!(!out.status.success(), "{}", stdout(&out));
let reason = String::from_utf8_lossy(&out.stderr);
assert!(reason.contains("not a relation kind"), "{reason}");
// The message names the three, in the spelling the flags and the completions use.
for kind in ["blocked-by", "regression-of", "relates-to"] {
assert!(reason.contains(kind), "{reason}");
}
assert_eq!(ticket(&worklane, GATED), before);
}
/// `--clear` takes exactly two values per occurrence, so clap refuses an odd number with
/// a usage error and nothing reaches the handler.
#[test]
fn a_clear_with_one_value_is_a_usage_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by"]);
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}"
);
}
+1 -1
View File
@@ -80,7 +80,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect()
}
+65
View File
@@ -316,6 +316,71 @@ fn an_annotation_that_would_read_as_a_heading_is_refused() {
assert!(!temp.path().join(".worklane").join("tags.md").exists());
}
/// A tab anywhere in an annotation is refused by `tags add`, because the listing's fields
/// are tab separated: past the first tab everything after it reads as a fourth field. The
/// refusal says why, and nothing is written — the value parser refuses before the handler
/// runs, so not even a placeholder file is left behind.
#[test]
fn an_annotation_carrying_a_tab_is_refused_by_tags_add() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags", "add", "bug", "-a", "Something\twrong."]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(!out.status.success(), "{stderr}");
assert!(
stderr.contains("tab") && stderr.contains("separates its fields"),
"{stderr}"
);
assert!(!temp.path().join(".worklane").join("tags.md").exists());
// No staged write survived either, so the directory holds only the status folders.
let left: Vec<_> = fs::read_dir(temp.path().join(".worklane"))
.unwrap()
.map(|e| e.unwrap().file_name())
.collect();
assert_eq!(left.len(), 4, "{left:?}");
}
/// The same value is refused by `tags set`, and the declaration that is already there is
/// untouched.
#[test]
fn an_annotation_carrying_a_tab_is_refused_by_tags_set() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "Something wrong."]);
let before = vocabulary(&temp);
let out = run(&temp, &["tags", "set", "bug", "-a", "Now\twith a tab."]);
assert!(!out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(vocabulary(&temp), before);
}
/// Ordinary prose is unaffected, paragraphs included: the refusal is for the tab alone,
/// which is what keeps it from standing in front of the command's whole purpose.
#[test]
fn an_annotation_without_a_tab_is_taken_whatever_its_shape() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(
&temp,
&[
"tags",
"add",
"bug",
"-a",
"A defect.",
"-a",
"",
"-a",
"--plan is prose",
],
);
assert_eq!(declared(&temp, "bug").as_deref(), Some("A defect.\n\n--plan is prose"));
}
/// The file is made on demand, the way `campaign add` makes the campaigns directory: a board
/// that predates the vocabulary must not need `worklane init` run over it.
#[test]
+564
View File
@@ -0,0 +1,564 @@
//! The history log: what the CLI records about a ticket besides what somebody said.
//!
//! One file rather than a few tests in each command's suite: the rules are about the log
//! and not about `mv` or `chown`, and the interesting cases are the ones where two
//! commands have to agree — every mechanical entry has the same shape, and every refusal
//! writes nothing.
use assert_cmd::Command;
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Output;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
const UUID: &str = "475534a3-8a0d-45cb-9a97-39c251dd8e39";
fn setup_worklane(temp: &TempDir) -> PathBuf {
let worklane = temp.child(".worklane");
worklane.create_dir_all().unwrap();
for dir in ["backlog", "committed", "reviewing", "done"] {
worklane.child(dir).create_dir_all().unwrap();
}
worklane.path().to_path_buf()
}
/// A ticket with every field an entry can record a change to.
fn create_ticket(worklane: &Path, status: &str) -> String {
let filename = format!("{}_a-ticket.md", UUID);
fs::write(
worklane.join(status).join(&filename),
format!(
"# A ticket\n\
\n\
## Description\n\
Something to do.\n\
\n\
## Acceptance Criteria\n\
- [ ] Crit one\n\
- [ ] Crit two\n\
\n\
## Implementation Plan\n\
1. Step one\n\
\n\
## Metadata\n\
\n\
- **ID**: {}\n\
- **Priority**: 3\n\
- **Tags**: alpha\n\
- **Due**: 2026-09-01\n\
- **Owner**: alice\n\
- **Status**: {}\n",
UUID, status
),
)
.unwrap();
filename
}
/// Run with the actor named, so every author assertion is about the log and not about
/// the git user of whoever runs the suite.
fn run(temp: &TempDir, args: &[&str]) -> Output {
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.args(args)
.assert()
.get_output()
.clone()
}
/// Every entry on the ticket, name and content, in the order the log sorts them.
fn entries(worklane: &Path) -> Vec<(String, String)> {
let dir = worklane.join("history").join(UUID);
if !dir.exists() {
return vec![];
}
let mut found: Vec<(String, String)> = fs::read_dir(&dir)
.unwrap()
.filter_map(|entry| entry.ok())
.map(|entry| {
(
entry.file_name().into_string().unwrap(),
fs::read_to_string(entry.path()).unwrap(),
)
})
.collect();
found.sort_by(|a, b| a.0.cmp(&b.0));
found
}
/// The one entry a call wrote, with its kind checked off the filename.
fn only_entry(worklane: &Path, kind: &str) -> String {
let found = entries(worklane);
assert_eq!(found.len(), 1, "expected one entry, got {found:?}");
assert!(found[0].0.ends_with(&format!("_{kind}.md")), "was {}", found[0].0);
found[0].1.clone()
}
#[test]
fn mv_writes_a_status_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["mv", UUID, "--status", "committed"]);
let entry = only_entry(&worklane, "status");
assert!(entry.starts_with("**Status**\nbacklog → committed\n"), "{entry:?}");
assert!(entry.contains("**Author**: claude"), "{entry:?}");
}
/// One file, one event, its explanation: `--reason` rides in the status entry that
/// records the transition it explains, as a field after **Time**, and `show` renders it
/// indented under the row rather than as a paragraph of its own.
#[test]
fn the_reason_travels_with_its_transition() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
run(
&temp,
&[
"mv",
UUID,
"--status",
"backlog",
"-f",
"--reason",
"sent back: the first plan was wrong",
],
);
let entry = only_entry(&worklane, "status");
assert!(entry.starts_with("**Status**\nreviewing → backlog\n"), "{entry:?}");
assert!(
entry.ends_with("**Reason**: sent back: the first plan was wrong\n"),
"{entry:?}"
);
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
let moved = stdout.find("reviewing → backlog").expect("the move is missing");
let reason = stdout
.find("\n sent back: the first plan was wrong")
.expect("the reason is missing");
// Attached means the very next line: nothing, not even a blank line, between.
assert!(
!stdout[moved..reason].contains('\n'),
"the reason is detached from its row:\n{stdout}"
);
}
/// The unusual moves are exactly the ones that need a why, so a refused one must not
/// log one either: the entry is written after the edit, and there was no edit.
#[test]
fn a_refused_move_writes_no_reason_either() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
let out = run(
&temp,
&[
"mv",
UUID,
"--status",
"backlog",
"--reason",
"this move never happened",
],
);
assert_eq!(out.status.code(), Some(1));
assert_eq!(entries(&worklane), vec![], "a refused move logged its reason");
}
/// Same for the move that changes nothing.
#[test]
fn a_no_op_move_writes_no_reason_either() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "committed");
let out = run(
&temp,
&[
"mv",
UUID,
"--status",
"committed",
"--reason",
"nothing moved",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert_eq!(entries(&worklane), vec![], "a no-op move logged its reason");
}
#[test]
fn chown_writes_an_owner_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["chown", "bob", UUID]);
let entry = only_entry(&worklane, "owner");
assert!(entry.starts_with("**Owner**\nalice → bob\n"), "{entry:?}");
}
/// Clearing is the same field going somewhere, so it is logged, and the value it goes to
/// is the sentinel the ticket now holds rather than a word this log invented.
#[test]
fn clearing_the_owner_writes_an_owner_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["chown", "--clear", UUID]);
let entry = only_entry(&worklane, "owner");
assert!(entry.starts_with("**Owner**\nalice → _Not set_\n"), "{entry:?}");
}
#[test]
fn set_tags_writes_a_tags_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["set", UUID, "--tags", "beta", "--tags", "gamma"]);
let entry = only_entry(&worklane, "tags");
assert!(entry.starts_with("**Tags**\nalpha → beta, gamma\n"), "{entry:?}");
}
#[test]
fn clearing_the_tags_writes_a_tags_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["set", UUID, "--clear", "tags"]);
let entry = only_entry(&worklane, "tags");
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
}
/// The entry names the campaign the way a reader knows it, the codename, not the uuid
/// the field actually holds. A ticket never assigned starts from the sentinel an unset
/// field reads as everywhere else.
#[test]
fn assign_writes_a_campaign_entry_naming_the_codename() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First public release",
"--codename",
"v1",
],
);
run(&temp, &["assign", "v1", UUID]);
let entry = only_entry(&worklane, "campaign");
assert!(entry.starts_with("**Campaign**\n_Not set_ → v1\n"), "{entry:?}");
}
/// A campaign filed without a codename is recorded by its title, the name `show` and
/// `campaign ls` fall back to.
#[test]
fn a_campaign_without_a_codename_is_recorded_by_its_title() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["campaign", "add", "--title", "First public release"]);
run(&temp, &["assign", "First public", UUID]);
let entry = only_entry(&worklane, "campaign");
assert!(
entry.starts_with("**Campaign**\n_Not set_ → First public release\n"),
"{entry:?}"
);
}
/// A ticket leaving one campaign for another records both ends, which is the move the
/// log exists to answer for: the field is rewritten, so nothing else remembers where the
/// ticket was.
#[test]
fn moving_between_campaigns_records_both_names() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(
&temp,
&[
"campaign",
"add",
"--title",
"Second release",
"--codename",
"beaver",
],
);
run(&temp, &["assign", "v1", UUID]);
run(&temp, &["assign", "beaver", UUID]);
let found = entries(&worklane);
assert_eq!(found.len(), 2, "{found:?}");
assert!(found[1].1.starts_with("**Campaign**\nv1 → beaver\n"), "{:?}", found[1].1);
}
/// Assigning the campaign a ticket already names is reported as no change, and a log of
/// no change would be a log of nothing happening.
#[test]
fn a_no_op_assign_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(&temp, &["assign", "v1", UUID]);
let out = run(&temp, &["assign", "v1", UUID]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert_eq!(
entries(&worklane).len(),
1,
"a no-op assign logged a change it did not make"
);
}
/// The fields that change often enough that a log of them is noise. `set` writing one of
/// them is not an entry, and neither is a criterion being ticked.
#[test]
fn the_edits_that_are_not_logged_write_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
for args in [
vec!["set", UUID, "--title", "A better title"],
vec!["set", UUID, "--due", "2026-10-01"],
vec!["set", UUID, "--priority", "1"],
vec!["set", UUID, "--description", "Rewritten."],
vec!["set", UUID, "--plan", "One step"],
vec!["check", UUID, "1"],
vec!["uncheck", UUID, "1"],
vec!["append", UUID, "--description", "One more paragraph."],
vec!["comment", UUID, "-", "--"],
] {
let out = run(&temp, &args);
assert!(
out.status.success(),
"{args:?}: {:?}",
String::from_utf8_lossy(&out.stderr)
);
}
// The comment is the exception: it is an entry, and the only one this run wrote.
let found = entries(&worklane);
assert_eq!(found.len(), 1, "{found:?}");
assert!(found[0].0.ends_with("_comment.md"), "was {}", found[0].0);
}
/// An edit reported as no change writes no entry: the field is already what the call
/// asked for, and a log of that would be a log of nothing happening.
#[test]
fn a_no_op_edit_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
for args in [
vec!["mv", UUID, "--status", "backlog"],
vec!["chown", "alice", UUID],
vec!["set", UUID, "--tags", "alpha"],
] {
let out = run(&temp, &args);
assert!(
out.status.success(),
"{args:?}: {:?}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(entries(&worklane), vec![], "{args:?} logged a change it did not make");
}
}
/// A refused move is not a move. The entry is written after the edit for exactly this.
#[test]
fn a_refused_move_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
let backward = run(&temp, &["mv", UUID, "--status", "backlog"]);
assert_eq!(backward.status.code(), Some(1));
let skipped = run(&temp, &["mv", UUID, "--status", "backlog", "-f"]);
assert!(skipped.status.success(), "{:?}", String::from_utf8_lossy(&skipped.stderr));
// The forced one moved, so it is logged; the refused one is not.
let found = entries(&worklane);
assert_eq!(found.len(), 1, "{found:?}");
assert!(found[0].1.contains("reviewing → backlog"), "{:?}", found[0].1);
}
/// A failed edit logs nothing, whatever the failure. This ticket has no Owner field, so
/// `chown` refuses it after resolving it and before writing anything.
#[test]
fn a_failed_edit_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
fs::write(
worklane.join("backlog").join(format!("{}_bare.md", UUID)),
format!("# Bare\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", UUID),
)
.unwrap();
let out = run(&temp, &["chown", "bob", UUID]);
assert_eq!(out.status.code(), Some(1));
assert_eq!(entries(&worklane), vec![], "a refused chown was logged");
}
/// One sequence, oldest first, with a comment rendered as it always was and a field
/// change as one line.
#[test]
fn show_prints_the_comments_and_the_changes_in_one_sequence() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["comment", UUID, "Picked this up."]);
run(&temp, &["mv", UUID, "--status", "committed"]);
run(&temp, &["chown", "bob", UUID]);
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
assert!(stdout.contains("HISTORY"), "{stdout}");
let said = stdout.find("Picked this up.").expect("the comment is missing");
let moved = stdout.find("backlog → committed").expect("the move is missing");
let owned = stdout.find("alice → bob").expect("the chown is missing");
assert!(said < moved && moved < owned, "out of order:\n{stdout}");
for line in ["status backlog → committed", "owner alice → bob"] {
assert!(stdout.contains(line), "{line:?} not in:\n{stdout}");
}
assert!(stdout.contains("From claude ("), "{stdout}");
}
/// A ticket nothing has happened to says so, where it used to say there were no comments.
#[test]
fn show_says_so_when_there_is_no_history() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let out = run(&temp, &["show", UUID]);
assert!(
String::from_utf8(out.stdout)
.unwrap()
.contains("No history yet.")
);
}
/// A board written by an older version: the directory is adopted on the first access,
/// the entries in it are read as the comments they are, and nothing is rewritten.
#[test]
fn an_old_comments_directory_is_adopted() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let legacy = worklane.join("comments").join(UUID);
fs::create_dir_all(&legacy).unwrap();
let name = "20260820_143012_123456.md";
let content =
"**Comment**\nSaid long ago.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n";
fs::write(legacy.join(name), content).unwrap();
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
assert!(stdout.contains("Said long ago."), "{stdout}");
assert!(stdout.contains("From Ansho Rei ("), "{stdout}");
assert!(!worklane.join("comments").exists(), "the old directory survived");
let moved = worklane.join("history").join(UUID).join(name);
assert_eq!(fs::read_to_string(&moved).unwrap(), content, "the entry was rewritten");
// And a new entry lands beside it, in the order it was written.
run(&temp, &["mv", UUID, "--status", "committed"]);
let found = entries(&worklane);
assert_eq!(found.len(), 2, "{found:?}");
assert_eq!(found[0].0, name);
assert!(found[1].0.ends_with("_status.md"), "was {}", found[1].0);
}
/// The flag is spelled the same on every command that writes an entry, and it overrides
/// the variable on each of them.
#[test]
fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(&temp, &["comment", UUID, "By hand.", "--actor", "opencode"]);
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]);
let found = entries(&worklane);
assert_eq!(found.len(), 5, "{found:?}");
for (name, content) in found {
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
}
}