Files
worklane/docs/ticket-format.md
T
Ansho ReiandClaude Opus 5 ead3c4340d (2c95d38) Gate a blocker by the column it is in, not by whether it is done, and bump to 0.33.1
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>
2026-09-10 11:38:17 +02:00

10 KiB

Tickets on Disk

What a ticket file holds, how the statuses move it, and how a search finds it.

Ticket File Format

  • Filenames: <uuid_v4>_<slug>.md
  • The slug is the title through slug(): lowercased, alphanumerics plus - and _ kept, spaces turned into dashes. Ticket 06 lands as <uuid>_ticket-06.md. Derive fixture filenames through slug(), never by hand
  • Metadata fields parsed by parse_ticket_field(): ID, Priority, Tags, Due, Owner, Created At, Committed On, Submitted On, Completed On, Discarded On, Campaign, Status. The last five are the ones no ticket is born with: add writes none of them, so they are inserted on demand, against METADATA_ORDER, which is also what keeps Status last
  • The four stamps are mv's, written by set_status_stamp from Status::stamp_field, and they accumulate: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status after the target. One arrival rule keyed off Status::ALL, not a case per move, which is why a backward move truncates the journey at the target (done back to reviewing drops Completed On, anything back to backlog drops all three) and a forward skip under -f stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with Created At, Committed On, Submitted On and Completed On side by side, so presence means got this far and has not been sent back past it, not is here now — Status is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. backlog has no stamp, Created At already answers for it
  • Discarded is last in Status::ALL, and that placement is what makes the stamp rule fall out right. Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps Committed On and Submitted On, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs -f without a rule of its own. Discarded On is its stamp, and Completed On stays untouched, because a discarded ticket was never done
  • Each status column is ordered by its own date, through by_status_order. Past the backlog that date is the entry stamp, so committed sorts by Committed On ascending, reviewing by Submitted On ascending, and done and discarded by their stamp descending. The backlog has no stamp of its own, so it sorts by Due ascending, through TicketItem::due_key. Said once: the head of every column is what the reader acts on next, and in the backlog that is the nearest deadline rather than the loudest priority — priority alone sat a p1 nobody had promised above a p3 due tomorrow. A ticket carrying no date sinks below every dated one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal dates and both-undated fall through to by_priority_then_title, which is still the whole order among undated backlog tickets. 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 dates 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 and %Y-%m-%d are both lexicographic in chronological order, so nothing parses a date at sort time. due_key answers None for a Due that is not a plain YYYY-MM-DD after due_date has cut a legacy datetime back — free text is unknown, not a date, and sorting on its spelling would rank it against real deadlines
  • 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
  • History entries stored in .worklane/history/<ticket_uuid>/<stamp>_<kind>.md, with the kind's marker (**Comment**, **Status**, **Owner**, **Tags**, **Campaign**), then the body, then **Author** and **Time**. See The History Log

Status Workflow

backlog → committed → reviewing → done, and discarded off to one side

  • Status::ALL is every directory that can hold a ticket, and that is the only list left. It is what the tree walkers want: status_dirs, RelationIndex::load, collect_ticket_items' callers, cmd_tags, list_ids, the resolver, the digest and the board's own columns all have to see a discarded ticket or it becomes unaddressable. There was a second list, FLOW, the four stages work moves through, which used to be what the board drew from; a136d13 drew the discarded column behind a visibility prefix instead, which took FLOW's last reader away, so it is gone. Hiding is decided by Visibility, never by leaving a status out of the walk: what is drawn changes, what is read does not. The prefix property survives on the order alone — done and discarded are deliberately the last two in ALL — and the_terminal_columns_are_last_in_the_order_drawn pins it
  • Discarding is not a stage, so the walk rules do not apply to entering it. mv --status discarded is allowed from any status with no -f, because a backlog ticket that turns out to be a duplicate should not have to be walked through committed and reviewing to be abandoned. Leaving it needs -f, which comes free from the backward-move rule
  • The two dependency guards look opposite ways, and mv picks by direction. check_blockers asks what this ticket waits on and gates work moves, refusing the ones that would put it ahead of a blocker; check_dependents asks who waits on this ticket and gates the discard. A ticket being abandoned owes nothing to its own blockers, but the tickets blocked by it recorded a dependency on work that is about to be declared never-happening, so those plans get a look before the ground moves. -f is the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded; check_blockers also skips a blocker already further along than the move being made
  • Discarded satisfies a block the way done does. There is nothing left to wait for, and whether the dependent still makes sense was asked at discard time by the guard above, which is what makes it safe to pass here rather than a second place to re-ask. It is also why blocks_move answers a discard by name and not by position: discarded is last in Status::ALL, so comparing positions alone would read the two terminal statuses as the furthest stages of the flow rather than the ends of it
  • Both terminal statuses are hidden by default and counted anyway. ls leaves done and discarded out of the decorated listing and keeps them in the summary counts, and --ids and the status positional still reach both: a ticket nobody will work still has to be nameable by a completion or a script
  • A campaign counts a discarded member as finished. The work was decided out of the campaign rather than left in it, and counting it outstanding would hold a campaign open forever over a ticket nobody will ever do
  • mv creates the target directory before moving into it. A board made before a status existed has no directory for it, and the first move into one is the wrong place to refuse. init gets all five from status_dirs()

Ticket Resolution

  • resolve_ticket() returns (status, title, content) tuple
  • Four tiers, evaluated in order: exact codename > UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the tiers reported an exact prefix match as ambiguous against whichever title mentioned it
  • The codename tier is a campaign's, and empty for a ticket, which has no such field. Case insensitive like the other three, so a codename typed back off a listing resolves whatever case it was read in. See Campaigns for why it sits above the uuid prefix
  • The UUID tier applies from MIN_ID_SEARCH (4) characters up. Not 8: ls prints SHORT_ID_WIDTH (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so show 641 is a title search
  • The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
  • Ambiguous matches (multiple results) print options and exit(1)
  • Never return empty strings for required fields — use the NOT_SET and NONE constants in util.rs, which are what add writes and what --clear puts back. is_unknown_value reads those two and nothing else
  • -None- and -Not set- are not unset, and re-adding them would be a mistake with a plausible story behind it. They were accepted by is_unknown_value from the day it was written, by analogy with the **-Status** field name the mv splicing bug really did produce, c230d2c. But no version of this tool ever wrote a hyphenated value: git log -S finds both spellings in exactly one commit, the one that added them to the check. Dead from birth, and dropped by bdddc09. a_hyphenated_marker_is_not_unset is what stops the analogy being drawn a second time
  • The **-Status** repair in is_status_line is the opposite case and stays. That corruption was real, mv wrote it, and the repair is what fixes a damaged ticket as it moves. Do not tidy the two away together on the grounds that they look alike