Compare commits

..
15 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
25 changed files with 7303 additions and 709 deletions
+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
+67 -7
View File
@@ -13,6 +13,8 @@
- `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
@@ -23,6 +25,7 @@
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- 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
@@ -42,6 +45,10 @@ and this file is for what someone changing worklane's own code needs.
- Tests use `assert_cmd` and `assert_fs` for CLI testing
- `setup_worklane()` creates temp `.worklane/` with all four status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it
- `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:
@@ -118,6 +125,7 @@ and this file is for what someone changing worklane's own code needs.
- 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` 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
@@ -178,9 +186,14 @@ and this file is for what someone changing worklane's own code needs.
- `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` is the only writer of a filed campaign's fields, and it carries the two scalars.** d637288 decided it: 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. `--title`, which renames the file the way `set --title` does, and `--codename`. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
- **`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
- **No `campaign set --description`, and that is the line, not an oversight.** `set` and `append` are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line `append` already draws for a ticket. `campaign_set_offers_no_description_and_no_owner` pins it. No `--owner` either, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign; and no `--clear`, because a wrong codename is replaced rather than emptied and `Clearable` is `SetArgs`'s, its variants being a ticket's fields
- **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
@@ -196,6 +209,7 @@ 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
@@ -217,24 +231,54 @@ and this file is for what someone changing worklane's own code needs.
- `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 is three rows, and `Chrome` is what every measurement takes.** `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 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` on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards
- **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
@@ -302,6 +346,13 @@ and this file is for what someone changing worklane's own code needs.
- `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
@@ -309,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
@@ -318,13 +369,14 @@ 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. `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 **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
@@ -333,6 +385,14 @@ and this file is for what someone changing worklane's own code needs.
- 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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.22.0"
version = "0.27.1"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.22.0"
version = "0.27.1"
edition = "2024"
[dependencies]
+5 -3
View File
@@ -5,7 +5,7 @@ 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, whose border carries a page indicator 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; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. 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. `--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 |
@@ -19,13 +19,15 @@ Worklane is a local Kanban flow for agentic software development.
| `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 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, and `--codename`. At least one required. The only way to change a campaign after it is filed, and the way a campaign filed before codenames existed gets one. 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. No `--description`: replacing prose without an `append` to add a paragraph is half a pair |
| `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. Three 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. 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-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
+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.
+19 -1
View File
@@ -136,6 +136,14 @@ field on purpose, which is a different thing from emptying it by forgetting a ta
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:
@@ -160,7 +168,8 @@ fields; a goal is a campaign.
worklane campaign ls
worklane campaign show v1
worklane campaign add --title "..." --codename v1 --description "..."
worklane campaign set v1 --title "..." # or --codename, on one already filed
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
```
@@ -186,6 +195,12 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
- **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.
@@ -199,6 +214,9 @@ out of it. The last part is what makes it a goal rather than a pile.
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.
+12 -4
View File
@@ -211,7 +211,8 @@ worklane campaign add --title "First public release" --codename v1 \
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 or the codename
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
```
@@ -226,9 +227,16 @@ existed needs. **Replacing a codename it already has needs `--force`**: that wor
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` is the only way to change a campaign after it is filed, and it reaches the
title and the codename only. There is no way to edit a campaign's description or its owner
yet.
`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
+16 -9
View File
@@ -201,26 +201,33 @@ pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
let mut grouped = Vec::new();
for status in status_dirs() {
let status_path = worklane_dir.join(status);
// 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(),
};
grouped.push((
status,
items
.into_iter()
.filter(|item| item.campaign.as_deref() == Some(uuid))
.collect(),
));
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,
+208 -19
View File
@@ -130,6 +130,56 @@ fn codename(raw: &str) -> Result<String, 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.
///
@@ -244,15 +294,18 @@ pub enum Command {
ticket: String,
},
/// List the tags the board carries, and how many tickets carry each
/// 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 output is machine-readable, like `ls --ids`: the tag, a tab, the count.
Tags,
/// 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
///
@@ -281,6 +334,23 @@ 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.
@@ -288,10 +358,18 @@ pub enum Command {
/// No `mv`: a campaign has no status to move it to, its state is derived from its
/// members.
///
/// No `append`, and therefore no `set --description`: `set` and `append` are a pair for a
/// prose section, and a way to replace a description with no way to add a paragraph to one
/// is half of it. That pair is its own ticket. `set` here carries the two scalars, which
/// have no append form at all, the same line `append` already draws for a ticket.
/// `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
@@ -299,11 +377,19 @@ pub enum CampaignCommand {
/// Replace fields on an existing campaign
///
/// The only way to change a campaign 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.
/// 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
@@ -324,25 +410,30 @@ pub enum CampaignCommand {
},
}
/// What can be replaced on a campaign that is already filed: its title and its codename.
///
/// The two scalars, and deliberately not the description. See [`CampaignCommand`].
/// 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`: nothing has asked to empty a codename, a wrong one is replaced rather than
/// emptied, and the vocabulary is a real question — `Clearable` is `SetArgs`'s and its
/// variants are a ticket's fields, so reusing it here would put a ticket's enum on a
/// campaign and inventing a second one is a decision worth making on purpose.
/// 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.
/// 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`].
@@ -351,7 +442,7 @@ pub enum CampaignCommand {
clap::ArgGroup::new("campaign_set_fields")
.required(true)
.multiple(true)
.args(["title", "codename"])
.args(["title", "description", "codename"])
))]
pub struct CampaignSetArgs {
/// Campaign UUID, title, filename or codename
@@ -361,6 +452,13 @@ pub struct CampaignSetArgs {
#[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
@@ -379,6 +477,25 @@ pub struct CampaignSetArgs {
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
@@ -412,6 +529,78 @@ pub struct CampaignAddArgs {
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
+100 -16
View File
@@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
/// Nested subcommands whose first argument is a campaign, as `parent child`.
///
/// `campaign show` and `campaign set`, 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); 2] = [("campaign", "show"), ("campaign", "set")];
/// `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"];
@@ -66,6 +71,15 @@ pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
/// 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);
@@ -92,6 +106,11 @@ fn fish_dynamic() -> String {
.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
@@ -178,9 +197,21 @@ 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. The count after the tab lands as fish's description, which is what makes the list
# worth reading: it says which spelling the board actually uses.
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
# 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`
@@ -348,9 +379,24 @@ mod tests {
// A guard on the walker itself: if it stopped finding arguments, every assertion
// above would pass by never running.
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
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.
@@ -363,19 +409,31 @@ mod tests {
}
seen += 1;
let name = path.join(" ");
let long = arg.get_long().unwrap_or_else(|| {
panic!(
"`worklane {name}` takes a tag as a positional, \
which the fish block has no rule for"
)
});
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, 1, "expected ls --tag");
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
@@ -471,6 +529,32 @@ mod tests {
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.
+333 -58
View File
@@ -7,10 +7,11 @@ use std::path::Path;
use crate::campaign::*;
use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
RelateArgs, SetArgs,
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
};
use crate::install;
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
use crate::util::*;
pub fn cmd_init(start: &Path) -> Result<()> {
@@ -33,6 +34,13 @@ pub fn cmd_init(start: &Path) -> Result<()> {
// campaigns, which is why `status_dirs()` is untouched.
fs::create_dir_all(campaigns_dir(&worklane_dir))?;
// The tag vocabulary, beside both for the same reason, and written empty rather than
// left for the first `tags add` to make. An empty file explains itself when it is
// opened, which is the point of the preamble, and a board that has one from the start
// has one file shape rather than two. `fs::write` and not `write_then_replace`: the
// directory was made three lines ago, so there is nothing here to truncate.
fs::write(tags_path(&worklane_dir), TagIndex::default().render())?;
println!("Initialized worklane in: {}", worklane_dir.display());
Ok(())
}
@@ -63,8 +71,10 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
}
if let Some(status) = args.status {
let status = status.as_str();
let status_path = worklane_dir.join(status);
// The `Status` is kept alongside its name: the directory is joined from the
// name, and the order the column prints in is keyed on the status itself.
let name = status.as_str();
let status_path = worklane_dir.join(name);
if !status_path.exists() {
// The status itself is clap's to reject now, so reaching here means the
// board is missing a directory it should have rather than that the name was
@@ -72,19 +82,20 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
// alone.
return Err(anyhow!(
"No '{}' directory in {}. Every board has all four; creating it is enough.",
status,
name,
worklane_dir.display()
));
}
let items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
let mut items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
items.sort_by(|a, b| by_status_order(status, a, b));
if items.is_empty() {
println!("No tickets in '{}' status.", status);
println!("No tickets in '{}' status.", name);
return Ok(());
}
println!("Tickets in '{}' status:\n", status);
println!("Tickets in '{}' status:\n", name);
display_ticket_items(&items);
} else {
// List all statuses with their ticket counts
@@ -101,23 +112,27 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
println!(" [{}] {} {}", status.to_uppercase(), count, label);
}
// Show all tickets except done grouped by status
for status in &statuses {
if *status == DONE {
// Show all tickets except done grouped by status. Over `Status::ALL` rather
// than the names, because each column is ordered by its own entry stamp and the
// comparator is keyed on the status, not on the directory it was read from.
for status in Status::ALL {
if status.as_str() == DONE {
continue;
}
let status_path = worklane_dir.join(status);
let status_path = worklane_dir.join(status.as_str());
if !status_path.exists() || !fs::metadata(&status_path)?.is_dir() {
continue;
}
let items = match collect_ticket_items(&status_path) {
let mut items = match collect_ticket_items(&status_path) {
Ok(items) => filtered(items, priority_filter, uuid, tag),
Err(_) => continue,
};
items.sort_by(|a, b| by_status_order(status, a, b));
if items.is_empty() {
continue;
}
let status_header = color_text(&format!("[{}]", status.to_uppercase()), Color::Orange);
let status_header =
color_text(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange);
println!("\n{}", status_header);
display_ticket_items(&items);
}
@@ -150,16 +165,20 @@ fn list_ids(
worklane_dir: &Path,
) -> Result<()> {
let statuses = match status {
Some(status) => vec![status.as_str()],
None => status_dirs(),
Some(status) => vec![status],
None => Status::ALL.to_vec(),
};
for status in statuses {
let status_path = worklane_dir.join(status);
let status_path = worklane_dir.join(status.as_str());
if !status_path.exists() {
continue;
}
for item in filtered(collect_ticket_items(&status_path)?, level, campaign, tag) {
// The same order the listing prints, so a completion and the board agree on
// which ticket is at the head of a column.
let mut items = filtered(collect_ticket_items(&status_path)?, level, campaign, tag);
items.sort_by(|a, b| by_status_order(status, a, b));
for item in items {
println!("{}\t{}", item.id, item.title);
}
}
@@ -434,7 +453,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
println!("\n{}", content_trim_colored(&content, &resolved));
if ticket_uuid != "_Not set_" {
let comments_dir = worklane_dir.join("comments").join(&ticket_uuid);
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
let comments = read_comments(&comments_dir)?;
let formatted = format_comments(&comments);
println!("{}", formatted);
@@ -451,6 +470,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
/// mid-sentence so there is no capital to case.
const TICKET: &str = "ticket";
const CAMPAIGN: &str = "campaign";
const TAG: &str = "tag";
/// Write `content` over `path`, without ever leaving half a file behind.
///
@@ -720,7 +740,7 @@ pub fn cmd_comment(
return Err(anyhow!("Could not determine ticket ID."));
}
let comments_dir = worklane_dir.join("comments").join(&ticket_uuid);
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
fs::create_dir_all(&comments_dir)?;
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
@@ -764,6 +784,42 @@ fn section_args<'a>(
]
}
/// The lines a caller's values amount to, or the refusal an all-blank call earns.
///
/// An empty value is a paragraph break, so a call whose values are *every one* blank asked
/// for nothing, and writing an empty section is not what it meant. Shared by `set` and
/// `campaign set` because the rule is the section's rather than the object's.
///
/// `instead` is the way out, and it is the caller's because the callers differ: a ticket's
/// section is emptied with `--clear <field>`, and a campaign's description has no cleared
/// form at all, per [`CampaignSetArgs`].
fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result<Vec<String>> {
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"An empty value is a paragraph break, not a way to empty the {}: {}",
section.label,
instead
));
}
Ok(items)
}
/// The same for `append`, which has no way out to name: appending nothing was never a way
/// to empty anything, so the message says only that there was nothing to add.
fn appended_items(section: &Section, values: &[String]) -> Result<Vec<String>> {
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"Nothing to append to the {}: every value given was blank",
section.label
));
}
Ok(items)
}
/// Write the ticket back, renaming the file when a new title changes its slug.
///
/// The content goes down first and the rename second, the same order and for the same
@@ -852,12 +908,23 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static
}
fn report(fields: &[&str], title: &str, verb: &str) {
report_in(fields, title, Color::Green, verb)
}
/// The same, for a subject that is not a title.
///
/// Green means title, everywhere, so the one caller whose subject is a tag cannot use it:
/// a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong, and green is deliberately
/// not one of them. The colour is passed in rather than decided here, which is the trade
/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports
/// a no-op in the same words a ticket does.
fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) {
if fields.is_empty() {
println!("No changes to '{}'", color_text(title, Color::Green));
println!("No changes to '{}'", color_text(title, color));
return;
}
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, Color::Green));
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color));
}
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
@@ -886,14 +953,8 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
continue;
}
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"An empty value is a paragraph break, not a way to empty the {}: use --clear {}",
section.label,
section.clear.map_or("", Clearable::name)
));
}
let clear = format!("use --clear {}", section.clear.map_or("", Clearable::name));
let items = replaced_items(section, values, &clear)?;
let next = set_section_body(&content, section, &items)?;
apply(&mut content, &mut changed, section.label, next);
@@ -1000,13 +1061,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
continue;
}
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"Nothing to append to the {}: every value given was blank",
section.label
));
}
let items = appended_items(section, values)?;
content = append_section_body(&content, section, &items)?;
changed.push(section.label);
@@ -1186,27 +1241,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
Ok(())
}
/// Every tag on the board, with how many tickets carry it.
/// Every tag on the board: the ones the tickets carry, the ones the file declares, and
/// what each declared one means.
///
/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag
/// already known, and the decorated listing does not print tags at all. A grooming sweep
/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say
/// that the question could only be answered by reading the tickets.
///
/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are
/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing
/// carries lists at zero rather than being dropped, and a carried tag nothing declares
/// still lists. Those two cases are the whole reason to declare tags at all, so this is
/// the command that has to show them apart.
///
/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively,
/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter
/// came back short. Sorting puts them next to each other, which is where a near-duplicate
/// is spotted.
///
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count.
/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither
/// wants an escape sequence. Every status, done included, for the reason `ls --ids`
/// includes it: a tag retired months ago is still part of the answer to what the
/// vocabulary has been.
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and
/// a tab and the annotation's opening line for a tag the file declares. Fish reads what
/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an
/// escape sequence.
///
/// **A carried but undeclared tag is marked by the absence of the third field**, which is
/// where the shape comes from. Anything appended to the tag itself would have a completion
/// offer a tag that does not exist, and anything added to the count would stop the second
/// field being a number. Absence costs neither, and it buys the one property a marker
/// could not: 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. The shipped
/// fish completion of an older version is still reading that.
///
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
/// ago is still part of the answer to what the vocabulary has been.
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
// is an error here too. The listing is the one tag command that could go on without the
// file, and reporting a vocabulary while silently treating a broken file as no file is
// the wrong half of the answer.
let index = TagIndex::load(worklane_dir)?;
// BTreeMap rather than a sort afterwards: the order is the point, and the counting
// wants a map anyway.
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
// wants a map anyway. Seeded from the vocabulary rather than merged into afterwards,
// which is what puts a declared tag nothing carries in at zero.
let mut counts: BTreeMap<String, usize> =
index.names().map(|tag| (tag.to_string(), 0)).collect();
for status in status_dirs() {
let status_path = worklane_dir.join(status);
@@ -1222,12 +1302,110 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
}
for (tag, count) in counts {
println!("{}\t{}", tag, count);
match index.summary(&tag) {
Some(summary) => println!("{tag}\t{count}\t{summary}"),
None => println!("{tag}\t{count}"),
}
}
Ok(())
}
/// Declare a tag, and what it means.
///
/// The counterpart of `cmd_tags`, which reports the vocabulary the tickets *carry*. This
/// writes the one the board *intends*, and the two are deliberately not kept in step: a
/// declaration tags nothing, so the file cannot be used to work out what is in use, and
/// `tags add` on a word no ticket carries is the normal case rather than a mistake.
///
/// **A tag already declared is refused rather than overwritten**, the way `add` refuses
/// nothing and `campaign set --codename` refuses a replacement without `--force`. An
/// annotation is the sentence a whole team files tickets against, so replacing one by
/// typing `add` twice is not something to do by accident. The refusal names the command
/// that does replace it, since that is the next thing the caller wants.
///
/// The whole file is re-rendered from the parsed vocabulary, so declaring a tag also
/// re-sorts the file and rewrites its preamble. That is why an unreadable file is an error
/// in `TagIndex::load` rather than an empty vocabulary: here, empty would mean erased.
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
if index.declared(&args.tag) {
return Err(anyhow!(
"Tag '{}' is already declared, so nothing was written. \
Use `worklane tags set` to change what it means",
args.tag
));
}
// Joined with a single newline, so an empty value is a paragraph break, exactly as it
// is for a description.
let annotation = trim_blank_ends(&args.annotation).join("\n");
index.declare(&args.tag, &annotation);
write_then_replace(
&worklane_dir,
&tags_path(&worklane_dir),
TAGS_FILE,
&index.render(),
TAG,
&args.tag,
)?;
// The tag in its own colour, which is the colour it is drawn in on every card and in
// every listing: `tag_color` is a pure function of the word.
println!("Declared tag: {}", color_text(&args.tag, tag_color(&args.tag)));
Ok(())
}
/// Replace what a declared tag means.
///
/// The other half of `tags add`, and the half `campaign` still lacks for its description,
/// 32e98ab. An annotation is the sentence a whole team files tickets against, so getting it
/// wrong once must not be permanent.
///
/// **A tag that is not declared is refused rather than declared here.** `add` and `set` are
/// a pair, each refusing what the other is for, so which of the two wrote a line is never a
/// question of which one happened to be typed. The refusal names the other command, the way
/// `add`'s names this one.
///
/// The no-op compares the rendered file rather than the annotation, which is what `apply`
/// does for a ticket: the file is the thing that would be written, so it is the thing worth
/// asking whether the write would change.
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
if !index.declared(&args.tag) {
return Err(anyhow!(
"No tag '{}' is declared, so nothing was written. \
Use `worklane tags add` to declare it",
args.tag
));
}
let original = index.render();
index.declare(&args.tag, &trim_blank_ends(&args.annotation).join("\n"));
let next = index.render();
let mut changed: Vec<&'static str> = Vec::new();
if original != next {
changed.push("annotation");
write_then_replace(
&worklane_dir,
&tags_path(&worklane_dir),
TAGS_FILE,
&next,
TAG,
&args.tag,
)?;
}
report_in(&changed, &args.tag, tag_color(&args.tag), "Updated");
Ok(())
}
/// Replace fields on a campaign that is already filed.
///
/// `cmd_set` for a campaign, and built out of the same parts: `set_title` for the heading,
@@ -1255,6 +1433,18 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
/// No-op detection compares the whole file, the way `set` and `chown` do, so setting a
/// codename a campaign already carries writes nothing. That is a no-op and not a refusal:
/// `--force` is about overwriting a *different* word, and there is nothing to overwrite.
///
/// **The description goes through `set_section_body` and the `DESCRIPTION` entry**, the
/// section table `cmd_set` and `campaign_body` already read, so what a campaign's one prose
/// section *is* stays decided in one place. A second definition scoped to campaigns would
/// drift on the spelling of the heading, which is the drift `campaign_body` was written
/// against.
///
/// A campaign whose Description heading is gone is refused by that call rather than given
/// the section back through `ensure_section`. Every campaign the tool has ever filed carries
/// the heading, so an insertion path here would be reachable only from a hand-edited file:
/// that is the opposite of the Relations case, where `add` writes nothing and the insertion
/// is the only path there is.
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
@@ -1282,6 +1472,16 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
apply(&mut content, &mut changed, "title", next);
}
if !args.description.is_empty() {
let items = replaced_items(
&DESCRIPTION,
&args.description,
"a campaign's description has no cleared form",
)?;
let next = set_section_body(&content, &DESCRIPTION, &items)?;
apply(&mut content, &mut changed, DESCRIPTION.label, next);
}
if let Some(codename) = &args.codename {
let next = set_or_insert_metadata_field(&content, CODENAME_FIELD, codename, &title)?;
apply(&mut content, &mut changed, "codename", next);
@@ -1299,6 +1499,32 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
Ok(())
}
/// Add a paragraph to a campaign's description.
///
/// The other half of `campaign set --description`, and `cmd_append` for a campaign: the same
/// `append_section_body` and the same `DESCRIPTION` entry, so a paragraph lands under a
/// campaign's description the way it lands under a ticket's, blank line and all. A campaign
/// filed with no description holds the placeholder, and that is replaced rather than
/// followed, which is `append_section_body`'s rule and not a case handled here.
///
/// No whole-file comparison, unlike `set`: every value blank is refused above, so there is
/// nothing left that appends nothing. `cmd_append` says it the same way.
///
/// One section, so there is no loop and no list to report: what changed is the description
/// or the call failed.
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
let items = appended_items(&DESCRIPTION, &args.description)?;
let content = append_section_body(&campaign.content, &DESCRIPTION, &items)?;
save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?;
report(&[DESCRIPTION.label], &campaign.title, "Appended to");
Ok(())
}
/// Show a campaign, then its members grouped by status.
///
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
@@ -1551,9 +1777,38 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
};
let root = install::skills_root()?;
let written = install_each(&chosen, &root, force, |asset| {
format!("worklane install-skill {} --print", asset.name)
})?;
// Once, and only when something arrived: repeating it per document would make the
// instruction look like part of each outcome rather than the one thing to do next.
if written {
println!("Claude Code and opencode pick it up on their next session");
}
Ok(())
}
/// Write each asset under `root` and report what happened to it.
///
/// Shared by both install commands, which differ in what they install and in what they
/// say afterwards, never in how an outcome is reported. `compare` is the invocation the
/// refusal points at, which is the one line that has to name the command it came from.
///
/// Returns whether anything was written, because that is what decides the closing line:
/// each command has its own thing to say about what picks the asset up, and neither
/// should say it once per asset.
fn install_each(
chosen: &[&install::Asset],
root: &Path,
force: bool,
compare: impl Fn(&install::Asset) -> String,
) -> Result<bool> {
let mut written = false;
for asset in chosen {
match asset.install(&root, force)? {
match asset.install(root, force)? {
install::Outcome::Written(path) => {
println!("Installed the {} {} to: {}", asset.name, asset.what, path.display());
written = true;
@@ -1563,18 +1818,41 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
}
install::Outcome::Refused(path) => {
println!("Differs from the version in this binary: {}", path.display());
println!(
"Compare with `worklane install-skill {} --print`, or overwrite with --force",
asset.name
);
println!("Compare with `{}`, or overwrite with --force", compare(asset));
}
}
}
// Once, and only when something arrived: repeating it per document would make the
// instruction look like part of each outcome rather than the one thing to do next.
Ok(written)
}
/// Install the opencode tool definitions.
///
/// No name argument, where `install-skill` has an optional one: there is a single tool
/// file, so a name could only be right or wrong, and `--print` needs no help deciding
/// what to print.
pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
if print {
print!("{}", install::TOOL.content);
return Ok(());
}
let chosen: Vec<&install::Asset> = install::TOOLS.iter().collect();
let root = install::tools_root()?;
let written =
install_each(&chosen, &root, force, |_| "worklane install-tool --print".to_string())?;
// Not "on its next session", which is what the skills say: opencode reads its config
// once at startup and does not reload it, so a running one keeps the tools it began
// with. The second line is there because the file is executable and looks like it
// needs a toolchain: it does not, it runs inside opencode.
if written {
println!("Claude Code and opencode pick it up on their next session");
println!(
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded"
);
println!(
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine"
);
}
Ok(())
@@ -1588,8 +1866,7 @@ mod tests {
/// will not share a microsecond, but it is the whole point of the guard.
#[test]
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
let dir = std::env::temp_dir().join(format!("worklane-test-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
let dir = Fixture::new("worklane-test");
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
@@ -1608,7 +1885,5 @@ mod tests {
let mut names = vec![second.clone(), third.clone(), first.clone()];
names.sort();
assert_eq!(names, vec![first, second, third]);
fs::remove_dir_all(&dir).unwrap();
}
}
+198 -5
View File
@@ -11,9 +11,11 @@
//! 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 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.
//! 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};
@@ -67,11 +69,56 @@ pub const PLAN_SKILL: Asset = Asset {
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; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
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> {
@@ -106,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),
@@ -331,7 +420,7 @@ mod tests {
/// 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.
@@ -395,6 +484,34 @@ mod tests {
}
}
/// 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
@@ -417,4 +534,80 @@ mod tests {
);
}
}
// ------------------------------------------------------------ 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:?}"
);
}
}
}
+35 -11
View File
@@ -7,6 +7,7 @@ mod command;
mod completions;
mod handlers;
mod install;
mod tag;
mod tui;
mod util;
@@ -72,16 +73,24 @@ fn main() -> Result<()> {
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),
Some(Command::Tags) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir)
}
// 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 }) => {
@@ -92,6 +101,9 @@ fn main() -> Result<()> {
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),
}
}
@@ -199,16 +211,23 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
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.
@@ -218,8 +237,9 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
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, so this arm
// is only ever the way in.
// 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
@@ -228,7 +248,11 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// 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(),
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());
}
}
+3570 -309
View File
File diff suppressed because it is too large Load Diff
+742 -32
View File
@@ -16,6 +16,32 @@ pub const TIMESTAMP_FORMAT: &str = "%Y-%m-%d %H:%M:%S";
/// Fixed width, so the lexicographic sort in `read_comments` stays chronological.
pub const COMMENT_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
/// Where a ticket's comments live, under the board.
///
/// Beside the status directories rather than among them, the way `campaigns_dir` is: a
/// comment has no status of its own. Spelled once here, so the writer, the reader and the
/// card's counter cannot disagree about the path.
pub const COMMENTS_DIR: &str = "comments";
/// The comments directory for one ticket, named by its full uuid.
pub fn comments_dir(board: &Path, uuid: &str) -> std::path::PathBuf {
board.join(COMMENTS_DIR).join(uuid)
}
/// The mark a card puts after its comment count.
///
/// A closing quotation ornament, so `2\u{275e}` reads as two things somebody said rather
/// than as a second bracketed counter beside the criteria.
///
/// Deliberately neither U+1F4AC SPEECH BALLOON nor U+1F5E8 LEFT SPEECH BUBBLE. The first
/// has emoji presentation and East Asian Width Wide, so it draws two cells where
/// `spans_width` counts one character and every corner on the card would be a cell out.
/// The second is text presentation and Neutral, but sits in a pictograph block most
/// terminal fonts leave as tofu. This one is a Dingbat, with the coverage the priority
/// meter's Geometric Shapes have, and Neutral, so it is one cell wherever `BLOCKED_MARK`
/// already is.
pub const COMMENT_MARK: &str = "\u{275e}";
/// Whether colour is wanted, from the three inputs that decide it.
///
/// Split out from the caching wrapper so it can be tested without a pty and
@@ -254,13 +280,87 @@ pub fn color_text(text: &str, color: Color) -> String {
paint(text, color, should_use_colors())
}
/// What sits at a candidate `.worklane` path.
///
/// The distinction the walk turns on is between nothing there and something
/// unusable there. `exists()` follows a link, so a dangling one answered the same
/// as an empty parent and the walk carried on upward until it met a board above
/// the project, which then became the board every write went to. Silently. With
/// the boards kept outside the project a dangling link is an ordinary state
/// rather than a corrupted tree: it is what you have before the boards repo is
/// cloned, and after a board directory is renamed.
#[derive(Debug, PartialEq)]
enum Candidate {
/// Nothing at that path, which is the one answer the walk carries on from.
Absent,
/// A directory, or a link that resolves to one.
Board,
/// A link that resolves to nothing, carrying the target it names.
Dangling(std::path::PathBuf),
/// There, and not a directory: a regular file, or a link to one.
NotADirectory,
}
/// Which of the four a `.worklane` path is.
///
/// `symlink_metadata` first, so the answer is about the entry itself and absence
/// cannot be confused with a target that is gone. Only then is the link followed,
/// which is what makes a resolvable one indistinguishable from a real directory.
fn classify(path: &Path) -> Result<Candidate> {
let entry = match fs::symlink_metadata(path) {
Ok(entry) => entry,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Candidate::Absent),
// Anything other than absence is a filesystem that could not answer, and
// reading that as absence is how the walk-past worked in the first place.
Err(error) => return Err(anyhow!("Could not read {}: {error}", path.display())),
};
if !entry.is_symlink() {
return Ok(match entry.is_dir() {
true => Candidate::Board,
false => Candidate::NotADirectory,
});
}
// Read whether or not it resolves: the target is the only part of the failure
// that says what to go and fix.
let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf());
Ok(match fs::metadata(path) {
Ok(resolved) if resolved.is_dir() => Candidate::Board,
Ok(_) => Candidate::NotADirectory,
Err(_) => Candidate::Dangling(target),
})
}
/// The first `.worklane` at or above `start`.
///
/// The symlink stays unresolved in what is returned, so a board reached through a
/// link is the same path to everything downstream as one sitting in the project.
pub fn find_worklane_dir(start: &Path) -> Result<std::path::PathBuf> {
let mut current = start.canonicalize()?;
loop {
let worklane_dir = current.join(".worklane");
if worklane_dir.exists() {
return Ok(worklane_dir);
match classify(&worklane_dir)? {
Candidate::Board => return Ok(worklane_dir),
// The only answer that hands the search upward. A `.worklane` that is
// there but unusable is this project's board and is reported here,
// rather than quietly becoming a write to whatever sits above it.
Candidate::Absent => {}
Candidate::Dangling(target) => {
return Err(anyhow!(
"{} is a symlink to {}, which does not exist. The boards repo may not be cloned on this machine.",
worklane_dir.display(),
target.display()
));
}
Candidate::NotADirectory => {
return Err(anyhow!(
"{} is not a directory. A board is a directory of ticket files.",
worklane_dir.display()
));
}
}
if !current.pop() {
@@ -1676,23 +1776,38 @@ fn section_body(lines: &[&str], heading: &str) -> Option<std::ops::Range<usize>>
Some(after..section_end(lines, after))
}
/// The first line of a section's body, or nothing when the section is absent or holds
/// only its placeholder.
/// A section's body as prose, or nothing when the section is absent or holds only its
/// placeholder.
///
/// For a view with one row to spend on prose: the board's campaign frame and its picker
/// both want the opening line of a description and have no room for the rest. Through
/// [`section_body`] rather than a scan of its own, so what counts as the section is
/// The whole of it, the blank lines between paragraphs included, for a view that can page
/// through what it cannot fit: the board's campaign frame gives a description three rows
/// and scrolls the rest, and the one line the picker draws is the first line of this.
///
/// It replaced `section_opening`, which did the cut here. The cut belongs to the view that
/// wants one line, not to the read: the 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` is where the one line comes off it again.
///
/// Through [`section_body`] rather than a scan of its own, so what counts as the section is
/// decided in one place, and the placeholder reads as nothing here the way it does to
/// `append`.
pub fn section_opening(content: &str, section: &Section) -> Option<String> {
/// `append`. Only the ends are trimmed: those blanks separate the body from its heading and
/// from whatever follows, and a view that kept them would open on empty rows and scroll
/// past empty ones at the end. Indentation inside a line survives, since a nested list is
/// part of the prose.
pub fn section_prose(content: &str, section: &Section) -> Option<String> {
let lines: Vec<&str> = content.lines().collect();
let body = section_body(&lines, section.heading)?;
lines[body]
let kept: Vec<&str> = lines[body]
.iter()
.map(|line| line.trim())
.find(|line| !line.is_empty() && *line != section.placeholder)
.map(|line| line.to_string())
.map(|line| line.trim_end())
.filter(|line| *line != section.placeholder)
.collect();
let start = kept.iter().position(|line| !line.is_empty())?;
let end = kept.iter().rposition(|line| !line.is_empty())?;
Some(kept[start..=end].join("\n"))
}
/// Where the body's content ends, ignoring the blank lines that separate it from
@@ -1728,6 +1843,12 @@ pub fn clear_section_body(content: &str, section: &Section) -> Result<String> {
}
/// The line surgery both of the above are, given a body that is already rendered.
///
/// The refusal names the section and not the file it is missing from, because both a ticket
/// and a campaign reach here: `campaign set --description` writes a campaign's one prose
/// section through this, so "Ticket has no description section" would be wrong half the
/// time. `write_then_replace` carries the noun instead, where a message about a *file* is
/// worth spelling.
fn replace_section_body(
content: &str,
section: &Section,
@@ -1735,7 +1856,7 @@ fn replace_section_body(
) -> Result<String> {
let lines: Vec<&str> = content.lines().collect();
let body = section_body(&lines, section.heading)
.ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?;
.ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?;
let mut out: Vec<String> = lines[..body.start].iter().map(|l| l.to_string()).collect();
out.extend(body_lines);
@@ -1756,7 +1877,7 @@ fn replace_section_body(
pub fn append_section_body(content: &str, section: &Section, items: &[String]) -> Result<String> {
let lines: Vec<&str> = content.lines().collect();
let body = section_body(&lines, section.heading)
.ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?;
.ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?;
let at = body_content_end(&lines, &body);
let existing: Vec<&&str> = lines[body.start..at]
@@ -2506,8 +2627,8 @@ pub enum Status {
}
impl Status {
/// Every status, in flow order. The one list, which [`status_dirs`] and `mv` both
/// read rather than spelling the four names again.
/// Every status, in flow order. The one list, which [`status_dirs`], `mv` and every
/// caller of [`by_status_order`] read rather than spelling the four names again.
pub const ALL: [Status; 4] = [
Status::Backlog,
Status::Committed,
@@ -2660,9 +2781,59 @@ pub struct TicketItem {
/// malformed ticket is the worse failure, and is the same exception `detail_of`
/// already makes.
pub blockers: Vec<String>,
/// How many comments the ticket carries, `0` for one with none.
///
/// Read here for the reason `criteria` is: the board draws it on every card, so
/// asking per card would mean a `read_dir` per ticket per frame. It is the one field
/// on this pass that costs a directory listing rather than coming off the content
/// already in hand, which is why it is counted and never read: the bodies are the
/// detail view's business, and a count needs none of them.
pub comments: usize,
/// The file this came from. The listing ignores it; the TUI opens it for the
/// detail view rather than resolving the ticket a second time.
pub path: std::path::PathBuf,
/// The time `mv` stamped on entering committed, or `None` for a ticket that has
/// never got that far.
///
/// Read here for the reason `criteria` is, and it is what its column is ordered by:
/// a comparator that read the file would re-read every ticket on every comparison,
/// where this pass reads each one once.
pub committed_on: Option<String>,
/// The same for reviewing.
pub submitted_on: Option<String>,
/// The same for done.
pub completed_on: Option<String>,
}
impl TicketItem {
/// The stamp the ticket entered a status with, which is what that column sorts on.
///
/// A slot per status rather than a lookup by field name, so a fifth status carrying
/// a stamp is a compile error here the way it is in [`Status::stamp_field`].
/// Backlog has none: nothing stamps it, and `Created At` is not an entry time, so
/// every ticket in that column answers `None` and the whole order is the fallback.
fn entry_stamp(&self, status: Status) -> Option<&str> {
match status {
Status::Backlog => None,
Status::Committed => self.committed_on.as_deref(),
Status::Reviewing => self.submitted_on.as_deref(),
Status::Done => self.completed_on.as_deref(),
}
}
}
/// The stamp a ticket carries for a status, or `None` for one it has not reached.
///
/// The field name comes off [`Status::stamp_field`], so what is read here cannot drift
/// from what `mv` writes. An absent field reads as `_Not set_` like every other, and a
/// stamp is machine-written so that spelling never appears as a value; both count as no
/// stamp rather than as a time.
fn parse_stamp(content: &str, status: Status) -> Option<String> {
let value = parse_ticket_field(content, status.stamp_field()?);
match is_unknown_value(&value) {
true => None,
false => Some(value),
}
}
/// The date part of a due value, for a view with only a corner to spend on it.
@@ -2770,7 +2941,31 @@ pub fn display_ticket_items(items: &[TicketItem]) {
}
}
/// How many comments a ticket has, counted off the directory rather than read.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A missing directory is none, which is what a
/// ticket nobody has commented on has: no directory is created until the first comment.
fn count_comments(board: &Path, uuid: &str) -> usize {
let Ok(entries) = fs::read_dir(comments_dir(board, uuid)) else {
return 0;
};
entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
.count()
}
pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketItem>> {
let status_path = status_path.as_ref();
// The comments sit beside the status directories, so the board is this one's parent.
// Derived rather than taken as a second argument: every caller joins a status onto a
// board it already holds, and two arguments would let a status from one board arrive
// with the comments of another. `None` only for a bare relative path, which no caller
// passes and which counts nothing rather than failing.
let board = status_path.parent();
let entries: Vec<_> = fs::read_dir(status_path)?
.filter_map(|e| e.ok())
// A status directory is a plain directory, so anything can be dropped in it.
@@ -2811,6 +3006,11 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
}),
};
// The ticket's own ID field, not the filename stem: a comment directory is
// named by the uuid the file records, which is what `comment` wrote it under.
let uuid = parse_ticket_field(&content, "ID");
let comments = board.map_or(0, |board| count_comments(board, &uuid));
Some(TicketItem {
title,
owner,
@@ -2821,9 +3021,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
criteria: progress,
campaign: parse_campaign(&content),
tags: parse_tags(&content),
uuid: parse_ticket_field(&content, "ID"),
uuid,
blockers,
comments,
path: e.path(),
committed_on: parse_stamp(&content, Status::Committed),
submitted_on: parse_stamp(&content, Status::Reviewing),
completed_on: parse_stamp(&content, Status::Done),
})
})
.collect();
@@ -2832,11 +3036,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
Ok(items)
}
/// The order a status column is read in: priority first, title as the tiebreak.
/// The order the backlog is read in, and the tiebreak every other column falls back to:
/// priority first, title second.
///
/// Named and exported because the board's All tab merges several boards' columns into
/// one and has to land in the order the listing uses. A merge sorted a second way
/// would put a p1 below a p5 depending on which project it came from.
/// one and has to land in one order. A merge sorted a second way would put a p1 below a
/// p5 depending on which project it came from, and the merge spans statuses, so no
/// single stamp governs it.
pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
a.priority
.rank()
@@ -2844,10 +3050,216 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
.then_with(|| a.title.to_lowercase().cmp(&b.title.to_lowercase()))
}
/// The order one status column is read in, keyed on the status.
///
/// Priority is the clock in the backlog, and that column keeps exactly the order it has
/// always printed. Past the backlog the question changes: committed asks what has waited
/// longest, reviewing what was handed over first, done what just landed. The head of
/// every column is therefore what the reader acts on next, which is ascending by entry
/// stamp in committed and reviewing and descending in done, the way a changelog reads.
///
/// A ticket with no stamp sinks below every stamped one in its column. A missing time is
/// unknown, not ancient, and unknown must not claim the head of a queue ahead of a wait
/// somebody can point at. Reading absence as the epoch would come free from the string
/// comparison and put every legacy ticket first on data nothing verified.
///
/// The comparison is a string comparison. The stamp format is `%Y-%m-%d %H:%M:%S`, where
/// lexicographic order is chronological order, the same property `Due` already relies
/// on, so there is no date parsing at sort time. Equal stamps happen, `mv` writes whole
/// seconds, and they fall through to priority and title like everything else.
pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
let by_stamp = match (a.entry_stamp(status), b.entry_stamp(status)) {
(Some(left), Some(right)) => match status {
Status::Done => right.cmp(left),
_ => left.cmp(right),
},
(Some(_), None) => std::cmp::Ordering::Less,
(None, Some(_)) => std::cmp::Ordering::Greater,
// Both unstamped, which is every ticket in the backlog: the fallback is the
// whole order there rather than a tiebreak.
(None, None) => std::cmp::Ordering::Equal,
};
by_stamp.then_with(|| by_priority_then_title(a, b))
}
/// The environment variable that keeps a test's fixture directory on disk.
///
/// Opt-in rather than on-by-default-when-a-test-fails, because the assertions in this crate
/// carry the state they are about: a failing board test prints the rendered rows, a failing
/// listing test prints the listing. The path is what you want when you would rather poke at
/// the files than read the message, which is the less common of the two.
#[cfg(test)]
pub const KEEP_FIXTURES: &str = "WORKLANE_KEEP_FIXTURES";
/// A fixture directory under the system temp directory that removes itself.
///
/// Every unit test in this crate builds its board or its status directory by hand under
/// `std::env::temp_dir()`. The ones that remembered a `remove_dir_all` at the end of the
/// test only cleaned up when their assertions passed, and most had no such line at all, so
/// a full run left one directory per test behind. `/tmp` reached 18363 of them and filled
/// the disk, which failed a link step and then a `git add` with "No space left on device" —
/// an error that names neither the tests nor what they left behind. That is b74dc5a.
///
/// A `Drop` rather than a line at the end of each test, because that is the only shape that
/// runs when an assertion fails, which is exactly when a fixture is most likely to be
/// stranded: unwinding runs destructors, so the guard holds on the failing path without the
/// test having to say anything.
///
/// `assert_fs::TempDir` is a dev-dependency already and is what the integration tests use,
/// and it was still not the answer here. 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 — and it has no opinion about naming the path when it keeps one. Wrapping it to
/// add both is more code than this.
///
/// `Deref` to `Path`, so a fixture reads as the path it stands for at the call sites that
/// already had one and nothing had to change but the type.
#[cfg(test)]
pub struct Fixture {
/// What is removed: the directory this fixture created at the top.
root: std::path::PathBuf,
/// What the test works with, at or below the root. The two differ only for a fixture
/// that needs a named directory inside a parent it can also throw away.
path: std::path::PathBuf,
/// Whether to leave the directory behind, read once here rather than at drop time.
///
/// At construction because the answer must not be able to change between a test
/// starting and ending, and because it is what [`Fixture::swept`] can then turn off for
/// the tests that are about the guard rather than about this flag.
keep: bool,
}
#[cfg(test)]
impl Fixture {
/// A fresh directory, named after the family of tests that asked for it.
///
/// The prefix earns its place on the kept path: `worklane-tui-` says which suite left it
/// where a random name would not, and the uuid is what makes two fixtures with one
/// prefix two directories, so no test can reach another's.
pub fn new(prefix: &str) -> Self {
let root = std::env::temp_dir().join(format!("{prefix}-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&root).unwrap();
Fixture {
path: root.clone(),
root,
keep: std::env::var_os(KEEP_FIXTURES).is_some(),
}
}
/// The same fixture, swept up whatever the environment says.
///
/// For the tests below, which assert that the directory goes: they are about the guard
/// and not about the flag, so `WORKLANE_KEEP_FIXTURES` in a reader's environment must
/// not be able to fail them.
pub fn swept(mut self) -> Self {
self.keep = false;
self
}
/// The same fixture, pointing at a directory inside it.
///
/// For the tree a project test needs: `<root>/<project>/.worklane`, where the path the
/// test hands to `projects` is the project and what has to be removed is the root above
/// it. Consuming, so one directory never has two guards and therefore never two attempts
/// to remove it.
pub fn child(mut self, name: &str) -> Self {
self.path = self.root.join(name);
self
}
}
#[cfg(test)]
impl AsRef<std::path::Path> for Fixture {
fn as_ref(&self) -> &std::path::Path {
&self.path
}
}
/// Beside `AsRef`, because the two reach different call sites: a parameter bound by
/// `impl AsRef<Path>` is not a coercion site, and a parameter typed `&Path` is.
#[cfg(test)]
impl std::ops::Deref for Fixture {
type Target = std::path::Path;
fn deref(&self) -> &std::path::Path {
&self.path
}
}
#[cfg(test)]
impl Drop for Fixture {
fn drop(&mut self) {
if self.keep {
// Named, since a fixture kept and not findable is a fixture kept for nothing.
eprintln!("kept fixture {}", self.root.display());
return;
}
// Best effort. A directory that will not go must not turn a passing test into a
// failing one, and must not panic a second time out of a drop that is already
// unwinding, which would lose the failure the test was reporting.
std::fs::remove_dir_all(&self.root).ok();
}
}
#[cfg(test)]
mod tests {
use super::*;
/// The guard removes the directory when it goes out of scope, which is what makes the
/// cleanup independent of the assertions passing: unwinding runs destructors, so a
/// failing test drops its fixture on the way out exactly as a passing one does.
#[test]
fn a_fixture_removes_itself_when_its_guard_goes() {
let path = {
let dir = Fixture::new("worklane-guard").swept();
fs::write(dir.join("a.md"), "body").unwrap();
assert!(dir.exists(), "the fixture was not created");
dir.to_path_buf()
};
assert!(!path.exists(), "the fixture outlived its guard: {}", path.display());
}
/// And on the failing path, which is the whole point: a line at the end of a test does
/// not run when an assertion above it does not pass.
#[test]
fn a_fixture_removes_itself_when_the_test_panics() {
// The default hook would print this deliberate panic and make a green run read as a
// red one. Swapped for the length of the call and put straight back, which is as
// narrow as a process-wide hook can be made.
let hook = std::panic::take_hook();
std::panic::set_hook(Box::new(|_| {}));
let caught = std::panic::catch_unwind(|| {
let dir = Fixture::new("worklane-guard").swept();
// Handed out through the payload, so the assertion below has a path to look at
// whether or not the guard did its job.
std::panic::panic_any(dir.to_path_buf());
});
std::panic::set_hook(hook);
let path = *caught
.expect_err("the closure did not panic")
.downcast::<std::path::PathBuf>()
.expect("the panic did not carry the fixture path");
assert!(!path.exists(), "the fixture survived a failing test: {}", path.display());
}
/// Two fixtures with one prefix are two directories, so no test can rely on one another
/// test built — which the shared temp directory is what made possible.
#[test]
fn two_fixtures_with_one_prefix_are_two_directories() {
let first = Fixture::new("worklane-guard");
let second = Fixture::new("worklane-guard");
assert_ne!(first.to_path_buf(), second.to_path_buf(), "one directory, two guards");
let kept = second.to_path_buf();
drop(first);
assert!(kept.exists(), "one fixture going took the other with it");
}
#[test]
fn no_color_disables_colour_on_a_terminal() {
assert!(!colors_wanted(true, Some("1"), Some("xterm-256color")));
@@ -3221,8 +3633,7 @@ mod tests {
/// in `show`, so the two cannot disagree about what a criterion is.
#[test]
fn collect_ticket_items_counts_the_criteria_show_would_number() {
let dir = std::env::temp_dir().join(format!("worklane-count-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
let dir = Fixture::new("worklane-count");
let write = |name: &str, body: &str| {
fs::write(
@@ -3247,8 +3658,50 @@ mod tests {
counted.contains(&None),
"a ticket with no criteria got a count: {counted:?}"
);
}
fs::remove_dir_all(&dir).unwrap();
/// The count is a directory listing rather than a read: nothing here parses a comment,
/// and the bodies are the detail view's business.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A ticket with no directory at all has
/// none, which is every ticket until the first comment creates one.
#[test]
fn collect_ticket_items_counts_the_comments_under_the_board() {
let board = tempfile::tempdir().unwrap();
let backlog = board.path().join("backlog");
fs::create_dir_all(&backlog).unwrap();
let write = |uuid: &str| {
fs::write(
backlog.join(format!("{uuid}.md")),
format!("# T{uuid}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Owner**: alice\n"),
)
.unwrap();
};
let talked_about = "11111111-0000-4000-8000-000000000001";
let quiet = "11111111-0000-4000-8000-000000000002";
write(talked_about);
write(quiet);
let comments = comments_dir(board.path(), talked_about);
fs::create_dir_all(&comments).unwrap();
fs::write(comments.join("20260823_120000_000000.md"), "**Comment**\n").unwrap();
fs::write(comments.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
// Not a comment, and not counted as one.
fs::write(comments.join("notes.txt"), "scratch\n").unwrap();
let items = collect_ticket_items(&backlog).unwrap();
let counted = |uuid: &str| {
items
.iter()
.find(|item| item.uuid == uuid)
.unwrap_or_else(|| panic!("no item for {uuid}"))
.comments
};
assert_eq!(counted(talked_about), 2);
assert_eq!(counted(quiet), 0);
}
/// The blockers come off the read that builds the item, so the board pays no second
@@ -3260,8 +3713,7 @@ mod tests {
/// listing that stops on one malformed ticket is the worse failure.
#[test]
fn collect_ticket_items_reads_the_uuid_and_the_blockers_it_records() {
let dir = std::env::temp_dir().join(format!("worklane-blocked-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
let dir = Fixture::new("worklane-blocked");
let uuid = |tail: &str| format!("11111111-0000-4000-8000-00000000000{tail}");
let write = |name: &str, relations: &str| {
@@ -3286,8 +3738,6 @@ mod tests {
assert_eq!(of("T1").blockers, vec![uuid("2")]);
assert!(of("T2").blockers.is_empty(), "a regression was read as a blocker");
assert!(of("T3").blockers.is_empty(), "an unreadable section was not survived");
fs::remove_dir_all(&dir).unwrap();
}
/// Whole values, so a filter or a card cannot confuse two tags that share a prefix.
@@ -3314,8 +3764,7 @@ mod tests {
#[test]
fn collect_ticket_items_lists_only_md_files() {
let dir = std::env::temp_dir().join(format!("worklane-stray-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
let dir = Fixture::new("worklane-stray");
fs::write(
dir.join("11111111-0000-4000-8000-000000000001.md"),
@@ -3331,8 +3780,6 @@ mod tests {
let titles: Vec<&str> = items.iter().map(|item| item.title.as_str()).collect();
assert_eq!(titles, vec!["Real"], "{titles:?}");
fs::remove_dir_all(&dir).unwrap();
}
/// The template ticket, and the shape every insertion test measures against.
@@ -3521,6 +3968,168 @@ mod tests {
);
}
/// A listed ticket with only the fields the column order reads: its title, its
/// priority and the stamp for the status being sorted.
fn listed(title: &str, level: u8, status: Status, stamp: Option<&str>) -> TicketItem {
let stamp = stamp.map(|value| value.to_string());
TicketItem {
title: title.to_string(),
owner: NOT_SET.to_string(),
due: NOT_SET.to_string(),
id: "0000000".to_string(),
created: String::new(),
priority: Priority::Level(level),
criteria: None,
campaign: None,
tags: Vec::new(),
uuid: NOT_SET.to_string(),
blockers: Vec::new(),
comments: 0,
path: std::path::PathBuf::new(),
committed_on: match status {
Status::Committed => stamp.clone(),
_ => None,
},
submitted_on: match status {
Status::Reviewing => stamp.clone(),
_ => None,
},
completed_on: match status {
Status::Done => stamp,
_ => None,
},
}
}
/// Sorted the way the column is read, titles out, so a case reads as the order it
/// asserts rather than as a pair of comparisons.
fn ordered(status: Status, mut items: Vec<TicketItem>) -> Vec<String> {
items.sort_by(|a, b| by_status_order(status, a, b));
items.into_iter().map(|item| item.title).collect()
}
/// The backlog is the one column priority still governs, and it prints exactly what
/// it always has: the stamps a ticket carries from an earlier trip through the flow
/// do not reach it, because backlog has no stamp of its own to sort on.
#[test]
fn the_backlog_keeps_priority_then_title() {
let items = vec![
listed("zebra", 5, Status::Backlog, None),
listed("alpha", 1, Status::Backlog, None),
listed("beta", 1, Status::Backlog, None),
];
assert_eq!(ordered(Status::Backlog, items), ["alpha", "beta", "zebra"]);
}
/// Committed and reviewing are queues: the head is what has waited longest, which is
/// where the reader picks next from.
#[test]
fn committed_and_reviewing_list_the_oldest_stamp_first() {
for status in [Status::Committed, Status::Reviewing] {
let items = vec![
listed("newest", 1, status, Some("2026-08-03 09:00:00")),
listed("oldest", 5, status, Some("2026-08-01 09:00:00")),
listed("middle", 1, status, Some("2026-08-02 09:00:00")),
];
assert_eq!(ordered(status, items), ["oldest", "middle", "newest"], "{status:?}");
}
}
/// Done reads like a changelog: what just landed is at the top, and priority no
/// longer decides anything about finished work.
#[test]
fn done_lists_the_newest_stamp_first() {
let items = vec![
listed("first", 1, Status::Done, Some("2026-08-01 09:00:00")),
listed("last", 5, Status::Done, Some("2026-08-03 09:00:00")),
listed("middle", 1, Status::Done, Some("2026-08-02 09:00:00")),
];
assert_eq!(ordered(Status::Done, items), ["last", "middle", "first"]);
}
/// A missing stamp is unknown, not ancient. Reading absence as the epoch would come
/// free from the string comparison and hand the head of the queue to every legacy
/// ticket, so it sinks instead, in both directions.
#[test]
fn a_ticket_with_no_stamp_sorts_below_every_stamped_one() {
for status in [Status::Committed, Status::Reviewing, Status::Done] {
let items = vec![
listed("unstamped", 1, status, None),
listed("stamped", 5, status, Some("2026-08-01 09:00:00")),
];
assert_eq!(ordered(status, items), ["stamped", "unstamped"], "{status:?}");
}
}
/// `mv` writes whole seconds, so two moves in the same second is a real tie rather
/// than a hypothetical one, and it falls through to the order the backlog uses.
#[test]
fn equal_stamps_fall_back_to_priority_then_title() {
let same = Some("2026-08-01 09:00:00");
let items = vec![
listed("zebra", 1, Status::Committed, same),
listed("beta", 3, Status::Committed, same),
listed("alpha", 3, Status::Committed, same),
];
assert_eq!(ordered(Status::Committed, items), ["zebra", "alpha", "beta"]);
}
/// Two unstamped tickets in one column are ordered among themselves the way the
/// backlog is, rather than left in whatever order the directory handed them back.
#[test]
fn unstamped_tickets_are_ordered_among_themselves_by_priority_then_title() {
let items = vec![
listed("zebra", 1, Status::Done, None),
listed("beta", 3, Status::Done, None),
listed("alpha", 3, Status::Done, None),
];
assert_eq!(ordered(Status::Done, items), ["zebra", "alpha", "beta"]);
}
/// The stamps come off the pass that builds the listing, not off a second read at
/// comparison time, which is what makes an ordered column cost one read per file.
#[test]
fn collect_ticket_items_reads_the_stamps_the_order_sorts_on() {
let dir = Fixture::new("worklane-stamps");
fs::write(
dir.join("aaaa_walked.md"),
"# Walked\n\n## Metadata\n\n\
- **ID**: aaaa\n\
- **Committed On**: 2026-08-01 09:00:00\n\
- **Submitted On**: 2026-08-02 09:00:00\n\
- **Completed On**: 2026-08-03 09:00:00\n\
- **Status**: done\n",
)
.unwrap();
fs::write(
dir.join("bbbb_fresh.md"),
"# Fresh\n\n## Metadata\n\n- **ID**: bbbb\n- **Status**: backlog\n",
)
.unwrap();
let items = collect_ticket_items(&dir).unwrap();
let walked = items.iter().find(|item| item.title == "Walked").unwrap();
assert_eq!(walked.committed_on.as_deref(), Some("2026-08-01 09:00:00"));
assert_eq!(walked.submitted_on.as_deref(), Some("2026-08-02 09:00:00"));
assert_eq!(walked.completed_on.as_deref(), Some("2026-08-03 09:00:00"));
// Absent reads as no stamp rather than as the `_Not set_` every other field
// falls back to, so the order sinks it instead of comparing that text.
let fresh = items.iter().find(|item| item.title == "Fresh").unwrap();
assert_eq!(fresh.committed_on, None);
assert_eq!(fresh.submitted_on, None);
assert_eq!(fresh.completed_on, None);
}
/// Removal is scoped to the section for the same reason the write is: a description
/// quoting a field marker is prose, and rewriting it would corrupt the ticket text
/// while leaving the real field in place.
@@ -4533,4 +5142,105 @@ mod tests {
"{rendered:?}"
);
}
// ----------------------------------------------------- finding the board --
/// A project directory under a temp root.
///
/// The root is canonicalized because `find_worklane_dir` canonicalizes its
/// start: on a system whose temp path runs through a link, the two spellings
/// of the same directory would not compare equal.
fn project_in(root: &tempfile::TempDir) -> std::path::PathBuf {
let dir = root.path().canonicalize().unwrap().join("project");
fs::create_dir_all(&dir).unwrap();
dir
}
/// The failure names the target, since the link is not the thing to fix, and it
/// does not say to run `init`: that answer belongs to an empty tree, and giving
/// it here points at the wrong problem.
#[test]
fn a_dangling_board_link_is_reported_with_its_target() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let target = project.parent().unwrap().join("boards/2fed877-the-board");
std::os::unix::fs::symlink(&target, project.join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains(&target.display().to_string()), "{error}");
assert!(error.contains("boards repo"), "{error}");
assert!(!error.contains("worklane init"), "{error}");
}
/// The bug this was written for: `exists()` follows the link, so a dangling one
/// answered false, the walk carried on up the tree, and the board above the
/// project became the board every write landed in.
#[test]
fn a_dangling_board_link_does_not_reach_the_board_above_it() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let above = project.parent().unwrap().join(".worklane");
fs::create_dir_all(&above).unwrap();
let link = project.join(".worklane");
std::os::unix::fs::symlink(project.parent().unwrap().join("gone"), &link).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains(&link.display().to_string()), "{error}");
// And the walk really would have reached it, so the assertion above is
// about where the walk stopped rather than about an empty tree.
assert_eq!(find_worklane_dir(project.parent().unwrap()).unwrap(), above);
}
/// Nothing at that path is still the one answer the walk carries on from.
#[test]
fn no_worklane_at_all_lets_the_walk_carry_on_upward() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let above = project.parent().unwrap().join(".worklane");
fs::create_dir_all(&above).unwrap();
assert_eq!(find_worklane_dir(&project).unwrap(), above);
}
/// A link that resolves is the board, and what comes back is the link rather
/// than its target: `.worklane/backlog` has to read the same either way.
#[test]
fn a_link_to_a_board_resolves_the_way_a_directory_does() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let board = project.parent().unwrap().join("boards/2fed877-the-board");
fs::create_dir_all(&board).unwrap();
let link = project.join(".worklane");
std::os::unix::fs::symlink(&board, &link).unwrap();
assert_eq!(find_worklane_dir(&project).unwrap(), link);
}
/// A regular file is reported rather than stepped over, and a board above it
/// does not make it the walk's problem to solve.
#[test]
fn a_regular_file_where_the_board_goes_is_an_error() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
fs::write(project.join(".worklane"), "board = \"2fed877\"\n").unwrap();
fs::create_dir_all(project.parent().unwrap().join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains("not a directory"), "{error}");
}
/// A link that resolves to a file, which the follow catches and the entry check
/// on its own cannot: the entry is a symlink and the target is not a directory.
#[test]
fn a_link_to_a_file_is_not_a_board_either() {
let root = tempfile::tempdir().unwrap();
let project = project_in(&root);
let file = project.parent().unwrap().join("pointer.toml");
fs::write(&file, "board = \"2fed877\"\n").unwrap();
std::os::unix::fs::symlink(&file, project.join(".worklane")).unwrap();
let error = find_worklane_dir(&project).unwrap_err().to_string();
assert!(error.contains("not a directory"), "{error}");
}
}
+27
View File
@@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
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);
}
+478 -5
View File
@@ -13,6 +13,8 @@ const CAMP_B: &str = "bb22cc33-44dd-4ee5-8ff6-001122334455";
const MEMBER: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
const OTHER: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
const LONER: &str = "f1f2f3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f";
/// A second done member, for the one test that needs two in one column to see an order.
const LATE: &str = "a9a8a7a6-5b4c-4d3e-8f2a-1b0c9d8e7f60";
fn setup_worklane(temp: &TempDir) -> PathBuf {
let worklane = temp.child(".worklane");
@@ -507,6 +509,37 @@ fn campaign_show_prints_the_body_and_the_members_grouped_by_status() {
assert!(!shown.contains("The loner"), "{shown}");
}
/// The members of a status are listed in that status's own order, not in the board-wide
/// one: a campaign's done list answers what just landed, for the same reason the board's
/// column does. Every fixture is a p3, so the stamp is doing all of the work.
#[test]
fn campaign_show_lists_each_status_in_its_own_order() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let stamp = |uuid: &str, day: &str| {
let path = find(&worklane, uuid);
let body = fs::read_to_string(&path).unwrap().replace(
"- **Status**: done\n",
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
);
fs::write(&path, body).unwrap();
};
// A second done member, finished after the one the fixture writes.
create_ticket(&worklane, "done", "The late member", LATE);
stamp(OTHER, "1");
stamp(LATE, "3");
run(&temp, &["assign", "v1 release", OTHER]);
run(&temp, &["assign", "v1 release", LATE]);
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
let at = |needle: &str| shown.find(needle).unwrap_or_else(|| panic!("{needle}: {shown}"));
assert!(at("The late member") < at("The other member"), "{shown}");
}
#[test]
fn ls_campaign_lists_only_that_campaigns_members() {
let temp = TempDir::new().unwrap();
@@ -1096,11 +1129,13 @@ fn an_unknown_campaign_is_refused_and_nothing_is_written() {
);
}
/// No `--description`: `set` and `append` are a pair for a prose section, and a way to
/// replace a description with no way to add a paragraph is half of it. Pinned so the
/// omission stays a decision rather than becoming an oversight somebody fills in.
/// `--description` arrived with `campaign append`, 32e98ab, because for a prose section the
/// two are a pair. What is still deliberately absent is what this pins: no `--owner`, which
/// would settle by accident whether `chown` grows a campaign, and no `--clear`, because a
/// campaign's description has no cleared form and `Clearable`'s variants are a ticket's
/// fields.
#[test]
fn campaign_set_offers_no_description_and_no_owner() {
fn campaign_set_offers_no_owner_and_no_clear() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
@@ -1109,7 +1144,7 @@ fn campaign_set_offers_no_description_and_no_owner() {
assert!(help.contains("--codename"), "{help}");
assert!(help.contains("--title"), "{help}");
assert!(!help.contains("--description"), "{help}");
assert!(help.contains("--description"), "{help}");
assert!(!help.contains("--owner"), "{help}");
assert!(!help.contains("--clear"), "{help}");
}
@@ -1230,3 +1265,441 @@ fn the_title_is_replaced_without_force() {
assert!(out.status.success(), "{}", stderr(&out));
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
}
// ---------------------------------------------- campaign set --description --
/// The point of 32e98ab: the description a campaign was filed with is no longer the one it
/// keeps. `create_campaign` writes prose, so this is a replacement rather than a first line.
#[test]
fn campaign_set_replaces_the_description() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let out = run(
&temp,
&[
"campaign",
"set",
"v1 release",
"--description",
"What the tag has to hold.",
],
);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).contains("Updated description"), "{}", stdout(&out));
let content = campaign_file(&worklane, CAMP_A);
assert!(content.contains("What the tag has to hold."), "{content}");
assert!(
!content.contains("What has to ship together."),
"the old description survived: {content}"
);
}
/// An empty value between two others is the paragraph break, the rule every prose argument
/// in the tool follows: `add --description`, `set --description` and `tags --annotation`.
#[test]
fn an_empty_value_is_a_paragraph_break_in_a_campaigns_description() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let out = run(
&temp,
&[
"campaign",
"set",
"v1 release",
"-d",
"The tag itself.",
"-d",
"",
"-d",
"And what blocks it.",
],
);
assert!(out.status.success(), "{}", stderr(&out));
let content = campaign_file(&worklane, CAMP_A);
assert!(content.contains("The tag itself.\n\nAnd what blocks it."), "{content}");
}
/// And an all-blank value is refused rather than emptying the section. The refusal names no
/// flag, because there is none: a campaign's description has no cleared form, which is the
/// `Clearable` question 32e98ab settled rather than deferred.
#[test]
fn an_all_blank_description_is_refused_and_names_no_clear_flag() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = campaign_file(&worklane, CAMP_A);
let out = run(&temp, &["campaign", "set", "v1 release", "-d", "", "-d", " "]);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
let said = stderr(&out);
assert!(said.contains("An empty value is a paragraph break"), "{said}");
assert!(said.contains("no cleared form"), "{said}");
assert!(!said.contains("--clear"), "it named a flag that does not exist: {said}");
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
}
/// The whole-file comparison `set`, `chown` and the codename already use, so a description
/// replaced with the one it already holds writes nothing.
#[test]
fn setting_the_description_a_campaign_already_has_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = campaign_file(&worklane, CAMP_A);
let out = run(
&temp,
&[
"campaign",
"set",
"v1 release",
"-d",
"What has to ship together.",
],
);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was rewritten");
}
/// Three fields in one call, since the group is `multiple` and the description is in it.
#[test]
fn campaign_set_takes_the_title_the_description_and_the_codename_together() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let out = run(
&temp,
&[
"campaign",
"set",
"v1 release",
"-t",
"First public release",
"-d",
"What the tag has to hold.",
"-c",
"v1",
],
);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).contains("title, description, codename"), "{}", stdout(&out));
let content = campaign_file(&worklane, CAMP_A);
assert!(content.starts_with("# First public release\n"), "{content}");
assert!(content.contains("What the tag has to hold."), "{content}");
assert!(content.contains("- **Codename**: v1"), "{content}");
}
/// A refused codename takes the description down with it, the way it already takes the
/// title: checked before any edit is applied, so a call writes all of what it asked for or
/// none of it.
#[test]
fn a_refused_codename_takes_the_description_down_with_it() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
let before = campaign_file(&worklane, CAMP_A);
let out = run(
&temp,
&[
"campaign",
"set",
"v1",
"-d",
"Rewritten anyway.",
"-c",
"beaver",
],
);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the description went through");
}
// ---------------------------------------------------------- campaign append --
/// The other half of the pair, and the reason `set --description` is not a flag on its own:
/// adding a line to a description must not mean retyping the rest of it.
#[test]
fn campaign_append_adds_a_paragraph_without_replacing_the_description() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let out = run(
&temp,
&[
"campaign",
"append",
"v1 release",
"-d",
"And what is out of scope.",
],
);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).contains("Appended to description"), "{}", stdout(&out));
let content = campaign_file(&worklane, CAMP_A);
// The paragraph lands after the one that was there, with the blank line between them
// that makes it a paragraph rather than a run-on.
assert!(
content.contains("What has to ship together.\n\nAnd what is out of scope.\n"),
"{content}"
);
}
/// Several values in one call are lines *within* the paragraph, not several paragraphs. The
/// same reading `append --description` gives a ticket, since it is the same section entry.
#[test]
fn the_values_of_one_append_are_lines_within_the_paragraph() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"campaign",
"append",
"v1 release",
"-d",
"Out of scope:",
"-d",
"the installer.",
],
);
let content = campaign_file(&worklane, CAMP_A);
assert!(content.contains("Out of scope:\nthe installer.\n"), "{content}");
}
/// A campaign filed with no description holds the placeholder, and appending replaces it
/// rather than following it: the alternative reads `_No description provided._` above the
/// description. `append_section_body`'s rule, so nothing here handles the case.
#[test]
fn appending_to_an_empty_description_replaces_the_placeholder() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "add", "--title", "No prose yet"]);
let uuid = {
let names = campaigns(&worklane);
let name = names
.iter()
.find(|name| name.ends_with("_no-prose-yet.md"))
.expect("the campaign was not filed");
name.split('_').next().unwrap().to_string()
};
assert!(
campaign_file(&worklane, &uuid).contains("_No description provided._"),
"the placeholder is not what add writes any more"
);
let out = run(
&temp,
&[
"campaign",
"append",
"No prose yet",
"-d",
"The first thing said.",
],
);
assert!(out.status.success(), "{}", stderr(&out));
let content = campaign_file(&worklane, &uuid);
assert!(content.contains("The first thing said."), "{content}");
assert!(
!content.contains("_No description provided._"),
"the placeholder is still above the description: {content}"
);
}
/// Every value blank is refused rather than writing nothing quietly, the answer `append`
/// gives a ticket, in the same words: appending nothing was never a way to empty anything,
/// so there is no flag to name.
#[test]
fn an_all_blank_append_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = campaign_file(&worklane, CAMP_A);
let out = run(&temp, &["campaign", "append", "v1 release", "-d", " "]);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
assert!(stderr(&out).contains("Nothing to append"), "{}", stderr(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
}
/// A bare `campaign append <campaign>` is a usage error rather than a silent no-op, the way
/// a bare `campaign set` is. `--description` is `required` rather than a group of one.
#[test]
fn campaign_append_with_no_description_is_a_usage_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = campaign_file(&worklane, CAMP_A);
let out = run(&temp, &["campaign", "append", "v1 release"]);
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
}
/// Appending to a scalar has no meaning, which is the line `append` already draws for a
/// ticket: no `--title` there and none here, and no `--codename` either.
#[test]
fn campaign_append_offers_only_the_description() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["campaign", "append", "--help"]);
let help = stdout(&out);
assert!(help.contains("--description"), "{help}");
assert!(!help.contains("--title"), "{help}");
assert!(!help.contains("--codename"), "{help}");
assert!(!help.contains("--force"), "{help}");
}
/// A campaign is addressed here by the same tiers everything else takes, codename included,
/// because it goes through `resolve_campaign` rather than a lookup of its own.
#[test]
fn campaign_append_resolves_the_campaign_by_its_codename() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
let out = run(&temp, &["campaign", "append", "beaver", "-d", "One more thing."]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(
campaign_file(&worklane, CAMP_A).contains("One more thing."),
"{}",
campaign_file(&worklane, CAMP_A)
);
}
/// An unknown campaign leaves every campaign alone, the answer `campaign set` and `assign`
/// already give.
#[test]
fn campaign_append_refuses_an_unknown_campaign() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = campaign_file(&worklane, CAMP_A);
let out = run(&temp, &["campaign", "append", "nothing-by-that-name", "-d", "Text."]);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
}
// ------------------------------------------------------ the shared machinery --
/// A campaign has one section where a ticket has four, and the section table in `util.rs` is
/// what both go through. So the surgery has to land against `## Metadata`, which is the only
/// heading that follows a campaign's description, and leave everything outside the body
/// alone: a handwritten section, the owner, and the codename in its place.
#[test]
fn the_description_is_edited_in_place_in_a_file_with_one_section() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
let path = worklane
.join("campaigns")
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
let original = fs::read_to_string(&path).unwrap();
fs::write(
&path,
original.replace("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
)
.unwrap();
run(&temp, &["campaign", "set", "v1", "-d", "Replaced."]);
run(&temp, &["campaign", "append", "v1", "-d", "Added."]);
let content = campaign_file(&worklane, CAMP_A);
assert!(content.contains("## Description\nReplaced.\n\nAdded.\n"), "{content}");
// Nothing outside the body moved: the section that follows it, the handwritten one
// between them, and the fields under it.
assert!(content.contains("## Notes\nA handwritten note."), "{content}");
assert!(content.contains("- **Codename**: v1"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(!content.contains("**Status**"), "a status was invented: {content}");
// And no section a campaign does not have was inserted to anchor against.
assert!(!content.contains("## Acceptance Criteria"), "{content}");
assert!(!content.contains("## Implementation Plan"), "{content}");
}
/// The heading is the one in the section table, so `campaign set --description` reaches the
/// section `campaign_body` wrote and `campaign show` prints. A second spelling scoped to
/// campaigns is what this would catch.
#[test]
fn the_description_a_campaign_is_filed_with_is_the_one_set_replaces() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"campaign",
"add",
"--title",
"Filed with prose",
"--description",
"As filed.",
],
);
run(&temp, &["campaign", "set", "Filed with prose", "-d", "As replaced."]);
let out = run(&temp, &["campaign", "show", "Filed with prose"]);
let shown = stdout(&out);
assert!(shown.contains("As replaced."), "{shown}");
assert!(!shown.contains("As filed."), "{shown}");
// One Description heading in the file, not a second one written beside it.
let names = campaigns(&worklane);
let name = names
.iter()
.find(|name| name.ends_with("_filed-with-prose.md"))
.expect("not filed");
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
assert_eq!(content.matches("## Description").count(), 1, "{content}");
}
/// A campaign file with no Description heading is refused rather than given one back. Every
/// campaign the tool files carries the heading, so an insertion path here would be reachable
/// only from a hand-edited file, which is the opposite of the Relations case. The message
/// names the section and not the object, because both a ticket and a campaign reach it.
#[test]
fn a_campaign_with_no_description_section_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let path = worklane
.join("campaigns")
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
let original = fs::read_to_string(&path).unwrap();
fs::write(
&path,
original.replace("## Description\nWhat has to ship together.\n\n", ""),
)
.unwrap();
let before = fs::read_to_string(&path).unwrap();
for args in [
["campaign", "set", "v1 release", "-d", "Text."],
["campaign", "append", "v1 release", "-d", "Text."],
] {
let out = run(&temp, &args);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
let said = stderr(&out);
assert!(said.contains("no description section"), "{said}");
assert!(!said.contains("Ticket"), "a campaign was called a ticket: {said}");
assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written");
}
}
+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());
}
+199 -3
View File
@@ -677,9 +677,9 @@ fn ls_names_the_four_statuses_when_given_another() {
}
}
/// The listing reads the fields it prints and nothing else, so the stamps `mv` writes
/// do not reach it. Pinned against a ticket carrying one, since a listing that started
/// showing them would change the output every board and completion script parses.
/// 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();
@@ -707,3 +707,199 @@ fn ls_output_is_unchanged_by_a_status_stamp() {
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}");
}
+457
View File
@@ -4,6 +4,12 @@
//! 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;
@@ -175,3 +181,454 @@ fn tags_skips_a_missing_status_directory() {
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."));
}