Compare commits

..
6 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 50e67483d8 (b2c5531) Delete the stale copy of the worklane skill, and bump to 0.24.0
`.opencode/skill/worklane-kanban-skill/SKILL.md` was 223 lines of the same
document `assets/SKILL.md` holds, shipped by nothing and checked by no test.
It drifted the way a copy nobody reads does: its frontmatter still called the
skill `worklane_kanban`, its examples still used short flags, and it knew
nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`classify` reads `symlink_metadata` first, so the answer is about the entry
rather than about its target, and it is one of four: `Absent`, `Board`,
`Dangling` or `NotADirectory`. `Absent` is the only one the walk carries on
from. A `.worklane` that is there but unusable is this project's board and
is reported here, not handed to whatever sits above it. Anything other than
`NotFound` out of `symlink_metadata` is an error too, since reading a
filesystem that could not answer as nothing-there is how the walk-past
worked in the first place.

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

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

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

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

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

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

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

The comparison is a string comparison. `%Y-%m-%d %H:%M:%S` is lexicographic
in chronological order, the property `Due` already relies on, so nothing
parses a date at sort time. The stamps are read on the pass
`collect_ticket_items` already makes over each file, the rule `criteria` and
`tags` already hold, and never per comparison.

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

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

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

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

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

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

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

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

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

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:28:40 +02:00
22 changed files with 1572 additions and 321 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
+22 -3
View File
@@ -13,6 +13,7 @@
- `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/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
@@ -22,7 +23,8 @@
- Filenames: `<uuid_v4>_<slug>.md`
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it
- 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
@@ -179,6 +181,7 @@ and this file is for what someone changing worklane's own code needs.
- **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
- **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 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
@@ -301,6 +304,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
@@ -308,7 +318,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
@@ -317,13 +327,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
@@ -332,6 +343,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.21.0"
version = "0.24.0"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.21.0"
version = "0.24.0"
edition = "2024"
[dependencies]
+2 -1
View File
@@ -19,13 +19,14 @@ 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. 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, 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 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-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
+4 -1
View File
@@ -160,7 +160,7 @@ fields; a goal is a campaign.
worklane campaign ls
worklane campaign show v1
worklane campaign add --title "..." --codename v1 --description "..."
worklane campaign set v1 --codename beaver # or --title, on one already filed
worklane campaign set v1 --title "..." # or --codename, on one already filed
worklane assign v1 1b78a24
```
@@ -183,6 +183,9 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
line, and a campaign filed without one is drawn by its short id, which says nothing. A
campaign already on the board that has no codename is worth pointing out for the same
reason a near-duplicate tag is, and `campaign set` is how it gets one without refiling.
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
called on every card in it and at the command line, so changing it is churn dressed as
grooming. `campaign set` refuses it without `--force` for that reason.
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.
+3 -1
View File
@@ -222,7 +222,9 @@ sentence, and it is the shortest thing that addresses the campaign at the comman
Optional: a campaign without one is drawn and listed by its short id instead, which
resolves but says nothing. `campaign set <campaign> --codename <word>` gives one to a
campaign that is already filed, which is what every campaign filed before the field
existed needs.
existed needs. **Replacing a codename it already has needs `--force`**: that word is how
the campaign is referred to on the board and at the command line, so changing it is a
decision rather than a correction. Setting the one it already has is a no-op either way.
`campaign set` 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
+12 -9
View File
@@ -201,20 +201,23 @@ 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)
+35 -1
View File
@@ -281,6 +281,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.
@@ -337,6 +354,13 @@ pub enum CampaignCommand {
/// 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.
///
/// `--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.
///
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
#[derive(clap::Args)]
@@ -357,9 +381,19 @@ pub struct CampaignSetArgs {
/// Replace the codename, a single word to call the campaign by
///
/// The same parser `campaign add --codename` takes, so a codename is one thing however
/// it was written.
/// it was written. Replacing one a campaign already has needs `--force`
#[arg(short, long, value_parser = codename)]
pub codename: Option<String>,
/// Replace a codename the campaign already has
///
/// Without it, `--codename` on a campaign that already has one is refused and nothing
/// is written. The codename is how a campaign is referred to once it has one, on every
/// card in it and at the command line, so changing it is a decision rather than a
/// correction. Setting the codename a campaign already carries is a no-op either way,
/// not a refusal: there is nothing to overwrite
#[arg(short, long)]
pub force: bool,
}
/// What a campaign holds: a title, a description and an owner.
+113 -25
View File
@@ -63,8 +63,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 +74,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 +104,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 +157,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);
}
}
@@ -1242,13 +1253,38 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
/// `set_or_insert_metadata_field`, the upsert `assign` already uses for the Campaign field
/// on a ticket, for the same reason.
///
/// **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 changing it out from under that is the same mistake
/// overwriting an edited skill document would be. So it is refused, and the refusal names
/// both words and the flag, the way `install-skill` names `--force` rather than leaving it
/// to be found.
///
/// Checked before any edit is applied, like `SetArgs::contested`, so a call that also
/// carries `--title` writes neither field rather than half of what was asked for.
///
/// No-op detection compares the whole file, the way `set` and `chown` do, so setting a
/// codename a campaign already carries writes nothing.
/// 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.
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)?;
let title = campaign.title.clone();
let overwrite = match (&args.codename, &campaign.codename) {
(Some(wanted), Some(held)) if wanted != held => Some((held, wanted)),
_ => None,
};
if let Some((held, wanted)) = overwrite.filter(|_| !args.force) {
return Err(anyhow!(
"Campaign '{}' is already codenamed '{}', so nothing was written. \
Pass --force to replace it with '{}'",
title,
held,
wanted
));
}
let mut content = campaign.content.clone();
let mut changed: Vec<&str> = Vec::new();
@@ -1526,9 +1562,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;
@@ -1538,18 +1603,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(())
+151 -4
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};
@@ -73,6 +75,33 @@ pub const PLAN_SKILL: Asset = Asset {
/// 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];
/// The opencode tool definitions, the second kind of asset this binary carries.
///
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
/// no directory it scans for one, so this is not the artifact that would reach it. That
/// asymmetry is the whole reason it is its own command with its own root rather than a
/// flag on `install-skill`.
///
/// Flat in the root rather than in a directory of its own, and the file name is load
/// bearing: opencode builds each tool id as the file name then the export, so this file
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
/// with; a tool carries it in the file name alone.
pub const TOOL: Asset = Asset {
name: "worklane",
what: "tool",
relative: "worklane.ts",
content: include_str!("../assets/TOOL.ts"),
};
/// Every tool this binary carries.
///
/// One, and an array anyway: it is what keeps the install loop the same shape as the
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
/// is one.
pub static TOOLS: [Asset; 1] = [TOOL];
/// The skill a name on the command line asks for.
pub fn skill_named(name: &str) -> Result<&'static Asset> {
SKILLS
@@ -106,6 +135,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 +402,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.
@@ -417,4 +488,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:?}"
);
}
}
}
+3
View File
@@ -92,6 +92,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),
}
}
+97 -3
View File
@@ -1157,12 +1157,14 @@ fn span_of(cell: Cell) -> Span<'static> {
fn columns_of(worklane_dir: &Path) -> (Vec<Column>, CampaignIndex) {
let campaigns = CampaignIndex::load(worklane_dir).unwrap_or_default();
let mut columns: Vec<Column> = status_dirs()
// Over `Status::ALL` rather than the names: each column is ordered by its own entry
// stamp, so the build needs the status itself and not just the directory to read.
let mut columns: Vec<Column> = Status::ALL
.into_iter()
.map(|status| {
// An absent or unreadable directory is an empty column, not a missing one:
// the four statuses are the shape of the board.
let cards = collect_ticket_items(worklane_dir.join(status))
let mut cards: Vec<Card> = collect_ticket_items(worklane_dir.join(status.as_str()))
.unwrap_or_default()
.into_iter()
.map(|ticket| Card {
@@ -1172,7 +1174,8 @@ fn columns_of(worklane_dir: &Path) -> (Vec<Column>, CampaignIndex) {
blocked: false,
})
.collect();
Column { status, cards }
cards.sort_by(|a, b| by_status_order(status, &a.ticket, &b.ticket));
Column { status: status.as_str(), cards }
})
.collect();
@@ -4530,6 +4533,97 @@ mod tests {
assert!(top.contains("backlog (1)"), "{top}");
}
/// The titles of one column, top to bottom, which is the order the reader acts on.
fn column_titles(board: &Board, at: usize) -> Vec<String> {
board.current().columns[at]
.cards
.iter()
.map(|card| card.ticket.title.clone())
.collect()
}
/// Each column is ordered by its own entry stamp, not by priority: committed is the
/// longest wait first, done is what just landed first. Every ticket here is a p2, so
/// the stamp is doing all of the work.
#[test]
fn a_column_is_ordered_by_the_stamp_the_ticket_entered_it_with() {
let dir = board_dir();
let stamp = |field: &str, at: &str| format!("- **{field}**: 2026-08-0{at} 09:00:00\n");
write_ticket(
&dir,
"committed",
"11111111-0000-4000-8000-000000000000",
"Waited",
&stamp("Committed On", "1"),
);
write_ticket(
&dir,
"committed",
"22222222-0000-4000-8000-000000000000",
"Fresh",
&stamp("Committed On", "3"),
);
write_ticket(
&dir,
"done",
"33333333-0000-4000-8000-000000000000",
"Older",
&stamp("Completed On", "1"),
);
write_ticket(
&dir,
"done",
"44444444-0000-4000-8000-000000000000",
"Newer",
&stamp("Completed On", "3"),
);
let board = boards(&[("only", &dir)]);
assert_eq!(column_titles(&board, 1), ["Waited", "Fresh"]);
assert_eq!(column_titles(&board, 3), ["Newer", "Older"]);
}
/// The merge spans statuses, so no single stamp governs it and it keeps priority then
/// title. Pinned on done, where the column order and the merge order disagree: the
/// board would put the newest first and the merge puts the p1 first.
#[test]
fn the_merge_keeps_priority_then_title_where_a_column_would_use_the_stamp() {
let (first, second) = (board_dir(), board_dir());
let card = |dir: &Path, uuid: &str, title: &str, level: u8, day: u8| {
let path = write_ticket(dir, "done", uuid, title, "");
let body = std::fs::read_to_string(&path)
.unwrap()
.replace("- **Priority**: 2", &format!("- **Priority**: {level}"))
.replace(
"- **Status**: done\n",
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
);
std::fs::write(&path, body).unwrap();
};
// Both on one board, so that board's own column can be read for the other
// order. The urgent one finished first, so stamp and priority disagree.
card(&first, "11111111-0000-4000-8000-000000000000", "Urgent", 1, 1);
card(&first, "22222222-0000-4000-8000-000000000000", "Later", 5, 3);
// A second board, which is what makes the merge tab exist at all.
card(&second, "33333333-0000-4000-8000-000000000000", "Other", 3, 2);
let mut board = boards(&[("alpha", &first), ("beta", &second)]);
assert_eq!(
column_titles(&board, 3),
["Urgent", "Other", "Later"],
"the merge sorted by stamp"
);
// The board the cards came from orders that column by the stamp, so the two
// really are two orders rather than one that happens to agree.
board.select_tab(1, SCREEN);
assert_eq!(column_titles(&board, 3), ["Later", "Urgent"]);
}
/// A tab per project, plus the merge, and the merge is where the view opens: it is
/// the reason to monitor several boards at once.
#[test]
+498 -30
View File
@@ -254,13 +254,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() {
@@ -1364,28 +1438,38 @@ pub const COMMITTED_ON_FIELD: &str = "Committed On";
pub const SUBMITTED_ON_FIELD: &str = "Submitted On";
pub const COMPLETED_ON_FIELD: &str = "Completed On";
/// Stamp the field of the status being entered and drop the other two.
/// Stamp the field of the status being entered and drop the ones after it.
///
/// A stamp is present exactly while the ticket sits in its status, so the three are
/// mutually exclusive: entering writes one, leaving removes it, and re-entering
/// restamps rather than keeping the first value. That is what keeps a ticket moved
/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is
/// the line between these fields and d4ce964's history log. Metadata carries current
/// state, which is why `Status` is a field at all; the trail of how the ticket got here
/// belongs to the log, and a stamp left behind would be a second copy of that job.
/// The stamps accumulate down the flow rather than being mutually exclusive, so a
/// ticket that has walked the whole way carries `Created At`, `Committed On`,
/// `Submitted On` and `Completed On` side by side and the journey behind it is legible.
/// Presence therefore means the ticket got that far and has not been sent back past it,
/// not that it is sitting there now; `Status` is what says where it is.
///
/// One arrival rule covers both directions. A backward move truncates the journey at
/// the target, so `done` back to `reviewing` drops `Completed On` and keeps the two
/// before it, and anything back to `backlog` drops all three. A forward skip under `-f`
/// has nothing after it to clear, so `backlog` straight to `done` stamps `Completed On`
/// alone and leaves the stages it jumped over unwritten rather than fabricated.
/// Re-entering restamps rather than keeping the earlier value.
///
/// This is still not d4ce964's history log. These fields answer how far and when, once
/// per stage; every status change, every owner and every tag along the way is the log's
/// job and must not be grown here. `backlog` has no stamp, `Created At` answers for it.
///
/// The time comes in as a string rather than being read here, so the caller stamps the
/// same moment it reports and a test can pin the value.
pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result<String> {
let mut content = content.to_string();
// Every status but the target, so a skipping move under `-f` clears the stamps of
// the stages it jumped over as well as the one it left.
for status in Status::ALL {
if status == target {
continue;
}
// Every status after the target, off the flow order `Status::ALL` already holds
// rather than a case per move, so arrival alone decides what is cleared and a
// backward move and a skip are the same rule.
for status in Status::ALL
.iter()
.skip_while(|status| **status != target)
.skip(1)
{
let Some(field) = status.stamp_field() else {
continue;
};
@@ -2496,8 +2580,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,
@@ -2653,6 +2737,48 @@ pub struct TicketItem {
/// 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.
@@ -2814,6 +2940,9 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
uuid: parse_ticket_field(&content, "ID"),
blockers,
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();
@@ -2822,11 +2951,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()
@@ -2834,6 +2965,39 @@ 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))
}
#[cfg(test)]
mod tests {
use super::*;
@@ -3403,10 +3567,10 @@ mod tests {
assert!(error.to_string().contains("Campaign"), "{error}");
}
/// The one stamp the target status carries, and nothing of the others: the fields
/// are current state, not a record of every stage the ticket has been through.
/// The stamp of the status being entered, added to what the ticket already carries:
/// the fields accumulate down the flow, so the stages behind it stay readable.
#[test]
fn entering_a_status_stamps_its_field_and_clears_the_rest() {
fn entering_a_status_stamps_its_field_and_keeps_the_ones_before_it() {
let content = with_metadata(
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n",
);
@@ -3415,25 +3579,64 @@ mod tests {
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
assert!(!updated.contains("**Committed On**"), "{updated}");
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
}
/// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket
/// carrying none rather than a Completed On for work it has undone.
/// Arrival truncates the journey at the target, so the stage the ticket has been
/// sent back out of is dropped and the ones it still got through are not.
#[test]
fn arriving_removes_the_stamps_of_the_statuses_after_the_target() {
let content = with_metadata(
"- **ID**: abc\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",
);
let updated =
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
assert!(!updated.contains("**Completed On**"), "{updated}");
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
}
/// Backlog has no stamp of its own and every status follows it, so a ticket forced
/// all the way back carries none of the three rather than a trail it has undone.
#[test]
fn moving_back_to_backlog_leaves_no_stamp_behind() {
let content = with_metadata(
"- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n",
"- **ID**: abc\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",
);
let updated =
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
assert!(!updated.contains("**Completed On**"), "{updated}");
for field in [COMMITTED_ON_FIELD, SUBMITTED_ON_FIELD, COMPLETED_ON_FIELD] {
assert!(!updated.contains(&format!("**{}**", field)), "{updated}");
}
assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}");
assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}");
}
/// A skip stamps the target and nothing else. The stages it jumped over are left
/// unwritten rather than given a time the ticket never spent there.
#[test]
fn a_forward_skip_stamps_only_the_status_it_lands_in() {
let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n");
let updated = set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap();
assert!(updated.contains("- **Completed On**: 2026-08-22 10:11:12"), "{updated}");
assert!(!updated.contains("**Committed On**"), "{updated}");
assert!(!updated.contains("**Submitted On**"), "{updated}");
}
/// Re-entry is the time of the move that brought it back, not the first one.
#[test]
fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() {
@@ -3472,6 +3675,170 @@ 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(),
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 = std::env::temp_dir().join(format!("worklane-stamps-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
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);
fs::remove_dir_all(&dir).unwrap();
}
/// 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.
@@ -4484,4 +4851,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);
}
+150
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();
@@ -1113,3 +1146,120 @@ fn campaign_set_offers_no_description_and_no_owner() {
assert!(!help.contains("--owner"), "{help}");
assert!(!help.contains("--clear"), "{help}");
}
/// A codename is how a campaign is referred to once it has one: on every card in it and at
/// the command line. Replacing that silently is the mistake `install-skill --force` exists
/// to prevent, so it is refused and the refusal names the flag.
#[test]
fn an_existing_codename_is_not_replaced_without_force() {
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", "-c", "beaver"]);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
let said = stderr(&out);
// Both words and the flag, so the message says what is there, what was asked for and
// how to get it.
assert!(said.contains("already codenamed 'v1'"), "{said}");
assert!(said.contains("'beaver'"), "{said}");
assert!(said.contains("--force"), "{said}");
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written anyway");
}
#[test]
fn force_replaces_an_existing_codename() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
let out = run(&temp, &["campaign", "set", "v1", "-c", "beaver", "--force"]);
assert!(out.status.success(), "{}", stderr(&out));
let content = campaign_file(&worklane, CAMP_A);
assert!(content.contains("- **Codename**: beaver"), "{content}");
// The line is replaced, not added beside the old one. Asserted on the field rather
// than on the word, since the campaign's title is "v1 release" and holds it too.
assert!(!content.contains("- **Codename**: v1"), "the old line survived: {content}");
assert_eq!(content.matches("**Codename**").count(), 1, "two codenames: {content}");
}
/// The guard is about overwriting a *different* word. A campaign with no codename has
/// nothing to overwrite, so `--force` is not the price of the first one.
#[test]
fn the_first_codename_needs_no_force() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
assert!(
!campaign_file(&worklane, CAMP_A).contains("Codename"),
"the fixture changed"
);
let out = run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
}
/// And setting the one it already has stays a no-op rather than becoming a refusal: there
/// is nothing to overwrite, which is the same answer `install-skill` gives an identical
/// document.
#[test]
fn setting_the_same_codename_again_is_a_no_op_not_a_refusal() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
let out = run(&temp, &["campaign", "set", "v1", "-c", "v1"]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
}
/// Refused before any edit is applied, like `SetArgs::contested`, so a call carrying both
/// fields writes neither rather than half of what was asked for.
#[test]
fn a_refused_codename_takes_the_title_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",
"-t",
"Renamed anyway",
"-c",
"beaver",
],
);
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the title went through");
let names = campaigns(&worklane);
assert!(
!names.iter().any(|name| name.contains("renamed-anyway")),
"renamed: {names:?}"
);
}
/// The title needs no guard, since a campaign always has one and replacing it is what the
/// flag is for. `--force` is the codename's alone.
#[test]
fn the_title_is_replaced_without_force() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
let out = run(&temp, &["campaign", "set", "v1", "--title", "First public release"]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
}
+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}");
}
+103 -13
View File
@@ -923,35 +923,89 @@ fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
}
/// One field per status, written with the time of the move, and only the current one:
/// the stamps are where the ticket is now, not the trail of how it got there.
/// One field per status, written with the time of the move and added to the ones
/// already there: walking the flow leaves the whole journey on the ticket.
#[test]
fn mv_stamps_the_field_of_the_status_it_enters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
for (status, stamp, cleared) in [
("committed", "Committed On", "Submitted On"),
("reviewing", "Submitted On", "Committed On"),
("done", "Completed On", "Submitted On"),
// The fixture predates Created At as well as the stamps, and the four reading as
// one block is the point, so it is seeded rather than asserted around.
let path = worklane.join("backlog").join(&filename);
let seeded = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:");
fs::write(&path, seeded).unwrap();
let mut carried: Vec<&str> = Vec::new();
for (status, stamp) in [
("committed", "Committed On"),
("reviewing", "Submitted On"),
("done", "Completed On"),
] {
let out = move_ticket(&temp, "cccc3333", status, false);
assert!(out.status.success(), "{:?}", out);
carried.push(stamp);
let content = ticket_at(&worklane, status, &filename);
let value = field(&content, stamp)
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
assert_eq!(field(&content, cleared), None, "{content}");
for stamp in &carried {
let value = field(&content, stamp)
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
}
}
// The four side by side and in flow order, which is what a reader asking when this
// was filed, picked up, handed over and finished gets one answer each from.
let content = ticket_at(&worklane, "done", &filename);
let block: Vec<&str> = content
.lines()
.filter_map(|line| line.strip_prefix("- **"))
.filter_map(|line| line.split("**:").next())
.skip_while(|name| *name != "Created At")
.collect();
assert_eq!(
block,
[
"Created At",
"Committed On",
"Submitted On",
"Completed On",
"Status"
],
"{content}"
);
}
/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all
/// rather than a Completed On for work that has been undone.
/// Arrival clears what comes after it and nothing before, so a ticket sent back out of
/// done keeps the stages it did get through.
#[test]
fn mv_removes_the_stamp_of_the_status_it_leaves() {
fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
for status in ["committed", "reviewing", "done"] {
move_ticket(&temp, "cccc3333", status, false);
}
move_ticket(&temp, "cccc3333", "reviewing", true);
let content = ticket_at(&worklane, "reviewing", &filename);
assert_eq!(field(&content, "Completed On"), None, "{content}");
assert!(field(&content, "Committed On").is_some(), "{content}");
assert!(field(&content, "Submitted On").is_some(), "{content}");
}
/// Backlog has no stamp of its own and every status follows it, so a ticket forced back
/// to it carries none at all rather than a Completed On for work that has been undone.
#[test]
fn mv_back_to_backlog_removes_all_three_stamps() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
@@ -968,6 +1022,42 @@ fn mv_removes_the_stamp_of_the_status_it_leaves() {
}
}
/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent
/// field says the ticket never got that far, and inventing one would say it did.
#[test]
fn mv_skipping_forward_stamps_only_the_target() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "done", true);
let content = ticket_at(&worklane, "done", &filename);
assert!(field(&content, "Completed On").is_some(), "{content}");
assert_eq!(field(&content, "Committed On"), None, "{content}");
assert_eq!(field(&content, "Submitted On"), None, "{content}");
}
/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to
/// write one or take one away, so a stamp is always the record of a real move. Pinned
/// so the omission stays a decision rather than becoming an oversight somebody fills in.
#[test]
fn no_other_command_can_write_or_clear_a_stamp() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
for command in ["add", "set", "append", "chown"] {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args([command, "--help"]);
let out = cmd.assert().get_output().clone();
let help = String::from_utf8_lossy(&out.stdout).to_lowercase();
for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] {
assert!(!help.contains(flag), "{command} --help names {flag}: {help}");
}
}
}
/// Re-entry is the time of the move that brought the ticket back, not the first one.
#[test]
fn mv_restamps_a_status_the_ticket_is_re_entering() {