check_blockers refused every move while a blocked by target was still open, so a dependent sat in backlog until its blocker landed even when the blocker was in reviewing and its code was there to build on. The way out was -f, which also waives the backward and skipping guard, on every move for as long as the pair existed. The rule is now the columns: a ticket may stand level with what it waits on but never ahead of it, so a blocker in reviewing lets the dependent be committed and reviewed and gates only done. util::blocks_move is the one place it is decided, taking the status moved into and the blocker's own, and mv passes the target through. A finished blocker still holds up nothing, answered through is_open, and a target of discarded is answered by name rather than by its place in Status::ALL, where it sits last. The refusal now names the status moved into and only the blockers still behind it: a dependent told to wait for work already ahead of it has nothing to act on. The board asks the same function about the column one stage ahead, so the blocked mark means the card cannot advance rather than that a dependency was ever recorded, which also takes it off cards in the two terminal columns. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
15 KiB
name: worklane-admin
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with worklane tags, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from ls, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
Administering a worklane board
For "set up a board for this", "what tags should this board have", "add a tag", "what does this tag mean", "the board is in a weird state", "this ticket has gone missing". The subject is the board itself: the vocabulary it files against, and the parts that can come apart.
The CLI is the worklane skill: the statuses, how a ticket is addressed, which command
owns which field. Read it too.
This is not worklane-plan. That skill grooms the work: priorities, due dates,
retagging tickets, campaigns. This one decides what the tags are and puts the board
back together. The line between them is the tag section: designing and annotating the
vocabulary is here, applying it across tickets is there.
A board is not only for software
Everything below holds for a board tracking a product strategy, a house move or a term's teaching, and the worked examples say so. What changes between domains is the tags, never the shape. Nothing in worklane knows what your tickets are about.
Two things you do not get to configure, whatever the board is for:
- The four statuses.
backlog,committed,reviewing,done, in that order, one step at a time. There is no way to rename them or add a fifth. If a board wants a waiting-on-someone-else state, that is a tag, and the ticket stays incommitted. - The fields. Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a concept these do not cover expresses it as a tag or a campaign, not as a new field.
So the tag vocabulary is where a board is fitted to its subject, and it is most of this document.
Starting a board
worklane init # in the directory the board belongs to
Which directory decides which board. Commands walk up from the working directory to the
nearest .worklane, so a board in ~/house answers every worklane run from anywhere
under ~/house and nowhere else.
init makes the four status directories, the campaigns directory and an empty tags.md.
Run on a board that already exists it prints a line and changes nothing, which is what
makes it safe to run when you are not sure.
Then declare the vocabulary before the tickets pile up. Tags applied for months are far harder to change than tags agreed once, because changing one means rewriting every ticket carrying it.
Designing a tag vocabulary
A tag is a word a ticket carries so the board can be cut by it later. worklane ls --tag kitchen is the whole payoff, so the test of a good vocabulary is whether the cuts it
allows are cuts anyone wants.
Work in axes
An axis is one question every ticket on this board can answer, with a small closed set of answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes bad is one where two axes were mixed into one pile of words.
A software tool:
| Axis | Answers |
|---|---|
| Kind | feature, bug, chore, docs |
| Area | cli, tui, api, build |
A product strategy:
| Axis | Answers |
|---|---|
| Kind | research, decision, experiment, writeup |
| Audience | enterprise, self-serve, internal |
A household:
| Axis | Answers |
|---|---|
| Kind | repair, errand, admin, cleaning |
| Room | kitchen, garden, garage, car |
Same shape, nothing in common. Derive the axes from the questions somebody will actually
ask this board, not from a template: if nobody will ever ask "show me everything in the
garage", garage is not earning its place.
The rules
- A tag is for kind, not for state. State is the status directory. A
doingtag besidecommitted, ablockedtag beside ablocked byrelation, adonetag at all: each is a second copy of something the board already knows, and the copy is the one that goes stale. - A tag is not a goal. Everything for one outcome is a campaign, which has a title, a
description and a state derived from its members.
worklane campaignowns that;worklane-plandecides what belongs in one. - A tag is not a field. No
p1beside Priority, noalicebeside Owner, noaugustbeside Due. The field is the writer and the tag will disagree with it. - A tag is not a person. Owner is a field, and
chownwrites it. - Two axes, not two words for one thing. Before adding a word, say which axis it is on. If it does not fit one, either it is a new axis, which is a decision, or it is a private note, which is not a tag.
- Around a dozen tags, up to twenty. Past that nobody remembers the vocabulary, so they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat a long tail nobody can recall.
- Singular or plural, pick one and keep to it.
bug/bugsandchore/choresare the commonest way a board ends up with two words for one idea. - Case matters.
Bugandbugare two tags to--tag, totagsand to the colour a card is drawn in. Lowercase everything unless there is a reason.
How many tags per ticket
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants three areas is usually two tickets, and a ticket with no tag at all is invisible to every question asked by tag.
Annotating a tag
worklane tags # every tag, its count and what it means
worklane tags add kitchen --annotation "..." # declare one, and say what it means
worklane tags set kitchen --annotation "..." # change what it means
.worklane/tags.md holds one section per declared tag, the tag as the heading and its
annotation under it. It is what a person opens to find out what the board means by a word,
and it is what an agent reads before choosing one.
Declaring a tag tags nothing, and tagging a ticket declares nothing. The two lists are
separate on purpose: the counts come from what the tickets carry, tags.md records what
the board agreed on, and the difference between them is the thing worth looking at. A tag
carried by tickets but never declared is a word somebody invented in a hurry.
worklane tags reports both, as the tag, a tab, the count, and a tab and the annotation's
opening line for a tag that is declared. So the two cases worth finding read off the
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
no annotation column at all is carried and was never declared.
What an annotation has to say
The definition is the easy half and does the least work. What stops drift is the boundary against the neighbouring tag, so write that.
Worthless, because nobody was ever unsure of this:
worklane tags add bug --annotation "Bugs."
Useful, because it answers the question somebody was actually about to get wrong:
worklane tags add bug \
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
--annotation "" \
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
The same for a household board:
worklane tags add repair \
--annotation "Something that worked and now does not." \
--annotation "" \
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
Repeat --annotation for more lines, and pass an empty one for a paragraph break. Three
lines is plenty: a definition, then the boundary.
Write an annotation for every tag, including the obvious ones. The obvious tags are the ones two people quietly disagree about.
Traps
tags addrefuses a tag that is already declared, andtags setrefuses one that is not. Each names the other, so the refusal tells you which you wanted.- A tag cannot contain a comma, because a comma is what separates one tag from the next in the Tags field. Surrounding spaces are trimmed.
- A tag you have declared and never applied lists at a count of zero. That is not a fault; it is the file and the board disagreeing, which is the state that tells you the vocabulary has not landed yet.
- Nothing removes a declaration. There is no
tags rm, so a tag declared in error stays in the file with whatever its annotation says. Say it is retired in the annotation.
Changing the vocabulary later
Renaming a tag
There is no rename. The tag is the key, so it means rewriting the Tags field of every ticket carrying it, one at a time:
worklane ls --tag bugs --ids # every ticket carrying the old word
worklane show 1b78a24 # read the whole Tags field of each
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
worklane tags add bug --annotation "..."
--tags replaces the whole field. Restate every tag the ticket should keep or the
ones you leave out are gone, with no undo. This is the most destructive command on the
board. Read the ticket's current tags before writing, never from memory, and run
worklane tags before and after: a count that moved where nothing was meant to change is
a tag lost to that rule.
Propose the whole list of edits and wait for approval before applying any of them, the way
worklane-plan requires for a sweep. The reason is the same: nothing records what a field
held before you wrote to it.
Retiring a tag
Take it off the tickets the same way, then leave the declaration saying it is retired and what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a better answer than a word that simply vanishes, because the next person will otherwise reinvent it.
Repairing a board
Every repair here has been run against a real board. Work by symptom.
The rule that does not bend: do not edit a ticket file. The filename, the Status
field and the directory have to agree, and the commands are what keep them agreeing. The
two exceptions below are files no command owns, and they are marked as such.
A ticket has vanished from ls
worklane ls leaves done out of its listing, though it still counts it at the top. So
first check worklane ls done. If it is there and should not be, its file has been moved
into the wrong directory by hand or by a restore.
mv reads the current status from the directory, so one move puts both halves right:
move the ticket to the status it belongs in and the field travels with it.
worklane mv 1b78a24 --status reviewing -f
If the file is where it belongs and only the Status field inside is stale — a hand move
that forgot the field, or a half-finished restore — name the directory the file actually
sits in: a move there finds the field disagreeing with the directory and rewrites just
the field, reporting the correction instead of refusing as a no-op.
worklane mv 1b78a24 --status done
That repair changes only the field: no stamp is written and no history entry either,
because the work went nowhere. Check either repair with worklane show 1b78a24, whose
Status line is read from the file rather than from where it sits.
A command says the id matches several tickets
Multiple tickets found matching 'bf2dc18':
1. (bf2dc18) Alpha [backlog]
2. (bf2dc18) Alpha [done]
The same file exists in two status directories, usually from a copy or a half-finished
restore. The ticket is now unaddressable: every command resolves before it acts, so show
and mv fail the same way and cannot be used to fix it.
File exception. Read both with cat, keep the one whose Status field agrees with
the directory it is in, and delete the other. If neither agrees, keep either and repair it
as above. Then confirm with worklane show.
A move is refused by a blocker
Cannot move 'Beta' to reviewing while it is blocked by:
...
A ticket cannot move ahead of what it waits on. Use --force (-f) to move it anyway.
Working as intended: a ticket may stand level with what it waits on but not ahead of it,
so this move was one column too far. Advance the blocker to that column, which is usually
the answer and costs nothing, or use -f if the dependency is no longer real. If it is
not real at all, take the edge off instead of forcing every move:
worklane relate <ticket> --clear blocked-by <blocker>.
If the message says is blocked by X, which is not on the board, the blocker has been
deleted. That is a warning rather than a refusal and the move goes through.
show renders _missing_
A relation or a Campaign field naming something the board no longer holds. Harmless to
read and impossible to clear, since relate only adds and assign only moves a ticket
between campaigns that exist. For a campaign, worklane assign <a-real-campaign> <ticket>
overwrites it. For a relation, leave it.
A status is missing from worklane ls
The count list at the top of ls names every status directory it found, so a status that
is absent from it has had its directory deleted. Nothing errors until something tries to
move a ticket there, which then fails with a raw file error.
File exception. worklane init will not repair it, since it refuses on a board that
already exists. Recreate the directory:
mkdir .worklane/reviewing
A .wl-*.tmp file in .worklane/
The staging file for a write that was killed part way. Every write stages here and renames into place, so a leftover means the write did not finish; nothing reads these and no listing shows them.
File exception. Delete it. Then check the ticket it names with worklane show and
redo whatever the interrupted command was.
Nothing works and the error names .worklane
Check where you are. Commands resolve the nearest .worklane at or above the working
directory, so running from the wrong directory addresses another board or none. worklane ls from where you think the board is, is the fastest way to find out.
What this skill does not touch
- Priorities, due dates, campaign membership and retagging sweeps. That is
worklane-plan. Deciding the vocabulary is here; applying it across the board is there. - Filing a ticket, working one, moving it through the statuses. That is the
worklaneskill. - Judging whether a finished ticket is really done. That is
worklane-review. - The content of a ticket. A description or an acceptance criterion that is wrong is the author's, and the answer is a comment on that ticket.