Compare commits

...
47 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 7126138d46 (0fd1ddc) Pick a tag in the tui, and bump to 0.27.1
The board could be cut by campaign and not by the axis `ls --tag` has answered
since 2f3796e. `t` opens a picker of every tag the board declares or carries,
and taking one filters every column to the cards carrying it, matched whole and
case sensitively the way the listing matches.

The picker is one piece of machinery over two lists rather than a second
picker. `PickerRow::key` is what made that cheap: a campaign is keyed by its
uuid and a tag by itself, both strings, so stepping over selectable rows,
keeping the highlight across a rebuild and taking a row with `enter` are
written once. Only the list and what the answer filters differ.

`Tab::campaign` became `Tab::filter`, an enum of whole, campaign or tag, with
`select_filter` its only writer. Picking either clears the other because they
are one field rather than because two setters remember to, which is also what
the shared frame slot needs: it holds one frame and can now only be asked to
name one thing.

The tag sections are declared above undeclared and neither is truncated, where
the completed campaigns are: a finished campaign is done with and that tail
only grows, while an undeclared tag is the row a reader most wants to see.
`campaign` and `campaigns` would have sat one under the other here the day the
second was invented.

The digest stamps `tags.md`, or a tag declared elsewhere would never reach an
open picker. The footer names the tag in its own colour beside `q board`,
because a tag draws no frame until 2a83bd4 and nothing else would say why the
cards are missing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 10:03:29 +02:00
Ansho ReiandClaude Opus 5 3592584747 Edit a campaign's description, and bump to 0.27.0
`campaign set` reached the title and the codename, so the description a
campaign was filed with was the description it kept: fixing a typo in the
one field nothing could edit meant a hand edit of the file, or refiling the
campaign and reassigning every member.

Both halves arrive together, which is why d637288 left this out rather than
adding the flag. `campaign set --description` replaces the section and
`campaign append --description` adds a paragraph to it, because a `set` with
no `append` is the half that is easy to reach for and wrong: replacing a
description to add a sentence is how the rest of it gets lost.

`append` is a campaign's own subcommand rather than the top-level one, which
resolves a ticket. `resolve_in`'s tiers are the same over both directories,
so one positional naming either object could resolve in each with nothing
but a flag to say which was meant, and it would make a liar of the
explanation `resolve_ticket` gives a ticket search that names a campaign.

The section is the `DESCRIPTION` entry and the surgery is
`set_section_body`, `append_section_body` and `Section::normalise`, not a
copy scoped to campaigns. `SECTION_ORDER` needs no campaign variant: a
campaign holds one section where a ticket holds four, and the followers a
campaign does not have are simply not in the file, so its description
anchors against `## Metadata`, where `campaign_body` writes it.

Still no `--clear`, and that is now a decision rather than a deferral: a
campaign's description has no cleared form, so an empty `--description ""`
is a paragraph break here as it is everywhere else, and the refusal for an
all-blank value says there is nowhere to go back to instead of naming a flag
that does not exist. `replaced_items` and `appended_items` hold that check
once for both objects, with the way out as the caller's argument.

The section refusal no longer says "Ticket", since a campaign reaches it
too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 04:53:49 +02:00
Ansho ReiandClaude Opus 5 5dc087d49e (9564ac9) Show the annotation in tags ls, and bump to 0.26.4
Since tags.md there are two vocabularies, the one the file declares and the one
the tickets carry, and the listing reported only the second. A tag declared and
never applied was invisible, and a word somebody invented in a hurry read
exactly like one the board had agreed on. Those two cases are the whole reason
to declare tags at all.

The listing is now the union: still alphabetical, still case sensitive, with the
annotation's opening line as a third tab-separated field and a count of zero for
a tag nothing carries.

**The absence of the third field is what marks a carried but undeclared tag.**
Nothing could be appended to the first field without a completion offering a tag
that does not exist, and nothing could be added to the second without it
stopping being a number. Absence costs neither, and it buys the property a
marker could not have: a board with no tags.md has every tag undeclared, so it
prints two fields a line, which is byte for byte what this printed before the
file existed. An older completion script on a newer binary keeps working, which
is the same compatibility 1db02e5 kept for the bare form.

A declared tag with nothing said about it answers the placeholder rather than an
empty string. An empty third field is a trailing tab and nothing else, so the
one difference between declared and not would have been invisible in a terminal
and in a completion alike. It is also what the file itself holds under that
heading, so the field is the section's opening line either way.

`TagIndex::summary` does the cut to one line, the way `CampaignRow::summary`
takes one line off a description the read carries whole: the annotation is prose
with paragraphs in it, and how much of it a view wants is the view's business.

The two fish rules pipe through `cut -f1,3`, since fish takes everything after
the *first* tab as one description and the count would otherwise land in the
middle of the prose. What is left is the annotation, and a tag the board has
never declared is offered with no description at all, which says what the count
used to say more weakly. `cut` rather than `string replace` because columns are
what is being picked, and `cut -f1` is how a script reads this listing anyway.
A test pins both rules rather than the script as a whole, so a rule added later
that reads `worklane tags` raw is caught.

`assets/ADMIN.md` claimed a declared and unapplied tag does not appear in the
listing, which is now the opposite of the truth; it lists at zero. Fixed here
rather than left to f7dd1a1, which does not list that file. The same stale
sentence in SKILL.md and PLAN.md is recorded on that ticket.

Filed on the way past: an annotation carrying a tab splits the listing into a
fourth field, 8f650fc, and the `tags set` completion offers the undeclared tags
it refuses, which only became filterable now that the listing tells them apart,
193f9be.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 03:58:04 +02:00
Ansho ReiandClaude Opus 5 07c783410c (b74dc5a) Remove a test's fixture directory with a guard, not a trailing line
Every unit test here built its board under the system temp directory,
and the ones that remembered a `remove_dir_all` at the end only cleaned
up when their assertions passed. Most had no such line at all. /tmp
reached 18363 of these and filled the disk, which failed a link step and
then a `git add` with "No space left on device": an error naming neither
the tests nor what they had left behind.

`util::Fixture` is a uuid-named directory whose `Drop` removes it, which
is the only shape that also runs when an assertion fails, since
unwinding runs destructors. It derefs to `Path` and 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. So nothing changed at the ~160 call sites but the type, and the 85
trailing cleanup lines are gone.

Five leaking prefixes, not the two the ticket names.
`worklane-project-*` from `project_tree` and `worklane-bare-*` never
cleaned up at all, and the four `worklane-count/blocked/stray/stamps-*`
sites in `util.rs` cleaned up only on the passing path.
`Fixture::child` is what covers `project_tree`, which needs the fixture
to point at the project and remove the directory above it.

`assert_fs::TempDir` is a dev-dependency already and was still not the
answer: it names its directories `.tmpXXXXXX`, which says nothing about
whose they are for the one case that matters, the one left on disk on
purpose. Wrapping it to add a prefix and a printed path is more code
than the guard.

`WORKLANE_KEEP_FIXTURES=1` keeps them and prints each path, opt-in
rather than kept-automatically-on-failure: the assertions here carry the
state they are about, so a path printed on every failure would be noise
on almost all of them. Read once when a fixture is made rather than at
drop time, so the answer cannot change mid-test, and `Fixture::swept()`
turns it off for the three tests that are about the guard itself and
must not be failed by a reader's environment.

Verified against a clean temp dir rather than against /tmp, which still
holds the historical leak: `TMPDIR=/tmp/scratch cargo test` leaves zero
directories behind, with the variable set and unset, 383 green either
way.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 03:35:23 +02:00
Ansho ReiandClaude Opus 5 dd2b457bff (9b7fa7d) Expand the campaign frame with enter
Three rows of prose was the right default and the wrong ceiling. enter
while the frame holds the selection gives it half the board, enter again
gives the rows back, and pgup and pgdn go on doing what they do against
whichever height it is at.

Half of what the frame and the columns divide, which is the screen less
the tab row and the footer. Half rather than most of it for the same
reason the frame is not an overlay: the columns below are the campaign's
members, and a reader inspecting the campaign has to go on seeing what
it is made of. So `Chrome::campaign` is an `Option<FrameSize>` rather
than a bool and `campaign_rows` takes a height, resolved in `frame_rows`
because that is the one place that already has an area to take a share
of, which keeps `Chrome` itself pure.

Bounded at both ends, and the upper bound is the one that matters:
`Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame
that asked for too many, silently, and the frame's own measurement would
then disagree with what is drawn. Floored at the collapsed height, since
expanding must never shrink the frame, so a board too short to divide
gives the collapsed height back rather than one nothing measured. Swept
over every height from 4 to 60, tabbed and not.

q does not gain a layer and the arrow keys do not take the height back.
The expanded frame is the frame at its other height, not a thing laid
over the board, so q goes on taking the campaign filter off from either
and enter is the only key that undoes what enter did. The height
outlives the selection for the same reason: it is a view of the campaign
the reader chose, so the columns stay short with the selection on a
card. `dismiss` and `select_card` are untouched, and two tests pin that.

`enter` routes through `Board::toggle_focused` rather than in the
`main.rs` arm, the rule `dismiss` and `scroll_page` follow. It was inert
on the frame for free before, because `Tab::selected` hands back nothing
there and `toggle_detail` had nothing to open; that answer is now the
thing in the way, and AGENTS.md and `Tab::selected`'s doc are amended
rather than left describing the key by what it used to do.

The toggle re-clamps the frame offset through `scroll_frame(0, screen)`.
A taller viewport has a smaller last offset, so where the reader was can
end up past the end of the frame they just asked for, and the next pgup
would count down from a number the frame never showed.

Criterion 13 is not done: 2a83bd4 has not landed, so there is no tag
frame to give a second height to. What it inherits is on the ticket, and
all of it is generic rather than campaign-specific.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 03:08:39 +02:00
Ansho ReiandClaude Opus 5 af1ef1f97f (ebad2fa) Scroll the campaign description in the frame above the board
The frame showed the opening line of a description and the rest was only
readable through `campaign show`, which means leaving the board. It now
holds three rows of prose and pages through the remainder on `pgup` and
`pgdn`, reached by going up past the top card of a column.

Four decisions rather than four edits:

`section_prose` replaces `section_opening`. The campaign file is only in
hand while the campaigns directory is being read, so that read carries
the whole description and `CampaignRow::summary` takes the picker's one
line back off it. Two fields, one cut from the other, would be two
strings free to come from different reads of the same file.

`CAMPAIGN_PROSE_ROWS` is a constant. Fitting the frame to the
description would resize every column whenever the filter changed, so
the height is fixed at three rows and scrolling covers the rest. Two
more rows of cards spent than the one row cost.

`Focus` is the third place the selection can be, held on `Tab` beside
the filter and the new `frame_offset`. Every key that acts on a card
answers for it: `enter` is inert because `Tab::selected` hands back
nothing there, `left` and `right` are inert because the frame spans the
board, and `y` copies the campaign's short id, so `y copy id` means the
id of the selected thing in every state. No card is drawn reversed while
the frame holds the selection, since that highlight is what says which
ticket a key is about. The frame is out of reach from under an open
ticket, where up and down step through tickets and the overlay follows.

`Board::scroll_page` holds the precedence, not the `main.rs` arm: an
open ticket keeps both keys whatever holds the selection behind it, the
rule `dismiss` follows for the same reason. The page indicator, the
step and the clamp are the overlay's `page_indicator`, `scroll_step` and
`last_offset`, so the two places a reader presses these keys behave the
same. The indicator sits beside `q board` rather than up beside the
title, which would shorten a long campaign name whenever its
description grew.

Criterion 11 is not done: 2a83bd4 has not landed, so there is no tag
frame to give the same treatment. The model it inherits is in place and
named on the ticket.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 17:47:09 +02:00
Ansho ReiandClaude Opus 5 8e2ab6332c (8c8a520) Ship a board administration skill, and bump to 0.26.1
Three skills taught the CLI, the review and the grooming sweep. Nothing taught
the board itself, and two jobs fell in the gap: deciding what the tags are, now
that `tags add` and `tags set` exist to declare them, and putting a board back
together when its files and fields disagree.

`worklane-admin` is the fourth. It is the one asset written to hold for a board
that tracks no software, since a vocabulary skill built around `bug` and `cli`
teaches nothing to a board tracking a household, so its worked examples span a
tool, a product strategy and a house. Tags as axes rather than as a pile of
words, what an annotation has to say to stop drift, which is the boundary
against the neighbouring tag and not the definition, and the fact that renaming
a tag means rewriting the Tags field of every ticket carrying it.

The repairs are by symptom and every one was run against a scratch board
rather than reasoned from the source, which is what the ticket demanded and
what turned up the one that matters: a ticket whose file sits in `done` while
its Status field says `backlog` cannot be repaired by one `mv`, because `mv`
reads the current status from the directory and refuses the target it is
already in. Two moves fix it. That is 7f772a7. Verifying also turned up that
nothing removes a relation, 8556048.

The line against `worklane-plan` is drawn in both documents: this one decides
the vocabulary, that one applies it across tickets.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 16:24:38 +02:00
Ansho ReiandClaude Opus 5 239d951b8c (9688d34) Add tags set, and bump to 0.26.0
A tag declared with the wrong annotation was stuck with it, which is 32e98ab's
hole arriving before the writer rather than after. The campaigns entry on this
board was already in that state: it reserved the singular for the campaign
command, and stopped being true the moment that tag was rolled in.

`worklane tags set <tag> --annotation` replaces the whole annotation.
`--annotation` is required, so a bare call is a usage error rather than a
silent no-op, and an empty one writes the placeholder, which is why there is
no `--clear`. `add` and `set` refuse what the other is for, each naming the
other, so which one wrote a line is never a question of which was typed.

No `--force`: a codename is guarded because a campaign is addressed by it,
where an annotation is prose written to be revised. No rename: the tag is the
key, so changing it means rewriting the Tags field of every ticket carrying
it.

`report` grew `report_in`, which takes the colour. `report` paints its subject
green and green means title, so a tag could not reuse it: a tag is drawn in a
`TAG_COLORS` slot or it is drawn wrong. Same wording, decision passed in,
which is the trade `paint` makes with `color_text`.

The no-op compares the rendered file rather than the annotation, the way
`apply` compares content for a ticket field.

`tags set` takes a tag the board already has, so it joins the new
`TAG_NESTED_COMMANDS` and gets a fish rule offering `worklane tags`; `tags
add` stays ruleless in `TAG_NEW_COMMANDS`. The guard now names both lists, so
the next tag positional has to pick one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 16:09:03 +02:00
Ansho ReiandClaude Opus 5 f515d69930 (1db02e5) Give the board a tags file, and bump to 0.25.0
The board carried twenty-four tags and defined none of them. `campaign` and
`campaigns` were both on it, one ticket each side, and nothing on disk could
have caught that.

`.worklane/tags.md` is the vocabulary: one level-two heading per tag, its
annotation as the prose under it, alphabetical by byte so a near-duplicate
lands next to what it duplicates. `worklane tags add <tag> --annotation`
writes it, `init` creates it empty, and `tags add` creates it on demand for a
board that predates it.

Declaring a tag tags no ticket, and tagging a ticket declares nothing. The
counts stay derived from the status directories, so the file and the board can
disagree; reporting that disagreement is 9564ac9.

`tags` becomes a group with an optional subcommand. The bare form is still the
listing, byte for byte, because the shipped fish completion calls it that way
to fill in `ls --tag`; `tags ls` is the same arm.

Every write re-renders the whole file from the parsed vocabulary rather than
splicing one section, which is why an unreadable file is an error in
`TagIndex::load` where an unreadable campaigns directory is an empty index:
empty here would mean erased.

`no_tag_taking_option_is_missing` used to panic on any tag positional. It now
allows what `TAG_NEW_COMMANDS` records, which is `tags add` alone: the tag it
takes does not exist yet, so completing it from `worklane tags` would offer
exactly the values it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 15:47:05 +02:00
Ansho ReiandClaude Opus 5 b1dbf3ed75 (4e4d88d) Split and search the campaign picker, and bump to 0.24.2
One flat list ordered by title put the completed campaigns among the open
ones forever. The tail only grows, so on a board that has run for a while
the campaigns worth picking were pushed towards the bottom of the box and
eventually off it, and nothing in the picker helped find one.

The rows are now two sections, open above completed, with completed by
Created At newest first and truncated to a couple behind a grey line
naming how many older ones are hidden. `/` starts a query, the key that
already searches the board's cards, filtering case insensitively on short
id, codename and title, and a query turns the truncation off: the
campaign a reader is searching for is exactly the one it hid.

`picker_list` is the one place that decides what a row is, so `Picker::row`
counts drawn rows and `stepped_picker_row` walks past the headings and the
truncation line rather than stopping on one. The highlight is placed by
uuid, the answer `Tab::campaign` already gives for the filter, so typing,
clearing the query and a tick that finishes a campaign all move it with its
campaign instead of leaving it at a number that now names another.

Every campaign's standing is settled at reload, counted by `standings_of`
in one pass over the cards the reload already holds rather than the walk
per campaign `campaign ls` pays. `Tab::standing` goes with it: the frame
reads the row's, since two counts of one number are two numbers free to
drift.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 15:10:49 +02:00
Ansho ReiandClaude Opus 5 154ffbdeb3 (001b639) Show the comment count on a board card, and bump to 0.24.1
A card had four corners and none of them said whether anybody had written
anything on the ticket. Finding out meant opening the detail view or running
`show`, which is the question the board exists to answer before you commit
to a card rather than after.

The count goes in the bottom right, left of the criteria count. Both are
about the ticket rather than about the reader, and the criteria count is what
that corner has always been: this is what has been added beside it, so it is
what sits further from the edge and what goes first when the column is
narrow. How far along a ticket is outranks whether somebody has said
something about it.

`corner_line` takes the whole right-hand group now instead of one span, and
the group gives up its items from the front until what is left fits. With one
item that is exactly the old behaviour, which is what the top row still
wants, so `due_span` returns a `Span` rather than the `Option<Span>` it only
ever had to satisfy the signature. The single space between items lives in
`corner_line` beside the gap arithmetic, not in the caller: the same reason
`column_areas` is shared between the draw and `follow_selection`, that
geometry reproduced by hand drifts from the draw.

`comments` is a field on `TicketItem`, filled where `criteria` and `tags`
already are, and it is the one entry on that pass that costs a directory
listing rather than coming off content in hand. So it is counted, never read:
`.md` only, the filter `read_comments` applies, and no body is opened,
because a count needs none of them. The alternative was a `read_dir` per
ticket per frame.

`collect_ticket_items` derives the board from `status_path.parent()` rather
than taking it as a second argument. Every caller joins a status onto a board
it already holds, and two arguments would let a status directory from one
board arrive with the comments of another. `comments_dir` now spells that
path once for the writer, the reader and the counter, the way `campaigns_dir`
does for its directory.

Zero draws nothing, not a `0` and not a blank cell held open. An uncommented
card is the row it has always been, down to the spacing, which is pinned
exactly rather than by a `contains`.

The mark is U+275E, a Dingbat, and the choice is about arithmetic as much as
reading. U+1F4AC SPEECH BALLOON is 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. U+1F5E8 LEFT SPEECH BUBBLE is
text presentation and Neutral but sits in a pictograph block most terminal
fonts leave as tofu. This one has the coverage the priority meter's Geometric
Shapes have. Cyan, and the only coloured thing on a row whose owner and
criteria count are grey: two counts side by side otherwise read as one number
in brackets and another that lost its brackets.

The no-per-draw test takes the comments directory away after the board is
built, and is paired with one that adds a comment and reloads, because a
count that never asked the filesystem again would pass the first by never
changing at all. The digest already moved on a new comment, so the reload is
what recounts.

Patch rather than minor: the corner was already two numbers and a mark, and
this settles what it says rather than adding a view.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 14:45:02 +02:00
Ansho ReiandClaude Opus 5 50e67483d8 (b2c5531) Delete the stale copy of the worklane skill, and bump to 0.24.0
`.opencode/skill/worklane-kanban-skill/SKILL.md` was 223 lines of the same
document `assets/SKILL.md` holds, shipped by nothing and checked by no test.
It drifted the way a copy nobody reads does: its frontmatter still called the
skill `worklane_kanban`, its examples still used short flags, and it knew
nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow.

It was not inert while it existed, and that was worth confirming rather than
assuming. `opencode debug skill` listed it by path, so an agent working in
this repo saw two worklane skills and could load either: the current one out
of `~/.claude/skills` or this one. After the delete the same command lists
`worklane`, `worklane-review` and `worklane-plan` and nothing else of ours.

The two agent files named it in their skill permission blocks,
`"worklane_kanban": "allow"`, an id only the deleted file defined, so the
permission granted access to nothing. Repointed at `worklane`, which is the
surviving document and what the grant meant. The files themselves stay: they
are the user's, and `reviewing-agent.md` is the prior art `assets/REVIEW.md`
grew out of. Neither was given `worklane-review` or `worklane-plan`, which
would be redesigning somebody else's agent rather than fixing a dead id.

`.opencode/skill/testing-skill` is untouched for the same reason. It is not a
copy of anything this repo ships.

8cc254c fixed the add example in the file this deletes, and it is moot rather
than reopened, recorded in a comment there. The fix was real: the example did
pass `-t` where `-g` was meant, gave `-p` three bare positionals, and clap
did reject it with exit 2. Nothing carries over, because `assets/SKILL.md`
never had either defect. Its examples are long flags throughout, one value
per flag, and it carries no "(or --due)" filler. Checked against the file.

AGENTS.md now says the surviving document is the only one and names this copy
as what happened last time, since the rule on its own does not say why it is
there.

The bump is the body of work's, not this commit's: `install-tool` in 11145b2
is the new command, and one bump on the last commit is what this tree does
when work spans several.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 14:26:57 +02:00
Ansho ReiandClaude Opus 5 11145b228e (c092ea7) Ship the opencode tool definitions with the binary, behind install-tool
`.opencode/tools/worklane.ts` was the second agent asset and the only one
that existed nowhere but a checkout. `cargo install` places binaries and
nothing else, so anyone who installed worklane got the skills and never the
tools, and the copy that did exist was reachable only from this repo. It is
now `assets/TOOL.ts`, embedded with `include_str!` like every other asset,
and `install-tool` writes it where opencode looks.

Its own command rather than a flag on `install-skill`, because the two
artifacts are not alike. A skill is inert markdown and one path serves both
agents. The tool is executable TypeScript and serves one: Claude Code has no
directory it scans for a tool definition, `claude mcp add` is the only way a
tool enters its list, and its plugin system adopts agents, hooks, monitors,
workflows, output-styles and themes and nothing named tools. Reaching it
would mean an MCP server, which is a different artifact and not this file.
So somebody on Claude Code takes the documents and never the wrapper, which
is the choice this command exists to give them.

The path was measured rather than guessed, as the ticket asked. 1.15.10
loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each
was served in turn from a directory outside any project and
`/experimental/tool/ids` came back with all eleven worklane tools. Singular
is the target, the spelling opencode's own documentation puts first the way
it writes `agent(s)` and `skill(s)`. `tools_root()` follows
`XDG_CONFIG_HOME` where `skills_root()` does not, because opencode's config
root is an XDG path and `~/.claude` is not; `opencode debug paths` reports
`$XDG_CONFIG_HOME/opencode` with it set. An empty value counts as unset, the
convention `colors_wanted` already follows.

`opencode_tool_dir` takes both variables as arguments for the reason
`colors_wanted` does: a threaded test binary cannot mutate the process
environment to reach one branch at a time.

The file name is load bearing and now pinned by a test. opencode builds each
tool id as the file name then the export, so `worklane.ts` plus eleven
`export const` lines is what makes them `worklane_add` through
`worklane_uncheck`. Renaming the file renames every tool and every
permission rule naming one.

The closing line is not the skills' "on their next session". opencode reads
its config once at startup and never reloads it, so a running one keeps the
tools it began with and the honest instruction is to restart it.

Nothing else has to be installed, which is worth saying because the file is
executable and reads as though it wants a toolchain. Criterion 6 asked the
command to name the plugin package and Bun as runtime requirements and both
are wrong: a copy in a project with no `node_modules` above it registered
all eleven tools on a machine with no `bun` on `PATH`. opencode is a Bun
binary and the import resolves inside it. The message says the opposite, and
the reasoning is on the ticket.

`install_each` is the outcome loop both commands now share, with the
compare-and-refuse invocation passed in: that line is the only part of an
outcome that has to name the command it came from. What each command says
after the loop stays with the command.

`every_tool_the_wrapper_exports_is_a_real_subcommand` guards the direction
that breaks at call time, a tool wrapping a command that has been renamed or
dropped. Deliberately not the reverse: the wrapper has no tool for `relate`,
`campaign`, `assign` or `tags`, so an agent holding the tools cannot reach
campaigns or relations at all, and a test asserting that gap would fail on a
decision nobody has taken rather than on a mistake. Its own ticket.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 14:14:14 +02:00
Ansho ReiandClaude Opus 5 2ddd0addf6 (59b23b7) Stop the board walk on a link that does not resolve, and bump to 0.23.1
`find_worklane_dir` asked `exists()`, which follows a symlink. A `.worklane`
that was a dangling link therefore answered exactly as no `.worklane` at
all: the walk carried on up the tree, the first board above the project
became the board, and every write landed in it. Silently, and in the board
belonging to someone else's project.

Latent while a board is a real directory inside the project it belongs to.
Once boards live in one shared directory and `.worklane` is a link into it,
a dangling link stops being a corrupted tree and becomes an ordinary state:
it is what you have before the boards repo is cloned, and after a board
directory is renamed. So this is reachable on an ordinary day rather than
only with a hand-made link.

`classify` reads `symlink_metadata` first, so the answer is about the entry
rather than about its target, and it is one of four: `Absent`, `Board`,
`Dangling` or `NotADirectory`. `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 here, not handed to whatever sits above it. Anything other than
`NotFound` out of `symlink_metadata` is an error too, since reading a
filesystem that could not answer as nothing-there is how the walk-past
worked in the first place.

The failure names the target and says the boards repo may not be cloned.
The old message, no board found and run `worklane init`, was wrong twice
over even with no board above: it describes an empty tree, and it points at
creating a board when the cause is an unsynced machine, which is the one
action that produces two boards with one name.

A regular file at that path is an error as well. It is a plausible future
pointer form and reading it as one is that change's decision to make;
stepping over it and writing above is the answer that is wrong today.

A link that resolves is still indistinguishable from a real directory, and
what comes back is the link rather than its target, so
`.worklane/backlog/*.md` reads the same either way and nothing downstream
learns whether the board is local.

Every writing command resolves the board before it writes, so the refusal
costs nothing halfway. `add` is where that is pinned end to end, against an
empty board above the project that stays empty. `init` is untouched: it
does not go through this walk, it writes nothing on a dangling link today,
and its symlink cases belong to the layout change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 13:47:31 +02:00
Ansho ReiandClaude Opus 5 cbc20848f6 (1845355) Order each status column by its entry stamp, and bump to 0.23.0
Every view read its rows out of `collect_ticket_items`, which sorts by
`by_priority_then_title` because it sees one directory and no status. That
is the right order for the backlog, where priority is the clock. Past the
backlog the question changes: committed asks what has waited longest,
reviewing what was handed over first, done what just landed. All four
columns answering the first question is why a finished p5 sat above the p1
nobody had read yet.

So each column takes its own order, through one `by_status_order` keyed on
the `Status` rather than four comparators at four call sites. Backlog
delegates to the comparator it already used. Committed sorts by
`Committed On` ascending and reviewing by `Submitted On` ascending, so the
longest wait is at the head where the reader picks next from; done sorts by
`Completed On` descending, newest first, the way a changelog reads.
Ascending twice and once descending is one rule said three ways: the head of
every column is what the reader acts on next.

A ticket carrying no stamp sinks below every stamped one in its column and
falls back to priority then title among its own kind, as do equal stamps --
`mv` writes whole seconds, so a tie is real. A missing time is unknown, not
ancient, and unknown must not claim the head of a queue ahead of a wait
somebody can point at. Reading absence as the epoch would have come free
from the comparison and put every ticket filed before f460853 first.

The comparison is a string comparison. `%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. The stamps are read on the pass
`collect_ticket_items` already makes over each file, the rule `criteria` and
`tags` already hold, and never per comparison.

Both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`
take it, which is why those loops walk `Status::ALL` rather than
`status_dirs()`: the directory name does not say which stamp governs it. The
merge tab keeps priority then title outright and is pinned there -- it spans
statuses, so no single stamp governs it. `cmd_tags` is left alone; it counts
into a `BTreeMap` and never reads an order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:58:34 +02:00
Ansho ReiandClaude Opus 5 eae411ab50 (f460853) Let the flow timestamps accumulate, and bump to 0.22.0
a6023e2 made the three stamps mutually exclusive: entering a status wrote
its field and leaving removed it, so a finished ticket carried exactly one
of the three and the journey behind it was invisible. A reader asking when
this was filed, when it was picked up, when it went out for review and when
it finished got one answer and three absences, and nothing could tell that
committed had ever happened.

So the removal rule is replaced by an accumulation rule. `mv` stamps the
target's field on entry, re-entering restamps, and arriving anywhere removes
the fields of every status *after* the target. That is one arrival rule off
the flow order `Status::ALL` already holds, not a case per move, and it is
also what a forward skip under `-f` wants: backlog straight to done stamps
`Completed On` alone and leaves the stages it jumped unwritten rather than
fabricated. A backward move truncates the journey at the target, so done
back to reviewing drops `Completed On` and keeps the two before it, and
anything back to backlog drops all three.

Presence therefore changes meaning. A field no longer says the ticket sits
in that status now, it says the ticket got that far and has not been sent
back past it. `Status` is what says where it is.

This is still not d4ce964's history log. These answer how far and when,
once per stage; every status change, every owner and every tag along the way
is the log's job.

The placement a6023e2 chose already holds: the three sit directly after
`Created At` in `METADATA_ORDER`, so a ticket that has walked the whole flow
reads as one block of four timestamps in flow order ahead of Campaign and
Status. Nothing but `mv` writes them, pinned by a test over `add`, `set`,
`append` and `chown`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:49:15 +02:00
Ansho ReiandClaude Opus 5 95426e87be (d637288) Guard an existing codename behind --force, and bump to 0.21.1
`campaign set --codename` replaced whatever was there. Once a campaign has
a codename it is referred to by it -- on every card in the campaign, at the
command line, and in somebody's shell history -- so changing it silently is
the mistake `install-skill --force` exists to prevent.

So it is refused, and the refusal names both words and the flag rather than
leaving it to be found. Checked before any edit is applied, like
`SetArgs::contested`, so a call also carrying `--title` writes neither
field rather than half of what was asked for.

Setting the codename a campaign already carries stays a no-op rather than
becoming a refusal: `--force` is about overwriting a *different* word, and
there is nothing to overwrite. That is the division `install::Outcome`
already draws between `Unchanged` and `Refused`.

`--force` guards the codename alone. A campaign always has a title, so
guarding that would mean the flag was always required, which is a tax
rather than a guard.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:28:40 +02:00
Ansho ReiandClaude Opus 5 72dbdec2ec (d637288) Add campaign set, and bump to 0.21.0
`campaign add --codename` was the only writer of the field, so a campaign
already on the board could not be given one without editing the file by
hand -- which is every campaign filed before 0.20.0.

A `campaign set`, not a flag on something narrower: the file has more than
one editable thing, and the moment somebody wants to fix a typo in a title
there would be a second command to design. It carries `--title`, which
renames the file the way `set --title` does, and `--codename`, through the
same parser `campaign add` takes. Built out of `set`'s own parts --
`set_title`, `apply`, `report`, and the whole-file no-op comparison -- so
nothing about writing a field lives twice.

The codename goes through `set_or_insert_metadata_field` rather than
`set_metadata_field`: a campaign filed before the field existed has no such
line, and those are exactly the campaigns this is for. That exposed a
second thing -- `Codename` was not in `METADATA_ORDER`, so an inserted line
landed at the end of the block while `campaign_body` writes it under the
ID, two shapes of one file. It is in the list now, directly after ID.

`save_ticket` split into `save_entry` with `save_ticket` and
`save_campaign` as named wrappers, so a campaign gets the same write-then-
rename a ticket has rather than a second copy of it. `write_then_replace`
and `find_entry_file` take the noun, so a failure says "campaign" where it
is one.

No `--description`, filed as 32e98ab: `set` and `append` are a pair for a
prose section, and replacing a description with no way to add a paragraph
is the half that loses the rest of it. No `--owner` and no `--clear`, each
for a reason recorded on the ticket.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:22:59 +02:00
Ansho ReiandClaude Opus 5 528566d103 (61879a4) Surface campaigns on the board, and bump to 0.20.0
A card label and a frame, not a campaign tab. A tab had to say what its
columns are, and a campaign groups across the flow rather than within one
status, so the answer is the four columns filtered: a filter on the board
it already has, not a fifth tab.

So a card names its campaign on the label row, before the tags, marked ~
and bold, and the row drops the tags whole before it drops the campaign.
`c` opens a picker; taking a campaign filters every column to its members
and draws a frame above them carrying the id, the codename, the name, the
opening line of the description and the standing. The standing comes from
the columns, since while a campaign is selected the columns are its
members. `q` takes off one layer at a time: the overlay, the filter, the
board.

The label needs something to say, which the stored uuid is not, so
campaigns gained `Codename`: one word, `v1` or `beaver`, written by
`campaign add --codename` and validated at parse time. `campaign ls`
prints it and `resolve_in` gained an exact-codename tier above the uuid
prefix, or it would be a field you can read and cannot type. Only
campaigns carry the field, so the tier is empty for a ticket and ticket
resolution is unchanged.

The campaigns index is read once per project in `columns_of`, on the pass
that already builds the cards, and `digest` now watches the campaigns
directory: without it a campaign filed elsewhere never reached the picker.
`frame_rows` grew a row, so the two bools deciding the geometry became one
`Chrome` and the row indices are named.

Left out and filed as d637288: nothing can give a codename to a campaign
that is already on the board.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:09:07 +02:00
Ansho ReiandClaude Opus 5 c65e1b4ed7 (55ee6e3) Complete campaigns and tags, and bump to 0.19.0
Every argument naming a campaign or a tag fell through to nothing: `campaign
show <TAB>`, `assign <TAB>`, `ls --campaign <TAB>` and `ls --tag <TAB>`. Neither
value had a listing a completion could parse.

`campaign ls --ids` is the same flag and the same two fields as `ls --ids`,
since it answers the same question about a different object. It skips the member
counting the decorated listing does, because `members()` reads every ticket on
the board and the caller is a shell on a keypress, and it prints nothing on an
empty board where the decorated listing prints a sentence.

Tags get a command rather than a mode on `ls`. `ls --tag <tag>` answers what
carries a tag and cannot answer what tags exist, which is the question a
grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a
filter that means something else. `worklane tags` prints the tag, a tab and the
count, alphabetical and case sensitive like the filter, so `bug` and `Bug` list
separately and land next to each other. assets/PLAN.md used to tell the agent to
count the vocabulary with a `show` per ticket; it now points here.

The fish half gains `__worklane_nested_arg_of`, which matches a parent and a
child, because `campaign show <TAB>` and `chown alice <TAB>` sit at the same
token count and the two counting helpers cannot tell them apart.

It also gains `__worklane_command_is`, which fixes a leak the campaign and tag
rules would have joined. A bare `complete -c worklane -l tag` does not only
complete that option's values, it tells fish the whole tool accepts `--tag`:
`worklane init --<TAB>` offered `--blocked-by`, `--regression-of`,
`--relates-to` and three others. `relate`'s three were already leaking that way,
so all of them are scoped now rather than leaving a correctly scoped twin beside
a wrong one. `__fish_seen_subcommand_from ls` is not the scope to use, since
`campaign ls` is an `ls` fish has seen.

The honesty tests grow to five lists and one walker, `every_argument`, since
they differ only in the id they look for. Each asserts how many arguments it
found, so a walker that stopped finding them fails rather than passing every
assertion by never running it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 01:16:51 +02:00
Ansho ReiandClaude Opus 5 6a800fb385 (bdddc09) Read only the underscore markers as unset, and bump to 0.18.1
`is_unknown_value` accepted `-None-` and `-Not set-` alongside the real
`_None_` and `_Not set_`. The ticket had them down as corrupted output handled
downstream instead of at the source, but the source never existed: `git log -S`
finds both spellings in exactly one commit, 2a96abd, the one that added them to
the check. They were written by analogy with the `**-Status**` field name the mv
splicing bug really did produce, c230d2c, and they have been dead since the day
the function was written.

So this is a deletion with nothing behind it. All five boards on this machine
hold no hyphenated marker in any metadata field, and the only files in this
repo that contain the spellings at all are the two tickets that describe the
bugs, in prose, which `parse_ticket_field` does not read.

A field that somehow holds one now reads as the text it is rather than passing
for unset, which is the right way round for corruption nothing can produce.
`a_hyphenated_marker_is_not_unset` pins that, because the risk here is not the
old code coming back but the analogy being drawn a second time. The
`**-Status**` repair in `is_status_line` is the opposite case and stays: that
corruption was real, and AGENTS.md now says why the two are not alike.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 00:52:39 +02:00
Ansho ReiandClaude Opus 5 4ae7ef03ff Let git blame look through the reformat
`.git-blame-ignore-revs` names 73ffcad, which touched 22 files and decided
nothing, so `git blame` no longer answers "who wrote this line" with the
formatter. Opt in per clone:

    git config blame.ignoreRevsFile .git-blame-ignore-revs

Also records the one thing the fmt rule does not cover: sixteen lines still run
past 100 columns and all sixteen are single string literals rustfmt cannot
break. `format_strings` stays off, since a message is prose and not the
formatter's to rewrite.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 00:23:22 +02:00
Ansho ReiandClaude Opus 5 73ffcad733 Reformat with cargo fmt, and nothing else
Layout only, no behaviour and no wording. 161 hunks across 22 files, 98 of them
rustfmt joining a call or a message onto the one line it fits on. The config it
formats to, and how its four numbers were arrived at, is the commit before this
one.

Separate so that it is reviewable by not being read: nothing here is a decision,
and every decision is next door.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 00:23:04 +02:00
Ansho ReiandClaude Opus 5 964ca342d8 (83d31cd) Make rustfmt the formatter, with a config measured against the tree
cargo fmt --check failed in about 160 places and rustfmt was neither run nor
switched off, so anyone who ran it once produced a diff that buried the change
it was run alongside. It is the formatter now, and the config is what makes
that affordable.

The default config wanted 305 hunks and would have added 1418 lines of pure
layout: its sub-widths (fn_call_width and chain_width at 60) sit far below the
100 columns this tree is written to, so 276 of those hunks were rustfmt
expanding lines that already fit. `use_small_heuristics = "Max"` went the other
way, 308 hunks and 796 lines removed, one-lining if/else and collapsing struct
literals that were split on purpose.

Coordinate descent over the stable width knobs lands at four settings and 161
hunks, 98 of them rustfmt joining calls that fit rather than breaking them.
Sweeping any one of the four in either direction makes the diff bigger, which
is recorded beside them so the next reader measures instead of adjusting by
eye. The reformat itself is the commit after this one, so neither is mixed
with the other.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 00:22:23 +02:00
Ansho ReiandClaude Opus 5 cc5f9b8a46 (74904dc) Let a ticket field be cleared back to unset, and bump to 0.18.0
`set --clear <field>` is the one way to take a value away, repeatable, with
the field as a `ValueEnum` value: an unknown one is a usage error listing the
six that are not, and the shells complete them for free. Not a per-field
`--clear-due`, which is a flag per field to keep in step with the one it
undoes, and not an empty value, which is already a paragraph break for a
section and would make an accidentally empty variable a silent delete.

What goes back is what `add` writes for a field it was never given, through
the new `NOT_SET` and `NONE` constants and each section's placeholder, so a
cleared ticket and one filed without the field read the same. Sections are in
scope and go back through `clear_section_body` rather than
`set_section_body`: the latter runs its items through `Section::render`, which
would have written `- [ ] _No acceptance criteria provided._`.

Owner is `chown --clear <ticket>`, so the field keeps its one writer. The flag
carries the ticket because the ticket is chown's second positional and a bare
flag would land it in the user's slot for the handler to read back out, which
is hand-parsing what clap can state. It writes `_Not set_` rather than the git
user: `add` falls back to the git user because it is filing something new, and
an owner taken away says nobody owns this.

The empty-value error split in two rather than being reworded. `non_empty`
says only that the value cannot be empty, for the arguments with no empty
form; `clearable` names `--clear`, for the arguments whose field has one. One
message for both would have lied about `ls --tag`.

Replacing and clearing one field in a single call is refused rather than
resolved by whichever was applied last, and cleared fields are reported as
`Cleared due on '...'` beside `Updated priority on '...'`, since one list
would say `Updated` of a field that was emptied.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 00:04:28 +02:00
Ansho ReiandClaude Opus 5 175c1d016d (6f44d16) Drop the unreachable duplicate-title check in add, and bump to 0.17.2
The branch tested a path built from a uuid generated three lines above
it, so it could not fire, and its message claimed a ticket with the
title already existed. Duplicate titles are supported on purpose.

What replaces it is the write's own failure, named with the ticket and
the path the way the other writes in the tree name them, and a test that
pins the message against an unwritable backlog directory.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 23:24:18 +02:00
Ansho ReiandClaude Opus 5 139c9b012f (a6023e2) Stamp the time a ticket entered its status, and bump to 0.17.1
mv writes Committed On, Submitted On or Completed On for the status it
enters, so the board answers how long a ticket has been where it is
without guessing from file mtimes.

The three are mutually exclusive: entering stamps, leaving removes and
re-entering restamps, so a backward move under -f leaves no stale
Completed On behind. These fields are current state, like Status itself;
the trail of how the ticket got there belongs to the history log.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 20:31:53 +02:00
Ansho ReiandClaude Opus 5 373ba519b3 Add a worklane completions command, and bump to 0.17.0
Every argument worklane takes names a ticket, a status, a shell or a skill, and
the shell offered a directory listing for all of them. `completions <shell>`
prints a script for fish, bash, zsh, elvish and powershell, following what frig
does, which is where the shape of this comes from.

Two halves, because neither alone is enough. `clap_complete` generates the
structure from the clap definition, so a flag added to `command.rs` is completed
without anyone touching `completions.rs`, and fish gets a hand-written block
appended for what only the board knows. That block runs `worklane ls --ids` in a
command substitution, one run per keypress, 2.5ms in release on a board of
seventy-five tickets.

A status is a `util::Status` value enum now rather than a string, which was the
plan's third step and pays for itself three ways. clap refuses an unknown one at
parse time naming the four, so `cmd_mv`'s `valid_statuses` and the status half of
`cmd_ls`'s error are gone and exit 2 is what an unreal status gets, the bargain
`--due` and `--priority` already take. `status_dirs()` and `DONE` are derived
from `Status::ALL`, so the flow is written once. And clap emits the four for `mv
--status` itself. Only half free: the fish generator emits nothing for the
possible values of a *positional*, so `ls <status>` and `completions <shell>` are
listed in the appended half after all, read off the enums with `possible_values`
rather than by hand.

`ls --ids` is the machine-readable listing, and prints the short id, a tab and
the title rather than the id alone. Both readers want both fields: fish takes
what follows a tab as the description, which is what makes `worklane show <TAB>`
a list of titles instead of hex, and a script takes the id back with `cut -f1`.
It includes done, where the decorated listing leaves done out, because a
completion has to be able to name a finished ticket and `show` is most often
pointed at one. It skips a missing status directory rather than refusing, since
an error printed over a shell prompt is worse than no candidates, and the
listing still refuses one so a person can act on it. The filters all still
apply, and an unknown `--campaign` is still refused ahead of everything.

Adding the mode tipped `cmd_ls` over the boundary AGENTS.md names, so it takes an
`LsArgs`, the way `add` took `AddArgs`.

More than the criteria asked, since the cost of each was a name in a list:
tickets are completed for `set`, `append`, `relate`, `check`, `uncheck`, the
second argument of `chown` and `assign`, and `relate`'s three target flags, plus
the skill names read off `install::SKILLS`. The three lists are kept honest by
tests that walk the clap definition and fail on a ticket-taking subcommand
missing from them, or listed at the wrong position. Nested subcommands are not
walked: `campaign` is the only one, none of its three takes a ticket, and the
token counting could not tell them apart if one did.

Position is counted rather than inferred. `__worklane_first_arg_of` reads
`$tokens[2]` and the token count instead of `__fish_seen_subcommand_from`,
because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish
has seen, and matching against the ticket list to find the position would run
worklane again inside the condition.

Files are turned off for the command and back on for `tui`, which is the one
argument that really is a path. The ticket said worklane takes no file arguments;
it takes those.

Campaigns and tags are completed nowhere, which needs a listing they do not have:
55ee6e3. And since fish runs whatever is on PATH, the completions are only as
current as the installed binary, an older one without `--ids` completing
nothing. That is in the README beside the install line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 20:02:37 +02:00
Ansho ReiandClaude Opus 5 88918b2f8a (c628759) Show a page indicator on the detail overlay's border, and bump to 0.16.1
The overlay has scrolled since 1b78a24 and nothing said where you were: a long
ticket opened looking exactly like a short one, so the only way to learn there
was more below was to press pgdn and watch whether anything moved.

`pg 2/8` now sits on the bottom right of the border, through
`Block::title_bottom` with a right-aligned line, which spends no text row. That
is the trade the title already makes on the top border, and the two cannot
crowd each other because they are on opposite borders.

Both of the things this had to get right are arithmetic. `wrapped_height` is
now the one measurement: `last_offset` is it less the viewport and
`page_indicator` takes the same two numbers, so the clamp and the indicator
cannot disagree. A second `line_count` call would be a number free to drift,
and an indicator claiming there is more to read where the scroll refuses to
move is worse than none.

The furthest offset is the last page by definition rather than by division. The
clamp stops at the wrapped height less the viewport, which is not a page
boundary, so the final screenful is partial and dividing reads `pg 2/3` at the
bottom of the ticket. The pages are counted in `scroll_step`, a screenful less
the overlap line, because that is the step the keys take: counting whole
screenfuls names a page pgdn cannot land on, and puts a 30 row ticket in a 10
row viewport at `pg 3/3` two rows short of its end.

Grey, the colour the footer keys and a rendered checkbox take, since this says
where you are in the ticket rather than anything about the ticket. Dropped
whole on an overlay too narrow for it and absent entirely when nothing scrolls,
the rules a corner and the tags row already follow.

`page_indicator` is four numbers in and an `Option<String>` out, so the
arithmetic is pinned without a terminal. The drawn tests answer the two things
it cannot: which border it landed on and what colour it reached the screen in.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 17:22:41 +02:00
Ansho ReiandClaude Opus 5 6784d80324 Let check and uncheck take several criteria, and bump to 0.16.0
Finishing a ticket means ticking every box, and that was one invocation per
box: each one resolved the ticket, spliced one line and rewrote the file.

The criterion positional is now variadic, so numbers and substrings mix in a
single call, and `all` stands for every criterion on the ticket. `all` is a
keyword checked before the text, the way the index already is, so a criterion
whose own words include "all" is reached by its number or by a longer
substring. `is_all_criteria` sits beside `is_index` for that reason.

`resolve_criteria` resolves every term before a byte is written and refuses the
whole batch on the first term it cannot place, naming it. A call that ticked
what it understood and then failed would leave the ticket half-marked with
nothing in the file to say which half was meant. The offsets are sorted and
deduped, so the report reads in `show`'s order and a criterion named twice, or
by both `all` and its number, is marked once. `set_criterion` becomes
`set_criteria` and takes every line in one pass.

Each named criterion gets a line, printed after the write. One already in the
target state reads `Already checked 2: text` and does not count towards the
write, so a batch where every box is already ticked writes nothing.

The opencode wrapper takes the terms one per line, like the other list
arguments. REVIEW.md gains the one thing a reviewer must not do with this:
reach for `all`, which would erase the implementer's claim on the criteria the
review agreed with.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 16:30:40 +02:00
Ansho ReiandClaude Opus 5 ae3ee1bb9e Show the target's status beside the relation kind, and bump to 0.15.2
A row now carries two marks, kind then status: what sort of edge this is, then
how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`.
Two questions are asked of this block, which rows hold this ticket up and
whether the ones that do are finished, and one glyph could not answer both.

○ not started, ◐ under way, ● finished, in grey, orange, cyan and green: the
shape says how far the target has got and the colour tells the two middle
stages apart, since committed and reviewing are both half circles. Green is the
colour the priority ramp deliberately leaves out because it means a title; on a
one-cell mark with no title behind it nothing else wants it, and it is the
obvious colour for done. Orange keeps the meaning it already has, Status.

These are the priority meter's own circles, and what keeps a status from
reading as a level is width: the meter is always two cells, a status mark is
one. the_status_mark_is_one_cell_where_the_meter_is_two pins both halves, and a
card carries the meter and never a status mark while the block carries the
status mark and never a meter.

The kind mark survives a target the board cannot find and the status mark
cannot, since a kind is read from the ticket's own file and a status from the
board. ? holds the column so the id does not move when one target has gone, and
_missing_ is what says it is gone.

Committed and reviewing are told apart by colour alone, so a pipe cannot tell
them apart: both read as under way. Accepted, since ● and ○ are the two answers
usually wanted and show on the target settles the rest, and assets/SKILL.md now
says so outright rather than leaving an agent to work it out from a colourless
half circle.

RelationTarget is back, carrying the title and the status in one Option because
they come from the same lookup. It went out in 5ae9c7f when nothing read the
status and came back one commit later, which is what a field nothing reads
costs: right at the time, churn either way.

A patch: 0.15.0 was the arrival of a marked relations block and this is still
settling what it marks. Three minors in an hour would read as three features.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 15:59:22 +02:00
Ansho ReiandClaude Opus 5 5ae9c7fe00 Mark a relation by its kind rather than its target's status, and bump to 0.15.1
A column of ▁▄▆█ read as undifferentiated blocks. What is worth seeing at a
glance is which kind of edge a row is: × for blocked by and blocks, → for
relates to, ← for regression of and regressed by. The labels are five long words
that blur when one ticket carries several, and the rows holding it up are now
the crosses.

Both directions of a kind carry one mark, since blocked by and blocks are the
same edge read from two ends and the label is what says which end you are on.

× is BLOCKED_MARK, the constant a held-up card already draws, in the same
brightred. On a card it says this ticket is held up, in the block that this edge
is what holds one, which is one word, so one glyph and one definition: the
constant moved to util.rs, where both renderers can reach it. Brightred rather
than the red asked for, because the id one cell to the right is red and the two
would have blended.

The arrows are the ones the footer already draws, so they render wherever it
does, and no_relation_mark_is_a_priority_glyph pins all three against every
level of the meter: the circles belong to priority.

The mark now survives a target the board cannot find, because a kind is read
from the ticket's own file rather than from the board. Only the name is gone,
and `_missing_` in grey is what says so. That is one case fewer than the status
mark had, which needed a `?` for a target with no status to show.

What this gives up is the status: 6ce2c47's motivation was reading whether a
blocker is finished without leaving the overlay, and nothing in the block shows
that now. Its criteria 1 and 3 describe the commit before this one, and the
ticket says so.

RelationTarget went with it. Nothing read the status field once the mark stopped
keying on it, and a field written but never shown is a field that goes stale
unnoticed, so RelationRow carries the kind and the title and the status is one
lookup away on the index if a later ticket wants it.

A patch, not a second minor: 0.15.0 was the arrival of a mark and settling which
glyph it is belongs to that, where a second minor would read as two features.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 15:35:24 +02:00
Ansho ReiandClaude Opus 5 ce32b42ae4 (dbf7b61) Guard the overlay's relation colours, and bump to 0.15.0
The mechanism arrived with 6ce2c47, as this ticket said it would: the block is
laid out once as cells, the id carries the red the guideline gives a uuid, and
the board turns the same cells into spans. So the id is red in the overlay
without anything here asking the terminal for a decision, and the three
criteria about what is drawn were true the moment ece201e landed.

What was left is the test the ticket was really about. The naive version of
this, passing true to the body renderers, puts escapes in the paragraph and
draws them as literal bytes, which is 6d327df, and the tests that pin that
assert on content_trim rather than on what detail_of builds.

the_relation_id_is_red_in_the_overlay_and_no_escape_reached_the_body asserts
the id span is red, that something on the row is coloured at all, and that the
body holds no escape byte. The middle one is the pair the Color and Output rule
demands: without it a version that dropped every colour to stay safe would
satisfy the absence. The one character version now fails this test and two
others, checked by making the change and running the suite.

a_missing_target_still_reads_as_missing_in_the_overlay is the same question
asked of a gap: _missing_ in grey, the id still red, and the mark ? in grey
rather than the status orange, so a target the board no longer holds cannot be
dressed up as one it does.

And the decision the ticket asked for, in AGENTS.md: the relations block is the
only coloured part of the overlay body, on purpose. The block earned it by
being where a reader compares several references at once, and by arriving as
rows rather than prose. The rest of the body is e4d0bb7, which is a larger
change than it looks, since every run content_parts paints has to become a cell
while show's output stays byte for byte what it prints today. One coloured
section reads as a decision; two would read as a bug.

The minor is 6ce2c47's, taken here because the pair is one body of work: show
now prints a status mark before each relation id.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 15:23:55 +02:00
Ansho ReiandClaude Opus 5 ece201e3ab (6ce2c47) Mark each relation with the status of the ticket it names
The Relations block named each target and said nothing about where it was, so
the question actually asked of it, whether a blocker is finished, meant closing
the overlay and going to find the other ticket. Each row now carries a mark for
its target's status, ahead of the id, where it describes the target rather than
the row.

A rising bar, U+2581 through U+2588 for backlog to done, and ? for a target the
board no longer holds. Not a circle: the cards spend those on the priority
meter two cells from nothing at all, and another circle would be read as a
level. The ramp is also the meaning, so the shape says which status it is.

The colour could not. Every colour in the guideline already means one thing and
the eight tag slots are reserved, so four status colours could only have come
out of something else's meaning. So the shape carries the status and the colour
says only that it is one: orange, which is what Status already means, and grey
on the missing mark, beside the _missing_ that grey already spells. An
unrecognised status reads as missing rather than as a fifth stage, and
every_status_has_a_mark pins the pairing against status_dirs so a status added
later fails a test instead of quietly reading as ?.

The plain text was the real cost. Detail.text was one String drawn by a
Paragraph, deliberately uncoloured because an escape sequence there is drawn as
literal bytes, which is 6d327df. So the block cannot arrive pre-painted.
Resolved.relations is now rows, content_parts returns the body as
BodyPart::Text and BodyPart::Relations with the text painted and the rows
untouched, and the two renderers take it from there: content_trim paints the
rows into escapes, and the board styles the same cells as spans.

One builder, two painters. relation_rows decides which edges there are, what
they are called and which direction leads; relation_cells decides the layout,
the mark and the colours; paint_cells and span_of are the only things that
differ. Cell is the unit both take, the same shape the palette uses to stop a
colour existing for one renderer and not the other. reference_cells is now the
one spelling of a cross reference, shared with the Campaign field.

Detail.body is a ratatui Text and is the only thing measured, so last_offset
and the Paragraph cannot wrap the body two ways. Detail::plain() flattens it
for the suite and is cfg(test): a second representation carried beside the
spans is a second thing to disagree.

show carries the same mark, decided here rather than discovered later. The rows
are one builder so it was free, and two views disagreeing about what a relation
shows is a difference nobody can explain afterwards. That is a change to what
the CLI prints, so the minor goes on the last commit of this pair.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 15:20:56 +02:00
Ansho ReiandClaude Opus 5 c437d87e9e (2f3796e) Add a --tag filter to worklane ls, and bump to 0.14.0
Tickets carry a Tags field, but ls could not select on it: finding what is
tagged bug meant reading the board. Step 1 of the plan was already done by
e41802b, which put tags: Vec<String> on TicketItem through parse_tags, so this
is the flag, the filter and the tests.

Whole values, not the field. parse_tags has already split and trimmed the
comma-separated field, so filter_by_tag compares against those values: --tag
bug is not answered by a ticket tagged bugfix, --tag "cli, filter" matches
nothing because the field as written is not itself a tag, and a ticket with no
tags matches none, however it spells it.

Case sensitive, which is the opinion the field already takes everywhere else.
tag_color draws Bug and bug in two colours because they are two tags to the
field, and a filter that folded them would list tickets carrying a tag nobody
asked for while hiding exactly the split a grooming sweep is looking for.

One tag per invocation. Several would have to decide between and and or, and
that decision is its own ticket, along with substring or regex matching and a
tag filter on the board.

A tag nothing carries lists nothing rather than being refused, deliberately
the opposite of --campaign. A campaign is an object that exists or does not,
so it is resolved before anything is read; a tag is free text with no
registry, and refusing an unknown one would mean maintaining a vocabulary the
format does not have. An emptied status keeps the message ls already gives
rather than one per filter naming what excluded them, which is what --priority
and --campaign already do.

The filter goes through filtered, the one call the three collect sites share,
so the counts are filtered by the same set as the rows. Every filter is an
Option and none asked for keeps everything, which is what makes them compose
in any combination. cmd_ls is now at four filters and the directory, two of
them adjacent &Option<String> parameters a caller can swap silently: left as
positionals rather than refactored mid-feature, with AGENTS.md recording that
the next filter takes an LsArgs struct the way add took AddArgs.

assets/PLAN.md said in as many words that there was no tag filter yet, so it
would have been actively wrong. It now says what --tag can and cannot answer:
it finds what is tagged bug, it does not enumerate the vocabulary, which is
the question a grooming sweep starts from. The README's ls row also gained
--campaign, which had never been documented there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 14:54:50 +02:00
Ansho ReiandClaude Opus 5 0ce3fdb246 (0546fc5) Copy the selected id with y in the tui, and bump to 0.13.7
The board is where a ticket is found and the CLI is where it is acted on, and
the only thing joining them was seven characters retyped off the screen. y
reads as yank to the readers a keyboard board is for, and was the letter left
after q, esc, enter, space, hjkl, the arrows, pgup, pgdn, tab, backtab, d and
/ took theirs.

The mechanism was chosen against ssh, which is where a board is often read.
OSC 52 crosses the connection, because it is the terminal at the reader's own
end that owns the clipboard. A crate wants X11 and Wayland libraries at build
time and, on X11, hands the selection to the process that set it: copy an id,
quit, and the paste buffer is empty, which is precisely the flow this key
exists for. Shelling out to wl-copy, xclip or pbcopy is platform sniffing plus
a spawn, and does nothing where none of them is installed. crossterm 0.28 is
what ratatui 0.29 pins and ships no clipboard command, so the sequence and its
base64 are twenty lines in src/clipboard.rs, pinned on the RFC 4648 vectors.

The cost is recorded rather than hidden, in AGENTS.md under The Copy Key: a
terminal that ignores OSC 52 ignores it silently, and tmux needs set-clipboard
on. What clipboard::copy reports is whether the sequence was written, and the
footer says no more than that. There is no reply to read either, since the
query form is refused by most emulators.

What is copied is ticket.id, the seven characters the card already prints and
every command already resolves, decided by Board::copy_text so the string is a
question the suite can ask without a clipboard. None on an empty column: an
empty string would take away whatever the reader had there and give nothing
back. The project is left off even on the merge tab, since a second word would
have to be deleted out of every paste.

Board::copy_selected_id takes the clipboard as an argument, clipboard::copy
from the dispatch and a closure from a test, which is what makes the hit and
the refusal both drivable. A failure is said in the footer rather than
returned: there is nobody above it to handle one, and an error swallowed there
would look exactly like a copy that worked until the paste came out wrong.

Notice is the board's first channel for saying something in words, and it has
to be, because a copy leaves nothing on screen to look at. failed means
nothing reached the clipboard, so an empty column and a refused write are one
answer to the reader, both in brightred like the search's no match. It takes
the whole footer row, since a message squeezed in beside the keys would move
every key in it. Cleared by the next keypress rather than on a timer: no clock
on the board, no wakeup in the loop, and never in tick, which runs four times
a second. clear_notice goes ahead of search_key as well as the arms, because a
key typed into a query is still a key.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 14:36:09 +02:00
Ansho ReiandClaude Opus 5 37dbd722e0 (3b16540) Open a search with / in the tui, and bump to 0.13.6
Finding a ticket meant scrolling four columns and reading, which is what the
id and the title are for.

The real work was the input mode: every key in the dispatch was a single-shot
action, and a query needs one that swallows the keys bound to them. That is
Board::search_key, offered every key ahead of the action arms and reporting
what it took. With no prompt open it takes nothing, so every other state's
dispatch is unchanged. On Board for the reason dismiss is: the arm is not
reachable from a test.

ctrl-c is the one key the prompt declines, since a terminal application
always honours it. Every other control combination is swallowed and does
nothing: it must not type its letter, and it must not fall through either,
because the action arms match on the code alone and ctrl-d would reach the
arm bound to d.

first_match runs over every card in the visible columns, in reading order,
not the rows on screen: a query that answered differently on a tall terminal
and a short one is not a search, and the jump scrolls the match into view. A
hidden done column stays out, or the highlight would land on a ticket that is
not on the board. Id and title only, both lowercased.

The jump goes through select_at, extracted as the tail select_card already
used, so follow_selection scrolls the match's own column and refresh_detail
keeps an open overlay on it. Nothing calculates either a second way.

A hit closes the prompt; a miss keeps it open, marked in brightred beside the
query it is about, with the selection untouched, so the query can be
corrected in place rather than retyped from /. The mark clears on the next
edit. An empty query matches nothing rather than everything.

The prompt takes the whole footer row, since the key list it replaces
describes nothing that works while every key goes into the buffer. The real
terminal cursor sits after the query: ratatui shows it only for a frame that
asked, so it is also what says "you are typing" on an empty query. Both
closed footers now name / search.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 13:29:30 +02:00
Ansho ReiandClaude Opus 5 4502de7ee3 (e7612de) Close the detail overlay on q instead of quitting, and bump to 0.13.5
q set should_quit outright, so a reader who pressed it to put a ticket away
lost the whole board instead. That is not what q means anywhere else that
lays a document over a list, and esc two arms below already did the right
thing.

The rule is Board::dismiss: close what is open, quit when there is nothing
left to close. On Board rather than in the match arm because the dispatch in
main.rs is not reachable from a test, so a rule written there is a rule
nothing can check. q and esc now share one arm, since two arms carrying one
rule is how a later edit changes it for one key and not the other.

The footer is the other half. Its last slot answers the same question in
both states, how to get out, and with a ticket open the honest answer is
ctrl-c: it is 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 close entry names both keys as enter/q close
rather than repeating close twice.

Criteria 3 and 7 live in a dispatch no test can reach, so
the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quitting scans
main.rs for them, over whitespace-collapsed source so rustfmt cannot fail
it, the way util.rs is already scanned for colour_text callers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 13:13:58 +02:00
Ansho ReiandClaude Opus 5 a16169ce8c (b8ce18c) Show a blocked marker on the tui card, and bump to 0.13.4
A ticket held up by an open blocker looked exactly like one that is ready,
and the board is where the next thing to pick up is chosen.

The mark is × in brightred, after the short id. Not a fourth Geometric
Shapes glyph: those are the priority meter's, two cells away, and another
circle there reads as part of that ramp. × is Latin-1, like the middle dot
the unset priority draws, so it renders wherever the meter does.

After the id rather than before it, because ahead of it the mark would push
every id in the column out of line whenever one card was blocked. 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.

No scan of the board per tick was needed after all. collect_ticket_items
also reads the ticket's own uuid and the targets of its blocked by lines,
off the file it is already holding, and mark_blocked walks the four columns
once for a uuid-to-status map and once to answer every card. The flag is on
Card rather than TicketItem: the answer is about two tickets at once, so no
card can reach it alone, and it is settled at reload the way project is.

The merge carries each card's flag from the board it came from. relate
resolves its target inside one .worklane, so a blocker in another project is
not a relation anything can record, and recomputing over the merged columns
would let one project's uuid match another project's ticket.

project_label now takes the width the row has actually spent, measured off
the spans, instead of adding up the widths those spans are supposed to have.
The hand-written sum left out the space after the priority mark, so a cut
label was handed one cell more than the column had.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 13:02:13 +02:00
Ansho ReiandClaude Opus 5 3d6a74bc53 (daa0e79) Validate the due date at parse time, and bump to 0.13.3
A clap value_parser beside priority_level rather than a check inside cmd_add,
so a bad date is a usage error with nothing written at all rather than
written and then rejected.

On set --due as well as add --due, from one definition. The planning skill
sets dates through set and never through add, so validating only the command
that files a ticket would have left the path the validation exists to
protect still accepting "next friday".

The shape is checked before chrono sees it. %Y-%m-%d accepts an unpadded
2026-8-9, which would be stored as typed and sort before 2026-10-01. Strict
on the way in, tolerant on the way out: util::due_date still cuts a datetime
down to its date, since a file written earlier can hold one.

PLAN.md told the planner the value was not validated. That is corrected, and
the guard test that failed on the edit now pins the half of the warning that
is still true: a date cannot be cleared, only replaced.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 03:22:04 +02:00
Ansho ReiandClaude Opus 5 7a0dd625ce (1e7b1a9) Colour a tag by its name, and bump to 0.13.2
FNV-1a over the tag bytes into an eight-colour reserved palette, so the same
tag is the same colour on every card and on every board with nothing stored.
The hash is written out rather than taken from std, whose output is not
promised stable across releases.

The index is multiply-shift, not `% len`. The length is a power of two, so a
modulus keeps the low three bits of the hash, and FNV-1a's low bits carry
only the low bits of the input bytes: nothing moves information downwards.
Every pair of tags differing above bit 2 landed in one slot, `bug` and `BUG`
among them. It looked like a good palette, two colliding cards in sixty-four
on this board, because the vocabulary had been folded into a handful of
slots. Using the whole hash gives 14/64, which is the real arithmetic for
eight colours.

The palette is reserved as a list and disjoint from the seven colours that
already mean something: a tag in red reads as a uuid, in green as a title.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 03:13:56 +02:00
Ansho ReiandClaude Opus 5 8d8ae8abfe (822e8a1) Add a worklane-plan skill, and bump to 0.13.1
A third asset on the machinery 16c2bed settled, so the wiring is one entry in
install::SKILLS.

Four jobs, priorities, due dates, tags and campaigns, with propose-then-apply
stated once at the top rather than per section. Every job writes to many
tickets at once and no field can be cleared back to unset, so the document
leans on the two traps that make a sweep destructive rather than merely
wrong: set --tags replaces the whole field, and a due date is neither
validated nor clearable.

feature-planner-agent.md is deliberately not folded in. It decomposes a
request into new tickets, which is intake; this orders the tickets that
already exist, and one document holding both would fit neither.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 02:58:50 +02:00
Ansho ReiandClaude Opus 5 d5fb22cfd8 (16c2bed) Add a worklane-review skill, and bump to 0.13.0
install-skill now writes every document the binary carries, with an optional
name to narrow it. Requiring a name per document would mean a skill added
later never reaches anyone who already knows the invocation, which is the
drift the command exists to prevent. --print is the exception and requires
the name: a diff is against one document.

The review skill is its own document rather than a section of SKILL.md,
because the frontmatter description is the whole of what decides loading and
one description cannot name both "anything touching a ticket" and "only when
a review is asked for".

The reviewer never ticks a criterion and never moves the ticket. A tick is
the implementer's claim and unticking is the review disagreeing; one mark for
both loses the disagreement. mv belongs to whoever does the work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 02:40:37 +02:00
Ansho ReiandClaude Opus 5 2c0a99f7c4 (e41802b) Record that the board is drawn for a person, not parsed
Scripts and agents drive worklane through the CLI, which is what the skill
teaches and what the integration tests pin. Nothing reads the drawn frame, so a
change to what a card carries breaks no caller and is judged on whether it reads
well. Written down beside the version rule as well, since "changed output" there
means the CLI's output: that is why a new row on every card is a patch.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 01:08:54 +02:00
Ansho ReiandClaude Opus 5 91bbc19c32 (e41802b) Show a ticket's tags on its tui card, and bump to 0.12.1
The Tags field was invisible on the board: a card carried the mark, the short id,
the due date, the owner and the criteria count, and nothing said a ticket was
tagged bug without opening it.

TicketItem gains a tags field, filled in collect_ticket_items through parse_tags
where the file is already being read, for the reason the criteria count is: the
board draws them on every card, and asking per card would re-read every ticket
body on every draw. 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 one answer. That is step one of 2f3796e5, lifted here
because the board cannot read the field before it exists.

The row sits under the title, dimmed like the owner and the count, each tag
prefixed with # so it does not read as a third line of the title. It is dropped
whole when the column will not hold it, the rule a corner follows, and an
untagged ticket spends no row at all.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 01:07:40 +02:00
Ansho ReiandClaude Opus 5 5b0bac9c2d (7bfb9fc) Add campaigns, a ticket container assigned through worklane assign, and bump to 0.12.0
There was no way to group the tickets that have to be finished together. A
goal such as a v1 release was either one ticket that could not describe its
parts, or a set of tickets with the goal restated in every description and
nothing tying them together.

A campaign is a file of its own under `.worklane/campaigns/`, with a title, a
description and metadata, and it sits in no status directory. Its state is
derived instead: open until every member is done. Deriving it means there is
no such thing as a done campaign holding an open ticket, and no second
forward-only ruleset beside `mv`'s. An empty campaign is neither open nor
done, since calling it done would make a container nothing has been filed
against the most complete thing on the board.

Membership is one field on the *member*, Campaign in the ticket Metadata,
written only by `assign`. The member list is deliberately not on the campaign:
that would put membership in two places and make one file that every
assignment edits, contended the moment two agents share a board. So `add`
gains no `--campaign` and neither does `set`.

`add` does not write the field either. Every ticket written before campaigns
existed has none, so the insertion path has to exist regardless, and leaving
it out of `add` means one path that is always exercised rather than two. That
is the Relations argument from 4179958, applied to a field instead of a
section. `set_or_insert_metadata_field` is the upsert and `METADATA_ORDER` is
its anchor list, the way `SECTION_ORDER` is `ensure_section`'s, so Campaign
lands beside Status rather than at the end and Status stays last. A file with
no Metadata heading is an error rather than an insertion, per 641e3d5.

The three tiers came out of `resolve_ticket` into `resolve_in`, shared by both
kinds. A campaign is addressed exactly the way a ticket is, and a second
resolver would be a second copy of the precedence rules to keep in step. Two
things fell out of that. `Found.dir` is the status for a ticket and empty for
a campaign, which is what drops the bracket from the ambiguity listing for
one. And `resolve_ticket` can now explain a search that names a campaign, so
`mv`, `show`, `chown` and everything else that takes a ticket give the same
reason instead of a bare "no ticket found" — one place rather than a check per
command. Only on the zero-match path, so an ambiguous ticket error is never
replaced by a complaint about a directory the caller never mentioned.

The stored value is the full uuid, per the same rule the Relations section
follows, and the title is resolved for display. `reference_cell` is now shared
between the two, so a dangling campaign and a dangling relation target are
both `_missing_` rather than each inventing a spelling. `Resolved` carries
what `content_trim` cannot render from the file alone: a struct rather than
two more parameters, so the next such field is one entry instead of an edit at
every call site.

`campaign show` lists done members, unlike `ls`, which leaves the done column
out of its listing. What is finished against what is left is the whole
question a campaign asks. `ls --campaign` is the other way round and keeps
every rule `ls` already has.

Deliberately out of scope. The derived progress figure is 1cb999f, now
recorded as blocked by this, since nothing here can compute it yet.
Unassigning needs a field cleared back to unset, which is 74904dc. And the
board gets neither a campaign tab nor a card marker: the detail view resolves
the field because it renders the body, and that is all. A marker would want a
read per reload and the four corners are already spent, which is the b8ce18c
reasoning; filed as 61879a4.

Twenty-four integration tests and eleven unit tests, covering assign,
reassign, the no-op, a dangling campaign, the ls filter, `mv` refusing a
campaign, insertion placement, and a handwritten section and unknown metadata
field surviving an assignment verbatim.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 00:52:57 +02:00
Ansho ReiandClaude Opus 5 41a65f95b2 (2ec6508) Filter status directories to md files in ls, and bump to 0.11.1
A status directory is a plain directory, so anything can land in it.
`collect_ticket_items` read every entry it could, so a stray `notes.txt`
was listed as `(notes) _No title_` and counted in the per-status summary
beside the real tickets.

The extension check is the one every other scan of a status directory
already makes: `resolve_ticket`, `RelationIndex::load`, `find_ticket_file`
and the tui's `digest` all skip a non-md path. This was the only reader
without it, so the fix is to join them rather than to invent a rule.

Subdirectories were already excluded, but by accident: `read_to_string`
fails on a directory and `filter_map` dropped it. The filter now refuses
them on the extension, and the test keeps a subdirectory in place so a
later change to how the file is read cannot bring them back.

The count needed nothing. It comes from `collect_ticket_items().len()`
since the priority filter was added, so filtering the source fixed both
the rows and the number in one place.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 00:20:16 +02:00
40 changed files with 18964 additions and 1164 deletions
+8
View File
@@ -0,0 +1,8 @@
# Revisions that changed layout and nothing else. Teach git to look through them:
#
# git config blame.ignoreRevsFile .git-blame-ignore-revs
#
# Only a commit whose diff is pure formatting belongs here.
# Reformat with cargo fmt, and nothing else
73ffcad73314621e299dc06ee688db9b4c4d6b29
+1 -1
View File
@@ -17,7 +17,7 @@ permissions:
bash:
"sudo *": "deny"
skill:
"worklane_kanban": "allow"
"worklane": "allow"
---
# Feature Planner Agent
+1 -1
View File
@@ -17,7 +17,7 @@ permissions:
bash:
"sudo *": "deny"
skill:
"worklane_kanban": "allow"
"worklane": "allow"
"testing-skill": "allow"
---
@@ -1,223 +0,0 @@
---
id: worklane_kanban
name: worklane_kanban
version: 1.0.0
description: >
Creates Kanban-style tickets in Worklane using the `worklane add` CLI command.
Supports listing tickets with `worklane ls`. Both commands support title, description,
acceptance criteria, implementation plan, tags, due date, owner assignment, and status filtering.
rendering:
strategy: cli_args
join_arrays_with: ","
omit_empty: true
---
# Worklane Kanban Skill
Use this skill when creating, listing, or managing Kanban-style tickets via the `worklane` CLI.
When asked to "create a ticket", use the `worklane add` command.
When using backticks in the command arguments, escape them so the terminal doesn't execute them.
When asked to "implement", "work on" or "read" a ticket, use the `worklane show` command.
## Commands
### `worklane add`
Add a new ticket to the backlog.
**Required:**
- `--title` (or `-t`): Ticket title
**Optional:**
- `--description` (or `-d`): Ticket description
- `--acceptance` (or `-a`): Acceptance criteria (repeat flag for each criterium)
- `--plan` (or `-p`): Implementation plan steps (repeat flag for each step)
- `--tags` (or `-g`): Tags (comma-separated)
- `--due`: Due date in YYYY-MM-DD format. No short form
- `--owner` (or `-o`): Owner name
- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted. No short form
Tags are `-g`, not `-t`: `-t` is the title, and passing it twice is an error. Each
plan step needs its own `-p`, since a bare value after one is not a second step.
```bash
worklane add -t "Implement login" -d "Add user login page" -g login,auth -p "Design UI" -p "Build backend" -p "Write tests" --due 2026-06-01 --owner "ilya"
```
When there's multiple acceptance criteria, add each using a separate `--acceptance` or `-a` flag.
When there's mulitple steps to the implementation plan, add each using a separate `--plan` or `-p` flag.
```bash
worklane add -t "Implement logic" -a "Acceptance criterium 1" -a "Acceptance criterium 2" -p "Step 1" -p "Step 2"
```
### `worklane ls`
List tickets, optionally filtered by status.
**Valid statuses:** `backlog`, `committed`, `reviewing`, `done`
```
worklane ls # List all tickets
worklane ls backlog # List tickets in backlog
worklane ls done # List completed tickets
worklane ls --priority 1 # Only the most urgent, any status
worklane ls backlog --priority 2 # Composes with the status filter
```
Tickets are listed priority first, then by title. Tickets with no priority sort last.
### `worklane show`
Show the full details of a single ticket by UUID or title.
```
worklane show "ticket title or uuid"
```
### `worklane mv`
Move a ticket between statuses.
**Positional arguments:**
- `<id>`: Ticket UUID prefix (4+ characters) or title
**Required options:**
- `--status <target>`: Target status (`backlog`, `committed`, `reviewing`, `done`)
**Options:**
- `-f`: Force move (allows skipping stages and backward moves)
**Default behavior:** Only allows forward moves, one stage at a time (`backlog` -> `committed` -> `reviewing` -> `done`).
Examples:
```bash
worklane mv ticket-id --status committed # Move forward one stage
worklane mv ticket-title --status reviewing -f # Force skip stages
worklane mv a1b2c3d4 --status committed # Move by UUID prefix
worklane mv "My Ticket" --status done -f # Move by title with force
```
### `worklane set`
Replace fields on an existing ticket. Only the fields given are touched; ticked
criteria and handwritten sections are left alone. At least one field is required.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
**Options:** `--title`, `--description` (or `-d`), `--acceptance` (or `-a`), `--plan`
(or `-p`), `--tags` (or `-g`), `--due`, `--priority`
Owner is not settable here, and neither is status: `chown` owns owner and `mv` owns
status. Changing the title renames the file, keeping the UUID.
```bash
worklane set a1b2c3d4 --priority 1
worklane set a1b2c3d4 --title "A clearer title" --due 2026-12-31
worklane set a1b2c3d4 -a "First criterium" -a "Second criterium"
```
### `worklane append`
Add to a section without replacing what is there. The description gains a new
paragraph; criteria and steps go on the end of their lists, steps numbered on from
the last. At least one section is required.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
**Options:** `--description` (or `-d`), `--acceptance` (or `-a`), `--plan` (or `-p`)
```bash
worklane append a1b2c3d4 -d "A paragraph amending the description."
worklane append a1b2c3d4 -a "One more criterium"
worklane append a1b2c3d4 -p "A later step"
```
### `worklane chown`
Set the owner of a ticket. The only command that writes the Owner field: `set` does
not offer it.
**Positional arguments:**
- `<user>`: The new owner. Free text, checked against nothing
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
The user comes first and the ticket second, after Unix `chown`. That is the one
command here that does not start with the ticket, so mind the order: swap the two and
the call fails, because the username has to resolve as a ticket. An owner set to the
value it already holds is reported unchanged and nothing is written.
```bash
worklane chown alice a1b2c3d4
worklane chown "Ansho Rei" "A clearer title"
```
### `worklane check` and `worklane uncheck`
Tick or untick a single acceptance criterion. Every other criterion keeps its state,
and handwritten lines in the section are left alone.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
- `[criterion]`: The number as shown by `worklane show`, or a substring of its text
Omit the criterion and the numbered criteria are listed and the number asked for. With
no terminal, as when driving the CLI from a tool, the same list comes back as an error
instead, so re-run with the number. A substring matching more than one criterion is an
error listing the matches with their real numbers.
```bash
worklane check a1b2c3d4 2
worklane check a1b2c3d4 "renames the file"
worklane uncheck a1b2c3d4 2
```
### `worklane comment`
Add a comment to a ticket.
**Positional arguments:**
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
- `<body>`: Comment text
Comments are stored as timestamped markdown files in `.worklane/comments/<ticket-uuid>/` and include the git author and timestamp.
Examples:
```bash
worklane comment ticket-id "Reviewed, looks good"
worklane comment "My Ticket" "Needs changes to the UI"
worklane comment a1b2c3d4 "LGTM, approved"
```
## Working a ticket
Move the ticket as you work it, not afterwards. The board should say what is happening
now, not only what already landed.
1. `worklane show <id>` to read it
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
the ticket as being worked on, so it belongs at the start
3. Do the work. `worklane check <id> <n>` as each criterion is met
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
acceptance criterion, something the ticket got wrong
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
makes moving it up front the same two commands in a more useful order.
## Commands
- `worklane add` creates tickets with all relevant details
- `worklane ls [status]` views tickets by status
- `worklane show <id>` views full ticket details
- `worklane mv <id> --status <target>` moves tickets through the workflow
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
- `worklane check <ticket> <n>` ticks a criterion as it is met
- `worklane comment <ticket> <body>` adds notes to tickets
+274 -14
View File
@@ -3,21 +3,32 @@
## Project Structure
- `src/main.rs` - dispatch, the SIGPIPE reset, and the TUI event loop
- `src/command.rs` - CLI argument definitions using clap derive
- `src/completions.rs` - the generated completion script and the fish half that asks the board
- `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/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
- `assets/SKILL.md` - the agent skill `install-skill` ships, embedded with `include_str!`
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
- `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI
- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
- `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`
- Ticket files stored as `.md` in `.worklane/<status>/` directories
- 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`, `Status`
- 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
- 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
## Status Workflow
@@ -32,9 +43,28 @@ 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
- `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
- `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
- **`WORKLANE_KEEP_FIXTURES=1 cargo test` keeps the fixtures and prints each path.** Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and `Fixture::swept()` turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment
- **Verify a claim about leaked fixtures against a clean temp dir, not against `/tmp`.** `TMPDIR=/tmp/scratch cargo test` then count what is left in it: `/tmp` still holds the historical leak, so counting there measures the past rather than the change
- In `tui.rs`, `write_member_card` is `write_tagged_card` plus a Campaign field and `write_campaign` puts a campaign on disk, creating the campaigns directory as it goes — `board_dir()` deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. `picker_rows` cuts the picker's list out of the frame by its own geometry, for the reason `overlay_title_row` exists: a card carries the same campaign label, so a search over every row finds the board rather than the list
- **`cargo clippy --all-targets` is clean. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
- **`cargo fmt --check` is clean too, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
| setting | value | why |
|---|---|---|
| `max_width` | 100 | The tree's own habit, and the measured optimum: 90 costs 268 hunks and 120 costs 194, against 161 at 100 |
| `fn_call_width` | 75 | A call stays whole if it fits in three quarters of the line. rustfmt's default of 60 is what expanded 276 of the 305 hunks the default config wanted |
| `chain_width` | 65 | The same for a method chain |
| `struct_lit_width` | 30 | A small struct literal stays whole, so `Size { width: 120, height: 20 }` is not six lines |
**The numbers were measured, not chosen.** Default rustfmt wanted 305 hunks and would have added 1418 lines of pure layout, because its sub-widths sit far below the 100 columns this tree is written to. `use_small_heuristics = "Max"` went the other way, 308 hunks and 796 lines *removed*, one-lining `if`/`else` and collapsing struct literals that were split on purpose. Coordinate descent over the stable width knobs landed here, at 161 hunks, and 98 of those are rustfmt *joining* calls that fit rather than breaking them. Sweeping any one of these four in either direction makes the diff bigger, so do not adjust one by eye; measure it the same way, with `cargo fmt --check | grep -c '^Diff in'`
- What this does not buy: rustfmt has no rule for "keep parallel arms parallel", so a match whose arms are one line and four lines depending on the length of their contents is what it produces, and that is accepted. Reach for `#[rustfmt::skip]` only where the layout carries meaning a reader needs, not to win an argument about density
- Do not add an unstable option. `cargo fmt` on stable ignores them with a warning, so the tree would format differently for whoever ran nightly
- **Sixteen lines still run past 100 columns and every one of them is a single string literal**, a test fixture or an error message rustfmt cannot break. `format_strings` is deliberately left at its default: turning it on would let the formatter rewrite message text, and a message is prose. So `max_width` is where rustfmt breaks lines, not a limit the tree keeps
- The reformat is `73ffcad`, and `.git-blame-ignore-revs` names it so `git blame` looks through it. Turn that on once per clone with `git config blame.ignoreRevsFile .git-blame-ignore-revs`. A commit belongs in that file only if its diff is pure layout
## Coding Guidelines
@@ -49,22 +79,65 @@ and this file is for what someone changing worklane's own code needs.
### CLI Arguments
- The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written
- **The trade:** on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why `due`, `priority`, `tags`, `owner` and `status` are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add `PROSE` to a new argument unless it holds prose
- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
- **`campaign add --codename` is validated at parse time by `codename`**, which is `non_empty` plus one word. The board draws it as a label with a mark and no quoting, so `~beaver release` on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason `ls --tag` refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
- `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails
- **A paragraph break in a description is an empty `--description` value.** `cmd_add` joins the values with a single newline, so `-d "First." -d "" -d "Second."` writes the blank line. `trim_blank_ends()` drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed
- `--acceptance` and `--plan` are lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only `--description` preserves blanks
### Completions
- **Two halves, and the split is the point.** `clap_complete` generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching `completions.rs`. Only fish gets the second half, appended by `fish_dynamic()`, and it holds exactly what clap cannot know: the tickets on the board
- **The dynamic values come from worklane itself**, as `worklane ls --ids` in a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without `--ids` completes nothing, which is a reinstall rather than a bug
- **What clap does and does not emit.** It emits the possible values of an *option*, which is why `mv --status <TAB>` needs nothing here, and nothing for a *positional*, which is why the `ls` status and the `completions` shell are listed in the fish half. Both lists are read off the enums with `possible_values`, never written out, so a fifth status appears in the script on its own
- **Position is counted, not inferred.** The four `__worklane_*` predicates all read `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition. `first_arg_of` and `second_arg_of` count a top-level command's arguments, `nested_arg_of` matches a parent and a child so `campaign show <TAB>` can be told from `chown alice <TAB>`, which sit at the same token count, and `command_is` asks only which command this is, at any position in it
- **Every rule carrying `-l` needs a `__worklane_command_is`, and `every_rule_naming_an_option_is_scoped_to_a_command` is what enforces it.** A bare `complete -c worklane -l tag` does not just complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --<TAB>` offered six options that only `relate` and `ls` have. Fixed in 55ee6e3. `__fish_seen_subcommand_from ls` is not the scope to use, for the nesting reason above
- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
- **A campaign is named in three shapes and a tag in one**, which is why the lists are not one list: a campaign is `assign`'s first positional, the first argument of `campaign show` and `campaign set`, and `ls --campaign`'s value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command
- **`ls --ids` is the machine-readable listing**, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused
- **`campaign ls --ids` is the same flag and the same two fields for the other object**, and it deliberately skips the member counting the decorated listing does: `members()` reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates
- **`worklane tags` is the third, and it is a command rather than a mode on `ls`.** Two reasons: `ls --tag <tag>` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so `bug` and `Bug` list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. `assets/PLAN.md` used to tell the agent to count tags with a `show` per ticket, and now points here
### Filtering the Listing
- **The filters are one call, `filtered`,** because `ls` collects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is an `Option` and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair
- **`--tag` matches whole values, not the field.** `parse_tags` has already split the comma-separated field, so the filter compares against those trimmed values: `--tag bug` is not answered by a ticket tagged `bugfix`, and `--tag "cli, filter"` matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none
- **Case sensitive**, the opinion the field already takes: `tag_color` draws `Bug` and `bug` in two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for
- **One tag per invocation.** Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, and `worklane tags` is what it checks against, since that is the failure this trades for
- An emptied status keeps the message `ls` already gives, `No tickets in '<status>' status.`, rather than one per filter naming what excluded them. That is pre-existing behaviour for `--priority` and `--campaign`, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket
- **`cmd_ls` takes an `LsArgs`**, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent `Option<String>` values a caller could swap silently. `--ids` was the argument that tipped it, the way `add` became `AddArgs`. A new filter is a field there, not a parameter
### Editing a Ticket
- `set` replaces a field, `append` adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and `append` only offers the sections that hold multiple lines
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s). Do not add either
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them
- `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username
- `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands
- `apply()` is the one place an edit is taken or dropped, shared by `set`'s replaced list and its cleared one. It was a closure over the single list until there were two, and two closures carrying one rule is how a later edit changes it for one and not the other
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, a `SectionKind` and the `--clear` value that empties it. Adding a section later is one entry, not edits in both commands
- Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten `## Notes` section intact when an unrelated field changes. `section_body()` finds the lines to touch, `set_metadata_line()` does the metadata, and every other byte is copied through
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` in `command.rs`. Clearing a field is not supported yet, and the error says so rather than guessing
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear <field>` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
### Clearing a Field
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
- **`Clearable` is a `ValueEnum` in `util.rs`**, so an unknown field is a usage error at the door listing the six that are not, and the shells complete them for free. It is also the whole table of what can be cleared: `Due`, `Tags` and `Priority` clear to a sentinel, `Description`, `Acceptance` and `Plan` to their section's placeholder. `Title` is absent because it addresses the ticket and names its file, so there is no state to go back to; `Owner`, `Status`, `Campaign` and the stamps because clearing them through `set` is exactly the second writer the missing `set --owner` exists to prevent
- **What is written is `NOT_SET` and `NONE`, the constants `add` writes.** A cleared ticket and one that was never given the field have to read the same, or clearing would be a third state that every parser then has to know about. `a_cleared_ticket_reads_like_one_filed_without_the_fields` compares the two files byte for byte, which is what keeps a new field honest
- **The placeholder goes into a section bare, via `clear_section_body`.** `set_section_body` runs its items through `Section::render`, which would write `- [ ] _No acceptance criteria provided._`. Both are `replace_section_body` underneath, so the line surgery and the trailing blank line live once
- **The pairing between a section and its `--clear` value is stored on both**, `Clearable::unset` one way and `Section::clear` the other, because the error for an empty value has to name the flag for *that* section and the section's label ("acceptance criteria") is not the flag's value ("acceptance"). `every_clearable_section_points_back_at_the_field_that_clears_it` keeps the two directions from drifting. `RELATIONS.clear` is `None`, the same rule that keeps it out of `section_args`
- **Cleared fields are reported apart from replaced ones**, as `Cleared due on '...'` beside `Updated priority on '...'`. One list would say `Updated` of a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the ones `set` already prints when it *writes* the field, so the two lines name a field the same way
- **Replacing and clearing one field in a single call is refused**, by `SetArgs::contested`. clap cannot express it, because the field arrives as `--clear`'s value rather than in its name, and answering by whichever was applied last is a silent answer to a contradictory call
- **Clearing the owner is `chown --clear <ticket>`, and `--clear` carries the ticket.** Owner has one writer and clearing it cannot introduce a second, so it lives on `chown`; but the ticket is `chown`'s *second* positional, and a bare flag would land it in the user's slot for the handler to read back out, which is hand-parsing what clap can state. The typed call is identical either way. `ChownArgs::target` returns the one shape the constraints allow, and an error rather than a panic for the combination they already refuse
- **Clearing the owner writes `NOT_SET`, not the git user.** `add` falls back to the git user because it is filing something new; an owner taken away says nobody owns this, and putting the person running the command there instead hands them a ticket they were giving up
- Clearing a field that is already unset writes the sentinel that is already there, so the whole-file comparison below reports no change and nothing is written. That is not a special case, and must not become one
- No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
- `find_ticket_file()` matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved: `mv <uuid-of-second>` used to move the first ticket sharing its title
- `write_then_replace()` is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
@@ -72,11 +145,16 @@ and this file is for what someone changing worklane's own code needs.
### Checking Off a Criterion
- `check` and `uncheck` are separate commands, not one verb with a flag. They share `CheckArgs` and `cmd_check(args, checked)`
- `criteria()` is scoped to the Acceptance Criteria section and counts only checkbox lines, so a checkbox written into a description is not a criterion and a handwritten line inside the section takes no number
- `set_criterion()` splices only the character between the brackets. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox
- The criterion argument is an index first, a substring second, so a criterion whose text is literally `2` is reachable only by substring
- `set_criteria()` splices only the character between the brackets, and takes every line in one pass. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox
- Each criterion term is the keyword `all` first, an index second, a substring third. So a criterion whose text is literally `2` is reachable only by substring, and one whose text merely contains "all" only by its number or a longer substring. `is_all_criteria()` and `is_index()` sit beside each other in `util.rs` for that reason
- **The keyword wins over the text on purpose.** Ticking every box is the reason the word is typed, and a board where `all` sometimes means one criterion and sometimes means the lot would be worse than one that can be addressed another way. `all_is_the_keyword_and_not_a_substring_of_the_text` pins it against its own fixture, so the shared one keeps its three criteria and its numbering
- **A number out of range is a bad index, not a failed substring search**, and says so. `is_index()` makes that distinction
- Any listing of a subset must keep the real numbers, via `numbered_criteria()`. Renumbering the matches from one contradicts the advice to use the number and points at the wrong criterion
- With the criterion omitted: prompt when stdin is a terminal, otherwise return the numbered list as an error. Never prompt unconditionally, the opencode wrapper has no tty and would block on a stdin that never closes. This is the same choice `resolve_ticket` makes for an ambiguous match, and for the same reason
- **The criterion positional is variadic**, so `check <ticket> 1 3 "the footer"` is one call and one write. Variadic rather than a repeated flag: the terms address criteria that are already there, the way the ticket positional does, instead of carrying content the way `--acceptance` does. The prompt path is unchanged and fires on an empty list
- **`resolve_criteria()` resolves every term before a byte is written, and one bad term refuses the whole batch.** A call that ticked the terms it understood and then failed would leave the ticket half-marked with nothing in the file to say which half was meant. It names the offending term alone rather than every failure at once, since each message carries the criteria listing and a batch of them would repeat the list per bad term
- The chosen offsets are sorted and deduped, so the report reads in `show`'s order whatever order the terms arrived in, and a criterion named twice, or by both `all` and its own number, is marked and reported once
- **Every named criterion gets a line, in `show`'s order, printed after the write.** A criterion already in the target state reads `Already checked 2: text` and does not count towards the write, so a batch where every box is already ticked writes nothing, which is the whole-file no-op rule the editing commands keep. The number is on the unchanged line too: without it a batch cannot be read back against `show`
- `show` numbers the criteria as `1. [x] text`, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it
### Relating Tickets
@@ -90,9 +168,39 @@ and this file is for what someone changing worklane's own code needs.
- `ensure_section` inserts against `SECTION_ORDER`, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten `## Notes` between the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to
- **The blocker check runs on every move**, after the already-in-that-status return and behind `force`. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused. `-f` now bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true
- **A blocker that is not on the board warns and allows the move.** Refusing would wedge the ticket with no way out but `-f`, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names **every** open blocker, since clearing the one that happened to be printed would leave the ticket blocked
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc, and a blocked marker on the TUI card, which is its own ticket. Nothing on a card is worth a scan of the board per tick until the card is designed for it
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See The Board View
### Campaigns
- **A campaign's state is derived, never stored.** Open until every member is done, computed by `Standing` from the members. A `Status` field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no `campaign mv` and no forward-only ruleset beside `mv`'s
- **A campaign with no members is neither open nor done.** `Standing::state()` returns `None` there, and both callers print `no members`. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
- **Membership is one field on the member**, `Campaign` in the ticket Metadata, written only by `assign`. The member list is deliberately *not* on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So `add` has no `--campaign` and `set` has no `--campaign`, the same rule as Owner and Status
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cell` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **`add` does not write the field.** Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of `add` means one path that is always exercised rather than two. Same reasoning as the Relations section
- `set_or_insert_metadata_field()` is the upsert, and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no `## Metadata` heading is an **error, not an insertion**: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
- **The four tiers are `resolve_in()`, shared by tickets and campaigns.** A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. `Found.dir` is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
- **An exact `Codename` is the top tier, and it lives in the shared resolver rather than in a campaign-only path.** Only campaigns carry the field, so `parse_codename` returns `None` for every ticket and the tier is always empty for one: ticket resolution is unchanged, which `a_ticket_search_is_unaffected_by_the_codename_tier` pins. It goes above the uuid prefix because it is an exact match on a field written for the purpose, where a substring can be a coincidence, and because a codename like `v1` is below `MIN_ID_SEARCH` and would never be tried as an id at all. A codename that a title also contains, `v2` against `v2 release`, has to win outright rather than be reported ambiguous against it
- **`resolve_ticket` explains a search that names a campaign**, rather than each command doing it. One place, so `mv`, `show`, `chown` and everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentioned
- **`Resolved` carries what `content_trim` cannot render from the file.** The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call site
- `campaign show` lists **done** members, unlike `ls`, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option. `ls --campaign` is the other way round: it is the ordinary board filtered, and keeps every rule `ls` already has
- `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
- **The TUI got a card label and a frame, not a campaign tab.** 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups *across* the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and `c` for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in `columns_of` and is what names the label; see The Board View
- **A campaign is named by its codename on the board, and by its short id when it has none.** The uuid does not fit on a card and the title is a sentence, which is the gap `Codename` fills. `campaign_label` builds it in one place, as a `Cell`, so the CLI paints it and the board makes a span of it; the mark is `CAMPAIGN_MARK`, `~`, beside `#` for a tag
- **`campaign set` and `campaign append` are the only writers of a filed campaign's fields.** d637288 decided the command: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `set` carries `--title`, which renames the file the way `set --title` does, `--description` and `--codename`; `append` carries `--description` alone. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
- **Replacing a codename the campaign already has needs `--force`.** Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake `install-skill --force` exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field. Setting the codename a campaign already carries stays a **no-op, not a refusal** — `--force` is about overwriting a *different* word, which is the same division `install::Outcome` draws between `Unchanged` and `Refused`. `--force` guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
- **The description arrived as a pair, `set --description` and `campaign append`, 32e98ab.** Never one without the other: for a prose section `set` replaces and `append` adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line `append` already draws for a ticket, and `campaign_append_offers_only_the_description` pins that. Neither flag takes `--force`: a description is prose written to be revised, the same reason `tags set --annotation` has none
- **`append` is a campaign's own subcommand, not the top-level `append`.** That one resolves a ticket, and one positional naming either object is the ambiguity `resolve_in` makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of `resolve_ticket`, which explains a ticket search that *names* a campaign. Under `campaign` the object is settled by the command, as it is for `set`, `show` and `ls`
- **Still no `--owner` and still no `--clear`.** No `--owner`, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign. No `--clear`, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be `Clearable` on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. `campaign_set_offers_no_owner_and_no_clear` pins both
- **An empty `--description ""` is a paragraph break here too, and the refusal for an all-blank value names no flag.** Every prose argument in the tool reads a blank value that way, `add`, `set` and `tags --annotation` alike, so a campaign reading it as *empty the section* would be the one exception. With no `--clear` to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. `replaced_items` is where the check lives, shared with `set`, and the way out is the caller's argument for exactly that reason
- **`SECTION_ORDER` needs no campaign variant, and that is what the one-section file proves.** A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, *filtered by what is actually in the file*, so a campaign's description anchors against `## Metadata` — which is where `campaign_body` writes it. `the_description_is_edited_in_place_in_a_file_with_one_section` pins that no section a campaign does not have gets inserted to anchor against
- **A campaign whose Description heading is gone is refused, not given the section back.** No `ensure_section` on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where `add` writes nothing and the insertion is the only path there is. The refusal therefore names the section and **not** the object — "There is no description section to write to" — because both a ticket and a campaign reach `replace_section_body` now. `write_then_replace` still carries the noun, where the message is about a file
- **The codename is written through `set_or_insert_metadata_field`, not `set_metadata_field`.** Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts `assign` on the upsert. **`Codename` is therefore in `METADATA_ORDER`, directly after ID**, so an inserted one lands where `campaign_body` writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
- **One write path for tickets and campaigns.** `save_entry` is the body, `save_ticket` and `save_campaign` are the named wrappers, and `write_then_replace` and `find_entry_file` take the noun as a `&str` so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, `<uuid>_<slug>.md` in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
- `campaign_body()` builds the file from `DESCRIPTION` and `METADATA_HEADING` rather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status
- The campaigns directory is created by `init` and **on demand** by `campaign add`, since every board made before campaigns existed has none and a `worklane init` over a live board to get one would be a strange thing to have to do
### The Board View
- **The board is for a person, and only for a person.** Scripts and agents drive worklane through the CLI, which is what `assets/SKILL.md` teaches and what the integration tests pin. Nothing parses the drawn frame, so its layout is free to change: a new row on a card, a moved corner, a different colour or a hidden column breaks no caller. Judge a change here on whether it reads well, not on what it might break, and do not preserve a layout for compatibility's sake. What the CLI prints is the opposite case and is not covered by this
- `worklane` with no subcommand and `worklane tui` both open it, the way a bare `frig` does. `Cli::command` is therefore an `Option`
- The worklane directory is looked for **before** the terminal, so running outside one gives the usual "No .worklane directory found" rather than a complaint about the tty. Both errors stay reachable and both are testable without a pty
- A missing tty is refused with a message naming a subcommand. Raw mode on a pipe fails with a bare "No such device or address (os error 6)", which explains nothing
@@ -101,23 +209,86 @@ and this file is for what someone changing worklane's own code needs.
- `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
- Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view
- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
- **The campaign frame scrolls on the same two keys, and `Board::scroll_page` is where the precedence lives.** An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In `Board` rather than in the `main.rs` arm for the reason `dismiss` is: a layering rule written into that dispatch is a rule nothing can check
- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
- **The overlay carries a page indicator on the bottom right of its border**, `pg 2/8`, so a long ticket does not open looking exactly like a short one. `Block::title_bottom` with a right-aligned `Line`, which spends no text row, the trade the title already makes on the top border. The two cannot crowd each other: they are on opposite borders
- **`wrapped_height` is the one measurement.** `last_offset` is it less the viewport and `page_indicator` takes the same two numbers, so the clamp and the indicator cannot disagree. A second `line_count` call, or a count of the raw lines, is a number free to drift, and an indicator that says there is more to read where the scroll refuses to move is worse than none
- **The furthest offset is the last page by definition, not by division.** The clamp stops at the wrapped height less the viewport, which is not a page boundary, so the final screenful is partial: `offset / step + 1` reads `pg 2/3` at the bottom of a 25 row ticket in a 10 row viewport and claims there is more below
- **The pages are counted in `scroll_step`, a screenful less the overlap line, not in whole screenfuls.** The step is what the keys take, so counting in it names only pages `pgdn` can land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport at `pg 3/3` two rows short of its end, since three presses are what it takes to get there
- The indicator is dropped whole on an overlay too narrow for it, the rule a corner and the tags row already follow, and absent entirely when nothing scrolls, the way an untagged card spends no row on tags
- `page_indicator` takes four numbers and returns an `Option<String>`, so every case above is pinned without a terminal. The drawn tests exist for the two things arithmetic cannot answer: which border it landed on and what colour it reached the screen in
- **Columns scroll to keep the selected card in view.** `Board::offsets` holds one offset per column, parallel to `columns` and resized in step by `reload`, so a column you leave stays where it was. The keypress aligns the focused column via `follow_selection(screen)`, taking the screen size for the same reason `scroll_detail` does: the visible height belongs to the terminal, which only the caller measures between draws
- Card heights are measured on `card_lines`, never assumed, on both the keypress and the draw side (`card_height`, and the `starts` vec as the cards are built). An alignment that trusted a fixed card height would drift from the renderer the first time the card changed shape
- The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back
- Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top. The index is shared and clamps permanently when a shorter column pulls it down, so a column you return to follows the selection to where it now sits rather than holding your old place
- **The footer names only keys that work.** It read `↑↓ scroll` when nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete
- **`q` and `esc` are one key: close what is open, quit when there is nothing left to close.** `q` used to set `should_quit` outright, so a reader who pressed it to put a ticket away lost the board instead, which is not what `q` does anywhere else that lays a document over a list. One match arm in `main.rs`, not two: two arms carrying one rule is how a later edit changes it for one key and not the other
- **The rule is `Board::dismiss`, not the match arm.** The dispatch in `main.rs` is not reachable from a test, so anything decided there is undecidable by the suite. The arm is the line that names the keys and nothing else. `the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quitting` scans `main.rs` for what the arm cannot say for itself, over whitespace-collapsed source so rustfmt cannot fail it
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on saying `q quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
- **The 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
- 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, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both were invisible at the end of a line of prose
- **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
- **A card's height therefore depends on the column's width**, so `card_lines` and `card_height` both take it. `column_areas` is shared between the draw and `follow_selection` for the same reason: `Ratio` hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
- **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 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
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
- **The toggle re-clamps the frame offset, through `scroll_frame(0, screen)`.** A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next `pgup` counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
- **A heading is drawn only over rows that exist**, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
- **`open` and `completed`, not `open` and `done`.** The split is taken from `Standing::state`, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not *in* done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
- **Headings and the truncation line take no number: the highlight moves over campaigns only.** `stepped_picker_row` walks past the chrome rather than stopping on it, since a highlight resting on a heading gives `enter` nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
- **The highlight follows its campaign, not its row number.** `place_picker` takes a uuid, the answer `Tab::campaign` already gives for the filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted uuid before the lists are rebuilt and puts it back after
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
- **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
- **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
@@ -126,6 +297,62 @@ and this file is for what someone changing worklane's own code needs.
- 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
### The Search Prompt
- **`search: Option<Search>` is the whole mode**, the shape `detail` uses: "the prompt is open" and "what is in it" cannot disagree, and closing it leaves nothing to reset. `Search` also carries `missed`, set when enter found nothing and cleared by the next edit, since the message is about the query that missed
- **The prompt swallows every key it is given.** `Board::search_key` runs ahead of the action arms in `main.rs` and reports what it took, rather than every arm below asking whether a search is open. Typing `d` into a query must not toggle done and `q` must not quit; with no prompt open it takes nothing, so the dispatch is unchanged for every other state. The rule is on `Board` for the reason `dismiss` is: the arm is not reachable from a test
- **`ctrl-c` is the one key it declines**, because a terminal application always honours it and a prompt that ate it would leave no way off the board. Every *other* control combination is swallowed and does nothing: it must not type its letter, and it must not fall through either, since the action arms match on the code alone and `ctrl-d` would reach the one bound to `d`
- **Esc is consumed by the search before it can mean anything else**, which is the collision e7612de left behind: `esc` and `q` close the overlay, and both have to lose to an open prompt. It falls out of the pre-branch rather than being ordered by hand
- **`first_match` searches the *visible columns*, every card in them, not the rows on screen.** A query that answered differently on a tall terminal and a short one is not a search, and the jump scrolls the match into view anyway. Hidden columns stay out: with done hidden, a match there would put the highlight on a ticket that is not on the board. Reading order is column by column, then top to bottom
- Id and title only, per 3b16540, both lowercased. The title has to be case insensitive to be worth typing, and giving the id the same treatment lets a pasted id match whatever case it was copied in. An empty or all-space query matches **nothing** rather than everything
- **The jump goes through `select_at`, the tail `select_card` already used.** `follow_selection` scrolls the column the card is in, and the offsets are per column and on the `Tab`, so a jump across columns moves the right one; `refresh_detail` keeps an open overlay on the ticket the selection names. A second version of either is how a jump comes to scroll differently from the arrow keys
- **A hit closes the prompt and a miss keeps it open**, marked, with the selection untouched. The query can then be corrected in place instead of retyped from `/`. Doing nothing visible is what makes a reader retype a query that was already right
- **The prompt takes the whole footer row**, because the key list it replaces describes nothing that currently works while every key is going into the buffer. The typed query is drawn in the default foreground and the keys in grey: one is content, the other is chrome. `no match` is brightred beside the query it is about, since grey chrome is what a reader skips
- **The real terminal cursor goes after the query**, not a glyph standing in for one. ratatui shows the cursor only for a frame that asked for it, so `set_cursor_position` is also what says "you are typing" while the query is still empty. Clamped to the row, so a query longer than the terminal leaves it on the last cell
- Both closed footers name `/`, since the jump works with a ticket open as well: it moves the selection and the overlay follows
- Out of scope on purpose, each its own ticket once the input mode exists: `n` and `N` for the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
### The Copy Key
- **`y` copies the selected card's short id, over OSC 52 written by hand.** The board is where a ticket is found and the CLI is where it is acted on, and the only thing joining them was seven characters retyped off the screen. `y` reads as yank to the readers a keyboard board is for, and was the letter left: `q`, `esc`, `enter`, `space`, `hjkl`, the arrows, `pgup`, `pgdn`, `tab`, `backtab`, `d` and `/` were taken
- **The mechanism was chosen against ssh**, which is where a board is often read. An escape sequence is the only one of the three ways that crosses the connection, since it is the terminal at the reader's end that owns the clipboard. A crate (`arboard` and its kind) wants X11 and Wayland libraries at build time, and on X11 the selection belongs to the process that set it: copy an id, quit, and the paste buffer is empty, which is precisely this flow. Shelling out to `wl-copy`, `xclip` or `pbcopy` is platform sniffing plus a process spawn, and does nothing on a machine where none of them is installed or on the far end of a connection. crossterm 0.28 is what ratatui 0.29 pins and it ships no clipboard command, and the backend types have to match whatever ratatui pins, so a newer crossterm cannot be picked up on its own
- **The cost is paid knowingly: a terminal that ignores OSC 52 ignores it silently**, and tmux needs `set-clipboard on`. What `clipboard::copy` reports is whether the sequence was written, not whether it was honoured, and the footer message says no more than that. There is no reply to read: the query form of OSC 52 is refused by most emulators as a security matter, so nothing better is available to us
- Base64 is twenty lines here rather than a dependency, because the only thing that goes through it is a seven-character id. Pinned on the RFC 4648 vectors, which cover both padding forms, since a wrong encoder would put plausible-looking rubbish on the clipboard
- **`c` and not `p`**: the clipboard proper, not the X11 primary selection, since this is pasted into a command line. Terminated with BEL, which is what tmux documents and what every emulator that implements this at all accepts
- **What is copied is `ticket.id`, the seven characters the card prints**, not the full uuid: they are what stops the retyping and what `show`, `mv` and `comment` all resolve. Decided by `Board::copy_text` rather than inside the arm that copies, so the string is a question the suite can ask without a clipboard. `None` on an empty column, since an empty string would take away whatever the reader had there and give nothing back
- The project is left off even on the merge tab, where the id alone is not an address. This goes onto a clipboard to be pasted into a command line, and a second word in it would have to be deleted every time; running the command in the wrong project fails to resolve rather than acting on the wrong ticket
- **The clipboard is handed to `Board::copy_selected_id` as an argument**, `clipboard::copy` from the dispatch and a closure from a test. That is what makes both answers drivable, and it keeps the terminal write out of the board state
- **A failure is said in the footer, not returned.** There is nobody above it to handle one: the board goes on being drawn, and an error swallowed there would look exactly like a copy that worked until the paste came out wrong
- **`Notice` is the board's one channel for saying something in words**, since a copy leaves nothing on screen to look at. `failed` means "nothing reached the clipboard" rather than "an error occurred", so an empty column and a refused write are one answer to the reader, both in brightred for the reason `no match` is
- **It takes the whole footer row**, on a weaker reason than the prompt's: every key still works while a notice is up. It is that a message squeezed in beside the key list would move every key in it, and the row is the only part of the board that is not a ticket. Drawn after the prompt, which is an input and cannot be covered
- **The notice is cleared by the next keypress, not by a timer.** No clock on the board and no wakeup in the loop, and the moment the reader does anything else the message has been read or was never going to be. Doing nothing leaves it up, which is the one state where it is still worth reading. `Board::clear_notice` runs ahead of `search_key` as well as the arms, since a key typed into a query is still a key, and it must never move into `tick`: the board redraws four times a second and a notice cleared there would never be read
### The Relations Block
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
- **`Cell` is the unit both renderers take**: a run of text and the colour it is drawn in, `None` for the default foreground. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
- **A row carries two marks, kind then status**: what sort of edge this is, then how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
- The status went through one bad shape first. It was a rising bar, `▁▄▆█`, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
- **Both directions of a kind carry one mark.** `blocked by` and `blocks` are the same edge read from two ends, and the label is what says which end you are on. `both_directions_of_a_kind_carry_one_mark` pins it
- **`×` is `BLOCKED_MARK`, the same constant a held-up card draws**, in the same brightred. On a card it says this ticket is held up and in the block it says this edge is what holds one, which is one word, so one glyph and one definition. It lives in `util.rs` for that reason, not in `tui.rs` where the card is
- **The kind marks stay out of the priority vocabulary**, which owns `●◐○·`, and `no_relation_mark_is_a_priority_glyph` pins that against every level. They are the arrows the footer already draws, so they render wherever it does
- **The status marks are those very circles, and what keeps them from reading as a level is width**: the meter is always two cells and a status mark is one. `the_status_mark_is_one_cell_where_the_meter_is_two` pins both halves. A card carries the meter and never a status mark, and the block carries the status mark and never a meter, so the two never sit in one column
- **Both marks go ahead of the id**, where they describe the target rather than the row. Every row carries both, so nothing is pushed out of line the way the card's blocked mark would have been, which is why that one sits after the id and these before it
- **The kind mark survives a target the board cannot find and the status mark cannot**, since a kind is read from the ticket's own file and a status from the board. `?` holds the column so the id does not move, and `_missing_` in grey is what says the target is gone
- **Committed and reviewing are told apart by colour alone**, both being `◐`, so a pipe cannot tell them apart: `should_use_colors` is false and both read as under way. Accepted, because `●` and `○` are the two answers usually wanted and `show` on the target settles the rest, and `assets/SKILL.md` says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
- `RelationTarget` carries the title and the status in one `Option`, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
- **`show` and the board carry the same mark**, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
- **`Resolved.relations` is rows, not a rendered block.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
- **`Detail.body` is a `Text`, and it is the only thing measured.** `last_offset` and the `Paragraph` both take it, so the clamp cannot wrap the body differently from the draw. `Detail::plain()` flattens it for the suite and is `#[cfg(test)]`: a second representation carried alongside the spans is a second thing to disagree
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
### 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
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
### Monitoring Several Boards
- `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
@@ -133,7 +360,7 @@ and this file is for what someone changing worklane's own code needs.
- **`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
- 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. That comparator is exported for this and is the one `collect_ticket_items` uses, so the two orders cannot drift
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
@@ -142,13 +369,31 @@ and this file is for what someone changing worklane's own code needs.
### 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
- **One install path serves both agents:** `~/.claude/skills/worklane/SKILL.md`. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own `~/.config/opencode/skill/`. Verified against opencode 1.15.10, whose built-in `customize-opencode` skill documents the table and whose `opencode debug skill` lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
- `Asset` carries the content, the path under its root and the word used in messages, so `install-tool` adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is `install.rs` and not `skill.rs`
- `install()` takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects `HOME` for the same reason
- **A modified copy is refused, not overwritten.** Someone may have edited it on purpose, and the message names `--print` so it can be diffed and `--force` so it can be replaced. A read error is not treated as absent either: the write reports the real reason
- Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every `worklane <x>` the skill shows has to be a real subcommand, and every subcommand outside `NOT_FOR_AGENTS` has to appear in the skill. The last one catches a new command that nothing tells an agent about
- `install-skill` looks for no board. The skill is what teaches an agent worklane, so needing a `.worklane` to install it would put it out of reach exactly when it is wanted
- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them
- The **agent files** under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question. The tool file is the exception and no longer lives there: it was `.opencode/tools/worklane.ts`, which meant it existed only inside a checkout, and it is now `assets/TOOL.ts` and shipped like every other asset
- **`install-skill` writes every shipped document, and the name narrows it.** One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog
- **`--print` requires the name.** It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the `comment --` body makes
- The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what
- **A refused document does not stop the ones behind it.** The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written
- **A role skill is its own document, not a section of `SKILL.md`.** The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read the `worklane` skill too
- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding)
- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
### Color and Output
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
@@ -168,6 +413,16 @@ and this file is for what someone changing worklane's own code needs.
- Title → green (32)
- 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
- 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
- Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a `TAG_COLORS` slot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
- **The index is multiply-shift, not `% TAG_COLORS.len()`.** The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2, `bug` and `BUG` among them, landed in one slot regardless of the rest of the string. It looked like a *good* palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash
- Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board
- 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
@@ -182,11 +437,14 @@ and this file is for what someone changing worklane's own code needs.
### Ticket Resolution
- `resolve_ticket()` returns `(status, title, content)` tuple
- Three tiers, evaluated in order: UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the three reported an exact prefix match as ambiguous against whichever title mentioned it
- Four tiers, evaluated in order: exact codename > UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the tiers reported an exact prefix match as ambiguous against whichever title mentioned it
- The codename tier is a campaign's, and empty for a ticket, which has no such field. Case insensitive like the other three, so a codename typed back off a listing resolves whatever case it was read in. See Campaigns for why it sits above the uuid prefix
- The UUID tier applies from `MIN_ID_SEARCH` (4) characters up. Not 8: `ls` prints `SHORT_ID_WIDTH` (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so `show 641` is a title search
- The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
- Ambiguous matches (multiple results) print options and exit(1)
- Never return empty strings for required fields — use `_Not set_` or `_None_` as defaults
- Never return empty strings for required fields — use the `NOT_SET` and `NONE` constants in `util.rs`, which are what `add` writes and what `--clear` puts back. `is_unknown_value` reads those two and nothing else
- **`-None-` and `-Not set-` are not unset, and re-adding them would be a mistake with a plausible story behind it.** They were accepted by `is_unknown_value` from the day it was written, by analogy with the `**-Status**` field name the `mv` splicing bug really did produce, c230d2c. But no version of this tool ever wrote a hyphenated *value*: `git log -S` finds both spellings in exactly one commit, the one that added them to the check. Dead from birth, and dropped by bdddc09. `a_hyphenated_marker_is_not_unset` is what stops the analogy being drawn a second time
- **The `**-Status**` repair in `is_status_line` is the opposite case and stays.** That corruption was real, `mv` wrote it, and the repair is what fixes a damaged ticket as it moves. Do not tidy the two away together on the grounds that they look alike
### Git Workflow
- Commit format: `([ticketID]) [short description]`
@@ -197,6 +455,8 @@ and this file is for what someone changing worklane's own code needs.
- Before every commit, decide whether the change warrants a version bump in `Cargo.toml`
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
- **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
- **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
- No bump for docs-only, tests-only or `--fixup` commits
- When one body of work spans several commits, bump once on the final commit rather than on each
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
Generated
+11 -1
View File
@@ -208,6 +208,15 @@ dependencies = [
"strsim",
]
[[package]]
name = "clap_complete"
version = "4.6.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3be2ad0423bdbbb0e25bc89add796f3559706d4a95e1bc98e4d9662a957b6a19"
dependencies = [
"clap",
]
[[package]]
name = "clap_derive"
version = "4.6.1"
@@ -1494,13 +1503,14 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.11.0"
version = "0.27.1"
dependencies = [
"anyhow",
"assert_cmd",
"assert_fs",
"chrono",
"clap",
"clap_complete",
"crossterm",
"libc",
"ratatui",
+2 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.11.0"
version = "0.27.1"
edition = "2024"
[dependencies]
@@ -14,6 +14,7 @@ libc = "0.2"
# widget until one of us changed.
ratatui = { version = "0.29", features = ["unstable-rendered-line-info"] }
crossterm = "0.28"
clap_complete = "4.6.9"
[dev-dependencies]
assert_cmd = "2"
+51 -10
View File
@@ -5,27 +5,68 @@ 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, `q` to quit. 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` 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 add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>` |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring |
| `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 |
| `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 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 check <ticket> [criterion]` | Ticks one acceptance criterion, by number as shown by `show` or by a substring. Prompts with the numbered list if omitted, or errors with it when there is no terminal |
| `worklane uncheck <ticket> [criterion]` | Unticks one acceptance criterion, addressed the same way |
| `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 check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
| `worklane install-skill` | Writes the embedded agent skill to `~/.claude/skills/worklane/SKILL.md`, which Claude Code and opencode both read. Leaves a modified copy alone unless `--force`; `--print` writes it to stdout instead |
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
## Completions
```sh
worklane completions fish > ~/.config/fish/completions/worklane.fish
```
Also `bash`, `zsh`, `elvish` and `powershell`, though only fish gets the dynamic half.
The structure comes from clap, so new flags appear without anyone remembering to add them. The four
statuses come with it, because a status is a value enum rather than a string. On top of that, fish
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 chown alice <TAB> the ticket, which is the second argument here
worklane chown --clear <TAB> the ticket, which the flag carries here
worklane relate x --blocked-by <TAB>
worklane campaign show <TAB> the campaigns, from `campaign ls --ids`
worklane assign <TAB> the same, since a campaign comes first here
worklane ls --campaign <TAB> and again
worklane ls --tag <TAB> the tags, from `worklane tags`, with their counts
```
The tickets come from `worklane ls --ids`, the campaigns from `worklane campaign ls --ids` and the tags
from `worklane tags`, one run per keypress, 2.5ms in release on a board of seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the
installed binary to be current**: an older one without `--ids` completes nothing. Re-run
`cargo install --path .` after pulling.
`tui` is the one command whose argument is a path, so it is the one place fish still offers
directories.
## Exit codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | An error, such as no matching ticket or an ambiguous search |
| 2 | A usage mistake, such as an unknown flag |
| 2 | A usage mistake, such as an unknown flag, an unreal `--due` date, a priority out of range or a status that is not one of the four |
| 141 | Output was piped to a reader that stopped early, for example `worklane ls \| head -3` |
141 is 128 + 13, the shell's way of reporting death by `SIGPIPE`. Worklane restores
+323
View File
@@ -0,0 +1,323 @@
---
name: worklane-admin
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
---
# Administering a worklane board
For "set up a board for this", "what tags should this board have", "add a tag", "what
does this tag mean", "the board is in a weird state", "this ticket has gone missing".
The subject is the board itself: the vocabulary it files against, and the parts that can
come apart.
The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command
owns which field. Read it too.
**This is not `worklane-plan`.** That skill grooms the work: priorities, due dates,
retagging tickets, campaigns. This one decides what the tags *are* and puts the board
back together. The line between them is the tag section: designing and annotating the
vocabulary is here, applying it across tickets is there.
## A board is not only for software
Everything below holds for a board tracking a product strategy, a house move or a term's
teaching, and the worked examples say so. What changes between domains is the tags, never
the shape. Nothing in worklane knows what your tickets are about.
Two things you do not get to configure, whatever the board is for:
- **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one
step at a time. There is no way to rename them or add a fifth. If a board wants a
waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`.
- **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a
concept these do not cover expresses it as a tag or a campaign, not as a new field.
So the tag vocabulary is where a board is fitted to its subject, and it is most of this
document.
## Starting a board
```
worklane init # in the directory the board belongs to
```
Which directory decides which board. Commands walk up from the working directory to the
nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere
under `~/house` and nowhere else.
`init` makes the four status directories, the campaigns directory and an empty `tags.md`.
Run on a board that already exists it prints a line and changes nothing, which is what
makes it safe to run when you are not sure.
Then declare the vocabulary before the tickets pile up. Tags applied for months are far
harder to change than tags agreed once, because changing one means rewriting every ticket
carrying it.
## Designing a tag vocabulary
A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag
kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it
allows are cuts anyone wants.
### Work in axes
An axis is one question every ticket on this board can answer, with a small closed set of
answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes
bad is one where two axes were mixed into one pile of words.
A software tool:
| Axis | Answers |
|---|---|
| Kind | `feature`, `bug`, `chore`, `docs` |
| Area | `cli`, `tui`, `api`, `build` |
A product strategy:
| Axis | Answers |
|---|---|
| Kind | `research`, `decision`, `experiment`, `writeup` |
| Audience | `enterprise`, `self-serve`, `internal` |
A household:
| Axis | Answers |
|---|---|
| Kind | `repair`, `errand`, `admin`, `cleaning` |
| Room | `kitchen`, `garden`, `garage`, `car` |
Same shape, nothing in common. Derive the axes from the questions somebody will actually
ask this board, not from a template: if nobody will ever ask "show me everything in the
garage", `garage` is not earning its place.
### The rules
- **A tag is for kind, not for state.** State is the status directory. A `doing` tag
beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all:
each is a second copy of something the board already knows, and the copy is the one that
goes stale.
- **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a
description and a state derived from its members. `worklane campaign` owns that;
`worklane-plan` decides what belongs in one.
- **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august`
beside Due. The field is the writer and the tag will disagree with it.
- **A tag is not a person.** Owner is a field, and `chown` writes it.
- **Two axes, not two words for one thing.** Before adding a word, say which axis it is
on. If it does not fit one, either it is a new axis, which is a decision, or it is a
private note, which is not a tag.
- **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so
they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat
a long tail nobody can recall.
- **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are
the commonest way a board ends up with two words for one idea.
- **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour
a card is drawn in. Lowercase everything unless there is a reason.
### How many tags per ticket
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants
three areas is usually two tickets, and a ticket with no tag at all is invisible to every
question asked by tag.
## Annotating a tag
```
worklane tags # every tag, its count and what it means
worklane tags add kitchen --annotation "..." # declare one, and say what it means
worklane tags set kitchen --annotation "..." # change what it means
```
`.worklane/tags.md` holds one section per declared tag, the tag as the heading and its
annotation under it. It is what a person opens to find out what the board means by a word,
and it is what an agent reads before choosing one.
**Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are
separate on purpose: the counts come from what the tickets carry, `tags.md` records what
the board agreed on, and the difference between them is the thing worth looking at. A tag
carried by tickets but never declared is a word somebody invented in a hurry.
`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's
opening line for a tag that is declared. So the two cases worth finding read off the
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
no annotation column at all is carried and was never declared.
### What an annotation has to say
The definition is the easy half and does the least work. What stops drift is the boundary
against the neighbouring tag, so write that.
Worthless, because nobody was ever unsure of this:
```
worklane tags add bug --annotation "Bugs."
```
Useful, because it answers the question somebody was actually about to get wrong:
```
worklane tags add bug \
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
--annotation "" \
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
```
The same for a household board:
```
worklane tags add repair \
--annotation "Something that worked and now does not." \
--annotation "" \
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
```
Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three
lines is plenty: a definition, then the boundary.
Write an annotation for every tag, including the obvious ones. The obvious tags are the
ones two people quietly disagree about.
### Traps
- `tags add` refuses a tag that is already declared, and `tags set` refuses one that is
not. Each names the other, so the refusal tells you which you wanted.
- A tag cannot contain a comma, because a comma is what separates one tag from the next in
the Tags field. Surrounding spaces are trimmed.
- A tag you have declared and never applied lists at a count of zero. That is not a fault;
it is the file and the board disagreeing, which is the state that tells you the
vocabulary has not landed yet.
- Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays
in the file with whatever its annotation says. Say it is retired in the annotation.
## Changing the vocabulary later
### Renaming a tag
There is no rename. The tag is the key, so it means rewriting the Tags field of every
ticket carrying it, one at a time:
```
worklane ls --tag bugs --ids # every ticket carrying the old word
worklane show 1b78a24 # read the whole Tags field of each
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
worklane tags add bug --annotation "..."
```
**`--tags` replaces the whole field.** Restate every tag the ticket should keep or the
ones you leave out are gone, with no undo. This is the most destructive command on the
board. Read the ticket's current tags before writing, never from memory, and run
`worklane tags` before and after: a count that moved where nothing was meant to change is
a tag lost to that rule.
Propose the whole list of edits and wait for approval before applying any of them, the way
`worklane-plan` requires for a sweep. The reason is the same: nothing records what a field
held before you wrote to it.
### Retiring a tag
Take it off the tickets the same way, then leave the declaration saying it is retired and
what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a
better answer than a word that simply vanishes, because the next person will otherwise
reinvent it.
## Repairing a board
Every repair here has been run against a real board. Work by symptom.
**The rule that does not bend: do not edit a ticket file.** The filename, the `Status`
field and the directory have to agree, and the commands are what keep them agreeing. The
two exceptions below are files no command owns, and they are marked as such.
### A ticket has vanished from `ls`
`worklane ls` leaves `done` out of its listing, though it still counts it at the top. So
first check `worklane ls done`. If it is there and should not be, its file has been moved
into the wrong directory by hand or by a restore.
The repair is two moves, not one:
```
worklane mv 1b78a24 --status reviewing -f
worklane mv 1b78a24 --status done -f
```
`mv` reads the current status from the *directory*, so moving it to the status the
directory already says it is in is refused as a no-op and the field stays wrong. Moving it
away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line
is read from the file rather than from where it sits.
### A command says the id matches several tickets
```
Multiple tickets found matching 'bf2dc18':
1. (bf2dc18) Alpha [backlog]
2. (bf2dc18) Alpha [done]
```
The same file exists in two status directories, usually from a copy or a half-finished
restore. The ticket is now unaddressable: every command resolves before it acts, so `show`
and `mv` fail the same way and cannot be used to fix it.
**File exception.** Read both with `cat`, keep the one whose `Status` field agrees with
the directory it is in, and delete the other. If neither agrees, keep either and repair it
as above. Then confirm with `worklane show`.
### A move is refused by a blocker
```
Cannot move 'Beta' while it is blocked by:
...
Use --force (-f) to move it anyway.
```
Working as intended: a ticket cannot advance while something it waits on is unfinished.
Finish the blocker, or use `-f` if the dependency is no longer real. Note that the
relation stays on the ticket and will refuse the next move too, and there is no way to
take a relation off, so `-f` is the answer every time until the blocker is done.
If the message says `is blocked by X, which is not on the board`, the blocker has been
deleted. That is a warning rather than a refusal and the move goes through.
### `show` renders `_missing_`
A relation or a Campaign field naming something the board no longer holds. Harmless to
read and impossible to clear, since `relate` only adds and `assign` only moves a ticket
between campaigns that exist. For a campaign, `worklane assign <a-real-campaign> <ticket>`
overwrites it. For a relation, leave it.
### A status is missing from `worklane ls`
The count list at the top of `ls` names every status directory it found, so a status that
is absent from it has had its directory deleted. Nothing errors until something tries to
move a ticket there, which then fails with a raw file error.
**File exception.** `worklane init` will not repair it, since it refuses on a board that
already exists. Recreate the directory:
```
mkdir .worklane/reviewing
```
### A `.wl-*.tmp` file in `.worklane/`
The staging file for a write that was killed part way. Every write stages here and renames
into place, so a leftover means the write did not finish; nothing reads these and no
listing shows them.
**File exception.** Delete it. Then check the ticket it names with `worklane show` and
redo whatever the interrupted command was.
### Nothing works and the error names `.worklane`
Check where you are. Commands resolve the nearest `.worklane` at or above the working
directory, so running from the wrong directory addresses another board or none. `worklane
ls` from where you think the board is, is the fastest way to find out.
## What this skill does not touch
- **Priorities, due dates, campaign membership and retagging sweeps.** That is
`worklane-plan`. Deciding the vocabulary is here; applying it across the board is there.
- **Filing a ticket, working one, moving it through the statuses.** That is the `worklane`
skill.
- **Judging whether a finished ticket is really done.** That is `worklane-review`.
- **The content of a ticket.** A description or an acceptance criterion that is wrong is
the author's, and the answer is a comment on that ticket.
+222
View File
@@ -0,0 +1,222 @@
---
name: worklane-plan
description: Groom a worklane board as a whole rather than one ticket at a time: review whether the priorities are right relative to each other, plan work by setting due dates, check the tags for consistency, and find the tickets that belong together in a campaign. Use for questions about the backlog as a body of work, what to do next week, what is mis-prioritised or mis-tagged, and what could become one goal. Not for filing or working a single ticket.
---
# Planning a worklane board
For "are the backlog priorities right", "plan in tickets for next week", "check the
tagging", "which of these could be one campaign". The subject is the board, not a
ticket. Filing one, working one and reviewing one are other jobs.
The CLI itself is the `worklane` skill: the statuses, how a ticket is addressed and
which command owns which field. Read it too. This document is the judgement.
## The one rule
**Propose the whole set of edits, wait, then apply exactly what was approved.**
Every job here writes to many tickets at once, and nothing on the board records what a
field held before you wrote to it. `--clear` puts a field back to unset, which is **not
back to what it held**, so a date written over another date is gone. A wrong edit to one
ticket is a mistake; a wrong sweep is thirty of them with no undo. So a proposal is a
list, one line per intended edit, each naming the ticket and the command that would make
it:
```
(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1
(4179958) due -> 2026-08-29 worklane set 4179958 --due 2026-08-29
```
Then apply what was approved and nothing else. Not "and a few obvious ones while I was
there": an approval is for the list that was shown.
## Who writes what
Every field has exactly one command that writes it, and a sweep that reaches for any
other way is editing the file by hand:
| Field | Writer |
|-------|--------|
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags`, and `--clear <field>` to empty one |
| Relations | `worklane relate <ticket> --blocked-by` / `--regression-of` / `--relates-to` |
| Campaign membership | `worklane assign <campaign> <ticket>` |
| Owner | `worklane chown <user> <ticket>`, and `worklane chown --clear <ticket>` to empty it |
| Status | `worklane mv <ticket> --status <target>` |
**Never edit a ticket file directly.** The filename, the `Status` field and the directory
have to agree, and the commands are what keep them agreeing. A hand-written Relations
line is worse still: it is the one section read back by machine, and a target that does
not resolve to a uuid is an error on every later read of that ticket.
The last two rows are in the table to be recognised, not used. See the closing section.
## Read the board first
```
worklane ls # every status, counts then tickets
worklane ls backlog # one status
worklane ls --priority 1 # the top of the pile
worklane ls --tag bug # one tag's worth of the board
worklane tags # the whole vocabulary, with counts
worklane show 1b78a24 # one ticket, with its relations and comments
worklane campaign ls # the goals that already exist
```
`ls` prints the mark, the id, the title, the owner and the due date, and **not** the tags.
So the vocabulary comes from `worklane tags`, which is the one command that answers what
tags exist rather than what carries a tag you already know. One line per tag, alphabetical,
as the tag, a tab and its count. It is case sensitive like the filter, so `bug` and `Bug`
list separately and, being alphabetical, land next to each other, which is where a
near-duplicate is spotted. Start a tag sweep there rather than with a `show` per ticket.
Read `done` too when the question is about what to do next. What was finished last is the
best evidence of what this board actually moves at, and a plan that ignores it is a wish.
## Priorities
Priority runs **1 most urgent to 5 least**, and may be unset. `worklane set <ticket>
--priority <n>` is the only writer.
Priority is relative. A ticket is never urgent by itself, it is urgent above something
else, so every proposed change has to name what it now sits above and below. "This looks
important" is not a reason; "this blocks three tickets that are all dated before it" is.
What to look for:
- **A blocker priced below what it blocks.** Read the Relations. A ticket that others are
`blocked by` cannot be less urgent than the most urgent of them, or the board is asking
for work in an order it will not allow.
- **A flat board.** If almost everything is 3, the field is carrying no information and
the answer is not to renumber everything at once. Propose the few that are genuinely 1
and the few that are genuinely 5, and leave the middle alone.
- **Too many 1s.** If everything is urgent, nothing is. Say how many there are before
proposing another.
- **A low priority already in `committed`.** Either the priority is wrong or starting it
was, and which one it is decides whether the fix is a `set` or a conversation.
- **A priority nobody has touched since the ticket was filed.** It is the filer's first
guess, not a decision. That is the pile worth reading.
## Due dates
`worklane set <ticket> --due 2026-08-29`, format `YYYY-MM-DD`.
A value that is not a real calendar date in that exact form is refused before anything
is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of
the format. A date can be taken off again with `worklane set <ticket> --clear due`. What
that cannot do is recover the date that was there before it, so a plan applied over
existing dates still has no undo.
Ask the system what today is rather than assuming it. A plan built on a guessed date is
wrong by however much the guess was wrong.
The rules a dating plan has to keep:
- **Nothing is dated before the ticket it is blocked by.** Read the Relations first and
date blockers ahead of their dependents. A dependent dated before its blocker is a date
`mv` will refuse to honour anyway.
- **A blocker left undated makes its dependent's date a fiction.** Either date both or
neither.
- **Date what fits, not what exists.** Ask how much capacity the week holds, or take the
answer from what `done` shows the board finishing in a comparable stretch. Dating the
whole backlog produces a board where every ticket is late, which is the same as no
dates at all.
- **Do not date `done`.** It is finished; a date on it is noise in every listing.
- Leave the rest unset. An unset due date is honest about what has not been planned, and
a date that turned out to be wrong is better cleared than left to read as a plan.
## Tags
`worklane set <ticket> --tags bug,cli` is the writer, and it **replaces the whole
field**. Restate every tag the ticket should keep, or the ones you left out are gone.
This is the single most destructive thing in this document. `--clear tags` empties the
field on purpose, which is a different thing from emptying it by forgetting a tag.
`worklane tags` before and after a tag sweep is the cheapest check that it did what was
proposed: a count that dropped where nothing was meant to change is a tag lost to the
replace-the-whole-field rule above.
**Designing the vocabulary is the `worklane-admin` skill, not this one.** What the tags
should be, what each one means, how one is declared with `worklane tags add` and annotated
so the next person picks the same word: read that document before proposing a vocabulary,
and read `.worklane/tags.md` before proposing a tag. This section is the sweep over
tickets already tagged, which is a different job. A board whose tags are declared has an
annotation per tag, and a ticket that contradicts one is mis-tagged against a written
standard rather than against your reading of the board.
Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count
what is actually used, and show the count before proposing anything. What to report:
- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already
used more and say so.
- **A tag used exactly once.** Either it is the start of a category and should be applied
to its siblings, or it is a private note and should go. Do not leave it as it is without
saying which.
- **A tag that restates a field.** A `p1` tag beside a Priority field, an `open` tag
beside a Status, an owner's name as a tag. The field is the writer; the tag is a copy
that will disagree with it. This board already made that mistake once with priority and
undid it deliberately.
- **An untagged ticket** in a board where everything else is tagged. It is invisible to
every question asked by tag, `worklane ls --tag` included.
Tags are for kind, not for state and not for goal. State is the status directory and the
fields; a goal is a campaign.
## Campaigns
```
worklane campaign ls
worklane campaign show v1
worklane campaign add --title "..." --codename v1 --description "..."
worklane campaign set v1 --title "..." # or --description or --codename, on one already filed
worklane campaign append v1 -d "..." # add a paragraph to the description
worklane assign v1 1b78a24
```
A campaign is the tickets that have to be finished **together** for one outcome. The test
is whether you can name the outcome in a single line without listing the members. "The
tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
- **Do not group by tag.** Ten tickets tagged `bug` share a kind, not a goal, and putting
them in a container says nothing that the tag did not already say.
- **Check what exists first.** `campaign ls` before proposing a new one, or you will
propose a second container for a goal that already has one.
- **A ticket is in at most one campaign**, and `assign` moves it rather than adding a
second. So two proposed campaigns that overlap are really one proposal to take members
out of the other, and it has to say so.
- **A campaign's state is derived**, open until every member is done. There is nothing to
close and nothing to move. A campaign whose members are all done is finished already.
- `assign` takes the **campaign first and the ticket second**, like `chown`.
- **Propose a codename with the campaign**, one word, `v1` or `beaver`. It is what the
board draws on every card in it and the shortest thing that addresses it at the command
line, and a campaign filed without one is drawn by its short id, which says nothing. A
campaign already on the board that has no codename is worth pointing out for the same
reason a near-duplicate tag is, and `campaign set` is how it gets one without refiling.
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
called on every card in it and at the command line, so changing it is churn dressed as
grooming. `campaign set` refuses it without `--force` for that reason.
- **A campaign's description is editable, so a wrong one is a fix rather than a refiling.**
A container whose description no longer describes what its members are for is worth
pointing out: it is the line every one of those tickets was filed against. `campaign set
--description` replaces it and `campaign append --description` adds to it, so neither
needs the campaign refiled and its members reassigned. Adding to it is the usual answer;
replacing prose to add a sentence to it is how the rest of it gets lost.
Proposing a campaign means naming the goal, the members, and what is deliberately left
out of it. The last part is what makes it a goal rather than a pile.
## What a planner does not touch
- **Descriptions, acceptance criteria and implementation plans.** They are the ticket
author's account of the work, and grooming is about how the work is ordered, not what
it is. Something wrong in there is a comment on that ticket.
- **Status.** `mv` belongs to whoever does the work. A plan that moves tickets between
columns is reporting progress that did not happen.
- **Owner.** `chown` records a commitment a person made. Propose it, do not write it,
unless you were asked to assign the work.
- **The tag vocabulary itself, and the state of the board's own files.** Declaring a tag,
writing what it means, retiring one, or repairing a ticket whose file and fields have
come apart: all `worklane-admin`. A sweep applies the vocabulary, it does not decide it.
- **New tickets.** Grooming is about what is on the board. Something genuinely missing is
worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather
than folding it into a grooming sweep.
+162
View File
@@ -0,0 +1,162 @@
---
name: worklane-review
description: Review a finished worklane ticket against the code that claims to close it, and record the verdict on the board. Use when asked to review a ticket, to check whether a ticket is really done, or to verify that an implementation matches its acceptance criteria, whether the ticket is named by id, by title or as "the one in reviewing". Covers finding the commits, judging each criterion against the code, and what a reviewer may and may not write back to the board.
---
# Reviewing a worklane ticket
For "review ticket 1b78a24", "is 4179958 actually done", "check the work on the tui
scroll ticket". The subject is one ticket. Reviewing a diff that no ticket claims is
ordinary code review and not this job.
This document is the review only. The CLI itself, the statuses, how a ticket is
addressed and the argument traps, is the `worklane` skill; read that too.
## What a review produces
Three things, in this order, and nothing else:
1. **One comment** on the ticket, in the structure below.
2. **Unticked criteria**, for the ones the code does not actually meet.
3. **Appended criteria**, for work the review found that the ticket never asked for.
You do not tick a criterion, you do not move the ticket, and you do not fix the code.
Each of those has a reason, given where it comes up.
## 1. Read the ticket before the code
```
worklane show 1b78a24
```
All of it, comments included. The description says what was wrong, the criteria say what
"done" was supposed to mean, the plan says what someone intended to do about it, and the
comments are where the intent moved after filing. A criterion that contradicts a comment
is one of the more useful things you can find: it means the ticket was not updated when
the plan changed, and one of the two is now lying to whoever reads the board.
Read the Relations too. A `blocked by` that is not done, or a `regression of`, changes
what the change was allowed to do and what the review has to check twice.
## 2. Find the work
The board stores no branch and no sha, so the link from ticket to code has to be found.
Check the repo's own commit convention first, in its `AGENTS.md`, `CLAUDE.md` or in
`git log`, rather than assuming the id appears in the message at all.
```
git log --all --oneline --grep 1b78a24 # where commits name the ticket
git log --oneline -20 # where they do not, read the recent ones
git branch -a --list '*scroll*' # a branch named after the work
git diff main...HEAD # the whole change, once you have both ends
```
Widen it with the files the description names, since a ticket that names
`src/tui.rs` is reviewable through `git log -p -- src/tui.rs` even when no commit
message mentions it.
**If nothing names the ticket, that is the finding.** Do not review the working tree on
the assumption that whatever is uncommitted must be the work, and do not report a pass
you could not check. Comment what you searched for and stop: a ticket sitting in
`reviewing` with no traceable work is exactly what a reviewer is for.
## 3. Judge each criterion separately
One criterion at a time, by its number from `show`, and each against **the code**. Never
against the implementation plan: the plan is what someone meant to do, and a review that
confirms the plan was followed cannot notice that following it was not enough.
Read the code the criterion is about, not only the lines the diff touched. A criterion
that the diff satisfies and the surrounding code defeats is not met.
Give each one a verdict and its evidence, a file and a line:
- **met** - and where.
- **not met** - and what is missing.
- **cannot tell** - and what would settle it. This is a real verdict. Use it instead of
guessing, and say what you would have to run or read.
Run whatever the repo runs, its test suite and its linter. A suite that fails is not a
criterion, but no criterion is met while it fails.
Then the two questions the criteria cannot ask themselves:
- **What did this change break that no criterion covers?** Silent behaviour changes,
a message or exit code something else reads, an edge case the ticket never named.
- **What did the ticket never think of?** That is what you append in step 5.
## 4. Write one comment
One call, one comment. Not one per criterion: the board renders comments in the order
they were written, and a review split over eight of them cannot be read as a verdict.
```
worklane comment 1b78a24 "**Verdict**: two criteria unmet, the scroll clamp is off by the header
**Work reviewed**: 4edc7fa, 6d327df on master
**Criteria**
1. met - PageUp and PageDown reach detail_scroll, src/tui.rs:412
2. not met - the footer still lists the arrow keys, src/tui.rs:88
3. cannot tell - no test covers a ticket longer than the viewport
**Findings**
- The clamp uses the raw line count, so a wrapped ticket scrolls past its end, src/tui.rs:430
- Unticked criterion 2 accordingly
**Recommendation**: back to committed, the clamp is the ticket's own subject"
```
Keep the structure, drop the sections that have nothing in them. `**Work reviewed**` is
never empty: it holds the shas, the branch, or what you searched for and did not find.
Write for the person who has to act on it, so every finding says where it is.
The comment body takes a leading hyphen without being parsed as a flag, so a finding can
quote `--force` literally. A body of exactly `--` needs its own separator.
## 5. Write the verdict back to the ticket
```
worklane uncheck 1b78a24 2 5
worklane append 1b78a24 --acceptance "The footer lists only the keys that are bound"
```
Untick every criterion you found unmet, by the numbers `show` printed, in one call. Do
it after the comment so there is a written reason on the board before the mark changes.
Do not reach for `all`: a review unticks what it found unmet, and unticking the lot would
erase the implementer's claim on the criteria you agreed with.
**Never tick a criterion.** A tick is the implementer's claim that something is done, and
unticking is the review disagreeing with that claim. A reviewer that also ticks makes
both the same mark, and the board stops recording that anyone ever disagreed. A criterion
you found met but left unticked is a line in the comment, not a mark for you to fix.
Append a criterion only for work the next commit has to make true, phrased so it can be
ticked off. Advice, praise and anything already covered by an existing criterion belong in
the comment. An appended criterion that restates a finding just makes the ticket longer
without making it clearer.
**Do not move the ticket.** `mv` belongs to whoever does the work, the same way ticking
does. Your half is the recommendation in the comment; acting on it is theirs. A reviewer
that reviews and closes in one breath leaves nobody to disagree with.
## What a reviewer does not touch
- **The description, plan, title, priority and tags.** Rewriting the ticket you are
reviewing destroys the record of what was asked for, which is the only thing your
verdict can be measured against. Say it in the comment.
- **The code.** Even a one-line fix is a finding: whoever wrote it gets to make the
change, and gets to keep the review that asked for it. Fix it only if you are asked to,
and then it is a new piece of work with its own comment.
- **Another ticket's business.** Something you found that is genuinely out of scope gets
its own ticket, filed the way the `worklane` skill says, and
`worklane relate <new> --relates-to <this>` so the two are findable from each other.
## Reviewing what is waiting
```
worklane ls reviewing
```
One ticket at a time, with its own comment. A single comment covering four tickets lands
on one of them and is lost to the other three.
+148 -11
View File
@@ -35,32 +35,70 @@ 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.
## Reading the board
```
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
```
`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
when you want the ids themselves: `worklane ls --ids | cut -f1`. The decorated listing is
for reading, not for cutting up.
The filters compose in any combination, with each other and with the status positional:
`worklane ls backlog --tag bug --priority 1`. `--tag` takes one tag and matches it
against the whole values of the comma-separated `Tags` field, case sensitively, so
`--tag bug` finds neither a ticket tagged `bugfix` nor one tagged `Bug`. A ticket with no
tags matches none. A tag nothing carries lists nothing rather than failing, so when a
listing comes back empty check the spelling against a ticket you know is tagged.
`worklane tags` answers the other question, the one `--tag` cannot: **what tags exist**.
One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case
sensitive, like the filter, so `bug` and `Bug` list separately and land next to each
other, which is where a near-duplicate is spotted. Read it before inventing a tag, and
read it when a `--tag` filter comes back emptier than expected.
## Working a ticket
```
worklane mv 1b78a24 --status committed
worklane check 1b78a24 3 # tick acceptance criterion 3
worklane check 1b78a24 "the footer describes" # or a substring of it
worklane check 1b78a24 1 3 "the footer" # several in one call
worklane check 1b78a24 all # every criterion on the ticket
worklane uncheck 1b78a24 3
worklane comment 1b78a24 "Found the cause: the offset was never passed to the widget."
worklane mv 1b78a24 --status reviewing
```
Criteria are numbered by `show`. With the criterion omitted, `check` prompts when there
is a terminal and otherwise fails with the numbered list, so **always pass the criterion
Criteria are numbered by `show`. With no criterion given, `check` prompts when there
is a terminal and otherwise fails with the numbered list, so **always pass the criteria
when you are not sitting at a prompt**.
One call takes as many terms as you like, mixing numbers and substrings, and `all` stands
for every criterion on the ticket. Use it when the work is done: it is one write instead
of one per box. `all` is a keyword, checked before the text, so a criterion whose own
words include "all" is reached by its number or by a longer substring.
**Every term is resolved before anything is written.** One term that matches nothing, or
matches more than one criterion, refuses the whole call and names that term, so the ticket
is never left half-marked. A criterion already in the state you asked for is reported
unchanged rather than refused, and a call that would change nothing writes nothing. Both
apply to `uncheck` exactly as they do to `check`.
## Filing a ticket
```
@@ -85,28 +123,44 @@ worklane add \
checked off as true or false.
- **`--plan`** takes one step per flag, numbered for you.
- **`--priority`** runs 1 (most urgent) to 5 (least), and is left unset if omitted.
- **`--due`** takes `YYYY-MM-DD` and nothing else. Anything that is not a real calendar
date in that exact form, `2026-8-9` and `2026-02-30` included, is a usage error with
nothing written. The same parser guards `set --due`.
Editing afterwards, on a ticket in any status:
```
worklane set 1b78a24 --priority 1 # replace a field
worklane set 1b78a24 --priority 1 # replace a field
worklane set 1b78a24 --title "A better title" # renames the file, keeps the uuid
worklane set 1b78a24 --clear due # take a value away again
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
worklane append 1b78a24 --acceptance "One more criterion"
worklane append 1b78a24 --description "What was learned since."
worklane chown alice 1b78a24 # hand the ticket to someone
worklane chown --clear 1b78a24 # hand it back to nobody
```
`set` replaces, `append` adds. Neither has `--owner` or `--status`: owner is `chown`'s
and status is `mv`'s, so each field has exactly one writer. A field set to the value it
already holds is reported unchanged and nothing is written.
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` has
`--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each field has
exactly one writer. A field set to the value it already holds is reported unchanged and
nothing is written, and so is a field cleared that was already unset.
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
writes for a field it was never given: `_Not set_`, `_None_` for tags, and the section
placeholder. There is no `--clear title`, because a title addresses the ticket and names
its file. There is no `--clear owner` either: that is `chown --clear <ticket>`, which
takes the ticket in the flag since there is no user to give, and returns the field to
unset rather than to the git user. Replacing and clearing the same field in one call is
refused rather than resolved.
`chown` takes the **user first and the ticket second**, after Unix `chown`, which is the
one command here that does not start with the ticket. The user is free text and is
checked against nothing. Swap the two and the call fails, because the username has to
resolve as a ticket.
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
`worklane init` creates `.worklane/` with the four status directories, for a repo that
has no board yet.
`worklane init` creates `.worklane/` with the four status directories and the campaigns
directory beside them, for a repo that has no board yet.
## Relating tickets
@@ -130,6 +184,78 @@ Recording a relation the ticket already holds reports no change. A ticket cannot
to itself, and a target that later disappears shows as `_missing_` rather than silently
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
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.
## Campaigns
A campaign groups the tickets that have to be finished together: a release, a migration,
anything whose parts are separate tickets but whose goal is one thing. It is a file of
its own under `.worklane/campaigns/`, with a title and a description, and it sits in no
status directory. Its state is derived instead, open until every member is done, so
there is no such thing as a done campaign holding an open ticket.
```
worklane campaign add --title "First public release" --codename v1 \
--description "Everything that has to ship before the tag."
worklane campaign ls # every campaign, its codename, how far it has got
worklane campaign ls --ids # id and title, tab separated, like ls --ids
worklane campaign show v1 # its body, then its members by status
worklane campaign set v1 --title "..." # replace the title, description or codename
worklane campaign append v1 -d "..." # add a paragraph to the description
worklane assign v1 1b78a24 # put a ticket in it
worklane ls --campaign v1 # only that campaign's tickets
```
**Give a campaign a `--codename`.** One word, `v1` or `beaver`. It is what the board
draws on every card in the campaign, because a uuid does not fit there and a title is a
sentence, and it is the shortest thing that addresses the campaign at the command line.
Optional: a campaign without one is drawn and listed by its short id instead, which
resolves but says nothing. `campaign set <campaign> --codename <word>` gives one to a
campaign that is already filed, which is what every campaign filed before the field
existed needs. **Replacing a codename it already has needs `--force`**: that word is how
the campaign is referred to on the board and at the command line, so changing it is a
decision rather than a correction. Setting the one it already has is a no-op either way.
`campaign set` and `campaign append` are the only ways to change a campaign after it is
filed. `set` replaces the title, the description or the codename; `append` adds a paragraph
to the description, which is what to use when the description is right and only incomplete,
since replacing prose to add a sentence to it is how the rest of it gets lost. An empty
`--description ""` between two values is a paragraph break, exactly as it is for a ticket,
and a call whose every value is blank is refused: a campaign's description cannot be
emptied. There is still no way to change a campaign's owner.
`append` here is `campaign append` and not the top-level `append`, which takes a ticket. The
two objects are addressed the same way, so the command is what says which one is meant.
`assign` takes the **campaign first and the ticket second**, like `chown`, and is the
only writer of the field. `add` has no `--campaign` and neither has `set`, so membership
has one writer the way owner and status do.
A ticket is in at most one campaign, so assigning one that already belongs somewhere
moves it rather than adding a second. Assigning it to the campaign it already names
reports no change and writes nothing.
`campaign show` lists done members too, unlike `ls`, which leaves the done column out of
its listing: a campaign is precisely the question of what is finished against what is
left.
A campaign is addressed the way a ticket is, by uuid prefix, title or filename, and by
its exact codename, which wins over all three. So `assign v1 1b78a24` reaches the
campaign codenamed `v1` even if another campaign's title contains `v1`. It is not a
ticket, though. Passing one where a ticket is expected is refused with a message saying
so, and there is no way to move a campaign, because it has no status to move.
## Search the backlog before filing
Run `worklane ls` in the directory the ticket would land in and look for the same issue,
@@ -144,6 +270,16 @@ 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.
## Shell completions
```
worklane completions fish > ~/.config/fish/completions/worklane.fish
```
For the person's shell, not for you, and `bash`, `zsh`, `elvish` and `powershell` are
there too. Only fish completes ticket ids, which it does by running `worklane ls --ids`,
so a stale binary on PATH completes nothing and the fix is to reinstall it.
## Addressing a ticket
Every command that takes a ticket accepts, in this order of precedence:
@@ -170,6 +306,7 @@ the candidates and exits 1 rather than guessing.
`worklane mv --status committed -- -leading-title`.
- A comment body of exactly `--` needs its own separator:
`worklane comment 1b78a24 -- --`.
- An empty value for a scalar is a usage error. Clearing a field back to unset is not
supported yet.
- An empty value for a scalar is a usage error, not a way to clear the field: use
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
the section either, and an all-blank one is refused with the `--clear` for it named.
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
+20 -10
View File
@@ -425,39 +425,49 @@ export const chown = tool({
/**
* check and uncheck differ only in the verb, so the tool is built once.
*
* The criterion is required here even though the CLI makes it optional: without it the
* CLI prompts, and there is no terminal on this side of the pipe. The CLI answers a
* The criteria are required here even though the CLI makes them optional: without any
* the CLI prompts, and there is no terminal on this side of the pipe. The CLI answers a
* missing criterion with the numbered list on stderr, which run() relays, so the model
* sees the options and can retry with a number.
*
* One value per line, like the other list arguments, and every value goes in one call.
* The CLI resolves them all before it writes, so a bad term costs nothing, and finishing
* a ticket is one tool call rather than one per box.
*/
function checkboxTool(verb: "check" | "uncheck") {
const past = verb === "check" ? "Checked" : "Unchecked";
return tool({
description:
`${past === "Checked" ? "Tick" : "Untick"} one acceptance criterion on a worklane ticket. ` +
"Every other criterion keeps its state. Identify the criterion by its number as shown by show, " +
"or by a substring of its text; a substring matching more than one is an error listing them.",
`${past === "Checked" ? "Tick" : "Untick"} acceptance criteria on a worklane ticket. ` +
"Every criterion not named keeps its state. Identify each one by its number as shown by show, " +
"or by a substring of its text; a substring matching more than one is an error listing them. " +
`Pass several, one per line, to ${verb} them in a single call, or the single word all for every ` +
"criterion on the ticket. If any value cannot be resolved the whole call is refused and nothing " +
"is written, so a partly wrong list never leaves the ticket half-marked.",
args: {
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
criterion: tool.schema
criteria: tool.schema
.string()
.describe(
"Criterion number as shown by show, or a substring of its text (required)",
"Criterion numbers as shown by show, or substrings of their text, one per line. " +
"Or the single word all for every criterion (required)",
),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
return `Error running ${verb}: ticket is required`;
}
if (!args.criterion) {
return `Error running ${verb}: criterion is required, give the number or a substring`;
const terms = args.criteria ? itemLines(String(args.criteria)) : [];
if (terms.length === 0) {
return `Error running ${verb}: criteria is required, give the numbers, substrings, or all`;
}
try {
return await run([verb, args.ticket, String(args.criterion)], context);
return await run([verb, args.ticket, ...terms], context);
} catch (err: any) {
return `Error running ${verb}: ${err.message}`;
}
+3 -3
View File
@@ -24,9 +24,9 @@ fn git_sha() -> String {
.output();
let sha = match output {
Ok(output) if output.status.success() => String::from_utf8_lossy(&output.stdout)
.trim()
.to_string(),
Ok(output) if output.status.success() => {
String::from_utf8_lossy(&output.stdout).trim().to_string()
}
_ => String::new(),
};
+22
View File
@@ -0,0 +1,22 @@
# rustfmt is the formatter for this tree, and these four widths are what make it agree
# with how the tree is already written. Measured, not chosen: the default config wanted
# 305 hunks and +1418 lines of layout, `use_small_heuristics = "Max"` wanted 308 the
# other way, and this lands at 161. The reasoning is in AGENTS.md beside the clippy rule.
#
# Sweeping any one of these in either direction makes the diff bigger. Measure before
# changing one: `cargo fmt --check | grep -c '^Diff in'`.
# The habit the tree is written to, and the measured optimum: 90 costs 268 hunks, 120
# costs 194.
max_width = 100
# A call stays whole if it fits in three quarters of the line. rustfmt's default of 60
# is what expands 276 of the 305 hunks the default config wants.
fn_call_width = 75
# The same for a method chain.
chain_width = 65
# A small struct literal stays whole, so `Size { width: 120, height: 20 }` is not six
# lines. Above the default of 18, which is what explodes it.
struct_lit_width = 30
+319
View File
@@ -0,0 +1,319 @@
//! Campaigns: the container for tickets that have to be finished together.
//!
//! A campaign is a file of its own under `.worklane/campaigns/`, holding a title, a
//! description and metadata. It has no status directory and never sits in one. Its
//! state is derived instead: open until every member is done. Deriving it means there
//! is no such thing as a done campaign holding an open ticket, and no second
//! forward-only ruleset to reason about beside `mv`'s.
//!
//! Membership is one field on the *member*, `Campaign` in the ticket Metadata, written
//! only by `assign`. The member list is deliberately not stored on the campaign: that
//! would put membership in two places, and would make one file that every assignment
//! edits, which is contended the moment two agents share a board.
use anyhow::{Result, anyhow};
use std::fs;
use std::path::{Path, PathBuf};
use crate::util::*;
/// Where campaigns live, beside the status directories rather than among them.
pub const CAMPAIGNS_DIR: &str = "campaigns";
pub fn campaigns_dir(worklane_dir: &Path) -> PathBuf {
worklane_dir.join(CAMPAIGNS_DIR)
}
/// The campaigns directory, created if the board predates it.
///
/// `init` writes it for a new board, but every board made before campaigns existed has
/// none, and refusing to file a campaign there would mean a `worklane init` over a live
/// board just to get a directory.
pub fn ensure_campaigns_dir(worklane_dir: &Path) -> Result<PathBuf> {
let dir = campaigns_dir(worklane_dir);
fs::create_dir_all(&dir).map_err(|e| anyhow!("Could not create {}: {}", dir.display(), e))?;
Ok(dir)
}
/// A campaign as it comes off disk.
pub struct Campaign {
pub uuid: String,
pub title: String,
/// The word the campaign is called by, or `None` for one filed without a codename.
///
/// Read here rather than parsed at each call site for the reason the title is: the
/// board draws it on every card that names this campaign, and the picker draws it on
/// every row, so it comes off the one read of the directory.
pub codename: Option<String>,
pub content: String,
}
/// The campaigns directory as [`resolve_in`] takes it.
///
/// The name is empty because a campaign has no status: it is what makes the ambiguity
/// listing print an id and a title with no bracket after it.
fn campaign_paths(worklane_dir: &Path) -> Vec<(String, PathBuf)> {
vec![(String::new(), campaigns_dir(worklane_dir))]
}
/// A campaign by the same three tiers a ticket resolves by, scoped to its own
/// directory.
///
/// The tiers are [`resolve_in`]'s, not a second copy: a campaign is addressed the way
/// everything else here is, and two resolvers would be two sets of precedence rules to
/// keep in step.
pub fn resolve_campaign(search: &str, worklane_dir: &Path) -> Result<Campaign> {
let mut matches = resolve_in(search, &campaign_paths(worklane_dir))?;
if matches.is_empty() {
return Err(anyhow!("No campaign found matching '{}'", search));
}
if matches.len() > 1 {
return Err(ambiguous("campaign", search, &matches));
}
let found = matches.remove(0);
let uuid = parse_ticket_field(&found.content, "ID");
if uuid.trim().is_empty() || is_unknown_value(&uuid) {
return Err(anyhow!(
"Campaign '{}' has no ID field, so nothing can be assigned to it",
found.title
));
}
Ok(Campaign {
codename: parse_codename(&found.content),
uuid,
title: found.title,
content: found.content,
})
}
/// The title of the campaign a search names, for a caller that only needs to say so.
///
/// Used by `resolve_ticket` to explain a search that names a campaign rather than a
/// ticket. Deliberately swallows both failures: nothing matched and too much matched
/// both mean "this is not the explanation", and an error here would replace a clear
/// "no ticket found" with a complaint about a directory the caller never mentioned.
pub fn campaign_named(search: &str, worklane_dir: &Path) -> Option<String> {
resolve_campaign(search, worklane_dir)
.ok()
.map(|campaign| campaign.title)
}
/// Every campaign on the board, read in one pass.
///
/// One pass for the same reason [`RelationIndex`] takes one: rendering a ticket's
/// Campaign field or listing the campaigns both need every one of them, and a lookup
/// per ticket would read the directory once per row.
///
/// `Default` is the empty index, which is what a board whose campaigns directory cannot be
/// read has: it still draws, with no campaign on any card. A *missing* directory is already
/// not an error, per [`CampaignIndex::load`]; this is for the unreadable one.
#[derive(Default)]
pub struct CampaignIndex {
campaigns: Vec<Campaign>,
}
impl CampaignIndex {
pub fn load(worklane_dir: &Path) -> Result<Self> {
let dir = campaigns_dir(worklane_dir);
let mut campaigns = Vec::new();
// A board with no campaigns directory has no campaigns, which is not an error:
// every board made before campaigns existed is in that state.
if !dir.exists() {
return Ok(Self { campaigns });
}
for entry in fs::read_dir(&dir)?.filter_map(|e| e.ok()) {
let path = entry.path();
if !path.extension().is_some_and(|e| e == "md") {
continue;
}
let Ok(content) = fs::read_to_string(&path) else {
continue;
};
campaigns.push(Campaign {
uuid: parse_ticket_field(&content, "ID"),
title: heading_title(&content),
codename: parse_codename(&content),
content,
});
}
// By title, so a listing does not depend on the order the directory hands its
// entries back in.
campaigns.sort_by_key(|campaign| campaign.title.to_lowercase());
Ok(Self { campaigns })
}
/// The campaign carrying `uuid`, or nothing when the board no longer has it.
pub fn get(&self, uuid: &str) -> Option<&Campaign> {
self.campaigns.iter().find(|campaign| campaign.uuid == uuid)
}
pub fn iter(&self) -> impl Iterator<Item = &Campaign> {
self.campaigns.iter()
}
pub fn is_empty(&self) -> bool {
self.campaigns.is_empty()
}
}
/// The Campaign field as it reads, or empty for a ticket in no campaign.
///
/// A uuid no campaign carries renders as `_missing_`, the way a dangling relation
/// target does, rather than as the bare value the file stores: the value is a full
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
/// gone.
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
let Some(uuid) = parse_campaign(content) else {
return String::new();
};
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
}
/// The parts [`content_trim`] cannot render from the ticket file alone.
///
/// Both halves read the tree beside the ticket, so they are gathered in one place
/// rather than at each call site.
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
Ok(Resolved {
relations: relations_for(content, worklane_dir)?,
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
})
}
/// The members of a campaign, grouped by status in flow order.
///
/// 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
/// 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();
// Over `Status::ALL` rather than the names, so each group can be put in its own
// column's order: a campaign's committed list answers what has waited longest for
// the same reason the board's column does.
for status in Status::ALL {
let status_path = worklane_dir.join(status.as_str());
let items = match status_path.exists() {
true => collect_ticket_items(&status_path)?,
false => Vec::new(),
};
let mut members: Vec<TicketItem> = items
.into_iter()
.filter(|item| item.campaign.as_deref() == Some(uuid))
.collect();
members.sort_by(|a, b| by_status_order(status, a, b));
grouped.push((status.as_str(), members));
}
Ok(grouped)
}
/// How far a campaign has got: members done against members held.
///
/// `Copy` because the board carries one on every `CampaignRow`, settled at reload: two
/// counters are cheaper to copy than to reach back through a reference for.
#[derive(Clone, Copy, Debug, Default)]
pub struct Standing {
pub done: usize,
pub total: usize,
}
impl Standing {
pub fn of(grouped: &[(&'static str, Vec<TicketItem>)]) -> Self {
Self {
done: grouped
.iter()
.filter(|(status, _)| *status == DONE)
.map(|(_, items)| items.len())
.sum(),
total: grouped.iter().map(|(_, items)| items.len()).sum(),
}
}
/// The count as it reads, or `no members` for a campaign nothing has been filed
/// against.
pub fn label(&self) -> String {
match self.total {
0 => "no members".to_string(),
total => format!("{}/{} done", self.done, total),
}
}
/// A campaign is done when it holds members and every one of them is done.
///
/// An empty campaign is neither, hence the `None`: calling it done would make a
/// container nothing has been filed against the most complete thing on the board,
/// and calling it open would claim work that does not exist.
pub fn state(&self) -> Option<&'static str> {
match (self.total, self.done == self.total) {
(0, _) => None,
(_, true) => Some(DONE),
(_, false) => Some("open"),
}
}
}
/// The campaign file as it is written.
///
/// The codename sits directly under the ID, because that is what it is: a second way to
/// say which campaign this is, in a word rather than in thirty-six characters.
///
/// The same shape a ticket has, minus what a campaign has no use for: no acceptance
/// criteria, because its definition of done is derived from its members rather than
/// written down, no implementation plan, and no Status, because it sits in no status
/// directory. The headings and the placeholder come from the section table in
/// `util.rs`, so the two file formats cannot drift apart on the spelling of a heading.
pub fn campaign_body(
title: &str,
description: &[String],
codename: Option<&str>,
id: &uuid::Uuid,
owner: Option<&str>,
created_at: &str,
) -> String {
// Joined with a single newline, so an empty value is how a caller spells a
// paragraph break, exactly as it is for a ticket.
let description = trim_blank_ends(description);
let description_text = match description.is_empty() {
true => DESCRIPTION.placeholder.to_string(),
false => description.join("\n"),
};
format!(
"# {title}\n\
\n\
{description_heading}\n\
{description_text}\n\
\n\
{metadata_heading}\n\
\n\
- **ID**: {id}\n\
- **{codename_field}**: {codename}\n\
- **Owner**: {owner}\n\
- **Created At**: {created_at}\n\
",
description_heading = DESCRIPTION.heading,
metadata_heading = METADATA_HEADING,
codename_field = CODENAME_FIELD,
// Written unset rather than left out, the way `add` writes an unset Due on every
// ticket: the line is then there to read and there to edit by hand, and one shape
// of file is one thing for the parser to be right about.
codename = codename.unwrap_or(NOT_SET),
owner = owner.unwrap_or(NOT_SET),
)
}
+90
View File
@@ -0,0 +1,90 @@
//! Putting text on the clipboard of whatever terminal is drawing the board.
//!
//! OSC 52, written by hand, and the reasoning is in AGENTS.md under The Copy Key. The
//! short of it: the board is often being read over ssh, and an escape sequence is the
//! only one of the three ways that crosses the connection. crossterm 0.28 is what
//! ratatui 0.29 pins and it ships no clipboard command, so the sequence and the base64
//! it carries are written here rather than pulled in.
//!
//! The honest limit is that a terminal which ignores OSC 52 ignores it silently: what
//! this reports is whether the sequence was written, not whether it was honoured.
use std::io::Write;
use anyhow::{Context, Result};
/// Ask the terminal to put `text` on the system clipboard.
///
/// `52;c` is the clipboard proper rather than `p`, the X11 primary selection, because
/// this is for pasting into a command line with ctrl-shift-v or cmd-v. Terminated with
/// BEL rather than ST: both are accepted, and BEL is what tmux's `set-clipboard`
/// documents and what every emulator that implements this at all takes.
///
/// Written straight to stdout, which is where ratatui's own frames go, and flushed
/// before returning so a failure belongs to this call rather than to the next draw.
pub fn copy(text: &str) -> Result<()> {
let mut out = std::io::stdout();
write!(out, "\x1b]52;c;{}\x07", base64(text.as_bytes()))
.and_then(|()| out.flush())
.context("could not write to the terminal")
}
/// Standard base64, the alphabet OSC 52 requires, padding included.
///
/// Twenty lines against a dependency: the only thing encoded here is a seven-character
/// id, and the crate would be carried for its own sake.
fn base64(bytes: &[u8]) -> String {
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
for chunk in bytes.chunks(3) {
// The missing bytes of a short chunk read as zero, and the characters they
// would have produced are the ones that become padding below.
let triple = chunk
.iter()
.chain([0u8; 2].iter())
.take(3)
.fold(0u32, |acc, byte| (acc << 8) | u32::from(*byte));
for slot in 0..4 {
match slot <= chunk.len() {
true => out.push(char::from(ALPHABET[(triple >> (18 - 6 * slot) & 0x3f) as usize])),
false => out.push('='),
}
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
/// The vectors from RFC 4648, which is what a terminal decodes with. Every chunk
/// length is in here, so the padding is covered in both of its forms.
#[test]
fn base64_encodes_the_rfc_vectors() {
assert_eq!(base64(b""), "");
assert_eq!(base64(b"f"), "Zg==");
assert_eq!(base64(b"fo"), "Zm8=");
assert_eq!(base64(b"foo"), "Zm9v");
assert_eq!(base64(b"foob"), "Zm9vYg==");
assert_eq!(base64(b"fooba"), "Zm9vYmE=");
assert_eq!(base64(b"foobar"), "Zm9vYmFy");
}
/// What actually goes on the wire for a short id, which is the whole use.
#[test]
fn base64_encodes_a_short_id() {
assert_eq!(base64(b"0546fc5"), "MDU0NmZjNQ==");
}
/// The high bits reach the end of the alphabet, which an off-by-one in the shift
/// would miss entirely on ascii input.
#[test]
fn base64_reaches_the_whole_alphabet() {
assert_eq!(base64(&[0xff, 0xff, 0xff]), "////");
assert_eq!(base64(&[0xfb, 0xff, 0xfe]), "+//+");
assert_eq!(base64(&[0x00, 0x00, 0x00]), "AAAA");
}
}
+574 -35
View File
@@ -2,7 +2,9 @@ use clap::Parser;
use std::sync::LazyLock;
use crate::util::{PRIORITY_RANGE, RelationKind, priority_legend};
use chrono::NaiveDate;
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
/// the same ramp the listing uses rather than spelled out a second time.
@@ -41,18 +43,143 @@ pub struct Cli {
/// Reject an empty value at parse time, so it lands as a usage error rather than a
/// runtime one.
///
/// An empty value looks like a way to clear a field, and clearing is not supported
/// yet. Refusing it keeps the gap visible and stops an accidentally empty variable
/// from silently blanking a field. Only the scalars use this: for the multi-line
/// sections an empty value is a paragraph break.
/// Two messages rather than one, because the arguments that use this fall into two
/// kinds. A search term or a title has no empty form at all, and that is all this says.
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
/// below: an accidentally empty variable must not blank a field silently, and somebody
/// typing an empty value on purpose is reaching for exactly the flag that does it.
///
/// Only the scalars use either one. For the multi-line sections an empty value is a
/// paragraph break.
fn non_empty(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, and clearing a field is not supported yet".to_string());
return Err("value cannot be empty".to_string());
}
Ok(raw.to_string())
}
/// Reject an empty value on an argument whose field can be cleared, and say how.
///
/// The message names no command, because the arguments that use this belong to three:
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
/// flag, which is what the caller was reaching for anyway.
fn clearable(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
}
Ok(raw.to_string())
}
/// Reject a due date that is not a real calendar date in the promised form.
///
/// At parse time, like `priority_level`, so a mistyped date is a usage error with
/// nothing written rather than a value the board goes on showing. `--due` is one of the
/// scalars deliberately left without `PROSE`, so this is the same bargain: nothing here
/// holds prose, and a wrong value should stop the command.
///
/// **The shape is checked before chrono sees it.** `%Y-%m-%d` accepts an unpadded
/// `2026-8-9`, which would then be stored exactly as typed and sort before `2026-10-01`
/// in any comparison of the strings. Checking the length and the two dashes first is
/// what lets a valid date be stored unchanged rather than normalised on the way in.
///
/// Strict on the way in, tolerant on the way out: `util::due_date` still cuts a
/// datetime down to its date, because a file written before this existed, or by hand,
/// can hold one and still has to render.
fn iso_date(raw: &str) -> Result<String, String> {
// An empty value keeps the message that explains why it is refused, since somebody
// typing it is reaching for a way to clear the field rather than mistyping a date.
clearable(raw)?;
let bytes = raw.as_bytes();
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
if !shaped || NaiveDate::parse_from_str(raw, "%Y-%m-%d").is_err() {
// Not echoing the value: clap has already printed `invalid value '...' for
// '--due <DUE>'` above this line, and `priority_level` says its piece the same
// way.
return Err(
"due date must be a real calendar date written as YYYY-MM-DD, for example 2026-08-29"
.to_string(),
);
}
Ok(raw.to_string())
}
/// Reject a codename that is not one word.
///
/// At parse time, like `iso_date` and `priority_level`, so a mistyped value is a usage
/// error with nothing written. One word because the board draws it as a label beside the
/// tags, with a mark and no quoting: `~beaver release` on that row reads as two labels, and
/// the second one is not a campaign. A title is where a sentence goes.
///
/// Nothing else is checked. There is no registry of codenames to check against, the same
/// reason `ls --tag` refuses to validate a tag, and a length limit would be a number
/// invented here: a label the column will not hold is dropped whole by the row that draws
/// it.
fn codename(raw: &str) -> Result<String, String> {
let value = non_empty(raw)?;
if value.split_whitespace().count() > 1 {
return Err("codename must be a single word, for example v1 or beaver".to_string());
}
Ok(value)
}
/// Reject a tag value that `ls --tag` could never match.
///
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
/// `tags.md`, and a heading is one line.
///
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
/// vocabulary. Refusing here would refuse a value that both of those accept.
///
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
fn tag_value(raw: &str) -> Result<String, String> {
let value = raw.trim();
if value.is_empty() {
return Err("tag cannot be empty".to_string());
}
if value.contains(',') {
return Err(
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
);
}
if value.contains(['\n', '\r']) {
return Err("tag must be a single line".to_string());
}
Ok(value.to_string())
}
/// Reject an annotation line that would be read back as a tag of its own.
///
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
/// starting with the section marker would split the annotation and declare whatever
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
/// a different line.
fn annotation_line(raw: &str) -> Result<String, String> {
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
true => Err(format!(
"an annotation line cannot start with '{}', which is how the vocabulary file \
starts a tag",
crate::tag::SECTION
)),
false => Ok(raw.to_string()),
}
}
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
@@ -74,14 +201,7 @@ pub enum Command {
/// List tickets, optionally filtered by status
#[command(after_help = PRIORITY_LEGEND.as_str())]
Ls {
/// Filter by status (backlog, committed, reviewing, done)
status: Option<String>,
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
priority: Option<u8>,
},
Ls(LsArgs),
/// Show a ticket by UUID or title
Show {
@@ -94,9 +214,9 @@ pub enum Command {
/// Ticket UUID or title
ticket: String,
/// Target status (backlog, committed, reviewing, done)
/// Target status
#[arg(short, long)]
status: String,
status: Status,
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
@@ -112,7 +232,7 @@ pub enum Command {
/// Record a relation from one ticket to another
Relate(RelateArgs),
/// Change the owner of a ticket
/// Change the owner of a ticket, or return it to unset
///
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
@@ -123,14 +243,7 @@ pub enum Command {
/// username usually will not, so the call fails on its own. It is silently wrong
/// only when both arguments resolve, which needs a ticket whose title matches the
/// username.
Chown {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = non_empty)]
user: String,
/// Ticket UUID or title
ticket: String,
},
Chown(ChownArgs),
/// Open the board view
Tui {
@@ -139,10 +252,10 @@ pub enum Command {
paths: Vec<std::path::PathBuf>,
},
/// Tick an acceptance criterion
/// Tick acceptance criteria
Check(CheckArgs),
/// Untick an acceptance criterion
/// Untick acceptance criteria
Uncheck(CheckArgs),
/// Add a comment to a ticket
@@ -159,8 +272,60 @@ pub enum Command {
owner: Option<String>,
},
/// Install the agent skill that teaches an agent to use worklane
/// Group tickets that have to be finished together
Campaign {
#[command(subcommand)]
command: CampaignCommand,
},
/// Put a ticket in a campaign
///
/// Campaign first, ticket second, after `chown` and for the same reason: the
/// container is what the call is about, and the order is worth being consistent
/// about across the two commands that name two things.
///
/// The only writer of the Campaign field. `add` has no `--campaign` and `set` has
/// no `--campaign`, so the field keeps one writer the way Owner and Status do.
Assign {
/// Campaign UUID or title
campaign: String,
/// Ticket UUID or title
ticket: String,
},
/// The tag vocabulary: what the board carries, and what each tag means
///
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
/// a filter that means something else.
///
/// The listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
Tags {
#[command(subcommand)]
command: Option<TagCommand>,
},
/// Print a shell completion script
///
/// The structure comes from the clap definition, so a flag added here appears
/// without anyone remembering to. Fish gets a hand-written half appended for the
/// values only the board knows, see `completions.rs`.
Completions {
/// fish, bash, zsh, elvish or powershell
shell: clap_complete::Shell,
},
/// Install the agent skills that teach an agent to use worklane
///
/// Every shipped document by default. The optional name narrows it to one, and
/// `--print` requires it: a diff is against one document, and printing them all
/// concatenated would only look like one.
InstallSkill {
/// Skill to install or print, all of them if omitted
skill: Option<String>,
/// Overwrite an existing copy that has been modified
#[arg(long)]
force: bool,
@@ -169,6 +334,298 @@ pub enum Command {
#[arg(long)]
print: bool,
},
/// Install the opencode tool definitions that wrap the worklane CLI
///
/// One artifact, so no name to pass where `install-skill` takes an optional one:
/// `--print` here can only mean the one file. opencode alone, and globally, so the
/// tools are there in every project rather than in a checkout that happens to carry
/// them. Claude Code has no directory it scans for a tool definition; reaching it
/// would mean an MCP server, which is not this file.
InstallTool {
/// Overwrite an existing copy that has been modified
#[arg(long)]
force: bool,
/// Write it to stdout instead of installing it
#[arg(long)]
print: bool,
},
}
/// What a campaign can be asked for.
///
/// No `mv`: a campaign has no status to move it to, its state is derived from its
/// members.
///
/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a
/// pair: a way to replace a description with no way to add a paragraph to one is the half
/// that is easy to reach for and wrong, since replacing a description to add a sentence is
/// how the rest of it gets lost. The two scalars have no append form at all, which is the
/// same line `append` already draws for a ticket.
///
/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one
/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers
/// are the same over both directories, so a search can resolve in each and nothing but a
/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which
/// explains a ticket search that names a campaign. Under `campaign` the object is settled by
/// the command, the way it is for `set`, `show` and `ls`.
#[derive(clap::Subcommand)]
pub enum CampaignCommand {
/// File a new campaign
Add(CampaignAddArgs),
/// Replace fields on an existing campaign
///
/// The only way to change a campaign's title or codename after it is filed.
/// `campaign add --codename` writes the field at creation the way `add --title` does for
/// a ticket; this is what replaces it, so every campaign filed before the field existed
/// can still be given one.
Set(CampaignSetArgs),
/// Add a paragraph to a campaign's description
///
/// The other half of `campaign set --description`, and the half that keeps what is
/// already written: a description is the sentence a whole campaign's members are filed
/// against, so adding a line to it must not mean retyping it.
Append(CampaignAppendArgs),
/// List campaigns with their member counts
Ls {
/// Print one campaign per line as its id and title, tab separated, for a script
/// or a completion
///
/// The same flag and the same two fields as `ls --ids`, since it answers the same
/// question about a different object. Member counts are left out: counting them
/// reads every ticket on the board, and the caller here is a shell filling in a
/// candidate list on a keypress
#[arg(long)]
ids: bool,
},
/// Show a campaign and its members grouped by status
Show {
/// Campaign UUID or title
campaign: String,
},
}
/// What can be replaced on a campaign that is already filed: everything it holds but its
/// owner.
///
/// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle
/// by accident whether `chown` grows a campaign or `set` keeps the field, which is the
/// one-field-one-writer question and not this command's to answer.
///
/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced
/// rather than emptied, and a campaign's one prose section has no cleared form worth
/// reaching: emptying the description of a container six tickets are filed against is not a
/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`]
/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one
/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it
/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go
/// back to rather than naming a flag that does not exist.
///
/// `--force` guards the codename and nothing else. A campaign that already has one is
/// referred to by it: it is on every card in the campaign, it is what resolves it at the
/// command line, and it is very likely in somebody's shell history. Replacing that silently
/// is the same mistake overwriting an edited skill document would be, which is what
/// `install-skill --force` exists for. A title needs no guard, since a campaign always has
/// one and replacing it is the whole point of the flag. Neither does a description: it is
/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a
/// guard in front of the command's whole purpose is worse than no command.
///
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("campaign_set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "codename"])
))]
pub struct CampaignSetArgs {
/// Campaign UUID, title, filename or codename
pub campaign: String,
/// Replace the campaign title, renaming the file to match
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
pub title: Option<String>,
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
///
/// The whole section, so a paragraph added to it is `campaign append --description`
/// rather than the description retyped
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Replace the codename, a single word to call the campaign by
///
/// The same parser `campaign add --codename` takes, so a codename is one thing however
/// it was written. Replacing one a campaign already has needs `--force`
#[arg(short, long, value_parser = codename)]
pub codename: Option<String>,
/// Replace a codename the campaign already has
///
/// Without it, `--codename` on a campaign that already has one is refused and nothing
/// is written. The codename is how a campaign is referred to once it has one, on every
/// card in it and at the command line, so changing it is a decision rather than a
/// correction. Setting the codename a campaign already carries is a no-op either way,
/// not a refusal: there is nothing to overwrite
#[arg(short, long)]
pub force: bool,
}
/// What can be added to a campaign that is already filed: a paragraph of its description.
///
/// One field, so it is `required` rather than a group of one, which is the longer way to say
/// the same thing and the shape [`TagSetArgs`] already takes. A bare
/// `worklane campaign append <c>` is therefore a usage error rather than a silent no-op.
///
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
/// the line `append` already draws for a ticket, where the title is absent for the same
/// reason.
#[derive(clap::Args)]
pub struct CampaignAppendArgs {
/// Campaign UUID, title, filename or codename
pub campaign: String,
/// Add a paragraph to the description. Repeat the flag for more lines within it
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
}
/// What a campaign holds: a title, a description and an owner.
///
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
/// campaign's definition of done is derived from its members rather than written down,
/// and no implementation plan. Priority, tags and a due date are left out because
/// nothing reads them yet, and a field written but never shown is a field that goes
/// stale unnoticed.
///
/// `--codename` is the exception to that last rule and earns it: the board draws it on
/// every card in the campaign, and it exists because the uuid does not fit there.
#[derive(clap::Args)]
pub struct CampaignAddArgs {
/// Campaign title
#[arg(short, long, allow_hyphen_values = PROSE)]
pub title: String,
/// What the campaign is for. Use multiple flags for multiline descriptions
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// A single word to call the campaign by, for example v1 or beaver
///
/// The uuid is what every command stores and the title is a sentence, so neither is
/// what a card has room to print. This is the short form the board draws, and it is
/// optional: a campaign without one is drawn by its short id instead.
#[arg(short, long, value_parser = codename)]
pub codename: Option<String>,
/// Owner. Defaults to the git user
#[arg(short, long)]
pub owner: Option<String>,
}
/// What the tag vocabulary can be asked for.
///
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
/// ls` is the same thing spelled the way `campaign ls` is.
///
#[derive(clap::Subcommand)]
pub enum TagCommand {
/// Declare a tag, and what it means
Add(TagAddArgs),
/// Replace what a declared tag means
Set(TagSetArgs),
/// List the tags the board carries, and how many tickets carry each
Ls,
}
/// What declaring a tag takes: the tag, and what it is for.
///
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
/// not an object with a history, it is a word the board agrees on, and `git log` over
/// `tags.md` answers who wrote which line better than a field would.
#[derive(clap::Args)]
pub struct TagAddArgs {
/// The tag to declare, spelled the way `ls --tag` matches it
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate. Use multiple flags for multiline
/// annotations
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
pub annotation: Vec<String>,
}
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
///
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
/// has one it is how the campaign is addressed, on every card and at every command line, so
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
/// command's whole purpose.
///
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
/// ticket carrying it. That is a migration, not a flag on `set`.
///
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
///
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
#[derive(clap::Args)]
pub struct TagSetArgs {
/// The tag to change, spelled the way it is declared
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
/// multiple flags for multiline annotations
#[arg(
short,
long,
required = true,
allow_hyphen_values = PROSE,
value_parser = annotation_line
)]
pub annotation: Vec<String>,
}
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
/// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option<String>`
/// values that a caller can swap silently, so the mode that joined them came as a
/// struct rather than a sixth parameter, the way `add` became [`AddArgs`].
#[derive(clap::Args)]
pub struct LsArgs {
/// Filter by status
pub status: Option<Status>,
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Only show tickets carrying this tag, matched whole
#[arg(long, value_parser = non_empty)]
pub tag: Option<String>,
/// Only show the members of this campaign, by UUID or title
#[arg(long, value_parser = non_empty)]
pub campaign: Option<String>,
/// Print one ticket per line as its id and title, tab separated, for a script or a
/// completion. Done included, and the filters still apply
#[arg(long)]
pub ids: bool,
}
/// `add` carries every field a new ticket can hold, so it is a struct rather than an
@@ -200,7 +657,7 @@ pub struct AddArgs {
pub tags: Vec<String>,
/// Due date (YYYY-MM-DD)
#[arg(long)]
#[arg(long, value_parser = iso_date)]
pub due: Option<String>,
/// Owner
@@ -222,7 +679,7 @@ pub struct AddArgs {
clap::ArgGroup::new("set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority"])
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
))]
pub struct SetArgs {
/// Ticket UUID or title
@@ -245,16 +702,92 @@ pub struct SetArgs {
pub plan: Vec<String>,
/// Replace the tags
#[arg(short = 'g', long, value_parser = non_empty)]
#[arg(short = 'g', long, value_parser = clearable)]
pub tags: Vec<String>,
/// Replace the due date (YYYY-MM-DD)
#[arg(long, value_parser = non_empty)]
///
/// The same parser as `add`: one field, one definition of what a due date is. The
/// planning skill sets dates through `set` rather than `add`, so validating only
/// the one that files a ticket would leave the path that is actually used open.
#[arg(long, value_parser = iso_date)]
pub due: Option<String>,
/// Replace the priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Return a field to unset. Repeat the flag for more than one
///
/// The counterpart to the flag it names, and the only way to take a value away: an
/// empty value is a paragraph break for a section and a usage error for a scalar, so
/// neither can spell this. What goes back is what `add` writes for a field it was
/// never given.
///
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
}
impl SetArgs {
/// A field this call both replaces and clears, if there is one.
///
/// clap cannot express the conflict, because `--clear` carries the field as a value
/// rather than in the flag's own name. So it is checked once here and refused, rather
/// than resolved by whichever of the two happens to be applied last, which is a
/// silent answer to a contradictory call.
pub fn contested(&self) -> Option<Clearable> {
self.clear.iter().copied().find(|field| match field {
Clearable::Due => self.due.is_some(),
Clearable::Tags => !self.tags.is_empty(),
Clearable::Priority => self.priority.is_some(),
Clearable::Description => !self.description.is_empty(),
Clearable::Acceptance => !self.acceptance.is_empty(),
Clearable::Plan => !self.plan.is_empty(),
})
}
}
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
/// that is what shapes the arguments.
///
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
/// can state outright. The typed call is the same either way; only who checks it differs.
///
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
/// both is a usage error from clap rather than a decision made here.
#[derive(clap::Args)]
pub struct ChownArgs {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
pub user: Option<String>,
/// Ticket UUID or title
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
pub ticket: Option<String>,
/// Return the owner to unset on this ticket, which is named here since there is no
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
}
impl ChownArgs {
/// The ticket the call names, and the owner to write on it, `None` being unset.
///
/// `None` for the pair is unreachable while the constraints above hold, and is an
/// error at the call site rather than a panic, so loosening one of them costs a
/// message instead of a crash.
pub fn target(&self) -> Option<(&str, Option<&str>)> {
match (self.clear.as_deref(), self.user.as_deref(), self.ticket.as_deref()) {
(Some(ticket), None, None) => Some((ticket, None)),
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
_ => None,
}
}
}
/// `append` only offers the sections that hold multiple lines, since appending to a
@@ -331,14 +864,20 @@ impl RelateArgs {
/// because the two read as opposites at the call site and neither needs the other's
/// name to make sense.
///
/// The criterion is optional: without it the criteria are listed and the index asked
/// The criteria are optional: without any the criteria are listed and the index asked
/// for, or, where there is no terminal to ask at, returned as an error carrying the
/// same list.
///
/// Several terms in one call because finishing a ticket means ticking every box, and
/// one invocation per box resolved the ticket and rewrote the file each time. The
/// terms are variadic rather than a repeated flag: they address something that is
/// already there, the way the ticket positional does, instead of carrying content the
/// way `--acceptance` does.
#[derive(clap::Args)]
pub struct CheckArgs {
/// Ticket UUID or title
pub ticket: String,
/// Criterion index as shown by `show`, or a substring of its text. Prompts if omitted
pub criterion: Option<String>,
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
pub criteria: Vec<String>,
}
+616
View File
@@ -0,0 +1,616 @@
//! Shell completions.
//!
//! Two halves, because neither alone is enough.
//!
//! `clap_complete` generates the structure (subcommands, flags, their arguments)
//! straight from the clap definition, so a new flag never needs remembering here. But it
//! can only offer values it knows at compile time, and the value worth completing for
//! worklane is the ticket, which lives in the board the command is run above.
//!
//! So the fish output gets a hand-written block appended that asks worklane itself. That
//! costs one `worklane ls --ids` per keypress, which measured at 2.5ms in release on a
//! board of seventy-five tickets, comfortably below anything a person notices.
//!
//! The four statuses are half clap's: `Status` is a `ValueEnum`, so it emits them for
//! `mv --status`, but the fish generator does not emit possible values for a *positional*
//! and `ls <status>` gets nothing. Same for `completions <shell>`. So the block below
//! lists those two, from the enums rather than by hand.
use std::io;
use clap::{CommandFactory, ValueEnum};
use clap_complete::Shell;
use crate::install::SKILLS;
use crate::util::Status;
/// Subcommands whose first positional is a ticket.
///
/// Kept honest by a test rather than by memory: a new ticket-taking subcommand that is
/// missing here silently loses completion, which nothing else would catch.
pub const TICKET_COMMANDS: [&str; 8] = [
"show", "mv", "comment", "set", "append", "relate", "check", "uncheck",
];
/// Subcommands whose *second* positional is the ticket, because they name two things.
///
/// `chown alice <ticket>` and `assign "v1 release" <ticket>`, which put the ticket
/// second deliberately, see AGENTS.md. The first argument of each is a user or a
/// campaign, and neither is completed.
pub const TICKET_SECOND_COMMANDS: [&str; 2] = ["chown", "assign"];
/// Options whose value is a ticket, as `relate` takes three of.
pub const TICKET_FLAGS: [&str; 3] = ["blocked-by", "regression-of", "relates-to"];
/// Subcommands whose first positional is a campaign.
///
/// `assign` alone, which takes the campaign first and the ticket second. Kept honest by
/// the same test the ticket lists are.
pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
/// Nested subcommands whose first argument is a campaign, as `parent child`.
///
/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half
/// needs a third position helper: their argument is the *third* token, where
/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a
/// top-level command's arguments. Neither can tell `campaign show <TAB>` from
/// `chown alice <TAB>` by position.
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
("campaign", "show"),
("campaign", "set"),
("campaign", "append"),
];
/// Options whose value is a campaign.
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
/// Options whose value is a tag.
///
/// Its own list rather than a line in the block below, because the values come from a
/// different command: a tag is not an object with an id, so `worklane tags` answers this
/// one where `ls --ids` answers the tickets.
pub const TAG_FLAGS: [&str; 1] = ["tag"];
/// Nested commands whose first argument is a tag the board already has.
///
/// `tags set` changes what a declared tag means, so the values it takes are exactly the
/// ones `worklane tags` prints. `tags add` is deliberately absent: the tag it takes is one
/// the board does not have yet, so offering the ones it does would offer exactly the values
/// it refuses. Which of the two a new tag positional belongs to is what
/// `no_tag_taking_option_is_missing` makes somebody decide.
pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")];
pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> {
let mut command = crate::command::Cli::command();
clap_complete::generate(shell, &mut command, "worklane", out);
if shell == Shell::Fish {
write!(out, "{}", fish_dynamic())?;
}
Ok(())
}
/// The dynamic half, appended to what clap generated.
///
/// Fish merges completions from every `complete` call, so these add to the generated
/// rules rather than replacing them.
fn fish_dynamic() -> String {
let ticket_commands = TICKET_COMMANDS.join(" ");
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
let ticket_flags = flag_list(&TICKET_FLAGS);
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
.iter()
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
.collect::<Vec<_>>()
.join("; or ");
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
let tag_flags = flag_list(&TAG_FLAGS);
let tag_nested = TAG_NESTED_COMMANDS
.iter()
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
.collect::<Vec<_>>()
.join("; or ");
let statuses = possible_values(Status::value_variants());
let shells = possible_values(Shell::value_variants());
let skills = SKILLS
.iter()
.map(|skill| skill.name)
.collect::<Vec<_>>()
.join(" ");
format!(
r#"
# ---------------------------------------------------------------------------
# Dynamic values, appended by `worklane completions fish`. Fish accumulates
# completions, so these add to the generated rules above.
# ---------------------------------------------------------------------------
# Almost every argument worklane takes names something on the board rather than
# something on disk, so stop fish falling back to the directory listing. Without this,
# `worklane show 1b78a24 <TAB>` offers Cargo.toml and src/.
complete -c worklane -f
# The exception, and the reason the line above is not the whole story: `tui` takes
# project paths, as many as you like. Directories only, since each is resolved to the
# first `.worklane` at or above it.
complete -c worklane -n '__worklane_command_is tui' \
-a '(__fish_complete_directories)' -d project
# Position is counted rather than inferred from what has been typed: matching against
# the ticket list would run worklane again inside the condition, and would also keep
# offering tickets after one had been chosen.
#
# The subcommand is the second token, so its first argument is being typed once two
# tokens are there. `$tokens[2]` rather than `__fish_seen_subcommand_from`, because
# `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen,
# and their arguments are not what these complete.
function __worklane_first_arg_of
set -l tokens (commandline -opc)
test (count $tokens) -eq 2; and contains -- $tokens[2] $argv
end
function __worklane_second_arg_of
set -l tokens (commandline -opc)
test (count $tokens) -eq 3; and contains -- $tokens[2] $argv
end
# The first argument of a nested subcommand, `worklane campaign show <TAB>`. Three tokens
# with both names matched, rather than the token counting the two above do: `campaign show`
# puts its argument where a top-level command puts its second, so counting alone would
# offer campaigns to `chown alice <TAB>` and tickets here.
function __worklane_nested_arg_of
set -l tokens (commandline -opc)
test (count $tokens) -eq 3; and test "$tokens[2]" = "$argv[1]"; and test "$tokens[3]" = "$argv[2]"
end
# Which command this is, at any position in it. `$tokens[2]` again rather than
# `__fish_seen_subcommand_from`, and for the reason spelled out above: `campaign ls` is an
# `ls` that fish has seen, so scoping `--tag` with fish's own helper would offer it under a
# command that does not take it.
#
# A rule carrying `-l` needs one of these. Without it fish takes the option as one the
# whole tool accepts, and `worklane init --<TAB>` offered `--blocked-by`, `--tag` and four
# others that only `relate` and `ls` have.
function __worklane_command_is
set -l tokens (commandline -opc)
test (count $tokens) -ge 2; and contains -- $tokens[2] $argv
end
# No `-d`: `ls --ids` prints the id and the title separated by a tab, which is fish's
# own form for a candidate and its description, so every ticket carries its own.
complete -c worklane \
-n '__worklane_first_arg_of {ticket_commands}; or __worklane_second_arg_of {ticket_second_commands}' \
-a '(worklane ls --ids)'
# `relate` takes its targets as option values, so they are completed by flag rather
# than by position.
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
-x -a '(worklane ls --ids)'
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
# argument, `campaign show`'s only one, and `ls --campaign`.
complete -c worklane \
-n '__worklane_first_arg_of {campaign_commands}; or {campaign_nested}' \
-a '(worklane campaign ls --ids)'
complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
-x -a '(worklane campaign ls --ids)'
# Tags come from `worklane tags` rather than from a listing of objects, since a tag has no
# id. Three fields now, the tag, its count and its annotation, and fish takes everything
# after the *first* tab as one description, so the count is dropped here rather than landing
# in the middle of the prose. `cut` and not `string replace` because the columns are what is
# being picked, and `cut -f1` is how a script reads this listing anyway.
#
# What is left is the annotation, and a tag the board carries but has never declared has
# none: it is offered with no description at all, which is the near-duplicate the file was
# added to catch. The count used to be the description and said the same thing more weakly.
complete -c worklane -n '__worklane_command_is ls' {tag_flags} \
-x -a '(worklane tags | cut -f1,3)'
# And `tags set` names one that is already declared, so it reads the same listing. `tags
# add` has no rule on purpose: it takes a tag the board does not have, so the candidates
# here are the values it refuses.
complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)'
# `chown --clear` names the ticket in the flag too, since with no user to give there is
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
# has a `--clear` of its own that takes a field name, and clap already offers those.
complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)'
# clap emits the four for `mv --status`, which is an option, but the fish generator
# emits nothing for the possible values of a positional. So the one place a status is
# positional needs them listed, and the same goes for the shell below.
complete -c worklane -n '__worklane_first_arg_of ls' -a '{statuses}' -d status
complete -c worklane -n '__worklane_first_arg_of completions' -a '{shells}' -d shell
# Shipped with the binary, so this list comes from `install::SKILLS` and cannot fall
# behind it.
complete -c worklane -n '__worklane_first_arg_of install-skill' -a '{skills}' -d skill
"#
)
}
/// Option names as fish wants them on a `complete` line, `-l one -l two`.
fn flag_list(flags: &[&str]) -> String {
flags
.iter()
.map(|flag| format!("-l {flag}"))
.collect::<Vec<_>>()
.join(" ")
}
/// The names a `ValueEnum` accepts, for a fish `-a` list.
///
/// Read off the enum rather than written out, so a status or a shell added to either one
/// is offered without anybody remembering this file. A variant marked hidden is left out,
/// which is what `to_possible_value` returning `None` means.
fn possible_values<T: ValueEnum>(variants: &[T]) -> String {
variants
.iter()
.filter_map(|variant| variant.to_possible_value())
.map(|value| value.get_name().to_string())
.collect::<Vec<_>>()
.join(" ")
}
#[cfg(test)]
mod tests {
use super::*;
/// Built, not just derived: an index is assigned when the command is built, and the
/// positionals of an unbuilt one all report `None`.
fn command() -> clap::Command {
let mut cli = crate::command::Cli::command();
cli.build();
cli
}
/// Every argument in the tool, as the path that reaches it and the argument itself.
///
/// One walker for the honesty tests below, rather than each one repeating the
/// traversal: they differ only in which id they are looking for. Two levels, which is
/// as deep as the tool goes, and `help` is skipped because clap generates it and it
/// takes no object of ours.
fn every_argument() -> Vec<(Vec<String>, clap::Arg)> {
let cli = command();
let mut found = Vec::new();
for subcommand in cli.get_subcommands() {
let name = subcommand.get_name().to_string();
if name == "help" {
continue;
}
for arg in subcommand.get_arguments() {
found.push((vec![name.clone()], arg.clone()));
}
for nested in subcommand.get_subcommands() {
let child = nested.get_name().to_string();
if child == "help" {
continue;
}
for arg in nested.get_arguments() {
found.push((vec![name.clone(), child.clone()], arg.clone()));
}
}
}
found
}
/// Every subcommand that takes a ticket must be listed, at the position it takes it,
/// or it silently loses completion.
///
/// Nested subcommands are walked now that `__worklane_nested_arg_of` exists, but
/// nothing under `campaign` takes a ticket, so a nested one is a panic rather than a
/// list: it would need a rule of its own in the fish block, and a name in a list here
/// would look like it already had one.
#[test]
fn no_ticket_taking_subcommand_is_missing() {
for (path, arg) in every_argument() {
// `show` calls it `id`; everything else calls it `ticket`.
if !matches!(arg.get_id().as_str(), "ticket" | "id") {
continue;
}
let name = path.join(" ");
if arg.is_positional() {
assert_eq!(
path.len(),
1,
"`worklane {name}` takes a nested ticket argument, \
which needs a rule in the fish block"
);
let top = path[0].as_str();
match arg.get_index() {
Some(1) => assert!(
TICKET_COMMANDS.contains(&top),
"`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS"
),
Some(2) => assert!(
TICKET_SECOND_COMMANDS.contains(&top),
"`worklane {name}` takes a ticket second but is not in \
TICKET_SECOND_COMMANDS"
),
index => panic!("`worklane {name}` takes a ticket at position {index:?}"),
}
}
}
}
/// The same for campaigns, which is why the lists above are three rather than one:
/// a campaign is named as a first positional, as a nested subcommand's only argument,
/// and as an option value, and each needs a different rule in the fish block.
#[test]
fn no_campaign_taking_argument_is_missing() {
let mut seen = 0;
for (path, arg) in every_argument() {
if arg.get_id().as_str() != "campaign" {
continue;
}
seen += 1;
let name = path.join(" ");
if let Some(long) = arg.get_long() {
assert!(
CAMPAIGN_FLAGS.contains(&long),
"`worklane {name} --{long}` takes a campaign but is not in CAMPAIGN_FLAGS"
);
continue;
}
assert_eq!(
arg.get_index(),
Some(1),
"`worklane {name}` takes a campaign somewhere the fish block has no rule for"
);
match path.as_slice() {
[top] => assert!(
CAMPAIGN_COMMANDS.contains(&top.as_str()),
"`worklane {name}` takes a campaign first but is not in CAMPAIGN_COMMANDS"
),
[parent, child] => assert!(
CAMPAIGN_NESTED_COMMANDS.contains(&(parent.as_str(), child.as_str())),
"`worklane {name}` takes a campaign but is not in CAMPAIGN_NESTED_COMMANDS"
),
_ => panic!("`worklane {name}` is nested deeper than the fish block goes"),
}
}
// A guard on the walker itself: if it stopped finding arguments, every assertion
// above would pass by never running.
assert_eq!(
seen, 5,
"expected assign, campaign show, campaign set, campaign append and ls --campaign"
);
}
/// Commands whose tag positional names a tag that does not exist yet.
///
/// `tags add` declares a word the board has never carried, so completing it from
/// `worklane tags` would offer exactly the values the command refuses. Recorded rather
/// than skipped, so the *next* tag positional has to say which it is: `tags set` takes
/// a tag that is already declared and wants a rule in the fish block, and the test
/// below fails until it gets one or lands here.
///
/// In the test module because nothing outside it reads the list; the rule it encodes is
/// about what the fish block is missing, which is a test's question.
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
/// Tags have their own list because their values come from `worklane tags` rather than
/// from a listing of objects, so a second tag-taking option would need that rule and
/// not the campaign one.
#[test]
fn no_tag_taking_option_is_missing() {
let mut seen = 0;
for (path, arg) in every_argument() {
if arg.get_id().as_str() != "tag" {
continue;
}
seen += 1;
let name = path.join(" ");
let Some(long) = arg.get_long() else {
let known = match path.as_slice() {
[parent, child] => {
let pair = (parent.as_str(), child.as_str());
TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair)
}
_ => false,
};
assert!(
known,
"`worklane {name}` takes a tag as a positional, so it belongs in \
TAG_NESTED_COMMANDS if the tag already exists and TAG_NEW_COMMANDS if it \
does not"
);
continue;
};
assert!(
TAG_FLAGS.contains(&long),
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
);
}
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
}
/// **Every rule naming an option has to say which command it belongs to.** A bare
/// `complete -c worklane -l tag` tells fish the whole tool takes `--tag`, so
/// `worklane init --<TAB>` offered six options that only `relate` and `ls` have. This
/// is what stops the next rule being written the same way.
#[test]
fn every_rule_naming_an_option_is_scoped_to_a_command() {
let script = fish_dynamic();
// Rules are one logical line, continued with a trailing backslash.
for rule in script.replace("\\\n", " ").lines() {
if !rule.starts_with("complete") || !rule.contains("-l ") {
continue;
}
assert!(
rule.contains("__worklane_command_is"),
"this rule declares an option for the whole tool: {rule}"
);
}
}
#[test]
fn every_listed_command_is_a_real_subcommand() {
let cli = command();
let known: Vec<&str> = cli.get_subcommands().map(|c| c.get_name()).collect();
for name in TICKET_COMMANDS.iter().chain(TICKET_SECOND_COMMANDS.iter()) {
assert!(known.contains(name), "no such subcommand: {name}");
}
}
/// `chown --clear` takes a ticket, so it is completed like one, and only under
/// `chown`: `set --clear` is the same flag name carrying a field.
#[test]
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
let script = fish_dynamic();
let rule = script
.lines()
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
.expect("chown --clear has a rule of its own");
assert!(rule.contains("__worklane_command_is chown"), "{rule}");
assert!(rule.contains("worklane ls --ids"), "{rule}");
let chown = command().find_subcommand("chown").expect("chown exists").clone();
assert!(
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
"`chown` has no --clear for the rule to complete"
);
assert!(
!TICKET_FLAGS.contains(&"clear"),
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
);
}
/// The flags completed as tickets have to be `relate`'s actual flags, or the rule
/// completes an option nothing accepts.
#[test]
fn every_ticket_flag_is_a_real_option() {
let relate = command()
.find_subcommand("relate")
.expect("relate exists")
.clone();
let known: Vec<String> = relate
.get_arguments()
.filter_map(|arg| arg.get_long().map(str::to_string))
.collect();
for flag in TICKET_FLAGS {
assert!(known.contains(&flag.to_string()), "`relate` has no --{flag}");
}
}
#[test]
fn the_fish_script_asks_worklane_for_its_tickets() {
let script = fish_dynamic();
assert!(script.contains("worklane ls --ids"));
// Both positions, in one rule.
assert!(script.contains("__worklane_first_arg_of show"));
assert!(script.contains("__worklane_second_arg_of chown assign"));
// Nothing here takes a file, bar the one that does.
assert!(script.contains("complete -c worklane -f\n"));
assert!(script.contains("__fish_complete_directories"));
// Generated from `install::SKILLS`, so every shipped skill is in it.
assert!(script.contains("worklane-review"));
}
/// The two listings the campaign and tag rules read, which are separate commands
/// because a campaign has an id and a tag does not.
#[test]
fn the_fish_script_asks_worklane_for_its_campaigns_and_tags() {
let script = fish_dynamic();
assert!(script.contains("worklane campaign ls --ids"), "{script}");
assert!(script.contains("worklane tags"), "{script}");
// The nested position, which neither of the two counting helpers can reach.
assert!(script.contains("__worklane_nested_arg_of campaign show"), "{script}");
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
}
/// Every rule that reads the tag listing drops the count, because `worklane tags` prints
/// three fields and fish takes everything after the first tab as the description. Left
/// whole, a tag would be described as its count, a tab and its annotation.
///
/// Pinned per rule rather than once over the script: a rule added later that reads
/// `worklane tags` raw is the bug this catches, and it would not show up in a single
/// `contains`.
#[test]
fn every_tag_rule_takes_the_annotation_as_its_description() {
let script = fish_dynamic();
let reading: Vec<&str> = script
.lines()
.filter(|line| line.contains("(worklane tags"))
.collect();
assert_eq!(
reading.len(),
2,
"expected the ls --tag rule and the tags set one: {reading:?}"
);
for line in reading {
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
}
}
/// The one status positional and the one shell positional, which clap does not emit
/// possible values for. Read off the enums, so a fifth status would appear here on
/// its own.
#[test]
fn the_fish_script_lists_the_statuses_and_the_shells() {
let script = fish_dynamic();
for status in Status::ALL {
assert!(
script.contains(status.as_str()),
"the ls positional is never offered {}",
status.as_str()
);
}
assert!(script.contains("-a 'backlog committed reviewing done' -d status"));
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
assert!(script.contains(shell), "the shell positional is never offered {shell}");
}
}
/// The four for `mv --status` are clap's, which is half of why `Status` is a
/// `ValueEnum`. If clap ever stops emitting them, the fish half has to carry them
/// too, and this is what says so.
#[test]
fn clap_emits_the_statuses_for_the_status_flag() {
let mut out = Vec::new();
generate(Shell::Fish, &mut out).expect("generates");
let script = String::from_utf8(out).expect("utf8");
let flag = script
.lines()
.find(|line| line.contains("using_subcommand mv") && line.contains("-l status"))
.expect("mv --status has a rule of its own");
assert!(flag.contains("backlog"), "{flag}");
}
#[test]
fn generating_fish_produces_both_halves() {
let mut out = Vec::new();
generate(Shell::Fish, &mut out).expect("generates");
let script = String::from_utf8(out).expect("utf8");
// clap's half.
assert!(script.contains("complete -c worklane"));
assert!(script.contains("install-skill"));
// Ours.
assert!(script.contains("__worklane_first_arg_of"));
}
#[test]
fn other_shells_get_only_the_generated_half() {
for shell in [Shell::Bash, Shell::Zsh] {
let mut out = Vec::new();
generate(shell, &mut out).expect("generates");
let script = String::from_utf8(out).expect("utf8");
assert!(
!script.contains("__worklane_first_arg_of"),
"fish-only helpers leaked into {shell}"
);
}
}
}
+1025 -201
View File
File diff suppressed because it is too large Load Diff
+382 -51
View File
@@ -1,14 +1,21 @@
//! Shipping the agent assets with the binary.
//!
//! The skill document lives at `assets/SKILL.md` in this repo and is embedded with
//! The skill documents live in `assets/` in this repo and are embedded with
//! `include_str!` rather than copied by an install script, because `cargo install`
//! places binaries and nothing else. Embedding means the document can never be a
//! places binaries and nothing else. Embedding means a document can never be a
//! different version from the binary it describes, and there is no second file to
//! lose track of.
//!
//! The machinery is written once for both assets this repo will ship. The tool file
//! for opencode is executable code needing Bun, so it gets its own command and its
//! own root, but the compare-and-refuse logic is the same and lives here.
//! `SKILLS` is every skill the binary carries, and `install-skill` writes all of them.
//! One document teaches the CLI and the others teach a job done with it; a person who
//! has learned the invocation should not have to learn a new name for each document
//! added later, or the new one silently never arrives.
//!
//! The machinery is written once for both kinds of asset. The tool file is executable
//! code and reaches opencode alone, so it gets its own command and its own root, but the
//! compare-and-refuse logic is the same and lives here. What it needs at runtime is
//! opencode and nothing else: it is loaded into opencode's own runtime, so neither Bun
//! nor `@opencode-ai/plugin` has to be installed for the import in it to resolve.
use std::io;
use std::path::{Path, PathBuf};
@@ -17,6 +24,9 @@ use anyhow::{Result, anyhow};
/// One thing the binary carries and can write into a user's agent configuration.
pub struct Asset {
/// How it is addressed on the command line. For a skill this is also its directory
/// and its frontmatter `name:`, which both agents require to agree.
pub name: &'static str,
/// What it is called in messages, e.g. `skill`.
pub what: &'static str,
/// Where it goes under its root, e.g. `worklane/SKILL.md`.
@@ -24,13 +34,109 @@ pub struct Asset {
pub content: &'static str,
}
/// The skill document, as of the commit this binary was built from.
/// The skill that teaches the CLI, as of the commit this binary was built from.
pub const SKILL: Asset = Asset {
name: "worklane",
what: "skill",
relative: "worklane/SKILL.md",
content: include_str!("../assets/SKILL.md"),
};
/// The skill that reviews a finished ticket against the code that claims to close it.
///
/// A document of its own rather than a section of `SKILL`, because it is loaded for a
/// different job: the CLI skill is wanted for anything touching a ticket, and this is
/// wanted only when a review is asked for. One document holding both would be loaded
/// constantly to say nothing, and the frontmatter description, which is the whole of
/// what decides the loading, cannot describe two jobs without fitting neither.
pub const REVIEW_SKILL: Asset = Asset {
name: "worklane-review",
what: "skill",
relative: "worklane-review/SKILL.md",
content: include_str!("../assets/REVIEW.md"),
};
/// The skill that grooms the board as a whole rather than a ticket at a time.
///
/// Its own document for the reason `REVIEW_SKILL` is: it is wanted for questions about
/// the backlog as a body of work, and loading it for every ticket touched would be a
/// description that fits nothing. It is also the document where the destructive edits
/// live, since every job in it writes to many tickets at once.
pub const PLAN_SKILL: Asset = Asset {
name: "worklane-plan",
what: "skill",
relative: "worklane-plan/SKILL.md",
content: include_str!("../assets/PLAN.md"),
};
/// The skill that sets a board up and puts one back together.
///
/// Its own document for the reason the two above are, and the split against `PLAN_SKILL`
/// is the one worth stating: that document grooms the *work*, priorities and dates and
/// campaigns, and this one configures the *board*, the tag vocabulary and the faults a
/// board can develop. The tag section is where they meet, so each points at the other.
///
/// The one document that has to hold for a board that tracks no software at all. The other
/// three describe a workflow that happens to be this repo's; a vocabulary skill written
/// around `bug` and `cli` would teach nothing to a board tracking a household, so the
/// examples in it deliberately span three subjects.
pub const ADMIN_SKILL: Asset = Asset {
name: "worklane-admin",
what: "skill",
relative: "worklane-admin/SKILL.md",
content: include_str!("../assets/ADMIN.md"),
};
/// Every skill this binary carries, in the order they install.
///
/// A `static` rather than a `const` so the slice borrowed from it outlives the
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
pub static SKILLS: [Asset; 4] = [SKILL, REVIEW_SKILL, PLAN_SKILL, ADMIN_SKILL];
/// The opencode tool definitions, the second kind of asset this binary carries.
///
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
/// no directory it scans for one, so this is not the artifact that would reach it. That
/// asymmetry is the whole reason it is its own command with its own root rather than a
/// flag on `install-skill`.
///
/// Flat in the root rather than in a directory of its own, and the file name is load
/// bearing: opencode builds each tool id as the file name then the export, so this file
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
/// with; a tool carries it in the file name alone.
pub const TOOL: Asset = Asset {
name: "worklane",
what: "tool",
relative: "worklane.ts",
content: include_str!("../assets/TOOL.ts"),
};
/// Every tool this binary carries.
///
/// One, and an array anyway: it is what keeps the install loop the same shape as the
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
/// is one.
pub static TOOLS: [Asset; 1] = [TOOL];
/// The skill a name on the command line asks for.
pub fn skill_named(name: &str) -> Result<&'static Asset> {
SKILLS
.iter()
.find(|asset| asset.name == name)
.ok_or_else(|| anyhow!("no skill named {name:?}. This binary ships {}", skill_names()))
}
/// The names, for the errors that have to say what there is to choose from.
pub fn skill_names() -> String {
SKILLS
.iter()
.map(|asset| asset.name)
.collect::<Vec<_>>()
.join(", ")
}
/// Where a skill has to sit to be found, for both agents worklane is used from.
///
/// One path serves both. Claude Code reads `~/.claude/skills/<name>/SKILL.md`, and
@@ -47,6 +153,48 @@ pub fn skills_root() -> Result<PathBuf> {
Ok(Path::new(&home).join(".claude/skills"))
}
/// Where the tool has to sit for opencode to load it in every project.
///
/// `XDG_CONFIG_HOME` when it is set and non-empty, `~/.config` otherwise, which is what
/// opencode itself resolves: `opencode debug paths` reports its config root under
/// `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without.
/// An empty value counts as unset, the convention `colors_wanted` already follows for
/// `NO_COLOR`. Checked against opencode 1.15.10.
///
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
/// directory outside any project and registered all eleven worklane tools. The singular
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
/// and `skill(s)`.
///
/// One agent, unlike `skills_root`. Claude Code has no path that belongs here at all: a
/// tool reaches it through an MCP server, which is a different artifact and not one this
/// binary carries.
pub fn tools_root() -> Result<PathBuf> {
let xdg = std::env::var_os("XDG_CONFIG_HOME");
let home = std::env::var_os("HOME");
opencode_tool_dir(xdg.as_deref().map(Path::new), home.as_deref().map(Path::new))
}
/// `tools_root` with the two variables passed in rather than read.
///
/// The seam exists for the reason `colors_wanted` has one: both branches and the failure
/// have to be reachable from a test, and a threaded test binary cannot mutate the process
/// environment to reach them one at a time.
fn opencode_tool_dir(xdg: Option<&Path>, home: Option<&Path>) -> Result<PathBuf> {
if let Some(xdg) = xdg.filter(|value| !value.as_os_str().is_empty()) {
return Ok(xdg.join("opencode/tool"));
}
let home = home.ok_or_else(|| {
anyhow!(
"cannot tell where your opencode config lives because neither XDG_CONFIG_HOME nor HOME is set in the environment"
)
})?;
Ok(home.join(".config/opencode/tool"))
}
#[derive(Debug, PartialEq, Eq)]
pub enum Outcome {
Written(PathBuf),
@@ -115,10 +263,7 @@ mod tests {
let root = root();
let path = SKILL.path(root.path());
assert_eq!(
SKILL.install(root.path(), false).unwrap(),
Outcome::Written(path.clone())
);
assert_eq!(SKILL.install(root.path(), false).unwrap(), Outcome::Written(path.clone()));
assert_eq!(std::fs::read_to_string(&path).unwrap(), SKILL.content);
}
@@ -143,43 +288,63 @@ mod tests {
SKILL.install(root.path(), false).unwrap();
std::fs::write(&path, "hand written\n").unwrap();
assert_eq!(
SKILL.install(root.path(), false).unwrap(),
Outcome::Refused(path.clone())
);
assert_eq!(SKILL.install(root.path(), false).unwrap(), Outcome::Refused(path.clone()));
assert_eq!(std::fs::read_to_string(&path).unwrap(), "hand written\n");
assert_eq!(
SKILL.install(root.path(), true).unwrap(),
Outcome::Written(path.clone())
);
assert_eq!(SKILL.install(root.path(), true).unwrap(), Outcome::Written(path.clone()));
assert_eq!(std::fs::read_to_string(&path).unwrap(), SKILL.content);
}
#[test]
fn the_skill_lands_where_both_agents_look_for_it() {
fn every_skill_lands_where_both_agents_look_for_it() {
let root = skills_root().unwrap();
assert!(root.ends_with(".claude/skills"), "{}", root.display());
assert!(
SKILL.path(&root).ends_with(".claude/skills/worklane/SKILL.md"),
"{}",
SKILL.path(&root).display()
);
for asset in &SKILLS {
let path = asset.path(&root);
assert!(
path.ends_with(format!(".claude/skills/{}/SKILL.md", asset.name)),
"{}",
path.display()
);
}
}
/// Two documents that install to one path means the second silently replaces the
/// first, and only whichever is listed last is ever read. A copy-pasted `relative`
/// is exactly how that happens.
#[test]
fn no_two_shipped_skills_share_a_name_or_a_path() {
for (index, asset) in SKILLS.iter().enumerate() {
for other in &SKILLS[index + 1..] {
assert_ne!(asset.name, other.name);
assert_ne!(asset.relative, other.relative);
}
}
}
#[test]
fn the_embedded_skill_has_usable_frontmatter() {
fn every_embedded_skill_has_usable_frontmatter() {
// Guards the whole shipping mechanism: without frontmatter, or under a name
// that does not match its directory, both agents ignore the document and
// nothing else would notice.
assert_eq!(frontmatter_field(SKILL.content, "name").as_deref(), Some("worklane"));
for asset in &SKILLS {
assert_eq!(
frontmatter_field(asset.content, "name").as_deref(),
Some(asset.name),
"the frontmatter name has to match the directory it installs into"
);
let description =
frontmatter_field(SKILL.content, "description").expect("a description to trigger on");
assert!(
description.len() > 80,
"the description is what decides whether the skill loads at all"
);
let description =
frontmatter_field(asset.content, "description").unwrap_or_else(|| {
panic!("{} ships without a description to trigger on", asset.name)
});
assert!(
description.len() > 80,
"{}: the description is what decides whether the skill loads at all",
asset.name
);
}
}
/// Every code span and fenced-block line, which is where commands live.
@@ -209,7 +374,7 @@ mod tests {
}
#[test]
fn the_embedded_skill_only_names_commands_that_exist() {
fn no_embedded_skill_names_a_command_that_does_not_exist() {
// Taken from clap rather than written out here. A hand-maintained list is the
// very drift this test exists to catch.
use clap::CommandFactory;
@@ -220,34 +385,50 @@ mod tests {
known.push("--help".to_string());
known.push("--version".to_string());
let mut checked = 0;
for snippet in code_snippets(SKILL.content) {
let mut words = snippet.split_whitespace();
// Only a snippet that *starts* with worklane is a command being shown.
if words.next() != Some("worklane") {
continue;
let mut total = 0;
for asset in &SKILLS {
let mut checked = 0;
for snippet in code_snippets(asset.content) {
let mut words = snippet.split_whitespace();
// Only a snippet that *starts* with worklane is a command being shown.
if words.next() != Some("worklane") {
continue;
}
let Some(candidate) = words.next() else {
continue;
};
// A flag before the subcommand, as in the `mv -- -leading-title` example.
if candidate.starts_with("--") && !known.iter().any(|k| k == candidate) {
continue;
}
checked += 1;
assert!(
known.iter().any(|k| k == candidate),
"{} shows `worklane {candidate}`, which is not a subcommand",
asset.name
);
}
let Some(candidate) = words.next() else { continue };
// A flag before the subcommand, as in the `mv -- -leading-title` example.
if candidate.starts_with("--") && !known.iter().any(|k| k == candidate) {
continue;
}
checked += 1;
assert!(
known.iter().any(|k| k == candidate),
"the skill shows `worklane {candidate}`, which is not a subcommand"
);
// A skill that shows no command at all is either not about worklane or has
// had its examples emptied out, and either way the check above passed on
// nothing.
assert!(checked > 0, "{} shows no worklane command at all", asset.name);
total += checked;
}
assert!(checked > 8, "expected the skill to show commands, checked only {checked}");
assert!(total > 8, "expected the skills to show commands, checked only {total}");
}
/// Subcommands the skill has no business teaching: the board is interactive and
/// belongs to a person, `install-skill` is how the document arrived, and `help`
/// is clap's own.
const NOT_FOR_AGENTS: [&str; 3] = ["tui", "install-skill", "help"];
const NOT_FOR_AGENTS: [&str; 4] = ["tui", "install-skill", "install-tool", "help"];
/// The converse, and the one that goes stale on its own: a *new* subcommand absent
/// from the skill is invisible to an agent, and nothing else would notice.
///
/// `SKILL` alone, deliberately. It is the document that owns the CLI surface, and
/// the others teach one job with the handful of commands that job uses. Requiring
/// every subcommand of each of them would fill a review document with campaigns
/// and `init` to satisfy a test.
#[test]
fn every_agent_facing_subcommand_is_documented() {
use clap::CommandFactory;
@@ -279,4 +460,154 @@ mod tests {
);
}
}
/// The rules that keep a grooming sweep from being a silent rewrite of the board.
///
/// Every one of these is a line an edit could drop while leaving a document that
/// still reads like a plan: `set --tags` replacing the whole field is how thirty
/// tickets quietly lose their tags, and propose-then-apply is the only thing
/// standing between a wrong judgement and thirty wrong tickets.
#[test]
fn the_plan_skill_keeps_the_rules_that_bound_a_sweep() {
for required in [
"Propose the whole set of edits",
"replaces the whole\nfield", // `set --tags` is the destructive one
"not\nback to what it held", // and --clear is not an undo
"blocked by", // ordering constrains any dating plan
"worklane campaign ls",
"does not touch",
] {
assert!(
PLAN_SKILL.content.contains(required),
"the plan skill no longer says {required:?}"
);
}
}
/// What makes the admin document usable on a board that tracks no software, and what
/// keeps its repairs honest.
///
/// The domain examples are the first thing an edit would quietly drop, since every
/// other skill here is written around this repo, and dropping them leaves a document
/// that teaches a household board to file `cli` tickets. The two-step repair is the
/// second: it looks like a typo until you have watched `mv` refuse the one-step
/// version, which is why the ticket for this skill demanded every repair be run rather
/// than reasoned about.
#[test]
fn the_admin_skill_stays_domain_neutral_and_keeps_its_verified_repairs() {
for required in [
"household", // the vocabulary section spans three subjects
"product strategy", //
"worklane tags add", // the vocabulary is declared through the CLI
"--tags` replaces the whole field", // the destructive one, restated where it bites
"two moves, not one", // the repair `mv` cannot do in one step
"do not edit a ticket file",
"File exception", // and the three places that rule does not reach
"worklane-plan", // the boundary against the sweep document
] {
assert!(
ADMIN_SKILL.content.contains(required),
"the admin skill no longer says {required:?}"
);
}
}
/// The decisions that make the review document a review rather than a rewrite.
///
/// Each of these is a rule an edit would drop without breaking anything else: a
/// reviewer that ticks criteria or moves the ticket still runs, and produces a
/// board where nothing records that anyone disagreed.
#[test]
fn the_review_skill_keeps_the_decisions_that_define_it() {
for required in [
"worklane show", // the ticket is read before the code
"nothing names the ticket", // and the no-work-found case is answered
"Never tick a criterion",
"Do not move the ticket",
"worklane uncheck",
"worklane append",
"cannot tell",
] {
assert!(
REVIEW_SKILL.content.contains(required),
"the review skill no longer says {required:?}"
);
}
}
// ------------------------------------------------------------ the tool --
/// `XDG_CONFIG_HOME` wins, because it is what opencode itself resolves its config
/// root from: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with it set.
#[test]
fn the_tool_root_follows_xdg_config_home_when_it_is_set() {
let root = opencode_tool_dir(Some(Path::new("/tmp/xdg")), Some(Path::new("/home/x")));
assert_eq!(root.unwrap(), Path::new("/tmp/xdg/opencode/tool"));
}
/// An empty value counts as unset, the convention `colors_wanted` already follows, so
/// a wrapper script that cleared an inherited one still lands in the home directory
/// rather than at `/opencode/tool`.
#[test]
fn an_empty_xdg_config_home_falls_back_to_the_home_directory() {
let root = opencode_tool_dir(Some(Path::new("")), Some(Path::new("/home/x")));
assert_eq!(root.unwrap(), Path::new("/home/x/.config/opencode/tool"));
let unset = opencode_tool_dir(None, Some(Path::new("/home/x")));
assert_eq!(unset.unwrap(), Path::new("/home/x/.config/opencode/tool"));
}
/// Neither one set is the case that has to fail rather than guess: writing to a
/// relative `.config/opencode/tool` would put the tool wherever the caller happened
/// to be standing.
#[test]
fn neither_variable_set_is_an_error_rather_than_a_relative_path() {
let error = opencode_tool_dir(None, None).unwrap_err().to_string();
assert!(error.contains("XDG_CONFIG_HOME"), "{error}");
assert!(error.contains("HOME"), "{error}");
}
/// The file name is the tool id prefix, not decoration: opencode names each tool as
/// the file then the export, so a renamed file renames all eleven tools and every
/// permission rule that mentions one.
#[test]
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
let root = opencode_tool_dir(None, Some(Path::new("/home/x"))).unwrap();
assert_eq!(TOOL.path(&root), Path::new("/home/x/.config/opencode/tool/worklane.ts"));
assert_eq!(TOOL.relative, "worklane.ts");
}
/// Every tool the file exports names a real subcommand.
///
/// The guard the fish completion lists already have, pointed the other way: this
/// catches a tool wrapping a command that has been renamed or dropped, which would
/// fail only when an agent finally called it. It cannot catch the reverse, a
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
#[test]
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
use clap::CommandFactory;
let commands: Vec<String> = crate::Cli::command()
.get_subcommands()
.map(|command| command.get_name().to_string())
.collect();
let exported: Vec<&str> = TOOL
.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect();
assert_eq!(exported.len(), 11, "{exported:?}");
for name in exported {
assert!(
commands.iter().any(|command| command == name),
"the wrapper exports {name:?}, which is not a subcommand: {commands:?}"
);
}
}
}
+110 -29
View File
@@ -1,9 +1,13 @@
use anyhow::Result;
use clap::Parser;
mod campaign;
mod clipboard;
mod command;
mod completions;
mod handlers;
mod install;
mod tag;
mod tui;
mod util;
@@ -44,33 +48,62 @@ fn main() -> Result<()> {
Some(Command::Tui { paths }) => run_tui(&paths, &start),
Some(Command::Init) => cmd_init(&start),
Some(Command::Add(args)) => cmd_add(&args, &start),
Some(Command::Ls { status, priority }) => {
Some(Command::Ls(args)) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_ls(&status, priority, &worklane_dir)
cmd_ls(&args, &worklane_dir)
}
Some(Command::Show { id }) => {
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 }) => cmd_mv(&ticket, status, force, &start),
Some(Command::Set(args)) => cmd_set(&args, &start),
Some(Command::Append(args)) => cmd_append(&args, &start),
Some(Command::Relate(args)) => cmd_relate(&args, &start),
Some(Command::Chown { user, ticket }) => cmd_chown(&user, &ticket, &start),
Some(Command::Chown(args)) => cmd_chown(&args, &start),
Some(Command::Check(args)) => cmd_check(&args, true, &start),
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
Some(Command::Comment {
ticket,
body,
owner,
}) => cmd_comment(&ticket, &body, &owner, &start),
Some(Command::Comment { ticket, body, owner }) => {
cmd_comment(&ticket, &body, &owner, &start)
}
Some(Command::Campaign { command }) => match command {
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
CampaignCommand::Ls { ids } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_ls(&worklane_dir, ids)
}
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start),
CampaignCommand::Show { campaign } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_show(&campaign, &worklane_dir)
}
},
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &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.
Some(Command::Tags { command }) => match command {
None | Some(TagCommand::Ls) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir)
}
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start),
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start),
},
// No board either, for the reason `install-skill` has none: a completion script
// is generated from the clap definition and is the same wherever it is run.
Some(Command::Completions { shell }) => {
completions::generate(shell, &mut std::io::stdout()).map_err(Into::into)
}
// No board is looked for: the point of the skill is to teach an agent worklane
// before there is a `.worklane` anywhere.
Some(Command::InstallSkill { force, print }) => cmd_install_skill(force, print),
Some(Command::InstallSkill { skill, force, print }) => {
cmd_install_skill(skill.as_deref(), force, print)
}
// No board either, and one agent rather than both: opencode loads the tool file,
// Claude Code has no path for one.
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print),
}
}
@@ -90,10 +123,7 @@ fn install_panic_hook() {
fn restore_terminal() -> std::io::Result<()> {
crossterm::terminal::disable_raw_mode()?;
crossterm::execute!(
std::io::stdout(),
crossterm::terminal::LeaveAlternateScreen
)
crossterm::execute!(std::io::stdout(), crossterm::terminal::LeaveAlternateScreen)
}
fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()> {
@@ -144,27 +174,60 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
continue;
}
// Every keypress takes away what the last one said, so a notice never
// outlives the moment it belongs to. Ahead of the prompt as well as the
// arms: a key typed into a query is still a key. The rule is
// `Board::clear_notice`, where a test can reach it, and the arm below that
// sets one runs after this.
board.clear_notice();
// Ahead of the arms, because a prompt has to swallow every key it is
// given: typing `d` into a query must not toggle the done column and `q`
// must not quit. It reports what it took, so the arms below stay a plain
// match on the keys it did not, and it takes nothing when no prompt is open.
// The rule is `Board::search_key`, where a test can reach it.
if board.search_key(key, screen) {
continue;
}
// The same contract for the campaign picker, which is the other mode that owns
// the keyboard while it is open. Two calls rather than one combined pre-branch,
// because only one of the two can be open at a time and each reports for
// itself; the rules are `Board::search_key` and `Board::picker_key`, where a
// test can reach them.
if board.picker_key(key, screen) {
continue;
}
match key.code {
KeyCode::Char('q') => board.should_quit = true,
// One arm, because the two keys mean one thing: close what is open, and
// quit when there is nothing left to close. Two arms carrying one rule
// is how a later edit changes it for one key and not the other, which is
// what `q` quitting out from under an open ticket already was. The rule
// itself is `Board::dismiss`, where a test can reach it.
KeyCode::Esc | KeyCode::Char('q') => board.dismiss(screen),
// The only key that leaves the board from an open ticket, which is why
// the footer names it there.
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
board.should_quit = true
}
// Esc closes the detail view, and only quits when there is nothing
// left to dismiss.
KeyCode::Esc => match board.detail {
Some(_) => board.toggle_detail(),
None => board.should_quit = true,
},
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(),
// The frame's own height while it holds the selection, and the detail
// overlay on a card. `Board::toggle_focused` rather than a condition here,
// for the reason the scroll keys route there.
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_focused(screen),
KeyCode::Left | KeyCode::Char('h') => board.select_column(-1, screen),
KeyCode::Right | KeyCode::Char('l') => board.select_column(1, screen),
// Up and down stay on the selection, open detail view or not, so a
// column can be read through without closing the modal. Scrolling the
// open ticket is a page at a time.
// open ticket is a page at a time, and so is scrolling the campaign
// frame that up reaches from the top card of a column.
KeyCode::Up | KeyCode::Char('k') => board.select_card(-1, screen),
KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen),
KeyCode::PageUp => board.scroll_detail(-1, screen),
KeyCode::PageDown => board.scroll_detail(1, screen),
// The open ticket first and the campaign frame behind it, which is
// `Board::scroll_page` rather than a condition written here: the arms in
// this dispatch are not reachable from a test.
KeyCode::PageUp => board.scroll_page(-1, screen),
KeyCode::PageDown => board.scroll_page(1, screen),
// Tabs cycle rather than clamp, the way tabs everywhere do, and are
// a no-op with a single board. Free of every other binding: the
// columns took hjkl and the arrows.
@@ -172,6 +235,24 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
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),
// 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
// at an open picker is taken by `picker_key` to open the picker's own
// query, so this arm is only ever the way in to the board's prompt.
KeyCode::Char('/') => board.open_search(),
// `y` as in yank, for the readers this board is for, and the only letter
// left that a vim hand would reach for. The clipboard is handed in rather
// than reached for inside `Board`, so the suite can drive both answers.
KeyCode::Char('y') => board.copy_selected_id(clipboard::copy),
// The way in to the campaign picker, like `/` is to the search prompt: from
// the next keypress on `picker_key` above has the keyboard. Free of every
// other binding, and `ctrl-c` is matched above this so quitting still wins.
KeyCode::Char('c') => board.open_picker(tui::PickerKind::Campaign, screen),
// The other axis the board is cut along, and the one `ls --tag` has
// answered since 2f3796e. Free of every other binding: `tab` is its own
// key code, not this letter.
KeyCode::Char('t') => board.open_picker(tui::PickerKind::Tag, screen),
_ => {}
}
}
+361
View File
@@ -0,0 +1,361 @@
//! The tag vocabulary: which tags the board declares, and what each one means.
//!
//! One file, `.worklane/tags.md`, beside the status directories rather than among them,
//! for the reason the campaigns directory sits there: a tag has no status. One section
//! per tag, the tag as the heading and its annotation as the prose under it, so the file
//! reads as a document to whoever opens it and parses by heading to the CLI.
//!
//! **Declaring a tag tags no ticket, and tagging a ticket declares nothing.** This is a
//! vocabulary and not an index of what carries what: the counts stay derived from the
//! status directories, where `cmd_tags` already reads them. So the file and the board can
//! disagree, and that disagreement is the point — a tag carried but never declared is a
//! word nobody agreed to, which is what `campaign` and `campaigns` on this board were.
//!
//! Unlike a campaign, a tag has no uuid and no file of its own. It *is* its name, which is
//! what `ls --tag` matches whole and case sensitively, so the name is the key here and
//! there is nothing to resolve by prefix.
use anyhow::{Result, anyhow};
use std::collections::BTreeMap;
use std::fs;
use std::path::{Path, PathBuf};
use crate::util::trim_blank_ends;
/// The vocabulary file, beside the status directories rather than among them.
pub const TAGS_FILE: &str = "tags.md";
pub fn tags_path(worklane_dir: &Path) -> PathBuf {
worklane_dir.join(TAGS_FILE)
}
/// What one tag's heading looks like, and therefore what an annotation may not start a
/// line with.
///
/// Public so the `--annotation` parser refuses the one line that would split a section,
/// rather than carrying its own copy of the spelling. Two places knowing what a heading
/// is, is how the file comes to be written in a shape it cannot be read back in.
pub const SECTION: &str = "## ";
/// What a tag declared with nothing to say about it writes.
///
/// A placeholder rather than an empty section, for the reason `add` writes one into an
/// empty Description: a heading with nothing under it reads as a file that failed to
/// write, and the round trip has nothing to be right about.
pub const NO_ANNOTATION: &str = "_No annotation provided._";
/// The heading the file opens with. Not a tag: [`tag_heading`] only reads level two.
const TITLE: &str = "# Tags";
/// What the file says for itself, for whoever opens it rather than for the parser.
///
/// Re-rendered on every write, so it is present whether `init` made the file or
/// `tags add` did. It says what declaring does and does not do, because the file's one
/// real trap is reading it as the list of tags in use.
const PREAMBLE: &str = "\
What each tag on this board means, and when it is appropriate to reach for it. Declaring a
tag here tags nothing: the counts come from the tickets themselves, and `worklane tags` is
what reports them. Written by `worklane tags`, not by hand.";
/// The tag a level-two heading names, or nothing for any other line.
///
/// Exactly two hashes. A `### ` line inside an annotation is prose about the tag it sits
/// under and not the start of another one, which a bare `strip_prefix` would read as a tag
/// called `# something`.
fn tag_heading(line: &str) -> Option<&str> {
let rest = line.strip_prefix(SECTION)?;
match rest.starts_with('#') {
true => None,
false => Some(rest.trim()),
}
}
/// The board's declared tags, each with what it means.
///
/// A `BTreeMap` rather than a `Vec`: the order is alphabetical by byte, which is the order
/// `cmd_tags` already prints in, so `Bug` and `bug` stay two entries and land next to each
/// other. Near-duplicates being adjacent is the property the whole file is for.
///
/// An annotation of `""` is a tag declared with nothing said about it, which is why the
/// placeholder is a rendering detail rather than a value anything holds.
#[derive(Default)]
pub struct TagIndex {
tags: BTreeMap<String, String>,
}
impl TagIndex {
/// The vocabulary as the file declares it.
///
/// A missing file is an empty vocabulary and not an error: every board made before this
/// existed has none, and refusing there would mean a `worklane init` over a live board
/// just to get a file.
///
/// An *unreadable* file is an error, which is the opposite of what [`CampaignIndex`]
/// does with its directory, and deliberately. The whole file is re-rendered on every
/// write, so treating one that is there as empty would erase every tag in it on the
/// next `tags add`. A campaign index that comes back empty loses a label on a card;
/// this one would lose the file.
///
/// [`CampaignIndex`]: crate::campaign::CampaignIndex
pub fn load(worklane_dir: &Path) -> Result<Self> {
let path = tags_path(worklane_dir);
if !path.exists() {
return Ok(Self::default());
}
let content = fs::read_to_string(&path).map_err(|e| {
anyhow!("Could not read the tag vocabulary at {}: {}", path.display(), e)
})?;
Ok(Self::parse(&content))
}
/// The vocabulary out of the file's text.
///
/// Everything above the first tag heading is prose for whoever opens the file and is
/// dropped: the title, the preamble, and anything else that ended up there. A heading
/// with no tag in it starts nothing, and the lines under it belong to no tag, so a
/// damaged file loses that section rather than attaching it to the tag above.
pub fn parse(content: &str) -> Self {
let mut tags = BTreeMap::new();
let mut open: Option<(String, Vec<String>)> = None;
for line in content.lines() {
match tag_heading(line) {
Some(tag) => {
if let Some((held, body)) = open.take() {
tags.insert(held, annotation(&body));
}
if !tag.is_empty() {
open = Some((tag.to_string(), Vec::new()));
}
}
None => {
if let Some((_, body)) = &mut open {
body.push(line.to_string());
}
}
}
}
if let Some((held, body)) = open {
tags.insert(held, annotation(&body));
}
Self { tags }
}
/// Whether the file already declares this tag, matched whole and case sensitively, the
/// way `ls --tag` matches it.
pub fn declared(&self, tag: &str) -> bool {
self.tags.contains_key(tag)
}
/// Every tag the file declares, alphabetical, whatever the board carries.
///
/// The half of the listing the status directories cannot answer. A tag declared and
/// never applied is carried by no ticket, so counting alone drops it, and that tag is
/// most of the reason the file exists: a word the board agreed on and nobody has
/// reached for yet is exactly what a grooming sweep wants to see.
pub fn names(&self) -> impl Iterator<Item = &str> {
self.tags.keys().map(String::as_str)
}
/// What a tag means, whole, or `None` for a tag the file does not declare.
///
/// The raw section, paragraphs and all, where [`Self::summary`] is the one line a
/// listing has room for. `Some("")` is a tag declared with nothing said about it, which
/// the caller has to tell apart from `None`: the board draws the two in different
/// sections.
pub fn annotation(&self, tag: &str) -> Option<&str> {
self.tags.get(tag).map(String::as_str)
}
/// The opening line of what a tag means, or `None` for a tag the file does not declare.
///
/// The cut to one line lives here rather than on the parse, the way
/// [`CampaignRow::summary`] takes one line off a description the read carries whole:
/// the annotation is prose with paragraphs in it, and which view wants how much of it
/// is the view's business.
///
/// **`None` is what marks a carried but undeclared tag**, since `cmd_tags` prints no
/// third field for it. Nothing is appended to the tag itself and nothing is added to
/// the count, so `cut -f1` still yields the tag values and a board with no file at all
/// lists what it listed before the file existed.
///
/// A declared tag with nothing said about it answers [`NO_ANNOTATION`] rather than an
/// empty string, because an empty third field is a trailing tab and nothing else: it
/// would be the only difference between declared and not, and it would be invisible in
/// a terminal and in a completion alike. The placeholder is also what the file itself
/// holds under that heading, so the field stays the section's opening line either way.
///
/// [`CampaignRow::summary`]: crate::tui::CampaignRow::summary
/// [`NO_ANNOTATION`]: crate::tag::NO_ANNOTATION
pub fn summary(&self, tag: &str) -> Option<&str> {
let annotation = self.tags.get(tag)?;
Some(match annotation.lines().next() {
Some(line) => line,
None => NO_ANNOTATION,
})
}
/// Declare `tag`, or replace what it means.
///
/// One writer for both, because the file holds one section per tag either way and the
/// question of whether a caller may overwrite is the caller's: `tags add` refuses a tag
/// already declared, and `tags set` refuses one that is not.
pub fn declare(&mut self, tag: &str, annotation: &str) {
self.tags.insert(tag.to_string(), annotation.to_string());
}
/// The whole file, rendered from the whole vocabulary.
///
/// Every write goes through here rather than splicing one section in place, which is
/// what keeps the file canonical: alphabetical, one blank line between sections, and
/// the preamble present however the file came to exist. The cost is that nothing
/// hand-written above the first heading survives a write, which is the bargain every
/// file under `.worklane/` already makes — the CLI is its only writer.
pub fn render(&self) -> String {
let mut out = format!("{TITLE}\n\n{PREAMBLE}\n");
for (tag, annotation) in &self.tags {
let body = match annotation.is_empty() {
true => NO_ANNOTATION,
false => annotation,
};
out.push_str(&format!("\n{SECTION}{tag}\n{body}\n"));
}
out
}
}
/// One section's prose, with the blank lines around it dropped and the placeholder read
/// back as nothing.
///
/// Through `trim_blank_ends`, the same function that decides where a ticket's description
/// starts and ends, so a blank line inside an annotation is kept and one at either end is
/// not.
fn annotation(body: &[String]) -> String {
let text = trim_blank_ends(body).join("\n");
match text == NO_ANNOTATION {
true => String::new(),
false => text,
}
}
#[cfg(test)]
mod tests {
use super::*;
/// What a tag holds, read back out of the file it was written into. The round trip is
/// the property that matters: nothing else keeps the writer and the parser agreeing on
/// what a section is.
fn round_trip(tag: &str, annotation: &str) -> String {
let mut index = TagIndex::default();
index.declare(tag, annotation);
let read = TagIndex::parse(&index.render());
read.tags
.get(tag)
.cloned()
.expect("the tag did not survive the round trip")
}
#[test]
fn an_annotation_survives_the_round_trip() {
assert_eq!(
round_trip("bug", "Something the binary does wrong."),
"Something the binary does wrong."
);
}
/// A blank line inside an annotation is a paragraph break and is kept, which is what
/// `trim_blank_ends` is doing here rather than a blanket trim.
#[test]
fn a_paragraph_break_inside_an_annotation_is_kept() {
assert_eq!(round_trip("bug", "One.\n\nTwo."), "One.\n\nTwo.");
}
/// A tag declared with nothing to say writes the placeholder and reads back as nothing,
/// so the file never holds a heading with a blank under it and nothing ever holds the
/// placeholder as if it were prose.
#[test]
fn a_tag_with_no_annotation_writes_the_placeholder_and_reads_back_empty() {
let mut index = TagIndex::default();
index.declare("cli", "");
let rendered = index.render();
assert!(rendered.contains(NO_ANNOTATION), "{rendered}");
assert_eq!(TagIndex::parse(&rendered).tags["cli"], "");
}
/// Byte order, so `Bug` and `bug` are two tags and sit next to each other. The same
/// order `tags` prints in, and the reason the file is worth reading at all: a
/// near-duplicate is spotted by being adjacent to what it duplicates.
#[test]
fn the_file_is_alphabetical_and_keeps_case_apart() {
let mut index = TagIndex::default();
for tag in ["tui", "bug", "Bug", "cli"] {
index.declare(tag, "");
}
let rendered = index.render();
let headings: Vec<&str> = rendered.lines().filter_map(tag_heading).collect();
assert_eq!(headings, vec!["Bug", "bug", "cli", "tui"]);
}
/// Everything above the first heading is for whoever opens the file. The preamble says
/// `## ` nowhere, but a parser that took the title for a tag would declare one called
/// `Tags` on the next write.
#[test]
fn the_prose_above_the_first_heading_declares_nothing() {
let index = TagIndex::parse(&TagIndex::default().render());
assert!(index.tags.is_empty(), "the preamble declared a tag");
}
/// A deeper heading is prose about the tag it sits under. `strip_prefix` alone read it
/// as a tag called `# whatever`, which then became a real section on the next write.
#[test]
fn a_deeper_heading_inside_an_annotation_is_not_a_tag() {
let index = TagIndex::parse("# Tags\n\n## bug\nProse.\n\n### An aside\nMore prose.\n");
assert_eq!(index.tags.len(), 1, "a sub-heading was read as a tag");
assert_eq!(index.tags["bug"], "Prose.\n\n### An aside\nMore prose.");
}
/// A heading naming nothing starts no section, and takes the lines under it with it
/// rather than attaching them to the tag above.
#[test]
fn an_empty_heading_declares_nothing_and_swallows_its_own_body() {
let index = TagIndex::parse("## bug\nProse.\n\n## \nOrphaned.\n");
assert_eq!(index.tags.len(), 1);
assert_eq!(index.tags["bug"], "Prose.");
}
/// A board that never had the file has an empty vocabulary rather than an error: every
/// board made before this existed is in that state.
#[test]
fn a_board_with_no_file_has_no_tags() {
let dir = tempfile::tempdir().unwrap();
assert!(TagIndex::load(dir.path()).unwrap().tags.is_empty());
}
/// And a file that is there but cannot be read is an error, not an empty vocabulary.
/// The whole file is re-rendered on every write, so empty here would mean erased on the
/// next `tags add`.
#[test]
fn a_file_that_cannot_be_read_is_an_error_rather_than_an_empty_vocabulary() {
let dir = tempfile::tempdir().unwrap();
// A directory where the file should be: `read_to_string` fails on it, which a
// missing file does not, so this is the path the error is actually for.
fs::create_dir(tags_path(dir.path())).unwrap();
assert!(TagIndex::load(dir.path()).is_err());
}
}
+6882 -217
View File
File diff suppressed because it is too large Load Diff
+2780 -216
View File
File diff suppressed because it is too large Load Diff
+187 -20
View File
@@ -1,6 +1,6 @@
use assert_cmd::Command;
use assert_fs::fixture::{PathChild, PathCreateDir};
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
@@ -106,9 +106,12 @@ fn add_joins_multiple_descriptions() {
cmd.current_dir(temp.path())
.args([
"add",
"--title", "Multi desc ticket",
"--description", "Line one",
"--description", "Line two",
"--title",
"Multi desc ticket",
"--description",
"Line one",
"--description",
"Line two",
])
.assert()
.success();
@@ -285,10 +288,7 @@ fn add_accepts_prose_values_that_begin_with_a_hyphen() {
// Stored verbatim, hyphens and all
assert!(content.contains("# -t is a flag name"), "was {content:?}");
assert!(content.contains("-x does nothing"), "was {content:?}");
assert!(
content.contains("- [ ] --print should be supported"),
"was {content:?}"
);
assert!(content.contains("- [ ] --print should be supported"), "was {content:?}");
assert!(content.contains("1. -f skips the check"), "was {content:?}");
}
@@ -308,10 +308,7 @@ fn add_still_accepts_the_equals_form() {
let content = only_ticket(&worklane);
assert!(content.contains("# -x equals form"), "was {content:?}");
assert!(
content.contains("- [ ] --print via equals"),
"was {content:?}"
);
assert!(content.contains("- [ ] --print via equals"), "was {content:?}");
}
/// Never silently dropped: a value that is nothing but hyphens is content.
@@ -328,10 +325,7 @@ fn add_stores_a_title_that_is_only_hyphens() {
.success();
let content = only_ticket(&worklane);
assert!(
content.starts_with(&format!("# {}\n", bare)),
"for {bare:?}: {content:?}"
);
assert!(content.starts_with(&format!("# {}\n", bare)), "for {bare:?}: {content:?}");
}
}
@@ -408,10 +402,7 @@ fn add_keeps_a_paragraph_break_in_the_description() {
let mut show = Command::cargo_bin(BIN_NAME).unwrap();
show.current_dir(temp.path()).args(["show", "Two Paras"]);
let stdout = String::from_utf8(show.assert().success().get_output().stdout.clone()).unwrap();
assert!(
stdout.contains("First paragraph.\n\nSecond paragraph."),
"was {stdout:?}"
);
assert!(stdout.contains("First paragraph.\n\nSecond paragraph."), "was {stdout:?}");
}
/// A break belongs between paragraphs, not against the section headings.
@@ -457,3 +448,179 @@ fn add_treats_an_all_blank_description_as_none() {
"was {content:?}"
);
}
/// The help, the README and the skill all promise `YYYY-MM-DD`, and until this the
/// value was written to the ticket whatever it said.
#[test]
fn add_stores_a_valid_due_date_unchanged() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.arg("add")
.args(["--title", "Dated"])
.args(["--due", "2026-08-29"])
.assert()
.success();
let content = read_only_ticket(&worklane.join("backlog"));
assert!(content.contains("- **Due**: 2026-08-29"), "{content}");
}
/// Every one of these is refused at parse time, so the exit code is 2 and nothing is
/// written. A date that cannot happen is as wrong as a word: `2026-02-30` has the shape
/// and is not a day.
#[test]
fn add_refuses_a_due_date_that_is_not_a_real_iso_date() {
for value in [
"next friday",
"29-08-2026",
"2026-13-01",
"2026-02-30",
"2026/08/29",
"",
] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let out = cmd
.current_dir(temp.path())
.arg("add")
.args(["--title", "Dated"])
.args(["--due", value])
.assert()
.failure()
.get_output()
.clone();
assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error");
assert_eq!(
fs::read_dir(worklane.join("backlog")).unwrap().count(),
0,
"{value:?} wrote a ticket anyway"
);
}
}
/// An unpadded date parses as a date and would be stored as typed, which sorts before
/// `2026-10-01` and is not the format anything promises.
#[test]
fn add_refuses_an_unpadded_due_date_rather_than_padding_it() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let stderr = String::from_utf8_lossy(
&cmd.current_dir(temp.path())
.arg("add")
.args(["--title", "Dated"])
.args(["--due", "2026-8-9"])
.assert()
.failure()
.get_output()
.stderr,
)
.to_string();
assert!(stderr.contains("YYYY-MM-DD"), "the error never names the format: {stderr}");
}
/// An empty value keeps the message about clearing, since that is what somebody typing
/// it is reaching for. On `add` the answer is to omit the flag, but the message names
/// `--clear` because the same parser guards `set --due`, where that is the answer.
#[test]
fn an_empty_due_date_points_at_clear() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let stderr = String::from_utf8_lossy(
&cmd.current_dir(temp.path())
.arg("add")
.args(["--title", "Dated"])
.args(["--due", ""])
.assert()
.failure()
.get_output()
.stderr,
)
.to_string();
assert!(stderr.contains("use --clear"), "{stderr}");
assert!(!stderr.contains("not supported"), "{stderr}");
}
fn read_only_ticket(dir: &Path) -> String {
let file = fs::read_dir(dir)
.unwrap()
.filter_map(|e| e.ok())
.find(|e| e.path().extension().is_some_and(|ext| ext == "md"))
.expect("no ticket written");
fs::read_to_string(file.path()).unwrap()
}
fn chmod(path: &Path, mode: u32) {
use std::os::unix::fs::PermissionsExt;
let mut perms = fs::metadata(path).unwrap().permissions();
perms.set_mode(mode);
fs::set_permissions(path, perms).unwrap();
}
/// A duplicate title is not a failure, so the only thing left to refuse is the write
/// itself, and it is named with the ticket and the path rather than raised as a bare io
/// error. The branch this replaces could not fire at all: the filename carries a fresh
/// uuid, and its message claimed the title was taken.
#[test]
fn add_names_the_ticket_and_the_path_when_the_write_fails() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let backlog = worklane.join("backlog");
chmod(&backlog, 0o555);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd
.current_dir(temp.path())
.args(["add", "--title", "Unwritable"])
.assert()
.failure();
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("Unwritable"), "{stderr}");
assert!(stderr.contains("unwritable.md"), "{stderr}");
assert!(!stderr.contains("already exists"), "{stderr}");
chmod(&backlog, 0o755);
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
}
/// The board above the project is real and empty, and stays empty: a dangling
/// `.worklane` link used to read as no board here, and the walk then wrote the
/// ticket into whatever board sat above it.
#[test]
fn add_writes_nothing_when_the_board_link_does_not_resolve() {
let temp = TempDir::new().unwrap();
let above = setup_worklane(&temp);
let project = temp.child("project");
project.create_dir_all().unwrap();
let target = temp.path().join("boards/2fed877-the-board");
std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd
.current_dir(project.path())
.args(["add", "--title", "Should not land"])
.assert()
.failure();
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains(&target.display().to_string()), "{stderr}");
assert!(stderr.contains("boards repo"), "{stderr}");
assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0);
}
File diff suppressed because it is too large Load Diff
+270 -4
View File
@@ -53,6 +53,43 @@ fn create_ticket(worklane: &Path) {
.unwrap();
}
/// A second ticket whose criteria carry the word `all`, so the keyword's precedence
/// can be pinned without renumbering the shared fixture.
const ALL_UUID: &str = "6b1f9c22-0d4e-4a1b-9f37-2c85ab4d1e70";
fn create_all_in_text_ticket(worklane: &Path) {
let lines = [
"# All in the text",
"",
"## Acceptance Criteria",
"- [ ] all the boxes are listed",
"- [ ] the footer is drawn",
"",
"## Metadata",
"",
&format!("- **ID**: {}", ALL_UUID),
"- **Status**: backlog",
"",
];
fs::write(
worklane
.join("backlog")
.join(format!("{}_all-in-the-text.md", ALL_UUID)),
lines.join("\n"),
)
.unwrap();
}
fn all_in_text_ticket(worklane: &Path) -> String {
fs::read_to_string(
worklane
.join("backlog")
.join(format!("{}_all-in-the-text.md", ALL_UUID)),
)
.unwrap()
}
fn run(temp: &TempDir, args: &[&str]) -> std::process::Output {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(args);
@@ -261,10 +298,7 @@ fn show_numbers_the_criteria() {
assert!(!stdout.contains("4. ["), "the handwritten line was numbered: {stdout:?}");
// And the description checkbox is left as it is, outside the numbering
assert!(
stdout.contains("- [ ] A checkbox in the description"),
"{stdout:?}"
);
assert!(stdout.contains("- [ ] A checkbox in the description"), "{stdout:?}");
}
#[test]
@@ -285,3 +319,235 @@ fn check_leaves_nothing_behind() {
.collect();
assert_eq!(strays, Vec::<String>::new());
}
/// The common case the batch exists for: the work is done, every box is true.
#[test]
fn all_ticks_every_criterion() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["check", UUID, "all"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- [x] alpha shared\n"), "{content}");
assert!(content.contains("- [x] beta alone\n"), "{content}");
assert!(content.contains("- [x] gamma shared\n"), "{content}");
// beta was already ticked, so it is reported unchanged rather than as a new mark
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Checked 1: alpha shared"), "{stdout:?}");
assert!(stdout.contains("Already checked 2: beta alone"), "{stdout:?}");
assert!(stdout.contains("Checked 3: gamma shared"), "{stdout:?}");
// And nothing outside the section was touched
assert!(
content.contains("- [ ] A checkbox in the description, which is not a criterion.\n"),
"the description checkbox was ticked: {content}"
);
assert!(
content.contains(" A handwritten line inside the section.\n"),
"the handwritten line was lost: {content}"
);
}
/// An index and a substring in one call, each addressed by the existing rules.
#[test]
fn one_call_takes_several_mixed_terms() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["check", UUID, "3", "ALPHA"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- [x] alpha shared\n"), "{content}");
assert!(content.contains("- [x] gamma shared\n"), "{content}");
// Reported in show's order whatever order the terms arrived in
let stdout = String::from_utf8_lossy(&out.stdout);
let alpha = stdout.find("Checked 1: alpha");
let gamma = stdout.find("Checked 3: gamma");
assert!(
matches!((alpha, gamma), (Some(alpha), Some(gamma)) if alpha < gamma),
"reported out of order, or one of them is missing: {stdout:?}"
);
}
/// The same criterion named twice, once by number and once by text, is one mark and
/// one line of output.
#[test]
fn a_criterion_named_twice_is_reported_once() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["check", UUID, "1", "alpha", "all"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let stdout = String::from_utf8_lossy(&out.stdout);
assert_eq!(
stdout.matches("alpha shared").count(),
1,
"alpha was reported more than once: {stdout:?}"
);
assert_eq!(
stdout.lines().count(),
3,
"one line per criterion, not per term: {stdout:?}"
);
}
/// Nothing to change, so nothing is written, the way a single already-ticked
/// criterion already behaves.
#[test]
fn a_batch_that_would_change_nothing_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["check", UUID, "all"]);
let before = ticket(&worklane);
let out = run(&temp, &["check", UUID, "all"]);
assert!(out.status.success());
let stdout = String::from_utf8_lossy(&out.stdout);
assert_eq!(stdout.matches("Already checked").count(), 3, "{stdout:?}");
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
}
/// One term that matches nothing refuses the whole call, so the ticket is never left
/// half-marked.
#[test]
fn a_term_matching_nothing_leaves_the_batch_unwritten() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["check", UUID, "1", "nowhere", "3"]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(1));
assert!(stderr.contains("nowhere"), "the term was not named: {stderr:?}");
assert_eq!(ticket(&worklane), before, "alpha was ticked anyway");
}
/// An ambiguous term in a batch is refused the same way a lone one is, and names
/// itself rather than whichever term happened to come first.
#[test]
fn an_ambiguous_term_in_a_batch_names_itself_and_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["check", UUID, "1", "shared"]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(1));
assert!(stderr.contains("'shared' matches 2 criteria"), "{stderr:?}");
assert!(stderr.contains("1. [ ] alpha shared"), "{stderr:?}");
assert!(stderr.contains("3. [ ] gamma shared"), "{stderr:?}");
assert_eq!(ticket(&worklane), before);
}
/// An index out of range in a batch is still a bad index, not a failed text search.
#[test]
fn an_index_out_of_range_in_a_batch_leaves_the_file_untouched() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["check", UUID, "1", "9"]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(1));
assert!(stderr.contains("is not one of the 3 criteria"), "{stderr:?}");
assert_eq!(ticket(&worklane), before);
}
/// The decision this pins: `all` is the keyword, checked before the substring the way
/// the index is, so it ticks every criterion and not the one whose text says "all".
#[test]
fn all_is_the_keyword_and_not_a_substring_of_the_text() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_all_in_text_ticket(&worklane);
run(&temp, &["check", ALL_UUID, "all"]);
let content = all_in_text_ticket(&worklane);
assert!(content.contains("- [x] all the boxes are listed\n"), "{content}");
assert!(
content.contains("- [x] the footer is drawn\n"),
"all matched its own text instead of every criterion: {content}"
);
}
/// And the criterion whose text carries the word is still reachable, by its number or
/// by a longer substring.
#[test]
fn a_criterion_whose_text_contains_all_is_still_reachable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_all_in_text_ticket(&worklane);
run(&temp, &["check", ALL_UUID, "all the boxes"]);
let content = all_in_text_ticket(&worklane);
assert!(content.contains("- [x] all the boxes are listed\n"), "{content}");
assert!(content.contains("- [ ] the footer is drawn\n"), "{content}");
}
#[test]
fn uncheck_takes_all() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["uncheck", UUID, "all"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- [ ] alpha shared\n"), "{content}");
assert!(content.contains("- [ ] beta alone\n"), "{content}");
assert!(content.contains("- [ ] gamma shared\n"), "{content}");
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Unchecked 2: beta alone"), "{stdout:?}");
assert!(stdout.contains("Already unchecked 1: alpha shared"), "{stdout:?}");
}
#[test]
fn uncheck_takes_several_mixed_terms() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["check", UUID, "all"]);
let out = run(&temp, &["uncheck", UUID, "2", "gamma"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- [x] alpha shared\n"), "{content}");
assert!(content.contains("- [ ] beta alone\n"), "{content}");
assert!(content.contains("- [ ] gamma shared\n"), "{content}");
}
#[test]
fn a_failing_term_refuses_an_uncheck_batch_too() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["uncheck", UUID, "2", "nowhere"]);
assert_eq!(out.status.code(), Some(1));
assert_eq!(ticket(&worklane), before, "beta was unticked anyway");
}
+90 -11
View File
@@ -89,11 +89,7 @@ fn chown_sets_the_owner() {
create_ticket(&worklane);
let out = run(&temp, &["chown", "bob", UUID]);
assert!(
out.status.success(),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(
String::from_utf8_lossy(&out.stdout).contains("owner"),
"{:?}",
@@ -139,10 +135,7 @@ fn chown_leaves_everything_it_was_not_asked_about_alone() {
run(&temp, &["chown", "bob", UUID]);
let content = ticket(&worklane);
assert!(
content.contains("- [x] Crit one"),
"the tick was lost: {content}"
);
assert!(content.contains("- [x] Crit one"), "the tick was lost: {content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"the unknown section was lost: {content}"
@@ -213,7 +206,8 @@ fn chown_refuses_a_swapped_call() {
assert_eq!(ticket(&worklane), before);
}
/// An empty user looks like a way to clear the field, and clearing is not supported.
/// An empty user is still a usage error, and now points at the flag that does take the
/// owner away.
#[test]
fn chown_refuses_an_empty_user_as_a_usage_error() {
let temp = TempDir::new().unwrap();
@@ -223,11 +217,96 @@ fn chown_refuses_an_empty_user_as_a_usage_error() {
let out = run(&temp, &["chown", "", UUID]);
assert_eq!(out.status.code(), Some(2));
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("use --clear"), "{stderr:?}");
assert!(!stderr.contains("not supported"), "{stderr:?}");
assert_eq!(ticket(&worklane), before);
}
/// The owner goes back to the sentinel, not to the git user: an owner taken away says
/// nobody owns this.
#[test]
fn chown_clear_returns_the_owner_to_unset() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["chown", "--clear", UUID]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
String::from_utf8_lossy(&out.stdout).contains("Cleared owner"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
let content = ticket(&worklane);
assert!(content.contains("- **Owner**: _Not set_"), "{content}");
// Nothing else on the way past.
assert!(content.contains("- **Status**: backlog"), "{content}");
}
/// The ticket is still resolved the three usual ways when it arrives in the flag.
#[test]
fn chown_clear_resolves_the_ticket_it_is_given() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["chown", "--clear", "Original"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(ticket(&worklane).contains("- **Owner**: _Not set_"));
}
#[test]
fn chown_clear_on_an_unowned_ticket_is_no_change() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["chown", "--clear", UUID]);
let before = ticket(&worklane);
let out = run(&temp, &["chown", "--clear", UUID]);
assert!(out.status.success());
assert!(
String::from_utf8_lossy(&out.stdout).contains("No changes"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
}
/// Setting an owner and clearing it are the two forms of the command, and clap keeps
/// them apart rather than the handler picking one.
#[test]
fn chown_refuses_a_user_and_a_clear_together() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for args in [
vec!["chown", "bob", "--clear", UUID],
vec!["chown", "bob", UUID, "--clear", UUID],
] {
let out = run(&temp, &args);
assert_eq!(out.status.code(), Some(2), "{args:?} was accepted");
assert!(
String::from_utf8_lossy(&out.stderr).contains("cannot be used with"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
}
// And a bare --clear still needs the ticket it is meant to name.
let out = run(&temp, &["chown", "--clear"]);
assert_eq!(out.status.code(), Some(2));
assert!(
String::from_utf8_lossy(&out.stderr).contains("a value is required"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(ticket(&worklane), before);
}
+2 -6
View File
@@ -1,6 +1,6 @@
use assert_cmd::Command;
use assert_fs::fixture::{PathChild, PathCreateDir};
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
@@ -17,11 +17,7 @@ fn setup_worklane(temp: &TempDir) -> PathBuf {
worklane.path().to_path_buf()
}
fn create_ticket(
worklane_dir: &Path,
status: &str,
title: &str,
) -> String {
fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
let uuid = uuid::Uuid::new_v4().to_string();
let slug = title
.to_lowercase()
+77
View File
@@ -0,0 +1,77 @@
use assert_cmd::Command;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
fn script(shell: &str) -> String {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd.arg("completions").arg(shell).assert().success();
String::from_utf8(assert.get_output().stdout.clone()).unwrap()
}
/// Every shell clap can generate for, since the README names all five.
#[test]
fn completions_prints_a_script_for_every_shell() {
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
let out = script(shell);
assert!(out.contains("worklane"), "the {shell} script never names the command");
// Long enough to be a script rather than an empty file with a comment in it.
assert!(out.len() > 500, "the {shell} script is {} bytes", out.len());
}
}
/// No board is looked for, the way `install-skill` looks for none: the script comes off
/// the clap definition and is the same wherever it is run. Run from a temp directory
/// with no `.worklane` above it, which every other command refuses.
#[test]
fn completions_needs_no_board() {
let temp = assert_fs::TempDir::new().unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.arg("completions")
.arg("fish")
.assert()
.success();
}
#[test]
fn fish_gets_both_halves() {
let out = script("fish");
// clap's, which is where the subcommands and the flags come from.
assert!(out.contains("__fish_worklane_needs_command"));
assert!(out.contains("install-skill"));
// Ours, which is where the tickets come from.
assert!(out.contains("__worklane_first_arg_of"));
assert!(out.contains("worklane ls --ids"));
}
/// The fish half is fish syntax, so it must not reach any other shell's output.
#[test]
fn no_other_shell_gets_the_fish_half() {
for shell in ["bash", "zsh", "elvish", "powershell"] {
let out = script(shell);
assert!(
!out.contains("__worklane_first_arg_of"),
"fish-only helpers leaked into {shell}"
);
assert!(!out.contains("worklane ls --ids"), "the dynamic half leaked into {shell}");
}
}
/// The four statuses reach fish twice over, from clap for the `mv` option and from the
/// appended half for the `ls` positional, which clap emits nothing for.
#[test]
fn fish_is_offered_every_status() {
let out = script("fish");
for status in ["backlog", "committed", "reviewing", "done"] {
assert!(out.contains(status), "fish is never offered {status}");
}
assert!(out.contains("-a 'backlog committed reviewing done' -d status"));
}
#[test]
fn an_unknown_shell_is_a_usage_error() {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd.arg("completions").arg("tcsh").assert().code(2);
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("invalid value 'tcsh'"), "{stderr}");
}
+117 -9
View File
@@ -3,9 +3,11 @@ use assert_fs::TempDir;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
/// The document as this test's binary carries it, so the print path is pinned to the
/// file in the repo rather than to a description of it.
/// The documents as this test's binary carries them, so the print path is pinned to the
/// files in the repo rather than to a description of them.
const SKILL: &str = include_str!("../assets/SKILL.md");
const REVIEW: &str = include_str!("../assets/REVIEW.md");
const PLAN: &str = include_str!("../assets/PLAN.md");
/// `HOME` is redirected, so the suite never writes into the home of whoever runs it.
/// A temp directory rather than the real one is also what makes the already-installed
@@ -20,9 +22,21 @@ fn installed(home: &TempDir) -> std::path::PathBuf {
home.path().join(".claude/skills/worklane/SKILL.md")
}
/// Nothing about the skill needs a board, and it is wanted before there is one.
fn installed_review(home: &TempDir) -> std::path::PathBuf {
home.path().join(".claude/skills/worklane-review/SKILL.md")
}
fn installed_plan(home: &TempDir) -> std::path::PathBuf {
home.path().join(".claude/skills/worklane-plan/SKILL.md")
}
/// Nothing about the skills needs a board, and they are wanted before there is one.
///
/// One invocation writes every document. A person who learned the command before the
/// review skill existed gets it without learning anything new, which is the whole
/// reason there is no name to pass.
#[test]
fn the_skill_installs_outside_a_worklane_directory() {
fn every_skill_installs_outside_a_worklane_directory() {
let home = TempDir::new().unwrap();
let out = run(&home, &["install-skill"]);
@@ -31,7 +45,50 @@ fn the_skill_installs_outside_a_worklane_directory() {
assert_eq!(out.status.code(), Some(0), "{stdout}");
assert!(stdout.contains("Installed the worklane skill"), "{stdout}");
assert!(stdout.contains(".claude/skills/worklane/SKILL.md"), "{stdout}");
assert!(stdout.contains("Installed the worklane-review skill"), "{stdout}");
assert!(stdout.contains(".claude/skills/worklane-review/SKILL.md"), "{stdout}");
assert!(stdout.contains("Installed the worklane-plan skill"), "{stdout}");
assert!(stdout.contains(".claude/skills/worklane-plan/SKILL.md"), "{stdout}");
assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL);
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN);
// Once, not per document: it is the one thing to do next, not part of an outcome.
assert_eq!(stdout.matches("pick it up on their next session").count(), 1, "{stdout}");
}
/// Narrowing to one document is the exception, and it must leave the others alone.
#[test]
fn a_named_skill_installs_only_that_one() {
let home = TempDir::new().unwrap();
let out = run(&home, &["install-skill", "worklane-review"]);
let stdout = String::from_utf8_lossy(&out.stdout);
assert_eq!(out.status.code(), Some(0), "{stdout}");
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
assert!(!installed(&home).exists(), "a named install wrote the other document too");
assert!(
!installed_plan(&home).exists(),
"a named install wrote the other document too"
);
}
/// A name nothing ships is a stop, with the choices in the message: guessing at the
/// nearest match would install a document nobody asked for.
#[test]
fn an_unknown_skill_name_is_refused_and_lists_what_there_is() {
let home = TempDir::new().unwrap();
let out = run(&home, &["install-skill", "reviewer"]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_ne!(out.status.code(), Some(0), "{stderr}");
assert!(stderr.contains("no skill named"), "{stderr}");
assert!(stderr.contains("worklane-review"), "{stderr}");
assert!(!installed(&home).exists());
assert!(!installed_review(&home).exists());
assert!(!installed_plan(&home).exists());
}
#[test]
@@ -60,7 +117,10 @@ fn a_modified_copy_is_reported_and_needs_force() {
assert_eq!(out.status.code(), Some(0), "{stdout}");
assert!(stdout.contains("Differs from the version in this binary"), "{stdout}");
assert!(stdout.contains("--force"), "{stdout}");
assert!(stdout.contains("--print"), "the message never says how to compare: {stdout}");
assert!(
stdout.contains("--print"),
"the message never says how to compare: {stdout}"
);
assert_eq!(
std::fs::read_to_string(installed(&home)).unwrap(),
"hand written\n",
@@ -73,17 +133,65 @@ fn a_modified_copy_is_reported_and_needs_force() {
assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL);
}
/// One refused document must not stop the ones behind it: the message is per document,
/// and the run still reports what it did with each.
#[test]
fn a_modified_copy_does_not_stop_the_other_documents() {
let home = TempDir::new().unwrap();
run(&home, &["install-skill"]);
std::fs::write(installed(&home), "hand written\n").unwrap();
std::fs::remove_file(installed_review(&home)).unwrap();
let out = run(&home, &["install-skill"]);
let stdout = String::from_utf8_lossy(&out.stdout);
assert_eq!(out.status.code(), Some(0), "{stdout}");
assert!(stdout.contains("Differs from the version in this binary"), "{stdout}");
assert!(stdout.contains("install-skill worklane --print"), "{stdout}");
assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), "hand written\n");
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN);
}
/// The print path is what makes a modified copy diffable, so it has to be the document
/// byte for byte and it must not install anything on the way past.
#[test]
fn print_writes_the_document_to_stdout_and_installs_nothing() {
fn print_writes_the_named_document_to_stdout_and_installs_nothing() {
let home = TempDir::new().unwrap();
let out = run(&home, &["install-skill", "worklane", "--print"]);
assert_eq!(out.status.code(), Some(0));
assert_eq!(String::from_utf8_lossy(&out.stdout), SKILL);
let out = run(&home, &["install-skill", "worklane-review", "--print"]);
assert_eq!(out.status.code(), Some(0));
assert_eq!(String::from_utf8_lossy(&out.stdout), REVIEW);
let out = run(&home, &["install-skill", "worklane-plan", "--print"]);
assert_eq!(out.status.code(), Some(0));
assert_eq!(String::from_utf8_lossy(&out.stdout), PLAN);
assert!(!installed(&home).exists(), "--print installed the skill anyway");
assert!(!installed_review(&home).exists(), "--print installed the skill anyway");
assert!(!installed_plan(&home).exists(), "--print installed the skill anyway");
}
/// A diff is against one document. Printing them all run together would be neither of
/// them, so an unnamed `--print` says what to type instead of guessing.
#[test]
fn print_without_a_name_says_which_names_there_are() {
let home = TempDir::new().unwrap();
let out = run(&home, &["install-skill", "--print"]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(0));
assert_eq!(String::from_utf8_lossy(&out.stdout), SKILL);
assert!(!installed(&home).exists(), "--print installed the skill anyway");
assert_ne!(out.status.code(), Some(0), "{stderr}");
assert!(stderr.contains("name the skill to print"), "{stderr}");
assert!(stderr.contains("worklane-review"), "{stderr}");
assert!(
String::from_utf8_lossy(&out.stdout).is_empty(),
"a document was printed anyway"
);
}
/// The command has to be findable by someone who does not already know it exists.
+149
View File
@@ -0,0 +1,149 @@
use assert_cmd::Command;
use assert_fs::TempDir;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
/// The tool as this test's binary carries it, so the print path is pinned to the file in
/// the repo rather than to a description of it.
const TOOL: &str = include_str!("../assets/TOOL.ts");
/// `XDG_CONFIG_HOME` is redirected, and `HOME` with it, so the suite never writes into
/// the config of whoever runs it. Both, because the fallback reads `HOME` and a machine
/// that has neither set is not the case under test here.
fn run(config: &TempDir, args: &[&str]) -> std::process::Output {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.env("XDG_CONFIG_HOME", config.path())
.env("HOME", config.path())
.args(args);
cmd.assert().get_output().clone()
}
fn installed(config: &TempDir) -> std::path::PathBuf {
config.path().join("opencode/tool/worklane.ts")
}
fn stdout(output: &std::process::Output) -> String {
String::from_utf8(output.stdout.clone()).unwrap()
}
/// Nothing about the tool needs a board, and it is wanted before there is one.
///
/// The file name is asserted, not just the directory: opencode names each tool as the
/// file then the export, so `worklane.ts` is what makes them `worklane_add` and
/// `worklane_mv`.
#[test]
fn the_tool_installs_outside_a_worklane_directory() {
let config = TempDir::new().unwrap();
let output = run(&config, &["install-tool"]);
assert!(output.status.success());
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
assert!(
stdout(&output).contains("Installed the worklane tool"),
"{}",
stdout(&output)
);
}
/// What the message has to carry, and it is not the skills' "next session": opencode
/// reads its config once at startup and never reloads it, so a running one keeps the
/// tools it began with. The second half is there because the file is executable and
/// looks like it needs a toolchain, which it does not.
#[test]
fn the_tool_says_to_restart_opencode_and_that_nothing_else_is_needed() {
let config = TempDir::new().unwrap();
let out = stdout(&run(&config, &["install-tool"]));
assert!(out.contains("Restart it"), "{out}");
assert!(out.contains("never reloaded"), "{out}");
assert!(out.contains("Nothing else to install"), "{out}");
assert!(out.contains("Bun"), "{out}");
}
/// Installing twice is a no-op rather than a rewrite, exactly as `install-skill` is.
#[test]
fn a_second_install_reports_the_copy_unchanged() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
let out = stdout(&run(&config, &["install-tool"]));
assert!(out.contains("Already up to date"), "{out}");
assert!(!out.contains("Installed the"), "{out}");
}
/// An edited copy is somebody's work, and the refusal names the invocation that shows
/// what it would be replaced with. `--print` there and not a skill name: there is one
/// tool file, so nothing has to say which.
#[test]
fn a_modified_copy_is_refused_until_force() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
std::fs::write(installed(&config), "// hand written\n").unwrap();
let refused = stdout(&run(&config, &["install-tool"]));
assert!(refused.contains("Differs from the version in this binary"), "{refused}");
assert!(refused.contains("worklane install-tool --print"), "{refused}");
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), "// hand written\n");
let forced = stdout(&run(&config, &["install-tool", "--force"]));
assert!(forced.contains("Installed the worklane tool"), "{forced}");
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
}
/// `--print` is for diffing against an installed copy, so it writes nothing.
#[test]
fn print_writes_the_tool_to_stdout_and_installs_nothing() {
let config = TempDir::new().unwrap();
let output = run(&config, &["install-tool", "--print"]);
assert_eq!(stdout(&output), TOOL);
assert!(!installed(&config).exists());
}
/// With no `XDG_CONFIG_HOME` the tool lands under `HOME`, which is the same answer
/// opencode gives: its config root is `$XDG_CONFIG_HOME/opencode` when that is set and
/// `~/.config/opencode` when it is not.
#[test]
fn the_tool_falls_back_to_the_home_directory_without_xdg_config_home() {
let home = TempDir::new().unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let output = cmd
.env_remove("XDG_CONFIG_HOME")
.env("HOME", home.path())
.arg("install-tool")
.assert()
.success()
.get_output()
.clone();
let path = home.path().join(".config/opencode/tool/worklane.ts");
assert_eq!(std::fs::read_to_string(&path).unwrap(), TOOL);
assert!(
stdout(&output).contains(&path.display().to_string()),
"{}",
stdout(&output)
);
}
/// The two commands are independent, which is the whole point of them being two: a
/// person on Claude Code takes the skills and never the tool, and one who wants the
/// tools is not made to take a second copy of the documents to get them.
#[test]
fn each_install_command_leaves_the_other_target_alone() {
let config = TempDir::new().unwrap();
run(&config, &["install-tool"]);
assert!(installed(&config).exists());
assert!(!config.path().join(".claude/skills").exists());
let skills_only = TempDir::new().unwrap();
run(&skills_only, &["install-skill"]);
assert!(
skills_only
.path()
.join(".claude/skills/worklane/SKILL.md")
.exists()
);
assert!(!installed(&skills_only).exists());
}
+610 -3
View File
@@ -191,7 +191,11 @@ fn ls_handles_short_and_non_ascii_filenames() {
}
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("backlog").assert().success();
cmd.current_dir(temp.path())
.arg("ls")
.arg("backlog")
.assert()
.success();
let stdout = get_stdout(&mut cmd);
assert_eq!(stdout.matches("Odd Name").count(), 3);
@@ -209,7 +213,11 @@ fn ls_survives_a_malformed_created_at() {
.unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("backlog").assert().success();
cmd.current_dir(temp.path())
.arg("ls")
.arg("backlog")
.assert()
.success();
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Bad Date"));
@@ -290,9 +298,608 @@ fn ls_shows_a_mark_for_the_level() {
// Piped, so no escapes: the glyph is carrying the level by itself
assert!(!stdout.contains('\u{1b}'));
assert!(stdout.contains("\u{25cf}\u{25cf} "), "no full meter for level 1 in {stdout:?}");
assert!(
stdout.contains("\u{25cf}\u{25cf} "),
"no full meter for level 1 in {stdout:?}"
);
assert!(stdout.contains("\u{25cb}\u{25cb} "), "no empty meter for level 5");
assert!(stdout.contains("\u{b7}\u{b7} "), "no unset mark");
// The raw number is not what the listing shows
assert!(!stdout.contains(" 1 "), "the digit leaked into the row");
}
/// A ticket whose Tags field is whatever the test needs it to be, written verbatim so a
/// missing field, an unset one and a real list are all reachable.
fn create_ticket_with_tags(
worklane_dir: &std::path::Path,
status: &str,
title: &str,
tags: &str,
priority: &str,
) {
let slug: String = title.to_lowercase().replace(' ', "-");
let body = format!(
"# {title}\n\n## Metadata\n\n - **ID**: 00000000-0000-0000-0000-000000000001\n - **Priority**: {priority}\n{tags} - **Due**: _Not set_\n- **Owner**: alice\n- **Status**: {status}\n"
);
fs::write(
worklane_dir
.join(status)
.join(format!("00000000-0000-0000-0000-000000000001_{slug}.md")),
body,
)
.unwrap();
}
/// The Tags line as a ticket carries it, for the common case of a real list.
fn tags(list: &str) -> String {
format!("- **Tags**: {list}\n")
}
#[test]
fn ls_filters_by_tag_and_composes_with_status_and_priority() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_tags(&worklane, "backlog", "Tagged bug", &tags("bug,cli"), "1");
create_ticket_with_tags(&worklane, "backlog", "Tagged feature", &tags("feature"), "1");
create_ticket_with_tags(&worklane, "backlog", "Lower bug", &tags("bug"), "3");
create_ticket_with_tags(&worklane, "committed", "Started bug", &tags("bug"), "1");
// Alone, through the grouped listing: every status, only the tagged tickets.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--tag", "bug"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Tagged bug"), "{stdout}");
assert!(stdout.contains("Lower bug"), "{stdout}");
assert!(
stdout.contains("Started bug"),
"a tagged ticket in another status was dropped"
);
assert!(!stdout.contains("Tagged feature"), "an untagged ticket came through");
// The counts are filtered too, since they are the same collect.
assert!(stdout.contains("[BACKLOG] 2 tickets"), "{stdout}");
assert!(stdout.contains("[COMMITTED] 1 ticket"), "{stdout}");
// With the status positional.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "bug"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Tagged bug"));
assert!(stdout.contains("Lower bug"));
assert!(!stdout.contains("Started bug"), "the status was ignored");
// With --priority, and with both: none asked for is everything kept, so the three
// compose without a rule per pair.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "--tag", "bug", "--priority", "1"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Tagged bug"));
assert!(stdout.contains("Started bug"));
assert!(!stdout.contains("Lower bug"), "the priority was ignored");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "bug", "--priority", "1"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Tagged bug"));
assert!(!stdout.contains("Lower bug"), "the priority was ignored");
assert!(!stdout.contains("Started bug"), "the status was ignored");
assert!(!stdout.contains("Tagged feature"), "the tag was ignored");
}
/// The field is a list of whole values, not a string to search: a ticket tagged `bugfix`
/// is not a ticket tagged `bug`, and neither is one tagged `Bug`. Case sensitive is the
/// opinion the field already takes, since `tag_color` draws those two differently.
#[test]
fn ls_matches_a_whole_tag_value_and_not_a_substring_or_another_case() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_tags(&worklane, "backlog", "Real bug", &tags("bug"), "2");
create_ticket_with_tags(&worklane, "backlog", "Only bugfix", &tags("bugfix"), "2");
create_ticket_with_tags(&worklane, "backlog", "Capital Bug", &tags("Bug"), "2");
// A value that only appears with its neighbours around it, so a match on the raw
// field would find it and a match on the split values cannot.
create_ticket_with_tags(&worklane, "backlog", "Spaced list", &tags("cli, filter"), "2");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "bug"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Real bug"), "{stdout}");
assert!(!stdout.contains("Only bugfix"), "bug matched bugfix");
assert!(!stdout.contains("Capital Bug"), "bug matched Bug");
// Trimmed on the way in, so the space after the comma is not part of the tag.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "filter"]);
assert!(get_stdout(&mut cmd).contains("Spaced list"));
// And the field as written is not itself a tag.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "cli, filter"]);
let stdout = get_stdout(&mut cmd);
assert!(!stdout.contains("Spaced list"), "the whole field matched as one tag");
}
/// No tags is no match, however the ticket spells it: the field absent, unset, or empty.
#[test]
fn ls_never_matches_a_ticket_carrying_no_tags() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_tags(&worklane, "backlog", "Has one", &tags("bug"), "2");
create_ticket_with_tags(&worklane, "backlog", "Field unset", &tags("_None_"), "2");
create_ticket_with_tags(&worklane, "backlog", "Field empty", "- **Tags**:\n", "2");
create_ticket_with_tags(&worklane, "backlog", "Field missing", "", "2");
create_ticket_with_tags(&worklane, "backlog", "Only commas", &tags(", ,"), "2");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "bug"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Has one"), "{stdout}");
for absent in ["Field unset", "Field empty", "Field missing", "Only commas"] {
assert!(!stdout.contains(absent), "{absent} matched a tag it does not carry");
}
// Nor does an empty tag reach the filter: the value parser refuses it, so nothing is
// listed rather than everything.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "backlog", "--tag", ""]);
cmd.assert().failure().code(2);
}
/// A tag nothing carries lists nothing and still succeeds. The message is the one `ls`
/// already gives for a filter that empties a status, rather than a second one invented
/// here for tags alone.
#[test]
fn ls_with_a_tag_nothing_carries_lists_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_tags(&worklane, "backlog", "Tagged bug", &tags("bug"), "2");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "frontend"]);
cmd.assert().success();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "backlog", "--tag", "frontend"]);
let stdout = get_stdout(&mut cmd);
assert!(!stdout.contains("Tagged bug"), "{stdout}");
assert!(stdout.contains("No tickets in 'backlog' status."), "{stdout}");
// Through the grouped listing the counts go to zero and no section is drawn.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--tag", "frontend"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("[BACKLOG] 0 tickets"), "{stdout}");
assert!(!stdout.contains("Tagged bug"), "{stdout}");
}
/// A ticket with an id of its own, since `create_ticket` gives every fixture the same
/// uuid and `--ids` is the one output where the id is the whole point.
fn create_ticket_with_id(
worklane_dir: &std::path::Path,
status: &str,
title: &str,
uuid: &str,
tags: &str,
) {
let ticket_body = format!(
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Tags**: {tags}\n- **Owner**: alice\n- **Status**: {status}\n"
);
let filename = format!("{uuid}_{}.md", slug(title));
fs::write(worklane_dir.join(status).join(filename), ticket_body).unwrap();
}
/// The slug rule, as AGENTS.md requires: derived, never written by hand.
fn slug(title: &str) -> String {
title
.to_lowercase()
.chars()
.filter(|c| c.is_alphanumeric() || *c == ' ' || *c == '-' || *c == '_')
.map(|c| if c == ' ' { '-' } else { c })
.collect()
}
/// One ticket per line, the seven-character id then a tab then the title, and nothing
/// else: no heading, no counts, no owner or due column.
#[test]
fn ls_ids_prints_the_id_and_the_title_and_nothing_else() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_id(
&worklane,
"backlog",
"Feature A",
"1b78a24c-0000-0000-0000-000000000001",
"bug",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
cmd.assert().success();
let stdout = get_stdout(&mut cmd);
assert_eq!(stdout, "1b78a24\tFeature A\n", "{stdout:?}");
}
/// Every status, done included, where the decorated listing leaves done out. A
/// completion has to be able to name a finished ticket.
#[test]
fn ls_ids_includes_done_and_narrows_to_a_named_status() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_id(
&worklane,
"backlog",
"Still open",
"aaaaaaa1-0000-0000-0000-000000000001",
"bug",
);
create_ticket_with_id(
&worklane,
"done",
"Finished",
"bbbbbbb2-0000-0000-0000-000000000002",
"bug",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
let stdout = get_stdout(&mut cmd);
assert!(stdout.contains("Still open"), "{stdout}");
assert!(stdout.contains("Finished"), "a done ticket cannot be named: {stdout}");
// The decorated listing is unchanged: done is counted, not listed.
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("Finished"), "{stdout}");
// The positional still narrows it.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "done", "--ids"]);
let stdout = get_stdout(&mut cmd);
assert_eq!(stdout, "bbbbbbb\tFinished\n", "{stdout:?}");
}
/// The filters apply to `--ids` exactly as they do to the listing, so a completion can
/// be narrowed the same way.
#[test]
fn ls_ids_still_takes_the_filters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_id(
&worklane,
"backlog",
"Tagged bug",
"aaaaaaa1-0000-0000-0000-000000000001",
"bug",
);
create_ticket_with_id(
&worklane,
"backlog",
"Tagged cli",
"bbbbbbb2-0000-0000-0000-000000000002",
"cli",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "--ids", "--tag", "cli"]);
let stdout = get_stdout(&mut cmd);
assert_eq!(stdout, "bbbbbbb\tTagged cli\n", "{stdout:?}");
}
/// An unknown campaign is refused before anything is read, even here. A completion that
/// listed the whole board because the name was misspelled would be worse than one that
/// printed nothing.
#[test]
fn ls_ids_still_refuses_an_unknown_campaign() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket_with_id(
&worklane,
"backlog",
"Feature A",
"aaaaaaa1-0000-0000-0000-000000000001",
"bug",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["ls", "--ids", "--campaign", "no such campaign"]);
cmd.assert().failure();
}
/// A status the board is missing is skipped rather than refused, unlike the listing:
/// the caller is a shell filling in candidates, and an error printed over the prompt is
/// worse there than no candidates.
#[test]
fn ls_ids_is_quiet_about_a_missing_status_directory() {
let temp = TempDir::new().unwrap();
let worklane = temp.child(".worklane");
worklane.create_dir_all().unwrap();
worklane.child("backlog").create_dir_all().unwrap();
create_ticket_with_id(
worklane.path(),
"backlog",
"Feature A",
"aaaaaaa1-0000-0000-0000-000000000001",
"bug",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
cmd.assert().success();
let stdout = get_stdout(&mut cmd);
assert_eq!(stdout, "aaaaaaa\tFeature A\n", "{stdout:?}");
// The listing still says so, since a person reading it can act on it.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "done"]);
let assert = cmd.assert().failure();
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("No 'done' directory"), "{stderr}");
}
/// A status outside the four is clap's to refuse now, so it is a usage error naming the
/// four rather than a runtime one.
#[test]
fn ls_names_the_four_statuses_when_given_another() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let assert = cmd
.current_dir(temp.path())
.args(["ls", "nonexistent"])
.assert()
.code(2);
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("invalid value 'nonexistent'"), "{stderr}");
for status in ["backlog", "committed", "reviewing", "done"] {
assert!(stderr.contains(status), "{status} is not offered: {stderr}");
}
}
/// The listing reads the stamps to order the column by them, and prints none of them.
/// Pinned against a ticket carrying one, since a listing that started showing them would
/// change the output every board and completion script parses.
#[test]
fn ls_output_is_unchanged_by_a_status_stamp() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "committed", "Stamped", "alice", "2026-06-01");
let path = worklane
.join("committed")
.join("00000000-0000-0000-0000-000000000001_stamped.md");
let before = {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("committed");
get_stdout(&mut cmd)
};
let stamped = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Committed On**: 2026-08-22 09:14:30\n- **Status**:");
fs::write(&path, stamped).unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("committed");
let after = get_stdout(&mut cmd);
assert_eq!(after, before);
assert!(!after.contains("Committed On"), "{after}");
}
/// A ticket in a status with the entry stamp that status is ordered by, or none.
///
/// The field is derived from the status rather than passed, so a case says which column
/// it is about and cannot name the wrong stamp for it.
fn create_stamped_ticket(
worklane_dir: &std::path::Path,
status: &str,
title: &str,
uuid: &str,
priority: &str,
stamp: Option<&str>,
) {
let field = match status {
"committed" => "Committed On",
"reviewing" => "Submitted On",
"done" => "Completed On",
other => panic!("{other} has no entry stamp"),
};
let line = match stamp {
Some(value) => format!("- **{field}**: {value}\n"),
None => String::new(),
};
let body = format!(
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Priority**: {priority}\n\
- **Tags**: test\n- **Due**: _Not set_\n- **Owner**: alice\n{line}\
- **Status**: {status}\n"
);
fs::write(
worklane_dir
.join(status)
.join(format!("{uuid}_{}.md", slug(title))),
body,
)
.unwrap();
}
fn positions(stdout: &str, titles: [&str; 3]) -> Vec<usize> {
titles
.iter()
.map(|title| {
stdout
.find(title)
.unwrap_or_else(|| panic!("{title} missing from {stdout}"))
})
.collect()
}
/// Committed and reviewing are queues, and the head is what has waited longest: that is
/// what the reader picks next from. Priority no longer decides it, which is why the
/// oldest here is the least urgent of the three.
#[test]
fn ls_orders_committed_and_reviewing_by_the_oldest_entry_stamp() {
for status in ["committed", "reviewing"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("aaaa000{n}-0000-0000-0000-000000000001");
create_stamped_ticket(
&worklane,
status,
"Newest",
&at(1),
"1",
Some("2026-08-03 09:00:00"),
);
create_stamped_ticket(
&worklane,
status,
"Oldest",
&at(2),
"5",
Some("2026-08-01 09:00:00"),
);
create_stamped_ticket(
&worklane,
status,
"Middle",
&at(3),
"1",
Some("2026-08-02 09:00:00"),
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", status]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Oldest", "Middle", "Newest"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status}: {stdout}");
// The overview lists the same columns, so it has to agree with the narrowed
// listing rather than falling back to priority for the same tickets.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls");
let overview = get_stdout(&mut cmd);
let seen = positions(&overview, ["Oldest", "Middle", "Newest"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status} overview: {overview}");
}
}
/// Done reads like a changelog: what just landed is at the top. The p1 that finished
/// first is at the bottom, which is the whole point of the column not being priority.
#[test]
fn ls_orders_done_by_the_newest_entry_stamp() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("bbbb000{n}-0000-0000-0000-000000000001");
create_stamped_ticket(&worklane, "done", "First", &at(1), "1", Some("2026-08-01 09:00:00"));
create_stamped_ticket(&worklane, "done", "Last", &at(2), "5", Some("2026-08-03 09:00:00"));
create_stamped_ticket(&worklane, "done", "Middle", &at(3), "1", Some("2026-08-02 09:00:00"));
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "done"]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Last", "Middle", "First"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
/// A missing stamp is unknown, not ancient, so it sinks below every stamped ticket
/// rather than claiming the head of the queue. Every ticket on a board older than the
/// stamps is one of these.
#[test]
fn ls_sinks_an_unstamped_ticket_below_the_stamped_ones() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("cccc000{n}-0000-0000-0000-000000000001");
create_stamped_ticket(&worklane, "committed", "Unstamped", &at(1), "1", None);
create_stamped_ticket(
&worklane,
"committed",
"Waited",
&at(2),
"5",
Some("2026-08-01 09:00:00"),
);
create_stamped_ticket(
&worklane,
"committed",
"Fresh",
&at(3),
"5",
Some("2026-08-09 09:00:00"),
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "committed"]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Waited", "Fresh", "Unstamped"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
/// The two listings are one order. A completion offering candidates in a different
/// order than the board prints them would make the head of a column mean two things.
#[test]
fn ls_ids_prints_the_same_order_the_listing_does() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("dddd000{n}-0000-0000-0000-000000000001");
create_stamped_ticket(
&worklane,
"reviewing",
"Newest",
&at(1),
"1",
Some("2026-08-03 09:00:00"),
);
create_stamped_ticket(
&worklane,
"reviewing",
"Oldest",
&at(2),
"5",
Some("2026-08-01 09:00:00"),
);
create_stamped_ticket(&worklane, "reviewing", "Unstamped", &at(3), "1", None);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "reviewing", "--ids"]);
let ids = get_stdout(&mut cmd);
let titles: Vec<&str> = ids.lines().filter_map(|line| line.split('\t').nth(1)).collect();
assert_eq!(titles, ["Oldest", "Newest", "Unstamped"], "{ids:?}");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "reviewing"]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
+278 -12
View File
@@ -277,13 +277,16 @@ fn mv_ignores_already_in_same_status() {
assert!(worklane.join("reviewing").join(&filename).exists());
}
/// A status is a value enum, so an unknown one is clap's to refuse: exit 2, the four
/// named, and the ticket untouched. The same bargain `--due` and `--priority` take, and
/// the reason `cmd_mv` no longer checks.
#[test]
fn mv_rejects_invalid_status() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let id = "abc123def456789012345678901234567890";
let _filename = create_ticket(
let filename = create_ticket(
&worklane,
"backlog",
"Invalid Target",
@@ -301,10 +304,17 @@ fn mv_rejects_invalid_status() {
.arg("--status")
.arg("invalid")
.assert()
.failure();
.code(2);
let stderr = get_stderr(&mut cmd);
assert!(stderr.contains("Invalid target status"));
assert!(stderr.contains("invalid value 'invalid'"), "{stderr}");
for status in ["backlog", "committed", "reviewing", "done"] {
assert!(stderr.contains(status), "{status} is not offered: {stderr}");
}
assert!(
worklane.join("backlog").join(&filename).exists(),
"the ticket moved anyway"
);
}
#[test]
@@ -463,7 +473,9 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
.unwrap()
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| !["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str()))
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
})
.collect();
for dir in ["backlog", "committed", "reviewing", "done"] {
@@ -512,10 +524,7 @@ fn mv_never_leaves_stale_content_in_the_target_directory() {
let moved = worklane.join("committed").join(&filename);
assert!(moved.exists(), "ticket did not move");
let content = fs::read_to_string(&moved).unwrap();
assert!(
content.contains("- **Status**: committed"),
"stale status: {content:?}"
);
assert!(content.contains("- **Status**: committed"), "stale status: {content:?}");
assert!(!content.contains("- **Status**: backlog"), "{content:?}");
assert_eq!(md_files(&worklane.join("backlog")).len(), 0);
@@ -621,10 +630,7 @@ fn mv_moves_the_resolved_ticket_when_two_share_a_title() {
] {
fs::write(
worklane.join("backlog").join(format!("{}_foo.md", uuid)),
format!(
"# Foo\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n",
uuid
),
format!("# Foo\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", uuid),
)
.unwrap();
}
@@ -878,3 +884,263 @@ fn mv_ignores_the_kinds_that_are_not_blockers() {
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(worklane.join("committed").join(&filename).exists());
}
/// The value of a metadata field, or nothing when the ticket does not carry it.
fn field(content: &str, name: &str) -> Option<String> {
let prefix = format!("- **{}**: ", name);
content
.lines()
.find_map(|line| line.strip_prefix(prefix.as_str()))
.map(str::to_string)
}
/// `%Y-%m-%d %H:%M:%S`, checked by shape. A test cannot pin the clock, so what it can
/// assert is that the stamp carries the same format `Created At` does.
fn is_timestamp(value: &str) -> bool {
value.len() == 19
&& value.chars().enumerate().all(|(index, c)| match index {
4 | 7 => c == '-',
10 => c == ' ',
13 | 16 => c == ':',
_ => c.is_ascii_digit(),
})
}
fn stamped_ticket(worklane: &Path, status: &str) -> String {
create_ticket(
worklane,
status,
"Stamped Task",
"Carries the stamps.",
"cccc3333cccc3333cccc3333cccc3333cccc",
"alice",
"_Not set_",
"test",
)
}
fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
}
/// One field per status, written with the time of the move and added to the ones
/// already there: walking the flow leaves the whole journey on the ticket.
#[test]
fn mv_stamps_the_field_of_the_status_it_enters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
// The fixture predates Created At as well as the stamps, and the four reading as
// one block is the point, so it is seeded rather than asserted around.
let path = worklane.join("backlog").join(&filename);
let seeded = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:");
fs::write(&path, seeded).unwrap();
let mut carried: Vec<&str> = Vec::new();
for (status, stamp) in [
("committed", "Committed On"),
("reviewing", "Submitted On"),
("done", "Completed On"),
] {
let out = move_ticket(&temp, "cccc3333", status, false);
assert!(out.status.success(), "{:?}", out);
carried.push(stamp);
let content = ticket_at(&worklane, status, &filename);
for stamp in &carried {
let value = field(&content, stamp)
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
}
}
// The four side by side and in flow order, which is what a reader asking when this
// was filed, picked up, handed over and finished gets one answer each from.
let content = ticket_at(&worklane, "done", &filename);
let block: Vec<&str> = content
.lines()
.filter_map(|line| line.strip_prefix("- **"))
.filter_map(|line| line.split("**:").next())
.skip_while(|name| *name != "Created At")
.collect();
assert_eq!(
block,
[
"Created At",
"Committed On",
"Submitted On",
"Completed On",
"Status"
],
"{content}"
);
}
/// Arrival clears what comes after it and nothing before, so a ticket sent back out of
/// done keeps the stages it did get through.
#[test]
fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
for status in ["committed", "reviewing", "done"] {
move_ticket(&temp, "cccc3333", status, false);
}
move_ticket(&temp, "cccc3333", "reviewing", true);
let content = ticket_at(&worklane, "reviewing", &filename);
assert_eq!(field(&content, "Completed On"), None, "{content}");
assert!(field(&content, "Committed On").is_some(), "{content}");
assert!(field(&content, "Submitted On").is_some(), "{content}");
}
/// Backlog has no stamp of its own and every status follows it, so a ticket forced back
/// to it carries none at all rather than a Completed On for work that has been undone.
#[test]
fn mv_back_to_backlog_removes_all_three_stamps() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "done", true);
let done = ticket_at(&worklane, "done", &filename);
assert!(field(&done, "Completed On").is_some(), "{done}");
move_ticket(&temp, "cccc3333", "backlog", true);
let content = ticket_at(&worklane, "backlog", &filename);
for stamp in ["Committed On", "Submitted On", "Completed On"] {
assert_eq!(field(&content, stamp), None, "{content}");
}
}
/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent
/// field says the ticket never got that far, and inventing one would say it did.
#[test]
fn mv_skipping_forward_stamps_only_the_target() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "done", true);
let content = ticket_at(&worklane, "done", &filename);
assert!(field(&content, "Completed On").is_some(), "{content}");
assert_eq!(field(&content, "Committed On"), None, "{content}");
assert_eq!(field(&content, "Submitted On"), None, "{content}");
}
/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to
/// write one or take one away, so a stamp is always the record of a real move. Pinned
/// so the omission stays a decision rather than becoming an oversight somebody fills in.
#[test]
fn no_other_command_can_write_or_clear_a_stamp() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
for command in ["add", "set", "append", "chown"] {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args([command, "--help"]);
let out = cmd.assert().get_output().clone();
let help = String::from_utf8_lossy(&out.stdout).to_lowercase();
for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] {
assert!(!help.contains(flag), "{command} --help names {flag}: {help}");
}
}
}
/// Re-entry is the time of the move that brought the ticket back, not the first one.
#[test]
fn mv_restamps_a_status_the_ticket_is_re_entering() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "committed");
// Hand-written so the earlier value is old enough to tell from the move's own time,
// which two moves in the same second would not be.
let path = worklane.join("committed").join(&filename);
let seeded = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Committed On**: 2020-01-01 00:00:00\n- **Status**:");
fs::write(&path, seeded).unwrap();
move_ticket(&temp, "cccc3333", "backlog", true);
move_ticket(&temp, "cccc3333", "committed", false);
let content = ticket_at(&worklane, "committed", &filename);
let value = field(&content, "Committed On").expect(&content);
assert!(is_timestamp(&value), "{value}");
assert_ne!(value, "2020-01-01 00:00:00");
assert_eq!(content.matches("**Committed On**:").count(), 1, "{content}");
}
/// The fixture predates the fields, as every ticket on a real board does, so the line
/// is inserted rather than rewritten. Against METADATA_ORDER, which keeps Status last.
#[test]
fn mv_inserts_the_stamp_before_the_status_field() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "committed", false);
let content = ticket_at(&worklane, "committed", &filename);
let value = field(&content, "Committed On").expect(&content);
assert!(
content.contains(&format!(
"- **Owner**: alice\n- **Committed On**: {}\n- **Status**: committed\n",
value
)),
"{content}"
);
assert!(content.ends_with("- **Status**: committed\n"), "{content}");
}
/// Behind the refusals, all of them: a move that does not happen leaves the file exactly
/// as it was, stamp included.
#[test]
fn mv_writes_no_stamp_when_the_move_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let backward = stamped_ticket(&worklane, "committed");
let before = ticket_at(&worklane, "committed", &backward);
let out = move_ticket(&temp, "cccc3333", "backlog", false);
assert!(!out.status.success());
assert_eq!(ticket_at(&worklane, "committed", &backward), before);
// The blocked ticket takes the other refusal, which sits after the no-op return.
let blocked = create_gated_pair(&worklane, &temp, "backlog");
let before = ticket_at(&worklane, "backlog", &blocked);
let out = move_ticket(&temp, "aaaa1111", "committed", false);
assert!(!out.status.success());
assert_eq!(ticket_at(&worklane, "backlog", &blocked), before);
}
/// A move to the status the ticket is already in returns before anything is written, so
/// it does not restamp either.
#[test]
fn mv_does_not_restamp_a_no_op_move() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "committed");
let before = ticket_at(&worklane, "committed", &filename);
let out = move_ticket(&temp, "cccc3333", "committed", false);
assert!(out.status.success());
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
}
+52 -20
View File
@@ -118,11 +118,7 @@ fn a_target_resolves_by_uuid_prefix_title_or_filename() {
let worklane = board(&temp);
let out = run(&temp, &["relate", GATED, "--blocked-by", search]);
assert!(
out.status.success(),
"{search}: {}",
String::from_utf8_lossy(&out.stderr)
);
assert!(out.status.success(), "{search}: {}", String::from_utf8_lossy(&out.stderr));
assert!(
ticket(&worklane, GATED).contains(&format!("- blocked by {}", BLOCKER)),
"{search}: {}",
@@ -249,11 +245,7 @@ fn a_relation_already_held_reports_no_change_and_writes_nothing() {
let out = run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
assert!(out.status.success());
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
assert_eq!(
ticket(&worklane, GATED),
before,
"the relation was recorded twice"
);
assert_eq!(ticket(&worklane, GATED), before, "the relation was recorded twice");
}
/// One direction is stored. The inverse is derived by a scan, so the ticket at the
@@ -289,6 +281,21 @@ fn relate_leaves_everything_it_was_not_asked_about_alone() {
assert!(content.contains("- **Owner**: alice"), "{content}");
}
/// The mark each kind prints before the id. Written out rather than imported: these
/// tests drive the binary, so they see only its output.
///
/// The cross is the one a held-up card already carries, since both say the same word.
const BLOCKED_MARK: &str = "\u{d7}";
const RELATES_MARK: &str = "\u{2192}";
/// And the mark for the status of the ticket the row names, which follows the kind: a
/// circle filling up as the target moves through the flow.
const BACKLOG_MARK: &str = "\u{25cb}";
const DONE_MARK: &str = "\u{25cf}";
/// A target the board no longer holds has no status, and `?` holds the column so the id
/// does not move.
const NO_STATUS_MARK: &str = "?";
/// The kind, the short id and the title, so the section reads without a second lookup.
#[test]
fn show_renders_the_kind_the_short_id_and_the_title() {
@@ -299,7 +306,10 @@ fn show_renders_the_kind_the_short_id_and_the_title() {
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("Relations"), "{shown}");
assert!(shown.contains("blocked by (b1b2c3d) The blocker"), "{shown}");
assert!(
shown.contains(&format!("blocked by {BLOCKED_MARK} {BACKLOG_MARK} (b1b2c3d) The blocker")),
"{shown}"
);
// Never the stored line: a bare uuid says nothing about what it points at.
assert!(!shown.contains(BLOCKER), "{shown}");
}
@@ -314,12 +324,33 @@ fn show_lists_the_relation_the_other_ticket_holds() {
run(&temp, &["relate", GATED, "--relates-to", FIXED]);
let shown = stdout(&run(&temp, &["show", BLOCKER]));
assert!(shown.contains("blocks (641e3d5) The gated one"), "{shown}");
assert!(
shown.contains(&format!("blocks {BLOCKED_MARK} {BACKLOG_MARK} (641e3d5) The gated one")),
"{shown}"
);
assert!(!ticket(&worklane, BLOCKER).contains("Relations"));
// Two kinds on one ticket, each with its own mark, and the second mark is the state
// of the ticket at the far end: the old fix is in done and the blocker is not. That
// is the pair the block is for, which kind of edge and whether it is finished.
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(
shown.contains(&format!("blocked by {BLOCKED_MARK} {BACKLOG_MARK} (b1b2c3d) The blocker")),
"{shown}"
);
assert!(
shown.contains(&format!("relates to {RELATES_MARK} {DONE_MARK} (f1f2f3f) The old fix")),
"{shown}"
);
// `relates to` is symmetric, so it reads the same way from either end.
let shown = stdout(&run(&temp, &["show", FIXED]));
assert!(shown.contains("relates to (641e3d5) The gated one"), "{shown}");
assert!(
shown.contains(&format!(
"relates to {RELATES_MARK} {BACKLOG_MARK} (641e3d5) The gated one"
)),
"{shown}"
);
}
#[test]
@@ -331,7 +362,10 @@ fn a_target_that_no_longer_exists_renders_as_missing() {
fs::remove_file(find(&worklane, BLOCKER)).unwrap();
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("blocked by (b1b2c3d) _missing_"), "{shown}");
assert!(
shown.contains(&format!("blocked by {BLOCKED_MARK} {NO_STATUS_MARK} (b1b2c3d) _missing_")),
"{shown}"
);
}
/// The section is the one part of a ticket read back by machine, so a line nobody can
@@ -342,12 +376,10 @@ fn a_line_that_is_not_a_relation_is_an_error() {
let worklane = board(&temp);
let path = find(&worklane, GATED);
let content = fs::read_to_string(&path)
.unwrap()
.replace(
"## Metadata",
&format!("## Relations\n- depends on {}\n\n## Metadata", BLOCKER),
);
let content = fs::read_to_string(&path).unwrap().replace(
"## Metadata",
&format!("## Relations\n- depends on {}\n\n## Metadata", BLOCKER),
);
fs::write(&path, content).unwrap();
let out = run(&temp, &["show", GATED]);
+365 -37
View File
@@ -94,13 +94,20 @@ fn set_replaces_each_field_it_is_given() {
let out = run(
&temp,
&[
"set", UUID,
"--description", "Only paragraph.",
"--acceptance", "New crit",
"--plan", "New step",
"--tags", "beta,gamma",
"--due", "2026-12-31",
"--priority", "1",
"set",
UUID,
"--description",
"Only paragraph.",
"--acceptance",
"New crit",
"--plan",
"New step",
"--tags",
"beta,gamma",
"--due",
"2026-12-31",
"--priority",
"1",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
@@ -190,7 +197,11 @@ fn set_reports_only_the_fields_that_changed() {
assert!(!stdout.contains("due"), "{stdout:?}");
}
/// An empty scalar looks like a way to clear a field, and clearing is not supported.
/// An empty scalar is still a usage error, and the message now points at the flag that
/// does clear a field, so the two do not contradict each other.
///
/// `--title` is the exception, and says only that the value cannot be empty: a title has
/// no unset state to return to, so there is nothing to point at.
#[test]
fn set_refuses_an_empty_scalar_as_a_usage_error() {
let temp = TempDir::new().unwrap();
@@ -198,12 +209,244 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
create_ticket(&worklane);
let before = ticket(&worklane);
for flag in ["--title", "--due", "--tags"] {
for (flag, expected) in [
("--title", "value cannot be empty"),
("--due", "use --clear"),
("--tags", "use --clear"),
] {
let out = run(&temp, &["set", UUID, flag, ""]);
assert_eq!(out.status.code(), Some(2), "{flag} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
"{flag}: {:?}",
!stderr.contains("not supported"),
"{flag} still says clearing is unsupported: {stderr:?}"
);
}
assert_eq!(ticket(&worklane), before);
}
/// An empty value is a paragraph break for a section, so it cannot also mean empty the
/// section. The error names the flag that does, per section.
#[test]
fn set_refuses_an_empty_section_and_names_the_clear_for_it() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for (flag, expected) in [
("--description", "--clear description"),
("--acceptance", "--clear acceptance"),
("--plan", "--clear plan"),
] {
let out = run(&temp, &["set", UUID, flag, ""]);
assert_eq!(out.status.code(), Some(1), "{flag} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
}
assert_eq!(ticket(&worklane), before);
}
/// Every field `--clear` reaches, in one call, back to what a ticket is born with.
#[test]
fn clear_returns_every_field_it_reaches_to_unset() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(
&temp,
&[
"set",
UUID,
"--clear",
"due",
"--clear",
"tags",
"--clear",
"priority",
"--clear",
"description",
"--clear",
"acceptance",
"--clear",
"plan",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- **Due**: _Not set_"), "{content}");
assert!(content.contains("- **Tags**: _None_"), "{content}");
assert!(content.contains("- **Priority**: _Not set_"), "{content}");
assert!(
content.contains("## Description\n_No description provided._\n"),
"{content}"
);
assert!(
content.contains("## Acceptance Criteria\n_No acceptance criteria provided._\n"),
"{content}"
);
assert!(
content.contains("## Implementation Plan\n_No implementation plan provided._\n"),
"{content}"
);
// The placeholder goes in bare, not dressed as an item of the section it replaces.
assert!(!content.contains("- [ ] _No"), "{content}");
assert!(!content.contains("1. _No"), "{content}");
// What --clear cannot reach is untouched, the handwritten section included.
assert!(content.starts_with("# Original title\n"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(content.contains("- **Status**: backlog"), "{content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"{content}"
);
}
/// A cleared ticket and one that was never given the field have to read the same, or
/// clearing would be its own third state.
#[test]
fn a_cleared_ticket_reads_like_one_filed_without_the_fields() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
run(&temp, &["add", "--title", "Bare"]);
run(
&temp,
&[
"add",
"--title",
"Full",
"--description",
"A body.",
"--acceptance",
"One criterion",
"--plan",
"One step",
"--tags",
"alpha,beta",
"--due",
"2026-09-01",
"--priority",
"2",
],
);
let full = added(&worklane, "full");
let out = run(
&temp,
&[
"set",
&full.0,
"--clear",
"due",
"--clear",
"tags",
"--clear",
"priority",
"--clear",
"description",
"--clear",
"acceptance",
"--clear",
"plan",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let cleared = comparable(&fs::read_to_string(&full.1).unwrap());
let bare = comparable(&fs::read_to_string(&added(&worklane, "bare").1).unwrap());
assert_eq!(cleared, bare);
}
/// The uuid and the file of the one ticket whose slug matches, as `add` wrote it.
fn added(worklane: &Path, slug: &str) -> (String, PathBuf) {
let entry = fs::read_dir(worklane.join("backlog"))
.unwrap()
.filter_map(|e| e.ok())
.find(|e| e.file_name().to_string_lossy().ends_with(&format!("_{slug}.md")))
.unwrap_or_else(|| panic!("no ticket slugged {slug}"));
let name = entry.file_name().into_string().unwrap();
let uuid = name.split('_').next().unwrap().to_string();
(uuid, entry.path())
}
/// A ticket without the three lines that are different by definition: its title, its
/// uuid and the moment it was filed.
fn comparable(content: &str) -> String {
content
.lines()
.filter(|line| {
!line.starts_with("# ")
&& !line.contains("**ID**:")
&& !line.contains("**Created At**:")
})
.collect::<Vec<_>>()
.join("\n")
}
/// Nothing to take away is not a rewrite, per the same whole-file comparison a
/// replacement uses.
#[test]
fn clearing_a_field_that_is_already_unset_is_no_change() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
let before = ticket(&worklane);
let out = run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
assert!(out.status.success());
assert!(
String::from_utf8_lossy(&out.stdout).contains("No changes"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
}
/// Replaced and emptied are reported in those words, since a caller doing both in one
/// call cannot tell which happened to which field otherwise.
#[test]
fn clear_is_reported_apart_from_a_replacement() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["set", UUID, "--priority", "1", "--clear", "due"]);
assert!(out.status.success());
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Updated priority on 'Original title'"), "{stdout:?}");
assert!(stdout.contains("Cleared due on 'Original title'"), "{stdout:?}");
}
/// Replacing and clearing one field in a single call is a contradiction, and answering
/// it by whichever was applied last would be a silent answer.
#[test]
fn clearing_and_replacing_the_same_field_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for (flag, value, field) in [
("--due", "2026-12-31", "due"),
("--tags", "beta", "tags"),
("--priority", "1", "priority"),
("--acceptance", "A criterion", "acceptance"),
] {
let out = run(&temp, &["set", UUID, flag, value, "--clear", field]);
assert_eq!(out.status.code(), Some(1), "{flag} with --clear {field} was accepted");
assert!(
String::from_utf8_lossy(&out.stderr).contains("contradict each other"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
}
@@ -211,25 +454,45 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
assert_eq!(ticket(&worklane), before);
}
/// An empty value is a paragraph break for a section, so an all-blank one is a
/// clearing attempt rather than a break.
/// The fields no writer of `set` can reach are not reachable through `--clear` either,
/// and an unknown one is a usage error listing what is.
#[test]
fn set_refuses_to_clear_a_section() {
fn clear_refuses_a_field_it_does_not_own() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["set", UUID, "--description", ""]);
assert_eq!(out.status.code(), Some(1));
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing is not supported"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
for field in [
"owner",
"title",
"status",
"campaign",
"relations",
"nonsense",
] {
let out = run(&temp, &["set", UUID, "--clear", field]);
assert_eq!(out.status.code(), Some(2), "--clear {field} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("possible values"), "{field}: {stderr:?}");
}
assert_eq!(ticket(&worklane), before);
}
/// `--clear` on its own satisfies the at-least-one-field rule, since it is a field
/// being written like any other.
#[test]
fn clear_alone_is_enough_of_a_field() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["set", UUID, "--clear", "due"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(ticket(&worklane).contains("- **Due**: _Not set_"));
}
/// A bare `set <ticket>` would otherwise be a silent no-op.
#[test]
fn set_requires_at_least_one_field() {
@@ -248,10 +511,7 @@ fn set_keeps_a_paragraph_break_in_a_replaced_description() {
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(
&temp,
&["set", UUID, "-d", "One.", "-d", "", "-d", "Two."],
);
run(&temp, &["set", UUID, "-d", "One.", "-d", "", "-d", "Two."]);
assert!(
ticket(&worklane).contains("## Description\nOne.\n\nTwo.\n\n## Acceptance"),
@@ -268,7 +528,14 @@ fn set_accepts_prose_that_begins_with_a_hyphen() {
let out = run(
&temp,
&["set", UUID, "-a", "--print should be supported", "-t", "-t is the title flag"],
&[
"set",
UUID,
"-a",
"--print should be supported",
"-t",
"-t is the title flag",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
@@ -296,11 +563,16 @@ fn append_adds_a_paragraph_items_and_numbered_steps() {
let out = run(
&temp,
&[
"append", UUID,
"-d", "A third paragraph.",
"-a", "Crit three",
"-a", "Crit four",
"-p", "Step three",
"append",
UUID,
"-d",
"A third paragraph.",
"-a",
"Crit three",
"-a",
"Crit four",
"-p",
"Step three",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
@@ -315,10 +587,7 @@ fn append_adds_a_paragraph_items_and_numbered_steps() {
"{content}"
);
// Numbered on from the last step, and the steps above are untouched
assert!(
content.contains("1. Step one\n2. Step two\n3. Step three\n"),
"{content}"
);
assert!(content.contains("1. Step one\n2. Step two\n3. Step three\n"), "{content}");
}
#[test]
@@ -342,14 +611,26 @@ fn append_replaces_an_empty_section_rather_than_following_its_placeholder() {
run(
&temp,
&["append", &uuid, "-d", "A description arrives late.", "-a", "First crit", "-p", "First step"],
&[
"append",
&uuid,
"-d",
"A description arrives late.",
"-a",
"First crit",
"-p",
"First step",
],
);
let content = ticket(&worklane);
assert!(!content.contains("_No description provided._"), "{content}");
assert!(!content.contains("_No acceptance criteria provided._"), "{content}");
assert!(!content.contains("_No implementation plan provided._"), "{content}");
assert!(content.contains("## Description\nA description arrives late.\n"), "{content}");
assert!(
content.contains("## Description\nA description arrives late.\n"),
"{content}"
);
assert!(content.contains("## Implementation Plan\n1. First step\n"), "{content}");
}
@@ -415,3 +696,50 @@ fn neither_command_can_write_owner_or_status() {
assert!(content.contains("- **Owner**: alice"));
assert!(content.contains("- **Status**: backlog"));
}
/// The same parser `add` uses, from one definition. Grooming a board sets dates through
/// `set`, so validating only the command that files a ticket would leave the path that
/// is actually used wide open.
#[test]
fn set_refuses_a_due_date_that_is_not_a_real_iso_date() {
for value in ["next friday", "2026-02-30", "2026-8-9"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = create_ticket(&worklane);
let before = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
let out = cmd
.current_dir(temp.path())
.args(["set", UUID])
.args(["--due", value])
.assert()
.failure()
.get_output()
.clone();
assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error");
assert_eq!(
fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap(),
before,
"{value:?} changed the ticket anyway"
);
}
}
#[test]
fn set_stores_a_valid_due_date_unchanged() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = create_ticket(&worklane);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args(["set", UUID])
.args(["--due", "2026-12-31"])
.assert()
.success();
let content = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap();
assert!(content.contains("- **Due**: 2026-12-31"), "{content}");
}
+38 -6
View File
@@ -350,7 +350,10 @@ fn show_disambiguates_tickets_with_non_ascii_filenames() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
for (filename, title) in [("émigré-un.md", "Accented One"), ("日本語-二.md", "Accented Two")] {
for (filename, title) in [
("émigré-un.md", "Accented One"),
("日本語-二.md", "Accented Two"),
] {
fs::write(
worklane.join("backlog").join(filename),
format!("# {}\n\n## Metadata\n\n- **ID**: 1234\n", title),
@@ -444,11 +447,7 @@ fn show_prints_the_title_once() {
cmd.current_dir(temp.path()).arg("show").arg("Once Only");
let stdout = get_stdout(&mut cmd);
assert_eq!(
stdout.matches("Once Only").count(),
1,
"title repeated in {stdout:?}"
);
assert_eq!(stdout.matches("Once Only").count(), 1, "title repeated in {stdout:?}");
// The rule under it is still the width of the title
assert!(stdout.contains("Once Only\n─────────\n"), "{stdout:?}");
}
@@ -489,6 +488,39 @@ fn show_renders_the_metadata_as_an_aligned_table() {
assert!(content.contains("- **Owner**: alice"));
}
/// The stamps `mv` writes are fields like any other: the table renders what the file
/// holds, so nothing here knows their names, and the column widens to the longest of
/// them the way it does for anything else.
#[test]
fn show_renders_a_status_stamp_in_the_metadata_table() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = "abc123def456789012345678901234567890_stamped.md";
fs::write(
worklane.join("committed").join(filename),
"# Stamped Ticket\n\n## Metadata\n\n\
- **ID**: abc123def456789012345678901234567890\n\
- **Created At**: 2026-08-20 15:51:01\n\
- **Committed On**: 2026-08-22 09:14:30\n\
- **Status**: committed\n",
)
.unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("show").arg("Stamped");
let stdout = get_stdout(&mut cmd);
assert!(
stdout.contains(
"Created At 2026-08-20 15:51:01\n\
Committed On 2026-08-22 09:14:30\n\
Status committed\n"
),
"{stdout:?}"
);
}
/// Write a ticket with an exact uuid and title, since both matter to resolution.
fn ticket_with(worklane: &std::path::Path, status: &str, uuid: &str, title: &str, slug: &str) {
fs::write(
+634
View File
@@ -0,0 +1,634 @@
//! `worklane tags`, the tag vocabulary.
//!
//! The command exists because `--tag` answers what carries a tag and cannot answer what
//! tags exist, which is the question a grooming sweep starts from. So the properties
//! under test are the ones that question needs: every status counted, case kept apart,
//! alphabetical order, and an output a shell can parse.
//!
//! `tags add` is the other half of the same question. The file reports the vocabulary the
//! board *intends* and the tickets carry the one it *has*, and the tests below are mostly
//! about the two being allowed to disagree without either one damaging the other. The
//! listing reports both and marks which is which, so the tests for the output shape are
//! about the marking: which field it lands in, and what a board with no file still prints.
use assert_cmd::Command;
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
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 carrying `tags` verbatim, so a test can write the field the way a hand-made
/// ticket would: spaced, unspaced, unset or absent.
fn create_ticket(worklane: &Path, status: &str, uuid: &str, tags: &str) {
let path = worklane.join(status).join(format!("{uuid}_ticket.md"));
fs::write(
&path,
format!(
"# Ticket {uuid}\n\
\n\
## Description\n\
Prose that says **Tags**: not-a-field, in the body.\n\
\n\
## Metadata\n\
\n\
- **ID**: {uuid}\n\
- **Priority**: 3\n\
- **Tags**: {tags}\n\
- **Owner**: alice\n\
- **Created At**: 2026-08-21 02:10:17\n\
- **Status**: {status}\n"
),
)
.unwrap();
}
fn run(temp: &TempDir, args: &[&str]) -> std::process::Output {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(args);
cmd.assert().get_output().clone()
}
fn tags(temp: &TempDir) -> Vec<String> {
let out = run(temp, &["tags"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
String::from_utf8_lossy(&out.stdout)
.lines()
.map(str::to_string)
.collect()
}
/// Every status, done included, and the count is tickets rather than mentions.
#[test]
fn tags_counts_every_tag_on_the_board() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
create_ticket(&worklane, "committed", "22222222", "bug,tui");
create_ticket(&worklane, "done", "33333333", "bug");
assert_eq!(tags(&temp), vec!["bug\t3", "cli\t1", "tui\t1"]);
}
/// Alphabetical, which is the property that makes a near-duplicate findable: the two
/// spellings land next to each other.
#[test]
fn tags_are_alphabetical_so_near_duplicates_are_adjacent() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "tui,bug,bugfix,cli");
assert_eq!(tags(&temp), vec!["bug\t1", "bugfix\t1", "cli\t1", "tui\t1"]);
}
/// Case sensitive, like the `--tag` filter. Folding the two together here would hide the
/// reason a filter came back short.
#[test]
fn tags_keeps_case_apart_the_way_the_filter_does() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug");
create_ticket(&worklane, "backlog", "22222222", "Bug");
assert_eq!(tags(&temp), vec!["Bug\t1", "bug\t1"]);
// And the filter agrees with the listing, which is the point of keeping them apart.
let filtered = String::from_utf8_lossy(&run(&temp, &["ls", "--tag", "bug", "--ids"]).stdout)
.lines()
.count();
assert_eq!(filtered, 1);
}
/// An unset field, an absent one and a field of separators are all no tags, the same
/// three cases `parse_tags` folds together.
#[test]
fn tags_ignores_a_ticket_with_nothing_to_count() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "_None_");
create_ticket(&worklane, "backlog", "22222222", " , ,");
create_ticket(&worklane, "backlog", "33333333", "");
// No Tags field at all, the way a hand-made ticket can be.
fs::write(
worklane.join("backlog").join("44444444_bare.md"),
"# Bare\n\n## Metadata\n\n- **ID**: 44444444\n- **Status**: backlog\n",
)
.unwrap();
create_ticket(&worklane, "backlog", "55555555", "real");
assert_eq!(tags(&temp), vec!["real\t1"]);
}
/// A board with no tags prints nothing rather than a sentence, since a completion reads
/// this and a sentence would become a candidate.
#[test]
fn tags_says_nothing_on_a_board_with_no_tags() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags"]);
assert!(out.status.success());
assert_eq!(String::from_utf8_lossy(&out.stdout), "");
}
/// Unstyled, like `ls --ids`: a shell reads this and an escape sequence would land in
/// the candidate.
#[test]
fn tags_is_unstyled() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug");
let listing = String::from_utf8_lossy(&run(&temp, &["tags"]).stdout).to_string();
assert!(!listing.contains('\u{1b}'), "{listing:?}");
}
/// The Tags line in a Description is prose, not a field, the same rule every other
/// metadata read follows.
#[test]
fn tags_reads_only_the_metadata_section() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug");
assert_eq!(tags(&temp), vec!["bug\t1"]);
}
/// A missing status directory is skipped rather than refused, as in `ls --ids`: the
/// caller is usually a shell, and an error over the prompt is worse than fewer answers.
#[test]
fn tags_skips_a_missing_status_directory() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug");
fs::remove_dir_all(worklane.join("reviewing")).unwrap();
assert_eq!(tags(&temp), vec!["bug\t1"]);
}
// ------------------------------------------------------------- the vocabulary --
fn vocabulary(temp: &TempDir) -> String {
fs::read_to_string(temp.path().join(".worklane").join("tags.md")).unwrap()
}
/// The section a tag holds in the file, heading excluded, or `None` when it is not
/// declared. Cut out of the file rather than asserted against a whole rendering, so a
/// change to the preamble does not fail every test here.
fn declared(temp: &TempDir, tag: &str) -> Option<String> {
let file = vocabulary(temp);
let (_, rest) = file.split_once(&format!("\n## {tag}\n"))?;
let body = match rest.split_once("\n## ") {
Some((body, _)) => body,
None => rest,
};
Some(body.trim().to_string())
}
/// The declaration lands in the file, with the annotation under it.
#[test]
fn tags_add_declares_a_tag_with_what_it_means() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(
&temp,
&[
"tags",
"add",
"bug",
"--annotation",
"Something the binary does wrong.",
],
);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something the binary does wrong."));
}
/// Several flags are several lines, and an empty one is a paragraph break, the way a
/// description is written.
#[test]
fn an_annotation_takes_several_lines_and_a_paragraph_break() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(
&temp,
&[
"tags",
"add",
"bug",
"-a",
"What it is.",
"-a",
"",
"-a",
"When to use it.",
],
);
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
}
/// A tag can be declared with nothing said about it. The word being agreed on is worth
/// recording before anyone has written the sentence.
#[test]
fn a_tag_can_be_declared_without_an_annotation() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags", "add", "cli"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "cli").as_deref(), Some("_No annotation provided._"));
}
/// Refused rather than overwritten, and the refusal names what does overwrite it: an
/// annotation is the sentence a team files tickets against, not something to replace by
/// typing `add` twice.
#[test]
fn declaring_a_tag_twice_is_refused_and_names_the_command_that_replaces_it() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
let out = run(&temp, &["tags", "add", "bug", "-a", "A different sentence."]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("tags set"), "{stderr}");
assert_eq!(declared(&temp, "bug").as_deref(), Some("The first sentence."));
}
/// A comma is what separates one tag from the next, so a value carrying one could never be
/// matched by `--tag`. Refused at parse, with nothing written.
#[test]
fn a_tag_the_filter_could_never_match_is_refused() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
for value in ["bug,cli", ""] {
let out = run(&temp, &["tags", "add", value]);
assert!(!out.status.success(), "'{value}' was accepted");
}
// Nothing was written on the way past, not even the empty file.
assert!(!temp.path().join(".worklane").join("tags.md").exists());
}
/// Surrounding space is trimmed rather than refused, because a ticket's Tags field is read
/// that way too: ` bug ` on a card is the tag `bug`, and the vocabulary has to agree.
#[test]
fn a_padded_tag_is_declared_under_its_trimmed_name() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", " bug "]);
assert!(declared(&temp, "bug").is_some(), "{}", vocabulary(&temp));
}
/// An annotation line that would be read back as a heading is refused, since it would split
/// the section and declare whatever followed it.
#[test]
fn an_annotation_that_would_read_as_a_heading_is_refused() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags", "add", "bug", "-a", "## cli"]);
assert!(!out.status.success());
assert!(!temp.path().join(".worklane").join("tags.md").exists());
}
/// The file is made on demand, the way `campaign add` makes the campaigns directory: a board
/// that predates the vocabulary must not need `worklane init` run over it.
#[test]
fn the_file_is_created_on_a_board_that_predates_it() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
assert!(!temp.path().join(".worklane").join("tags.md").exists());
run(&temp, &["tags", "add", "bug"]);
assert!(declared(&temp, "bug").is_some());
}
/// `init` writes it, so a new board has one file shape rather than two.
#[test]
fn init_writes_the_vocabulary_beside_the_status_directories() {
let temp = TempDir::new().unwrap();
let out = run(&temp, &["init"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let file = vocabulary(&temp);
assert!(file.starts_with("# Tags"), "{file}");
// The preamble and nothing else: a new board declares no tags.
assert!(!file.contains("\n## "), "{file}");
}
/// A second declaration keeps the first, and the file stays alphabetical: the whole file is
/// re-rendered, so this is the test that the re-render is not a truncation.
#[test]
fn declaring_a_tag_leaves_the_others_alone_and_keeps_the_order() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "tui", "-a", "The board view."]);
run(&temp, &["tags", "add", "bug", "-a", "Something wrong."]);
assert_eq!(declared(&temp, "tui").as_deref(), Some("The board view."));
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something wrong."));
let file = vocabulary(&temp);
assert!(file.find("## bug").unwrap() < file.find("## tui").unwrap(), "{file}");
}
/// A file that is there and cannot be read stops the write rather than being taken for an
/// empty vocabulary. Empty would mean erased, since every declaration re-renders the file.
#[test]
fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
// A directory where the file should be: `read_to_string` fails on it, which a missing
// file does not.
fs::create_dir(worklane.join("tags.md")).unwrap();
let out = run(&temp, &["tags", "add", "bug"]);
assert!(!out.status.success());
assert!(worklane.join("tags.md").is_dir(), "the file was replaced");
// And nothing was staged and left behind.
let stray: Vec<_> = fs::read_dir(&worklane)
.unwrap()
.filter_map(|e| e.ok())
.filter(|e| e.file_name().to_string_lossy().starts_with(".wl-"))
.collect();
assert!(stray.is_empty(), "a temp file was left in .worklane");
}
/// The listing is the union of the two vocabularies, and the two disagreeing is the normal
/// state rather than a fault: a declaration tags no ticket, and tagging a ticket declares
/// nothing.
///
/// Both halves of the disagreement in one assertion, since neither is legible without the
/// other. `chore` is declared and carried by nothing, so it lists at zero with what it
/// means; `bug` is carried and declared by nothing, so it lists with a count and no third
/// field at all.
#[test]
fn the_listing_is_the_union_of_the_declared_and_the_carried() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug");
run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]);
assert_eq!(tags(&temp), vec!["bug\t1", "chore\t0\tHousekeeping."]);
}
/// The third field is the annotation's *opening* line. An annotation is prose with
/// paragraphs in it, and a second line in this output would be read as a second tag.
#[test]
fn the_annotation_is_cut_to_its_opening_line() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(
&temp,
&[
"tags",
"add",
"bug",
"-a",
"What it is.",
"-a",
"",
"-a",
"When to use it.",
],
);
assert_eq!(tags(&temp), vec!["bug\t0\tWhat it is."]);
}
/// A tag declared with nothing said about it still carries a third field, and it is the
/// placeholder the file itself holds under that heading.
///
/// The subtle case, and the reason the field is not simply left empty: an empty third field
/// is a trailing tab, so the only difference between a declared tag and an undeclared one
/// would be invisible in a terminal and in a completion alike.
#[test]
fn a_tag_declared_without_an_annotation_is_still_marked_as_declared() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "carried");
run(&temp, &["tags", "add", "declared"]);
assert_eq!(tags(&temp), vec!["carried\t1", "declared\t0\t_No annotation provided._"]);
}
/// `cut -f1` over the listing yields exactly the tag values, undeclared ones included.
///
/// The constraint the whole output shape is built around: whatever marks a carried but
/// undeclared tag must stay out of the first field, or a completion offers a tag that does
/// not exist and `ls --tag` comes back empty for it.
#[test]
fn the_first_field_is_the_bare_tag_whether_it_is_declared_or_not() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "carried,both");
run(&temp, &["tags", "add", "both", "-a", "Carried and declared."]);
run(&temp, &["tags", "add", "declared", "-a", "Declared only."]);
let first: Vec<String> = tags(&temp)
.iter()
.map(|line| line.split('\t').next().unwrap().to_string())
.collect();
assert_eq!(first, vec!["both", "carried", "declared"]);
// And each of them is a value `--tag` can match, which is what the first field is for.
for tag in ["both", "carried"] {
let out = run(&temp, &["ls", "--tag", tag, "--ids"]);
assert_eq!(
String::from_utf8_lossy(&out.stdout).lines().count(),
1,
"--tag {tag} matched nothing"
);
}
}
/// A board with no vocabulary lists what it listed before the file existed, byte for byte.
///
/// Every tag on such a board is carried and undeclared, so the absence of the third field
/// is what keeps the old output shape: a marker in it would have changed every line of
/// every board that predates the file, and the shipped fish completion of an older version
/// is still reading this.
#[test]
fn a_board_with_no_vocabulary_lists_what_it_listed_before_the_file_existed() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
create_ticket(&worklane, "done", "22222222", "bug");
assert!(!temp.path().join(".worklane").join("tags.md").exists());
let out = run(&temp, &["tags"]);
assert_eq!(String::from_utf8_lossy(&out.stdout), "bug\t2\ncli\t1\n");
}
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
/// that way to fill in `ls --tag`. `tags ls` is the same thing spelled as a group.
#[test]
fn the_bare_form_and_ls_are_the_same_listing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
run(&temp, &["tags", "add", "chore"]);
let bare = run(&temp, &["tags"]);
let group = run(&temp, &["tags", "ls"]);
assert!(bare.status.success());
assert_eq!(bare.stdout, group.stdout);
assert_eq!(
String::from_utf8_lossy(&bare.stdout),
"bug\t1\nchore\t0\t_No annotation provided._\ncli\t1\n"
);
}
// -------------------------------------------------- changing what a tag means --
/// The replacement lands, and replaces rather than appends.
#[test]
fn tags_set_replaces_what_a_tag_means() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
let out = run(&temp, &["tags", "set", "bug", "-a", "The second sentence."]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "bug").as_deref(), Some("The second sentence."));
assert!(!vocabulary(&temp).contains("first"), "the old annotation survived");
}
/// Paragraph breaks survive the round trip, which is the whole difference between an
/// annotation and a one-line description of a tag.
#[test]
fn a_multiline_annotation_survives_being_set() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug"]);
run(
&temp,
&[
"tags",
"set",
"bug",
"-a",
"What it is.",
"-a",
"",
"-a",
"When to use it.",
],
);
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
}
/// Set to what it already says, nothing is written and the command says so, the way `set`
/// and `chown` report a field that already holds the value.
#[test]
fn setting_an_annotation_to_what_it_already_says_writes_nothing() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
let before = fs::metadata(temp.path().join(".worklane").join("tags.md"))
.unwrap()
.modified()
.unwrap();
let out = run(&temp, &["tags", "set", "bug", "-a", "The sentence."]);
assert!(out.status.success());
assert!(String::from_utf8_lossy(&out.stdout).contains("No changes"), "{out:?}");
let after = fs::metadata(temp.path().join(".worklane").join("tags.md"))
.unwrap()
.modified()
.unwrap();
assert_eq!(before, after, "the file was rewritten for a no-op");
}
/// `add` and `set` are a pair, each refusing what the other is for, so the refusal names
/// the other command rather than leaving it to be found.
#[test]
fn setting_a_tag_that_is_not_declared_is_refused_and_names_add() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug"]);
let out = run(&temp, &["tags", "set", "cli", "-a", "Anything."]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("tags add"), "{stderr}");
assert!(declared(&temp, "cli").is_none(), "the tag was declared by set");
}
/// A bare `tags set <tag>` is a usage error. Nothing to write is a mistake in the call, not
/// a command that quietly does nothing.
#[test]
fn setting_nothing_is_a_usage_error() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
let out = run(&temp, &["tags", "set", "bug"]);
assert_eq!(out.status.code(), Some(2), "{out:?}");
assert_eq!(declared(&temp, "bug").as_deref(), Some("The sentence."));
}
/// An annotation can be emptied back to the placeholder, which is the state a tag declared
/// without one is already in. That is why there is no `--clear`.
#[test]
fn an_annotation_can_be_emptied_back_to_the_placeholder() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
run(&temp, &["tags", "set", "bug", "-a", ""]);
assert_eq!(declared(&temp, "bug").as_deref(), Some("_No annotation provided._"));
}
/// The other tags keep their sections, since the whole file is re-rendered on every write.
#[test]
fn setting_one_annotation_leaves_the_others_alone() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "About bugs."]);
run(&temp, &["tags", "add", "tui", "-a", "About the board."]);
run(&temp, &["tags", "set", "bug", "-a", "Rewritten."]);
assert_eq!(declared(&temp, "bug").as_deref(), Some("Rewritten."));
assert_eq!(declared(&temp, "tui").as_deref(), Some("About the board."));
}
+3 -12
View File
@@ -44,10 +44,7 @@ fn the_tui_outside_a_worklane_directory_gives_the_usual_message() {
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(1), "{args:?}");
assert!(
stderr.contains("No .worklane directory found"),
"{args:?}: {stderr:?}"
);
assert!(stderr.contains("No .worklane directory found"), "{args:?}: {stderr:?}");
}
}
@@ -66,10 +63,7 @@ fn the_tui_without_a_terminal_says_so_and_names_an_alternative() {
assert_eq!(out.status.code(), Some(1), "{args:?}");
assert!(stderr.contains("needs a terminal"), "{args:?}: {stderr:?}");
assert!(stderr.contains("worklane ls"), "{args:?}: {stderr:?}");
assert!(
!stderr.contains("os error"),
"the raw mode error leaked: {stderr:?}"
);
assert!(!stderr.contains("os error"), "the raw mode error leaked: {stderr:?}");
}
}
@@ -105,10 +99,7 @@ fn several_path_arguments_are_accepted() {
let first = setup_project(&temp, "first");
let second = setup_project(&temp, "second");
let out = run(
&temp,
&["tui", first.to_str().unwrap(), second.to_str().unwrap()],
);
let out = run(&temp, &["tui", first.to_str().unwrap(), second.to_str().unwrap()]);
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(1), "{stderr:?}");