Compare commits

..
6 Commits
Author SHA1 Message Date
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
23 changed files with 2667 additions and 505 deletions
+47 -20
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
@@ -229,7 +240,7 @@ and this file is for what someone changing worklane's own code needs.
- **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 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,13 +248,13 @@ 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_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 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
- **`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
- **`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
- **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
@@ -280,20 +291,20 @@ and this file is for what someone changing worklane's own code needs.
- **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
@@ -348,7 +359,7 @@ and this file is for what someone changing worklane's own code needs.
- **`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 comments block is still flat, and it is the last piece that is.** `format_comments_with` is a string the board appends after the body rather than part of what `content_parts` lays out, so it was outside e4d0bb7. Its own ticket
- **The history block arrives as cells too, so nothing in the overlay is flat.** `history_cells` lays the block out once; `format_history` is those cells through `paint_cells` and the board pushes the same ones as a `Cells` part after the body, since the log lives outside the ticket file and `content_parts` never sees it. Pinned from both ends the way the body is: `show_prints_the_same_history_it_printed_before_the_cells_conversion` holds the CLI's output byte for byte, and `the_history_block_is_styled_in_the_overlay_and_no_escape_reached_it` pairs the presence with the absence (f3e099e, closing the gap e4d0bb7 left)
### 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
@@ -361,7 +372,7 @@ 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
@@ -382,6 +393,21 @@ and this file is for what someone changing worklane's own code needs.
- **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
@@ -430,7 +456,7 @@ 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
- 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
- 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
@@ -443,6 +469,7 @@ 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
- **`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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.28.0"
version = "0.31.2"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.28.0"
version = "0.31.2"
edition = "2024"
[dependencies]
+8 -8
View File
@@ -5,16 +5,16 @@ 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 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. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
@@ -33,7 +33,7 @@ Worklane is a local Kanban flow for agentic software development.
| Variable | Effect |
|----------|--------|
| `WORKLANE_ACTOR` | Who every entry the CLI writes is attributed to: today the author of a comment. 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 |
| `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 |
@@ -51,7 +51,7 @@ 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>
+94 -25
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
@@ -176,9 +209,10 @@ on B. **Only one side is stored**, on the ticket you name, and `show` derives th
end for the ticket at the far side, so never record both directions.
`--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 +221,15 @@ 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.
## Campaigns
@@ -270,6 +304,36 @@ 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 comment carries an author, and by default that is the git user of the machine you
@@ -283,11 +347,16 @@ WORKLANE_ACTOR=claude worklane comment 1b78a24 "The offset was never passed to t
Set it once where your session's environment is configured, not on each call: `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. `--actor` on
`comment` overrides it for one call, an empty value counts as unset and falls back to the
for opencode, since it passes its own environment to the tools it runs. `--actor`
overrides it for one call and is spelled the same on every command that writes an entry,
`comment`, `mv`, `chown`, `set` and `assign`. An empty value counts as unset and falls
back to the
git user, and with nothing at all the author is `unknown`. It is free text, checked
against nothing: name yourself something 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.
If the variable is not set and you cannot set it, pass `--actor` rather than letting the
comment claim to be the user's.
+24 -4
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);
@@ -249,7 +254,7 @@ export const comment = tool({
.describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."),
actor: tool.schema
.string()
.describe("Who the comment 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.")
.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) {
@@ -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}`;
}
+22 -3
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
@@ -192,11 +207,11 @@ pub fn resolved_for(content: &str, worklane_dir: &Path) -> Result<Resolved> {
})
}
/// 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(),
+28 -4
View File
@@ -180,6 +180,12 @@ fn annotation_line(raw: &str) -> Result<String, 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 +227,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,12 +281,9 @@ pub enum Command {
#[arg(allow_hyphen_values = PROSE)]
body: String,
/// Who the comment is attributed to, overriding `WORKLANE_ACTOR` and the git
/// user. Free text, checked against nothing
///
/// 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)]
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
@@ -296,6 +307,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
@@ -732,6 +746,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 {
@@ -777,6 +796,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 {
+1 -1
View File
@@ -568,7 +568,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}");
}
+171 -150
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,93 +353,6 @@ 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");
@@ -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,7 +644,7 @@ 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."
));
@@ -678,14 +660,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 +705,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),
@@ -740,26 +745,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 = resolve_actor(actor.as_deref());
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(())
@@ -993,6 +986,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");
@@ -1037,6 +1048,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",
@@ -1562,7 +1587,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)?;
@@ -1581,6 +1611,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),
@@ -1854,33 +1905,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]);
}
}
+763
View File
@@ -0,0 +1,763 @@
//! What happened to a ticket, one file per entry.
//!
//! The comments directory was already an append-only log with exactly one event kind:
//! one file per entry under a directory named by the ticket's uuid, stamped to the
//! microsecond and written with `create_new` so two writers cannot clobber each other.
//! This is that log with the kind named in it, so a status change, an owner change, a
//! tag change and a campaign move are recorded beside what somebody said about them.
//!
//! What is deliberately not logged: 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, which is
//! the record actually worth keeping.
//!
//! Every entry names its author, from [`resolve_actor`], so a board several agents write
//! to says which of them did what.
//!
//! [`resolve_actor`]: crate::util::resolve_actor
use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};
use anyhow::{Result, anyhow};
use chrono::Local;
use crate::util::{Cell, Color, TIMESTAMP_FORMAT, paint_cells, should_use_colors};
/// Where a ticket's history lives, under the board.
///
/// Beside the status directories rather than among them, the way `campaigns_dir` is: an
/// entry has no status of its own. Spelled once here, so the writer, the reader and the
/// card's counter cannot disagree about the path.
pub const HISTORY_DIR: &str = "history";
/// The name the same directory had while a comment was the only entry it could hold.
///
/// Kept so a board written by an older version is adopted rather than migrated by hand.
/// See [`adopt_comments`].
pub const COMMENTS_DIR: &str = "comments";
/// How an entry filename is stamped.
///
/// Microseconds, not seconds: at second resolution two entries in the same second
/// produced the same name and the second silently truncated the first. Fixed width and
/// first in the name, so the lexicographic sort in [`read_history`] stays chronological
/// whatever kind follows it.
pub const ENTRY_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
/// The history root of a board.
pub fn history_root(board: &Path) -> PathBuf {
board.join(HISTORY_DIR)
}
/// The history directory for one ticket, named by its full uuid.
pub fn history_dir(board: &Path, uuid: &str) -> PathBuf {
history_root(board).join(uuid)
}
/// What an entry records.
///
/// An enum rather than a string, so a kind the reader does not know is a compile error
/// instead of a word that renders as itself. The variants are the five things worth
/// keeping: what somebody said, and the four fields whose history answers a question.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Kind {
Comment,
Status,
Owner,
Tags,
Campaign,
}
impl Kind {
/// Every kind, which is what the reader matches a marker against and what the
/// counter matches a filename against.
pub const ALL: [Kind; 5] = [
Kind::Comment,
Kind::Status,
Kind::Owner,
Kind::Tags,
Kind::Campaign,
];
/// The width the mechanical labels are padded to, `campaign` being the longest of
/// the four. `comment` renders as a header and a body, not as a row, so it is not
/// among them.
const LABEL_WIDTH: usize = 8;
/// The word in the filename, and the label a mechanical entry renders under.
pub fn slug(self) -> &'static str {
match self {
Kind::Comment => "comment",
Kind::Status => "status",
Kind::Owner => "owner",
Kind::Tags => "tags",
Kind::Campaign => "campaign",
}
}
/// The marker the file opens with, which is what the reader keys the kind off.
///
/// The file is the record and the filename is an index into it: a name can be
/// changed by anything that touches the directory, so the kind is read from the
/// content and only counted from the name.
fn marker(self) -> &'static str {
match self {
Kind::Comment => "**Comment**",
Kind::Status => "**Status**",
Kind::Owner => "**Owner**",
Kind::Tags => "**Tags**",
Kind::Campaign => "**Campaign**",
}
}
}
/// One entry: what happened, who wrote it and when.
#[derive(Debug)]
pub struct Entry {
/// The file stem, which is what the entries are sorted by.
pub filename: String,
pub kind: Kind,
pub author: String,
pub time: String,
/// A comment's text, or the before and after of the field a mechanical entry names.
pub body: String,
/// Why a mechanical entry happened, as `mv --reason` gave it. Empty for every entry
/// that carries no such field, which is all of them but a reasoned move — including
/// every entry written before reasons existed.
pub reason: String,
}
/// Rename an old `comments` directory to `history`, before anything reads or writes it.
///
/// One rename rather than a migration command: the entries themselves need no rewriting,
/// since [`parse_entry`] reads a file with no marker as the comment it is. Called by the
/// reader, the writer and the counter, so no caller has to remember it and a board can
/// never be reached through a path that skips it.
///
/// Both directories at once is refused rather than merged. Only the CLI writes there, so
/// it cannot arrive at that state on its own, and choosing which of two entries with the
/// same name survives is not a decision to make silently.
pub fn adopt_comments(board: &Path) -> Result<()> {
let old = board.join(COMMENTS_DIR);
if !old.exists() {
return Ok(());
}
let new = history_root(board);
if new.exists() {
return Err(anyhow!(
"Board holds both {} and {}. Only worklane writes there, so this needs a \
person: move the entries under {} into the matching directories in {}, \
then remove it.",
old.display(),
new.display(),
COMMENTS_DIR,
HISTORY_DIR,
));
}
fs::rename(&old, &new)
.map_err(|e| anyhow!("Could not rename {} to {}: {}", old.display(), new.display(), e))
}
/// One entry, from its filename and its content.
///
/// Split out from the directory walk so the parse can be tested without a fixture, and
/// because it is where the compatibility lives: a file with no marker is a comment,
/// which is what every entry written before the kinds existed is.
fn parse_entry(filename: &str, content: &str) -> Entry {
let field = |name: &str| {
let marker = format!("**{}**:", name);
content
.lines()
.find(|line| line.starts_with(&marker))
.and_then(|line| line.split_once(&marker))
.map(|(_, value)| value.trim().to_string())
.unwrap_or_else(|| "unknown".to_string())
};
let kind = Kind::ALL
.into_iter()
.find(|kind| content.starts_with(&format!("{}\n", kind.marker())))
.unwrap_or(Kind::Comment);
let body = content
.strip_prefix(&format!("{}\n", kind.marker()))
.map(|rest| match rest.find("\n\n**Author**") {
Some(end) => rest[..end].trim(),
None => rest.trim(),
})
.unwrap_or("");
// A missing reason is legitimate rather than unreadable, which is why this does not
// share the `unknown` fallback the two fields above carry: every entry written
// before `mv --reason` existed has none.
let reason = content
.lines()
.find_map(|line| line.strip_prefix("**Reason**:"))
.map(str::trim)
.unwrap_or_default()
.to_string();
Entry {
filename: filename.to_string(),
kind,
author: field("Author"),
time: field("Time"),
body: body.to_string(),
reason,
}
}
/// Every entry on a ticket, oldest first.
///
/// Public for the TUI's detail view, which shows the same sequence `show` does.
pub fn read_history(board: &Path, uuid: &str) -> Result<Vec<Entry>> {
adopt_comments(board)?;
let dir = history_dir(board, uuid);
if !dir.exists() {
return Ok(vec![]);
}
let mut entries: Vec<Entry> = Vec::new();
for entry in fs::read_dir(&dir)? {
let path = entry?.path();
if path.extension().is_some_and(|ext| ext == "md") {
let content = fs::read_to_string(&path)?;
let filename = path
.file_stem()
.map(|stem| stem.to_string_lossy().to_string())
.unwrap_or_default();
entries.push(parse_entry(&filename, &content));
}
}
// The stamp is fixed width and leads the name, so this is chronological.
entries.sort_by(|a, b| a.filename.cmp(&b.filename));
Ok(entries)
}
/// The kind a filename names, which is what the count reads instead of the file.
///
/// A stem with no kind in it is a comment, the same compatibility [`parse_entry`] has.
/// The collision suffix is a number and matches no slug, so it is skipped.
fn kind_from_stem(stem: &str) -> Kind {
stem.split('_')
.find_map(|part| Kind::ALL.into_iter().find(|kind| kind.slug() == part))
.unwrap_or(Kind::Comment)
}
/// How many comments a ticket carries, counted off the directory rather than read.
///
/// Comments only, so the card's counter still says how many things somebody said: a
/// ticket that has moved three times has not been talked about. `.md` only, the filter
/// [`read_history`] applies, so a stray file dropped in there is not counted. A missing
/// directory is none, which is what a ticket nothing has happened to has.
pub fn count_comments(board: &Path, uuid: &str) -> usize {
// Swallowed, unlike the reader's: a count is drawn on every card and a board that
// cannot be adopted has to draw as the zero it looks like rather than take the TUI
// down. The next write reports the real reason.
let _ = adopt_comments(board);
let Ok(entries) = fs::read_dir(history_dir(board, uuid)) else {
return 0;
};
entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
.filter(|entry| {
let stem = entry.path().file_stem().map(|s| s.to_string_lossy().to_string());
stem.is_some_and(|stem| kind_from_stem(&stem) == Kind::Comment)
})
.count()
}
/// The file an entry is written as.
///
/// A comment's file is byte for byte what `comment` wrote before the kinds existed, so
/// nothing has to be rewritten and a board can be read by either version.
///
/// The optional reason rides after **Time**, so the two fields every entry has always
/// carried keep their places and an older binary reading this file finds its body and
/// fields exactly where they were. Empty writes no line, which is what keeps a reasoned
/// entry and one without reading as the same shape minus the field.
fn entry_content(kind: Kind, body: &str, author: &str, time: &str, reason: &str) -> String {
let mut content = format!(
"{}\n\
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n",
kind.marker(),
body,
author,
time
);
if !reason.is_empty() {
content.push_str(&format!("**Reason**: {}\n", reason));
}
content
}
/// Write an entry under the first free name derived from the stamp.
///
/// `create_new` rather than `fs::write`: a name that already exists means another entry
/// 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(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(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 entry filename for '{}' in {}", stem, dir.display()))
}
/// Record one entry on a ticket, returning the filename it landed under.
///
/// Called after the edit it describes has been written, never before: an entry for a
/// move that was refused would be a log of things that did not happen. The cost of that
/// order is that a failed write here leaves the edit in place and reports the failure,
/// which is the right way round — the ticket is the record and this is the story of it.
///
/// `reason` is the why [`Kind::Status`] can carry, from `mv --reason`; every other kind
/// passes the empty slice and gets no field written.
pub fn write_entry(
board: &Path,
uuid: &str,
kind: Kind,
body: &str,
author: &str,
reason: &str,
) -> Result<String> {
adopt_comments(board)?;
let dir = history_dir(board, uuid);
fs::create_dir_all(&dir)?;
let now = Local::now();
let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug());
let content =
entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string(), reason);
write_new(&dir, &stem, &content)
}
/// What a mechanical entry records: the field before the edit and after it.
///
/// The values as the ticket holds them, sentinels included, so `_Not set_` reads the way
/// the field it came from does rather than being translated into a word this module
/// invented.
pub fn change(before: &str, after: &str) -> String {
format!("{} → {}", before, after)
}
pub fn format_history(entries: &[Entry]) -> String {
format_history_with(entries, should_use_colors())
}
/// As above, with the colour decision passed in.
pub fn format_history_with(entries: &[Entry], colored: bool) -> String {
paint_cells(&history_cells(entries), colored)
}
/// The block laid out once, as [`Cell`]s: the CLI paints them and the board turns the
/// same ones into styled spans, so the two views cannot draw two different blocks.
pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
if entries.is_empty() {
return vec![Cell::colored("No history yet.", Color::Grey)];
}
let mut cells = Vec::new();
cells.push(Cell::plain("\n"));
cells.push(Cell::colored("HISTORY", Color::Orange));
cells.push(Cell::plain(format!("\n{}\n", "─".repeat(20))));
for entry in entries {
cells.push(Cell::plain("\n"));
let stamp = format!("{} ({})", entry.author, entry.time);
match entry.kind {
// As it has always read: a header naming who said it, then the text.
Kind::Comment => {
cells.push(Cell::colored(format!("From {}", stamp), Color::Cyan));
cells.push(Cell::plain("\n"));
if !entry.body.is_empty() {
cells.push(Cell::plain(format!(" {}", entry.body)));
}
cells.push(Cell::plain("\n"));
}
// One line: a field change is one fact and a paragraph for it would bury the
// comments it sits between. A reason grows an indented line under the row,
// the way a comment's text sits under its From header, so it reads as
// attached to the transition it explains rather than as the next entry.
_ => {
let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count());
cells.push(Cell::colored(entry.kind.slug(), Color::Orange));
cells.push(Cell::plain(format!("{} ", " ".repeat(padding))));
cells.push(Cell::plain(entry.body.clone()));
cells.push(Cell::plain(" "));
cells.push(Cell::colored(stamp, Color::Cyan));
cells.push(Cell::plain("\n"));
if !entry.reason.is_empty() {
cells.push(Cell::plain(format!(" {}", entry.reason)));
cells.push(Cell::plain("\n"));
}
}
}
}
cells
}
#[cfg(test)]
mod tests {
use super::*;
use crate::util::{Fixture, paint};
fn board() -> Fixture {
Fixture::new("worklane-history")
}
#[test]
fn an_entry_names_its_kind_in_the_file_and_in_the_filename() {
let board = board();
let filename =
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude", "")
.unwrap();
assert!(filename.ends_with("_status.md"), "was {filename}");
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].kind, Kind::Status);
assert_eq!(entries[0].body, "committed → reviewing");
assert_eq!(entries[0].author, "claude");
assert_eq!(entries[0].reason, "");
}
/// One file, one event, its explanation: the reason rides in the entry that records
/// the transition it explains, as a field after **Time**, and round-trips.
#[test]
fn a_reason_is_recorded_in_the_file_and_read_back() {
let board = board();
let filename = write_entry(
&board,
"uuid",
Kind::Status,
"reviewing → backlog",
"claude",
"sent back: the first plan was wrong",
)
.unwrap();
let content = fs::read_to_string(history_dir(&board, "uuid").join(filename)).unwrap();
assert!(
content.ends_with("**Reason**: sent back: the first plan was wrong\n"),
"{content}"
);
// The fields every reader keys off keep their places above it
assert!(content.contains("**Time**:"), "{content}");
assert!(content.find("**Author**").unwrap() < content.find("**Reason**").unwrap());
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].body, "reviewing → backlog");
assert_eq!(entries[0].reason, "sent back: the first plan was wrong");
}
/// The stamp leads the name and is fixed width, so the kind that follows it cannot
/// reorder the log.
#[test]
fn the_kind_in_the_name_does_not_disturb_the_order() {
let mut names = [
"20260824_120000_000000_status",
"20260824_115959_999999_tags",
"20260824_120000_000001_comment",
];
names.sort();
assert_eq!(
names,
[
"20260824_115959_999999_tags",
"20260824_120000_000000_status",
"20260824_120000_000001_comment",
]
);
}
/// A file written before the kinds existed: no marker, so it is the comment it was,
/// and nothing rewrites it.
#[test]
fn an_entry_with_no_marker_is_a_comment() {
let legacy = parse_entry(
"20260820_143012_123456",
"**Comment**\nSomething said\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
);
assert_eq!(legacy.kind, Kind::Comment);
assert_eq!(legacy.body, "Something said");
assert_eq!(legacy.author, "Ansho Rei");
// And one with no marker at all, which is what `read_comments` read as empty.
let bare = parse_entry("20260820_143012_123457", "notes\n");
assert_eq!(bare.kind, Kind::Comment);
assert_eq!(bare.body, "");
}
/// The comment file is byte for byte what `comment` wrote before this module, which
/// is what lets an old board be read without a migration.
#[test]
fn a_comment_file_is_shaped_as_it_always_was() {
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00", "");
assert_eq!(
content,
"**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
);
}
/// Same microsecond, three entries: the guard is `create_new`, and the suffix keeps
/// them in the order they were written.
#[test]
fn entries_in_one_microsecond_get_names_of_their_own() {
let board = board();
let dir = history_dir(&board, "uuid");
fs::create_dir_all(&dir).unwrap();
let first = write_new(&dir, "20260820_143012_123456_comment", "first").unwrap();
let second = write_new(&dir, "20260820_143012_123456_comment", "second").unwrap();
let third = write_new(&dir, "20260820_143012_123456_comment", "third").unwrap();
assert_eq!(first, "20260820_143012_123456_comment.md");
assert_eq!(second, "20260820_143012_123456_comment_01.md");
assert_eq!(third, "20260820_143012_123456_comment_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_history sorts on the stem, so the names must sort in write order
assert!(first < second && second < third, "the names lost their order");
}
#[test]
fn an_old_comments_directory_is_adopted_on_access() {
let board = board();
let comments = board.join(COMMENTS_DIR).join("uuid");
fs::create_dir_all(&comments).unwrap();
fs::write(
comments.join("20260820_143012_123456.md"),
"**Comment**\nOld news\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
)
.unwrap();
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].body, "Old news");
assert!(!board.join(COMMENTS_DIR).exists(), "the old directory survived");
assert!(history_dir(&board, "uuid").exists(), "the entries did not arrive");
}
/// Refused rather than merged: only the CLI writes there, so this is a board somebody
/// has been in by hand, and picking a survivor per name is not a silent decision.
#[test]
fn a_board_holding_both_directories_is_refused() {
let board = board();
fs::create_dir_all(board.join(COMMENTS_DIR).join("uuid")).unwrap();
fs::create_dir_all(history_dir(&board, "uuid")).unwrap();
let refused = read_history(&board, "uuid");
let message = refused.unwrap_err().to_string();
assert!(
message.contains(COMMENTS_DIR) && message.contains(HISTORY_DIR),
"{message}"
);
}
/// The count is the card's, and a card counts what somebody said.
#[test]
fn only_comments_are_counted() {
let board = board();
write_entry(&board, "uuid", Kind::Comment, "said", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude", "").unwrap();
assert_eq!(read_history(&board, "uuid").unwrap().len(), 4);
assert_eq!(count_comments(&board, "uuid"), 1);
}
/// A stem written before the kinds existed counts as the comment it is.
#[test]
fn a_legacy_name_counts_as_a_comment() {
assert_eq!(kind_from_stem("20260820_143012_123456"), Kind::Comment);
assert_eq!(kind_from_stem("20260820_143012_123456_01"), Kind::Comment);
assert_eq!(kind_from_stem("20260820_143012_123456_status"), Kind::Status);
assert_eq!(kind_from_stem("20260820_143012_123456_status_01"), Kind::Status);
}
#[test]
fn a_mechanical_entry_renders_as_one_line_and_a_comment_as_it_did() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
];
let rendered = format_history_with(&entries, false);
assert!(rendered.contains("HISTORY"), "{rendered}");
assert!(
rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"),
"{rendered}"
);
assert!(
rendered
.contains("From Ansho Rei (2026-08-24 12:00:01)\n The offset was never passed"),
"{rendered}"
);
assert!(!rendered.contains('\x1b'), "colour off still painted: {rendered:?}");
}
/// The pin for the cells conversion: `show` prints the block exactly as it printed
/// it before, every painted run spelled out, the way
/// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body.
///
/// Updated once since, deliberately: `campaign` widened the label column from 6 to
/// 8, and the campaign row itself joined the pin (f774a33).
#[test]
fn show_prints_the_same_history_it_printed_before_the_cells_conversion() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
parse_entry(
"20260824_120002_000000_campaign",
"**Campaign**\n_Not set_ → v1\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:02\n",
),
];
let expected = format!(
"\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n\n{} _Not set_ → v1 {}\n",
paint("HISTORY", Color::Orange, true),
"─".repeat(20),
paint("status", Color::Orange, true),
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
paint("campaign", Color::Orange, true),
paint("claude (2026-08-24 12:00:02)", Color::Cyan, true),
);
assert_eq!(format_history_with(&entries, true), expected);
assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true));
}
/// The reason is the row's, so it renders indented under the row it explains and
/// before whatever entry follows, in both renderers — this is the one layout they
/// share. Paired with the pin above: an entry without a reason renders exactly as
/// it always did.
#[test]
fn a_reason_renders_indented_under_its_row() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\nreviewing → backlog\n\n**Author**: claude\n**Time**: 2026-08-24 \
12:00:00\n**Reason**: sent back, the first plan was wrong\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nAnd why.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
];
let expected = format!(
"\n{}\n{}\n\n{} reviewing → backlog {}\n sent back, the first plan was wrong\n\n{}\n And why.\n",
paint("HISTORY", Color::Orange, true),
"─".repeat(20),
paint("status", Color::Orange, true),
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
);
assert_eq!(format_history_with(&entries, true), expected);
assert!(
format_history_with(&entries, false)
.contains("claude (2026-08-24 12:00:00)\n sent back, the first plan was wrong"),
"colour off lost the reason: {}",
format_history_with(&entries, false)
);
}
/// Padded to the longest of the four, so every body starts in the same column
/// however short the label above it is.
#[test]
fn the_mechanical_labels_are_aligned() {
let bodies = [
("status", "backlog → committed"),
("owner", "_Not set_ → alice"),
("tags", "bug → bug, cli"),
("campaign", "v1 → beaver"),
];
let entries: Vec<Entry> = bodies
.into_iter()
.map(|(kind, body)| {
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
parse_entry(
&format!("20260824_120000_000000_{kind}"),
&format!(
"{marker}\n{body}\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
),
)
})
.collect();
let rendered = format_history_with(&entries, false);
let columns: Vec<usize> = bodies
.into_iter()
.map(|(_, body)| rendered.find(body).expect("body missing"))
.map(|at| {
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
at - line_start
})
.collect();
assert_eq!(columns.len(), 4);
assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}");
}
#[test]
fn nothing_recorded_says_so() {
assert_eq!(format_history_with(&[], false), "No history yet.");
}
}
+14 -4
View File
@@ -6,6 +6,7 @@ mod clipboard;
mod command;
mod completions;
mod handlers;
mod history;
mod install;
mod tag;
mod tui;
@@ -56,7 +57,13 @@ 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),
@@ -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
+462 -155
View File
File diff suppressed because it is too large Load Diff
+100 -103
View File
@@ -5,29 +5,10 @@ use std::io::IsTerminal;
use std::path::Path;
use std::sync::OnceLock;
/// How timestamps are written into tickets and comments, and therefore how they
/// are read back. Shared so the writer and the reader cannot drift apart.
/// How timestamps are written into tickets and history entries, and therefore how
/// they are read back. Shared so the writer and the reader cannot drift apart.
pub const TIMESTAMP_FORMAT: &str = "%Y-%m-%d %H:%M:%S";
/// How a comment filename is stamped.
///
/// Microseconds, not seconds: at second resolution two comments in the same
/// second produced the same name and the second silently truncated the first.
/// Fixed width, so the lexicographic sort in `read_comments` stays chronological.
pub const COMMENT_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
/// Where a ticket's comments live, under the board.
///
/// Beside the status directories rather than among them, the way `campaigns_dir` is: a
/// comment has no status of its own. Spelled once here, so the writer, the reader and the
/// card's counter cannot disagree about the path.
pub const COMMENTS_DIR: &str = "comments";
/// The comments directory for one ticket, named by its full uuid.
pub fn comments_dir(board: &Path, uuid: &str) -> std::path::PathBuf {
board.join(COMMENTS_DIR).join(uuid)
}
/// The mark a card puts after its comment count.
///
/// A closing quotation ornament, so `2\u{275e}` reads as two things somebody said rather
@@ -663,37 +644,6 @@ pub fn resolve_ticket(search: &str, worklane_dir: &Path) -> Result<(String, Stri
let found = matches.remove(0);
Ok((found.dir, found.title, found.content))
}
pub fn format_comments(comments: &[(String, String, String, String)]) -> String {
format_comments_with(comments, should_use_colors())
}
/// As above, with the colour decision passed in for the TUI.
pub fn format_comments_with(
comments: &[(String, String, String, String)],
colored: bool,
) -> String {
if comments.is_empty() {
return paint("No comments yet.", Color::Grey, colored);
}
let mut result = String::new();
result.push('\n');
result.push_str(&paint("COMMENTS", Color::Orange, colored));
result.push_str(&format!("\n{}\n", "─".repeat(20)));
for (_filename, author, time, body) in comments {
result.push('\n');
result.push_str(&paint(&format!("From {} ({})", author, time), Color::Cyan, colored));
result.push('\n');
if !body.is_empty() {
result.push_str(" ");
result.push_str(body);
}
result.push('\n');
}
result
}
/// The parts of a ticket's body that cannot be rendered from the file alone.
///
/// Both are resolved against the rest of the board. The Relations section stores one
@@ -1487,7 +1437,7 @@ pub fn parse_tags(content: &str) -> Vec<String> {
/// Directly after ID, because that is where `campaign_body` writes it, so a campaign given
/// a codename later ends up with the same file as one filed with it. Nothing ever upserts
/// it on a ticket, so its place in a ticket's order costs nothing.
const METADATA_ORDER: [&str; 12] = [
const METADATA_ORDER: [&str; 13] = [
"ID",
CODENAME_FIELD,
"Priority",
@@ -1498,6 +1448,7 @@ const METADATA_ORDER: [&str; 12] = [
COMMITTED_ON_FIELD,
SUBMITTED_ON_FIELD,
COMPLETED_ON_FIELD,
DISCARDED_ON_FIELD,
CAMPAIGN_FIELD,
"Status",
];
@@ -1582,6 +1533,7 @@ fn insert_metadata_field(content: &str, field: &str, value: &str, title: &str) -
pub const COMMITTED_ON_FIELD: &str = "Committed On";
pub const SUBMITTED_ON_FIELD: &str = "Submitted On";
pub const COMPLETED_ON_FIELD: &str = "Completed On";
pub const DISCARDED_ON_FIELD: &str = "Discarded On";
/// Stamp the field of the status being entered and drop the ones after it.
///
@@ -2246,6 +2198,12 @@ impl RelationIndex {
self.tickets.iter().find(|ticket| ticket.uuid == uuid)
}
/// Every ticket the index holds, for a caller asking about the derived direction:
/// which tickets point *at* one, which no single `get` can answer.
pub fn iter(&self) -> impl Iterator<Item = &RelatedTicket> {
self.tickets.iter()
}
/// The relations other tickets hold pointing at `uuid`, as the kind reads from
/// this end and the ticket that holds it.
///
@@ -2338,11 +2296,14 @@ pub const REGRESSION_MARK: &str = "\u{2190}";
/// nobody has picked up, orange for work in hand, cyan for work waiting on a reader,
/// green for done. Green is the one the priority ramp deliberately leaves out because it
/// means a title, and it is safe on a one-cell mark that no title sits behind.
const STATUS_MARKS: [(&str, &str, Color); 4] = [
const STATUS_MARKS: [(&str, &str, Color); 5] = [
("backlog", "\u{25cb}", Color::Grey),
("committed", "\u{25d0}", Color::Orange),
("reviewing", "\u{25d0}", Color::Cyan),
("done", "\u{25cf}", Color::Green),
// 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 is unique, as with the two halves.
("discarded", "\u{25cf}", Color::Grey),
];
/// The mark for a status, or `?` for a target the board no longer holds.
@@ -2428,7 +2389,7 @@ impl Cell {
Cell { text: text.into(), color: None }
}
fn colored(text: impl Into<String>, color: Color) -> Self {
pub(crate) fn colored(text: impl Into<String>, color: Color) -> Self {
Cell {
text: text.into(),
color: Some(color),
@@ -2725,35 +2686,41 @@ pub fn trim_blank_ends(values: &[String]) -> &[String] {
/// A status, as clap accepts it and as the directory is named.
///
/// An enum rather than the string it was, so an unknown status is a usage error at parse
/// time with the four listed, the way `priority_level` and `iso_date` refuse a bad level
/// time with the five listed, the way `priority_level` and `iso_date` refuse a bad level
/// or date. That is the bargain the scalars already take, see AGENTS.md: nothing is
/// written, the exit code is 2, and no handler has to check. It also gives every shell
/// that completes possible values the four names for free.
/// that completes possible values the five names for free.
///
/// The variants are in flow order, which is the order `mv` reads to decide whether a
/// move goes forward, and the order [`status_dirs`] hands the two views.
/// The variants are in flow order with `Discarded` last, which is the order `mv` reads
/// to decide whether a move goes forward and the order the stamp arrival rule truncates
/// by. Discarded sits after done deliberately: entering it clears nothing, so a ticket
/// discarded from reviewing keeps the journey it made, and leaving it is always a
/// backward move, which is what makes un-discarding need `-f` for free.
#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
pub enum Status {
Backlog,
Committed,
Reviewing,
Done,
Discarded,
}
impl Status {
/// Every status, in flow order. The one list, which [`status_dirs`], `mv` and every
/// caller of [`by_status_order`] read rather than spelling the four names again.
pub const ALL: [Status; 4] = [
/// Every status, in flow order with discarded last. The one list, which
/// [`status_dirs`], `mv`, the board's columns and every caller of
/// [`by_status_order`] read rather than spelling the five names again.
pub const ALL: [Status; 5] = [
Status::Backlog,
Status::Committed,
Status::Reviewing,
Status::Done,
Status::Discarded,
];
/// The field `mv` stamps on entering this status, for the three that have one.
/// The field `mv` stamps on entering this status, for the four that have one.
///
/// Derived from the status rather than spelled at the call site, so the mapping is
/// in one place and a fifth status either brings its own stamp or explicitly has
/// in one place and a new status either brings its own stamp or explicitly has
/// none.
pub const fn stamp_field(self) -> Option<&'static str> {
match self {
@@ -2761,6 +2728,7 @@ impl Status {
Status::Committed => Some(COMMITTED_ON_FIELD),
Status::Reviewing => Some(SUBMITTED_ON_FIELD),
Status::Done => Some(COMPLETED_ON_FIELD),
Status::Discarded => Some(DISCARDED_ON_FIELD),
}
}
@@ -2772,6 +2740,7 @@ impl Status {
Status::Committed => "committed",
Status::Reviewing => "reviewing",
Status::Done => "done",
Status::Discarded => "discarded",
}
}
}
@@ -2780,15 +2749,41 @@ pub fn status_dirs() -> Vec<&'static str> {
Status::ALL.iter().map(|status| status.as_str()).collect()
}
/// The end of the flow, and the one status both views treat differently: `ls` counts it
/// in the summary and leaves it out of the listing, and the board hides its column until
/// asked. Named because that rule now has two readers.
/// The end of the flow, and one of the two statuses both views treat differently: `ls`
/// counts it in the summary and leaves it out of the listing, and the board hides its
/// column until `d` reveals it. Named because that rule now has two readers.
///
/// It is deliberately last in `status_dirs()`. The board leans on that: hiding done drops
/// the final column, so the other three keep their indices and the selection only has to
/// be handled when it is sitting on done itself.
/// Done and discarded are deliberately the last two in [`Status::ALL`], which is what
/// the board builds its columns from: hiding either is then a prefix of that list, so
/// the columns before them keep their indices and the selection only has to be handled
/// when it is sitting on a column that just went away. Discarded after done is also
/// what lets the stamp arrival rule keep a discard's journey.
pub const DONE: &str = Status::Done.as_str();
/// Where a ticket that will not be done ends up: the other terminal status, and the
/// other one `ls` leaves out of the listing and the board keeps off the screen until
/// asked, last in the rotation because it is the least likely thing to be looking for.
///
/// A discarded ticket counts as finished wherever progress is measured, since nothing is
/// left to do, and blocks nothing. What it is not is done: the two directories keep
/// "the work landed" and "the work was abandoned" answerable apart.
pub const DISCARDED: &str = Status::Discarded.as_str();
/// Whether a ticket in this status still has something outstanding.
///
/// The two terminal statuses do not: done landed and discarded never will, so in both
/// cases there is nothing left to wait for and nothing left to plan around. One spelling
/// for all three readers, because `mv` refuses a move on it, refuses a discard on it and
/// the board draws its blocked mark from it, and two views disagreeing about what counts
/// as open would be the difference nobody can explain later.
///
/// Takes the status as a string because that is what the callers hold: the directory a
/// ticket was found in, not a parsed [`Status`]. An unrecognised value reads as open,
/// which is the safe direction: it surfaces rather than silently satisfying a block.
pub fn is_open(status: &str) -> bool {
status != DONE && status != DISCARDED
}
/// Lowest and highest level a ticket can carry. 1 is the most urgent, which is
/// what the `p1` to `p3` tags this replaced already meant.
pub const PRIORITY_RANGE: std::ops::RangeInclusive<u8> = 1..=5;
@@ -2917,6 +2912,8 @@ pub struct TicketItem {
pub submitted_on: Option<String>,
/// The same for done.
pub completed_on: Option<String>,
/// The same for discarded.
pub discarded_on: Option<String>,
}
impl TicketItem {
@@ -2932,6 +2929,7 @@ impl TicketItem {
Status::Committed => self.committed_on.as_deref(),
Status::Reviewing => self.submitted_on.as_deref(),
Status::Done => self.completed_on.as_deref(),
Status::Discarded => self.discarded_on.as_deref(),
}
}
}
@@ -3055,22 +3053,6 @@ pub fn display_ticket_items(items: &[TicketItem]) {
}
}
/// How many comments a ticket has, counted off the directory rather than read.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A missing directory is none, which is what a
/// ticket nobody has commented on has: no directory is created until the first comment.
fn count_comments(board: &Path, uuid: &str) -> usize {
let Ok(entries) = fs::read_dir(comments_dir(board, uuid)) else {
return 0;
};
entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
.count()
}
pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketItem>> {
let status_path = status_path.as_ref();
// The comments sit beside the status directories, so the board is this one's parent.
@@ -3120,10 +3102,10 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
}),
};
// The ticket's own ID field, not the filename stem: a comment directory is
// named by the uuid the file records, which is what `comment` wrote it under.
// The ticket's own ID field, not the filename stem: a history directory is
// named by the uuid the file records, which is what wrote the entries under it.
let uuid = parse_ticket_field(&content, "ID");
let comments = board.map_or(0, |board| count_comments(board, &uuid));
let comments = board.map_or(0, |board| crate::history::count_comments(board, &uuid));
Some(TicketItem {
title,
@@ -3142,6 +3124,7 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
committed_on: parse_stamp(&content, Status::Committed),
submitted_on: parse_stamp(&content, Status::Reviewing),
completed_on: parse_stamp(&content, Status::Done),
discarded_on: parse_stamp(&content, Status::Discarded),
})
})
.collect();
@@ -3170,7 +3153,8 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
/// always printed. Past the backlog the question changes: committed asks what has waited
/// longest, reviewing what was handed over first, done what just landed. The head of
/// every column is therefore what the reader acts on next, which is ascending by entry
/// stamp in committed and reviewing and descending in done, the way a changelog reads.
/// stamp in committed and reviewing and descending in done and discarded, the way a
/// changelog reads.
///
/// A ticket with no stamp sinks below every stamped one in its column. A missing time is
/// unknown, not ancient, and unknown must not claim the head of a queue ahead of a wait
@@ -3184,7 +3168,7 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
let by_stamp = match (a.entry_stamp(status), b.entry_stamp(status)) {
(Some(left), Some(right)) => match status {
Status::Done => right.cmp(left),
Status::Done | Status::Discarded => right.cmp(left),
_ => left.cmp(right),
},
(Some(_), None) => std::cmp::Ordering::Less,
@@ -3853,12 +3837,13 @@ mod tests {
);
}
/// The count is a directory listing rather than a read: nothing here parses a comment,
/// The count is a directory listing rather than a read: nothing here parses an entry,
/// and the bodies are the detail view's business.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A ticket with no directory at all has
/// none, which is every ticket until the first comment creates one.
/// `.md` only, the filter `read_history` applies, so a stray file dropped in there is
/// not counted as something somebody wrote, and a mechanical entry is not counted
/// either: the card says how many things were said about the ticket. A ticket with no
/// directory at all has none, which is every ticket until the first entry creates one.
#[test]
fn collect_ticket_items_counts_the_comments_under_the_board() {
let board = tempfile::tempdir().unwrap();
@@ -3877,12 +3862,20 @@ mod tests {
write(talked_about);
write(quiet);
let comments = comments_dir(board.path(), talked_about);
fs::create_dir_all(&comments).unwrap();
fs::write(comments.join("20260823_120000_000000.md"), "**Comment**\n").unwrap();
fs::write(comments.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
// Not a comment, and not counted as one.
fs::write(comments.join("notes.txt"), "scratch\n").unwrap();
let history = crate::history::history_dir(board.path(), talked_about);
fs::create_dir_all(&history).unwrap();
fs::write(history.join("20260823_120000_000000_comment.md"), "**Comment**\n").unwrap();
// No kind in the name, as everything written before the kinds existed: a comment.
fs::write(history.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
// A field change is history but not something somebody said, so the card's
// counter leaves it out.
fs::write(
history.join("20260823_120002_000000_status.md"),
"**Status**\nbacklog → committed\n",
)
.unwrap();
// Not an entry at all, and not counted as one.
fs::write(history.join("notes.txt"), "scratch\n").unwrap();
let items = collect_ticket_items(&backlog).unwrap();
let counted = |uuid: &str| {
@@ -4189,7 +4182,11 @@ mod tests {
_ => None,
},
completed_on: match status {
Status::Done => stamp,
Status::Done => stamp.clone(),
_ => None,
},
discarded_on: match status {
Status::Discarded => stamp,
_ => None,
},
}
@@ -5247,7 +5244,7 @@ Plain line with **bold** and a [link](http://x.test/a).
);
}
assert_eq!(seen.len(), 4, "{seen:?}");
assert_eq!(seen.len(), status_dirs().len(), "{seen:?}");
}
/// An unrecognised value reads as missing rather than as a fifth stage of the flow.
+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()
}
+20 -20
View File
@@ -43,7 +43,7 @@ fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
/// 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("comments").join(uuid))
let files: Vec<_> = fs::read_dir(worklane_dir.join("history").join(uuid))
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -73,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();
@@ -125,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();
@@ -149,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();
@@ -160,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())
@@ -176,7 +176,7 @@ fn comment_creates_comments_directory() {
.assert()
.success();
assert!(comments_dir.exists());
assert!(history_dir.exists());
}
#[test]
@@ -218,7 +218,7 @@ fn the_owner_flag_is_gone() {
}
assert!(
!worklane.join("comments").join(&uuid).exists(),
!worklane.join("history").join(&uuid).exists(),
"a comment was written despite the usage error"
);
}
@@ -320,8 +320,8 @@ fn comment_falls_back_to_git_user_when_actor_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();
@@ -348,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();
@@ -383,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())
@@ -438,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"
);
@@ -448,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"));
}
+258 -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,260 @@ fn mv_does_not_restamp_a_no_op_move() {
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
}
// ---------------------------------------------------------------- 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:?}");
}
+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()
}
+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:?}");
}
}