9.7 KiB
9.7 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 06lands as<uuid>_ticket-06.md. Derive fixture filenames throughslug(), 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:addwrites none of them, so they are inserted on demand, againstMETADATA_ORDER, which is also what keepsStatuslast - The four stamps are
mv's, written byset_status_stampfromStatus::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 offStatus::ALL, not a case per move, which is why a backward move truncates the journey at the target (doneback toreviewingdropsCompleted On, anything back tobacklogdrops all three) and a forward skip under-fstamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends withCreated At,Committed On,Submitted OnandCompleted Onside by side, so presence means got this far and has not been sent back past it, not is here now —Statusis 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.backloghas no stamp,Created Atalready answers for it Discardedis last inStatus::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 keepsCommitted OnandSubmitted 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-fwithout a rule of its own.Discarded Onis its stamp, andCompleted Onstays 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 byCommitted Onascending, reviewing bySubmitted Onascending, and done and discarded by their stamp descending. The backlog has no stamp of its own, so it sorts byDueascending, throughTicketItem::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 toby_priority_then_title, which is still the whole order among undated backlog tickets. One function keyed on theStatus, taken by bothcmd_lsbranches,list_ids,columns_ofandcampaign::members, which is why those loops walkStatus::ALLrather thanstatus_dirs(). The dates are read incollect_ticket_items' existing pass, the rulecriteriaandtagsalready hold, and compared as strings:%Y-%m-%d %H:%M:%Sand%Y-%m-%dare both lexicographic in chronological order, so nothing parses a date at sort time.due_keyanswersNonefor aDuethat is not a plainYYYY-MM-DDafterdue_datehas 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,OwnerandCreated At, in that order, and noStatus.Codenamesits directly under the ID because that is what it is, a second way to say which campaign this is; it is written bycampaign add --codenamealone and is_Not set_when the flag was not given. It is not inMETADATA_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::ALLis 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 byVisibility, 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 inALL— andthe_terminal_columns_are_last_in_the_order_drawnpins it- Discarding is not a stage, so the walk rules do not apply to entering it.
mv --status discardedis 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
mvpicks by direction.check_blockersasks what this ticket waits on and gates work moves;check_dependentsasks 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.-fis the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded - 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
- Both terminal statuses are hidden by default and counted anyway.
lsleaves done and discarded out of the decorated listing and keeps them in the summary counts, and--idsand 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
mvcreates 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.initgets all five fromstatus_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:lsprintsSHORT_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, soshow 641is 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_SETandNONEconstants inutil.rs, which are whataddwrites and what--clearputs back.is_unknown_valuereads 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 byis_unknown_valuefrom the day it was written, by analogy with the**-Status**field name themvsplicing bug really did produce, c230d2c. But no version of this tool ever wrote a hyphenated value:git log -Sfinds 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_unsetis what stops the analogy being drawn a second time- The
**-Status**repair inis_status_lineis the opposite case and stays. That corruption was real,mvwrote 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