168 KiB
AGENTS.md
Project Structure
src/main.rs- dispatch, the SIGPIPE reset, and the TUI event loopsrc/command.rs- CLI argument definitions using clap derivesrc/completions.rs- the generated completion script and the fish half that asks the boardsrc/handlers.rs- onecmd_*per subcommandsrc/util.rs- the ticket format, resolution, rendering and the palettesrc/campaign.rs- the campaign file format, its resolution, its index and its memberssrc/history.rs- the history log: the path, the kinds, the reader, the writer, the card's counter and the blockshowand the board both rendersrc/tui.rs- board state, the change digest, and the ratatui drawsrc/clipboard.rs- the OSC 52 write and the base64 it carries, the board's only way out to the clipboardsrc/install.rs- the embedded agent assets and the compare-and-refuse installassets/SKILL.md- the agent skill for the CLI itself, embedded withinclude_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.mdkeeps its name because the role it teaches is the CLIassets/PLAN.md- the agent skill for grooming the whole board: priorities, due dates, tags and campaignsassets/ADMIN.md- the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line againstPLAN.mdin both directions: this one decides the vocabulary, that one applies itassets/TOOL.ts- the opencode tool definitions wrapping the CLI, embedded the same way and installed byinstall-tool. The only asset that is not a document and the only one that reaches a single agenttests/- Integration tests usingassert_cmdandassert_fs, one file per command- Unit tests live beside the code in
#[cfg(test)] mod tests, inutil.rs,history.rsandtui.rs - Ticket files stored as
.mdin.worklane/<status>/directories - History entries stored as
.mdin.worklane/history/<ticket_uuid>/, one file per entry, beside the status directories for the reason campaigns are - Campaign files stored as
.mdin.worklane/campaigns/, which is beside the status directories and deliberately not instatus_dirs()
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 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 byCommitted Onascending, reviewing bySubmitted Onascending, and done and discarded by their stamp 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 toby_priority_then_title. One function keyed on theStatus, taken by bothcmd_lsbranches,list_ids,columns_ofandcampaign::members, which is why those loops walkStatus::ALLrather thanstatus_dirs(). The stamps are read incollect_ticket_items' existing pass, the rulecriteriaandtagsalready hold, and compared as strings:%Y-%m-%d %H:%M:%Sis lexicographic in chronological order, the propertyDuealready 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,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()
How to use worklane is in assets/SKILL.md, not here. That document is what
worklane install-skill ships, so it is the one place the flow, the move-as-you-work
rule and the argument traps are written down. Read it before working a ticket in this
repo. Do not restate any of it in this file: a second copy is a copy that goes stale,
and this file is for what someone changing worklane's own code needs.
Testing
-
Run:
cargo test -
Tests use
assert_cmdandassert_fsfor CLI testing -
setup_worklane()creates temp.worklane/with the four flow status folders pre-created, pluscampaigns/incmd_campaign.rs, which is also where the on-demand creation is tested from a board without it. The fixtures deliberately do not creatediscarded/, so every discard test runs against a board that predates the status andmv_creates_the_discarded_directory_on_a_board_that_predates_itis not the only thing exercising the on-demand creation -
create_ticket()writes fully-formed markdown files directly (no--separator for positional args in test commands) -
Every unit-test fixture directory goes through
util::Fixture, and nothing callsremove_dir_allat the end of a test.Fixture::new(prefix)makes a uuid-named directory under the system temp dir and itsDropremoves it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a:/tmpreached 18363 of these and filled the disk, failing a link step and then agit addwith "No space left on device", an error naming neither the tests nor what they left behind -
Fixturederefs toPathand also implementsAsRef<Path>, because the two reach different call sites: a parameter typed&Pathis a coercion site and one bound byimpl AsRef<Path>is not.Fixture::child(name)points the fixture at a directory inside itself while still removing the parent, which is the treeproject_treeneeds. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather thanassert_fs::TempDir— that names its directories.tmpXXXXXX, which says nothing about whose they are -
WORKLANE_KEEP_FIXTURES=1 cargo testkeeps the fixtures and prints each path. Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, andFixture::swept()turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment -
Verify a claim about leaked fixtures against a clean temp dir, not against
/tmp.TMPDIR=/tmp/scratch cargo testthen count what is left in it:/tmpstill holds the historical leak, so counting there measures the past rather than the change -
In
tui.rs,write_member_cardiswrite_tagged_cardplus a Campaign field andwrite_campaignputs a campaign on disk, creating the campaigns directory as it goes —board_dir()deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws.picker_rowscuts the picker's list out of the frame by its own geometry, for the reasonoverlay_title_rowexists: a card carries the same campaign label, so a search over every row finds the board rather than the list -
cargo clippy --all-targetsis clean. Keep it clean, and do not silence a lint that is pointing at something real. The only twoallows in the tree sit on thecreate_ticketfixtures incmd_mv.rsandcmd_show.rs, each carrying the reason and what would replace it -
cargo fmt --checkis clean too, andrustfmt.tomlis what makes that affordable. rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:setting value why max_width100 The tree's own habit, and the measured optimum: 90 costs 268 hunks and 120 costs 194, against 161 at 100 fn_call_width75 A call stays whole if it fits in three quarters of the line. rustfmt's default of 60 is what expanded 276 of the 305 hunks the default config wanted chain_width65 The same for a method chain struct_lit_width30 A small struct literal stays whole, so Size { width: 120, height: 20 }is not six linesThe numbers were measured, not chosen. Default rustfmt wanted 305 hunks and would have added 1418 lines of pure layout, because its sub-widths sit far below the 100 columns this tree is written to.
use_small_heuristics = "Max"went the other way, 308 hunks and 796 lines removed, one-liningif/elseand collapsing struct literals that were split on purpose. Coordinate descent over the stable width knobs landed here, at 161 hunks, and 98 of those are rustfmt joining calls that fit rather than breaking them. Sweeping any one of these four in either direction makes the diff bigger, so do not adjust one by eye; measure it the same way, withcargo fmt --check | grep -c '^Diff in'- What this does not buy: rustfmt has no rule for "keep parallel arms parallel", so a match whose arms are one line and four lines depending on the length of their contents is what it produces, and that is accepted. Reach for
#[rustfmt::skip]only where the layout carries meaning a reader needs, not to win an argument about density - Do not add an unstable option.
cargo fmton stable ignores them with a warning, so the tree would format differently for whoever ran nightly - Sixteen lines still run past 100 columns and every one of them is a single string literal, a test fixture or an error message rustfmt cannot break.
format_stringsis deliberately left at its default: turning it on would let the formatter rewrite message text, and a message is prose. Somax_widthis where rustfmt breaks lines, not a limit the tree keeps - The reformat is
73ffcad, and.git-blame-ignore-revsnames it sogit blamelooks through it. Turn that on once per clone withgit config blame.ignoreRevsFile .git-blame-ignore-revs. A commit belongs in that file only if its diff is pure layout
- What this does not buy: rustfmt has no rule for "keep parallel arms parallel", so a match whose arms are one line and four lines depending on the length of their contents is what it produces, and that is accepted. Reach for
Coding Guidelines
Rust Style
- Use
if matches!(expr, Variant)instead ofif let Some(Variant) = exprfor enum variant matching - Use
if let Some(x) = exprinstead ofif let Some(Some(x)) = expr— drop unnecessary nesting - Prefer explicit
matchoverunwrap_or_default()for clarity - Use
unwrap_or_else(|| expr)for lazy defaults,unwrap_or(val)for eager defaults - Use
anyhow!()with context strings that include identifying info (e.g. UUID, title) not bare values - A command whose arguments run past a handful takes a clap
Argsstruct, not an inline variant with a matching parameter list:AddArgs,SetArgs,AppendArgs,CheckArgs.addwas nine positional parameters threaded frommainbefore it becameAddArgs, and the handler destructures the struct so the body reads the same as before
CLI Arguments
- The prose arguments carry
allow_hyphen_values, via thePROSEconstant incommand.rs:add --title,--description,--acceptance,--plan, and thecommentbody. Ticket text quotes flag names constantly, and without it a criterion reading--print is supportedis parsed as a flag and the whole ticket is refused with nothing written - The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why
due,priority,tags,ownerandstatusare deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not addPROSEto a new argument unless it holds prose --dueis validated at parse time byiso_date, the way--priorityis bypriority_level. A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars withoutPROSE. One parser servesaddandset: the field has one definition of what it accepts, and validating onlyaddwould leavesetopen, which is the command a grooming sweep actually uses- The shape is checked before chrono is asked.
%Y-%m-%daccepts an unpadded2026-8-9, which would be stored exactly as typed and sort before2026-10-01in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting - Strict on the way in, tolerant on the way out.
util::due_datestill cuts2026-12-31T09:30:00Zdown to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake - An empty
--duekeeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it campaign add --codenameis validated at parse time bycodename, which isnon_emptyplus one word. The board draws it as a label with a mark and no quoting, so~beaver releaseon that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reasonls --tagrefuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold- There are two empty-value parsers, and which one an argument takes is the point.
non_emptysays only that the value cannot be empty, for the arguments with no empty form: thelsfilters,relate's targets, andset --title, which addresses the ticket and names its file.clearablenames--clear, for the arguments whose field does have one:set --tags,--duethroughiso_date, and thechownuser. One message for both would either lie aboutls --tagor leave the useful half unsaid.add --duetakes the second one becauseiso_dateis shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser - A status is a
util::Status, not a string.mv --statusand thelspositional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain--dueand--prioritytake, and it is what lets the shells complete the four for free.Status::ALLis the flow order, whichstatus_dirs()andcmd_mvboth read rather than spelling the names again, andDONEis defined from it - The ticket positionals (
show <id>,mv <ticket>,comment <ticket>) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with--, as inmv --status committed -- -leading-title - A bare
--is a value when it follows an option (--title --stores--) and clap's end-of-options marker when it sits in a positional. So acommentbody of exactly--needs its own separator,comment <ticket> -- --. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop addhas no positionals, so anything after a bare--is an unexpected argument and fails- A paragraph break in a description is an empty
--descriptionvalue.cmd_addjoins the values with a single newline, so-d "First." -d "" -d "Second."writes the blank line.trim_blank_ends()drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed --acceptanceand--planare lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only--descriptionpreserves blanks
Completions
- Two halves, and the split is the point.
clap_completegenerates the structure from the clap definition, so a new flag or subcommand is completed without anyone touchingcompletions.rs. Only fish gets the second half, appended byfish_dynamic(), and it holds exactly what clap cannot know: the tickets on the board - The dynamic values come from worklane itself, as
worklane ls --idsin a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without--idscompletes nothing, which is a reinstall rather than a bug - What clap does and does not emit. It emits the possible values of an option, which is why
mv --status <TAB>needs nothing here, and nothing for a positional, which is why thelsstatus and thecompletionsshell are listed in the fish half. Both lists are read off the enums withpossible_values, never written out, so a fifth status appears in the script on its own - Position is counted, not inferred. The four
__worklane_*predicates all read$tokens[2]and the token count rather than using__fish_seen_subcommand_from, becausecampaign lsandcampaign showare also anlsand ashowthat fish has seen, and because matching against the ticket list would run worklane again inside the condition.first_arg_ofandsecond_arg_ofcount a top-level command's arguments,nested_arg_ofmatches a parent and a child socampaign show <TAB>can be told fromchown alice <TAB>, which sit at the same token count, andcommand_isasks only which command this is, at any position in it - Every rule carrying
-lneeds a__worklane_command_is, andevery_rule_naming_an_option_is_scoped_to_a_commandis what enforces it. A barecomplete -c worklane -l tagdoes not just complete that option's values, it tells fish the whole tool accepts--tag:worklane init --<TAB>offered six options that onlyrelateandlshave. Fixed in 55ee6e3.__fish_seen_subcommand_from lsis not the scope to use, for the nesting reason above - The five completion lists are kept honest by tests that walk the clap definition and fail on an argument left out of them.
TICKET_COMMANDSandTICKET_SECOND_COMMANDSby position,TICKET_FLAGS,CAMPAIGN_COMMANDS,CAMPAIGN_NESTED_COMMANDS,CAMPAIGN_FLAGSandTAG_FLAGSlikewise. The walk is one function,every_argument, since the tests differ only in the id they look for. Each also asserts how many it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them - A campaign is named in three shapes and a tag in one, which is why the lists are not one list: a campaign is
assign's first positional, the first argument ofcampaign showandcampaign set, andls --campaign's value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command ls --idsis the machine-readable listing, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script readscut -f1. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown--campaignis still refusedcampaign ls --idsis the same flag and the same two fields for the other object, and it deliberately skips the member counting the decorated listing does:members()reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidatesworklane tagsis the third, and it is a command rather than a mode onls. Two reasons:ls --tag <tag>answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a--tagsbeside a--tagis one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, sobugandBuglist separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been.assets/PLAN.mdused to tell the agent to count tags with ashowper ticket, and now points here
Filtering the Listing
- The filters are one call,
filtered, becauselscollects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is anOptionand none asked for keeps everything, which is what makes them compose in any combination without a rule per pair --tagmatches whole values, not the field.parse_tagshas already split the comma-separated field, so the filter compares against those trimmed values:--tag bugis not answered by a ticket taggedbugfix, and--tag "cli, filter"matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none- Case sensitive, the opinion the field already takes:
tag_colordrawsBugandbugin two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for - One tag per invocation. Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
- A tag nothing carries lists nothing rather than being refused, which is the opposite of
--campaign. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have.assets/PLAN.mdtells the agent to check the spelling when a listing comes back empty, andworklane tagsis what it checks against, since that is the failure this trades for - An emptied status keeps the message
lsalready gives,No tickets in '<status>' status., rather than one per filter naming what excluded them. That is pre-existing behaviour for--priorityand--campaign, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket cmd_lstakes anLsArgs, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacentOption<String>values a caller could swap silently.--idswas the argument that tipped it, the wayaddbecameAddArgs. A new filter is a field there, not a parameter
Editing a Ticket
setreplaces a field,appendadds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, andappendonly offers the sections that hold multiple lines- One field, one writer.
sethas no--owner(that ischown's) and no--status(that ismv's), and neitheradd,set,appendnorchowncan reach the three status stamps, whichmvwrites as a side effect of the move. Do not add any of them chowntakes the user first and the ticket second, after Unixchown, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left toresolve_ticket, which refuses a bare username as a ticket. No argument is inspected to see whether it also names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the usernamecmd_chownisset_metadata_fieldplussave_ticket, with the same whole-file no-op comparisonsetuses and the samereport()output, so nothing about writing a field lives twiceapply()is the one place an edit is taken or dropped, shared byset's replaced list and its cleared one. It was a closure over the single list until there were two, and two closures carrying one rule is how a later edit changes it for one and not the other- Sections are a table in
util.rs:DESCRIPTION,ACCEPTANCE,PLAN, each with a heading, a label, the placeholderaddwrites when empty, aSectionKindand the--clearvalue that empties it. Adding a section later is one entry, not edits in both commands - Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten
## Notessection intact when an unrelated field changes.section_body()finds the lines to touch,set_metadata_line()does the metadata, and every other byte is copied through - Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read
_No description provided._above its description - An empty value is a paragraph break for the three sections and a usage error for the scalars, via
non_emptyandclearableincommand.rs. Neither spells clearing, and both errors name the flag that does - A call whose values are every one blank is refused, by
replaced_itemsforsetandappended_itemsforappend. The check is the section's rather than the object's, socampaign set --descriptionshares it. What differs is the way out, which is whyreplaced_itemstakes it as an argument: a ticket's section is emptied with--clear <field>and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
Clearing a Field
set --clear <field>is the one way to take a value away, and it is a flag with the field as its value. Not a per-field--clear-due, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likesClearableis aValueEnuminutil.rs, so an unknown field is a usage error at the door listing the six that are not, and the shells complete them for free. It is also the whole table of what can be cleared:Due,TagsandPriorityclear to a sentinel,Description,AcceptanceandPlanto their section's placeholder.Titleis absent because it addresses the ticket and names its file, so there is no state to go back to;Owner,Status,Campaignand the stamps because clearing them throughsetis exactly the second writer the missingset --ownerexists to prevent- What is written is
NOT_SETandNONE, the constantsaddwrites. A cleared ticket and one that was never given the field have to read the same, or clearing would be a third state that every parser then has to know about.a_cleared_ticket_reads_like_one_filed_without_the_fieldscompares the two files byte for byte, which is what keeps a new field honest - The placeholder goes into a section bare, via
clear_section_body.set_section_bodyruns its items throughSection::render, which would write- [ ] _No acceptance criteria provided._. Both arereplace_section_bodyunderneath, so the line surgery and the trailing blank line live once - The pairing between a section and its
--clearvalue is stored on both,Clearable::unsetone way andSection::clearthe other, because the error for an empty value has to name the flag for that section and the section's label ("acceptance criteria") is not the flag's value ("acceptance").every_clearable_section_points_back_at_the_field_that_clears_itkeeps the two directions from drifting.RELATIONS.clearisNone, the same rule that keeps it out ofsection_args - Cleared fields are reported apart from replaced ones, as
Cleared due on '...'besideUpdated priority on '...'. One list would sayUpdatedof a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the onessetalready prints when it writes the field, so the two lines name a field the same way - Replacing and clearing one field in a single call is refused, by
SetArgs::contested. clap cannot express it, because the field arrives as--clear's value rather than in its name, and answering by whichever was applied last is a silent answer to a contradictory call - Clearing the owner is
chown --clear <ticket>, and--clearcarries the ticket. Owner has one writer and clearing it cannot introduce a second, so it lives onchown; but the ticket ischown's second positional, and a bare flag would land it in the user's slot for the handler to read back out, which is hand-parsing what clap can state. The typed call is identical either way.ChownArgs::targetreturns the one shape the constraints allow, and an error rather than a panic for the combination they already refuse - Clearing the owner writes
NOT_SET, not the git user.addfalls back to the git user because it is filing something new; an owner taken away says nobody owns this, and putting the person running the command there instead hands them a ticket they were giving up - Clearing a field that is already unset writes the sentinel that is already there, so the whole-file comparison below reports no change and nothing is written. That is not a special case, and must not become one
- No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
find_ticket_file()matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved:mv <uuid-of-second>used to move the first ticket sharing its titlewrite_then_replace()is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
Checking Off a Criterion
checkanduncheckare separate commands, not one verb with a flag. They shareCheckArgsandcmd_check(args, checked)criteria()is scoped to the Acceptance Criteria section and counts only checkbox lines, so a checkbox written into a description is not a criterion and a handwritten line inside the section takes no numberset_criteria()splices only the character between the brackets, and takes every line in one pass. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox- Each criterion term is the keyword
allfirst, an index second, a substring third. So a criterion whose text is literally2is reachable only by substring, and one whose text merely contains "all" only by its number or a longer substring.is_all_criteria()andis_index()sit beside each other inutil.rsfor that reason - The keyword wins over the text on purpose. Ticking every box is the reason the word is typed, and a board where
allsometimes means one criterion and sometimes means the lot would be worse than one that can be addressed another way.all_is_the_keyword_and_not_a_substring_of_the_textpins it against its own fixture, so the shared one keeps its three criteria and its numbering - A number out of range is a bad index, not a failed substring search, and says so.
is_index()makes that distinction - Any listing of a subset must keep the real numbers, via
numbered_criteria(). Renumbering the matches from one contradicts the advice to use the number and points at the wrong criterion - With the criterion omitted: prompt when stdin is a terminal, otherwise return the numbered list as an error. Never prompt unconditionally, the opencode wrapper has no tty and would block on a stdin that never closes. This is the same choice
resolve_ticketmakes for an ambiguous match, and for the same reason - The criterion positional is variadic, so
check <ticket> 1 3 "the footer"is one call and one write. Variadic rather than a repeated flag: the terms address criteria that are already there, the way the ticket positional does, instead of carrying content the way--acceptancedoes. The prompt path is unchanged and fires on an empty list resolve_criteria()resolves every term before a byte is written, and one bad term refuses the whole batch. A call that ticked the terms it understood and then failed would leave the ticket half-marked with nothing in the file to say which half was meant. It names the offending term alone rather than every failure at once, since each message carries the criteria listing and a batch of them would repeat the list per bad term- The chosen offsets are sorted and deduped, so the report reads in
show's order whatever order the terms arrived in, and a criterion named twice, or by bothalland its own number, is marked and reported once - Every named criterion gets a line, in
show's order, printed after the write. A criterion already in the target state readsAlready checked 2: textand does not count towards the write, so a batch where every box is already ticked writes nothing, which is the whole-file no-op rule the editing commands keep. The number is on the unchanged line too: without it a batch cannot be read back againstshow shownumbers the criteria as1. [x] text, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it
Relating Tickets
- The Relations section is
relate's alone.RELATIONSis in the section table but deliberately out ofsection_args, sosetandappendcannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer relate --clear <kind> <target>is the removal, and it is onrelaterather than onsetfor the same reason the section is absent fromsection_args: one writer owns both directions, the waychownowns setting an owner and clearing one. It names the target and not just the kind, because a ticket can hold several relations of one kind and emptying all of them is not what anybody is asking for. That is also why it is not spelled likeset --clear, which names a field and empties the whole of it- The two values are one flag, so clap cannot type them apart.
num_args = 2is per occurrence, which is what makes an odd number a usage error and every chunk a full pair;RelateArgs::clearedsplits the pairs and parses the kind, so a bad kind is refused before the ticket is resolved. It exits 1 rather than clap's 2, which is the price of a two-value flag and the reasonRelationKind::parse_valuenames the three in its message - Both spellings of the kind are accepted,
blocked-byfrom the flag andblocked byfrom the label. Both are in front of the reader: the flag is what recorded the relation and the label is whatshowprints and what the file stores, so refusing the printed form would be a trap for anyone clearing a row they just read.RelationKind::flagis a match rather thanlabel().replace(' ', "-"), so the flag, the--clearvalue and the completion list cannot drift apart find_relationsearches the ticket's own edges before the board, and that order is the feature. A dangling edge is the case most likely to need clearing, and no search of the board can reach a target whose ticket is gone, so the id-prefix tier over the stored targets is the only one that finds it.MIN_ID_SEARCHis the floorresolve_inputs under its own id tier and the comparison is case insensitive for the same reason. Two stored targets under one prefix name the candidates rather than guessing, which is what an ambiguous ticket search already does- An edge the ticket does not hold reports no change; a target naming nothing at all is an error. The two are different facts: the first is the state the caller asked for, and the second is a typo that reporting no change would swallow. The resolver's own reason is carried through, so an ambiguous search says so instead of being reported as nothing found
- Recording and clearing the same relation in one call is refused, and the check runs on what was asked for.
itemsdrops the additions already in the file, so comparing against that would let--blocked-by X --clear blocked-by Xquietly remove an existing X.requestedis the full list for exactly that reason. The refusal isset --clear's: nothing is written rather than one direction silently winning - Removals rewrite the section and additions are appended to the result, in that order. Two passes rather than one rebuild, so a call with no
--cleartakes exactly the path it always took andappend_section_bodygoes on deciding where a new line lands. Rewriting from the parsed relations is lossless because a line that is not a relation is already an error. The last edge leavesclear_section_body's placeholder, which is the lineappendtreats as no content, so the nextrelatereplaces it instead of writing under it - A relation is not logged, either direction.
relatewrites no history entry and neither does--clear, which keeps the two consistent; per the history rule, an edge that matters enough to explain gets a comment. Do not add an entry for the removal alone: a log that recorded only the destructive half would read as though the additions had never happened adddoes not write the section. The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A_No relations._block in every new ticket is noise in everyshow, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two- The full uuid is stored, not the seven characters
lsprints. It resolves without a scan and cannot turn ambiguous as the board grows.showrenders the short id and the target's title instead: the file is the machine's copy, the output is the reader's - One direction is stored and the inverse is derived.
blocked bygoes on the gated ticket rather thanblockson the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency.relates tois symmetric and is written once, on whichever end the caller ran it from.RelationIndex::inboundfinds the far end by scanning, which is what keepsrelatea single-file write - A derived row that reads exactly like a stored one is dropped, and the stored one is kept. Both ends of a symmetric relation could hold a line, since nothing stopped it until 03bdc76, and the block then drew the same neighbour twice under the same label. The stored row survives because it is the line
relate --clearcan address; the derived one is on a file this ticket does not own - The dedupe keys on the label and the target, not the kind and the target. Two tickets each blocking the other is two facts and the block says both,
blocked byfrom this end andblocksfrom the other; keying on the kind would fold them into one row and lose half of what the ticket says. Only a symmetric kind can collide with its own stored line, andRelationKind::is_symmetricderives that fromlabel() == inverse_label()rather than namingRelatesTo, so a kind added later answers by construction relatealso refuses to store the mirror, which is the other half of the same fix. The dedupe repairs a board that already holds both directions; the refusal stops it recurring.mirroredincmd_relatereads the target's own relations and reports no change, gated onis_symmetricbecause a target holdingblocked by <this>is a cycle rather than a duplicate. 4179958 decidedrelates tois written once and not onto both files; for six months nothing enforced it- A symmetric edge is cleared from the end that stores it. With both ends holding a line,
--clearon one leaves the other's, which then draws as the derived row: correct, since the far end still asserts the relation, and the reason the dedupe keeps the stored row rather than the derived one - A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but
relatewrites there, so a bad line means a hand-edited file. The TUI is the deliberate exception:detail_offalls back to no block, since one corrupt ticket must not take the whole board down - The block is built outside
content_trimand passed in. Half of it comes from other tickets andcontent_trimhas only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show ensure_sectioninserts againstSECTION_ORDER, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten## Notesbetween the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to- The blocker check runs on every move, after the already-in-that-status return and behind
force. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused.-fnow bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true - A blocker that is not on the board warns and allows the move. Refusing would wedge the ticket with no way out but
-f, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names every open blocker, since clearing the one that happened to be printed would leave the ticket blocked - Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See The Board View
Campaigns
- A campaign's state is derived, never stored. Open until every member is done, computed by
Standingfrom the members. AStatusfield on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is nocampaign mvand no forward-only ruleset besidemv's - A campaign with no members is neither open nor done.
Standing::state()returnsNonethere, and both callers printno members. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist - Membership is one field on the member,
Campaignin the ticket Metadata, written only byassign. The member list is deliberately not on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. Soaddhas no--campaignandsethas no--campaign, the same rule as Owner and Status - The full uuid is stored and the title is resolved for display, as the Relations section already does.
reference_cellsis shared between the two, so a dangling campaign and a dangling relation target are both spelled_missing_rather than each inventing a spelling adddoes not write the field. Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out ofaddmeans one path that is always exercised rather than two. Same reasoning as the Relations sectionset_or_insert_metadata_field()is the upsert, andMETADATA_ORDERis its anchor list, the waySECTION_ORDERisensure_section's. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no## Metadataheading is an error, not an insertion: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads- The four tiers are
resolve_in(), shared by tickets and campaigns. A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step.Found.diris the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one - An exact
Codenameis the top tier, and it lives in the shared resolver rather than in a campaign-only path. Only campaigns carry the field, soparse_codenamereturnsNonefor every ticket and the tier is always empty for one: ticket resolution is unchanged, whicha_ticket_search_is_unaffected_by_the_codename_tierpins. It goes above the uuid prefix because it is an exact match on a field written for the purpose, where a substring can be a coincidence, and because a codename likev1is belowMIN_ID_SEARCHand would never be tried as an id at all. A codename that a title also contains,v2againstv2 release, has to win outright rather than be reported ambiguous against it resolve_ticketexplains a search that names a campaign, rather than each command doing it. One place, somv,show,chownand everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentionedResolvedcarries whatcontent_trimcannot render from the file. The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call sitecampaign showlists done members, unlikels, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option.ls --campaignis the other way round: it is the ordinary board filtered, and keeps every rulelsalready hascampaign lsscans the status directories once per campaign to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice- The TUI got a card label and a frame, not a campaign tab. 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups across the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and
cfor the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project incolumns_ofand 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
Codenamefills.campaign_labelbuilds it in one place, as aCell, so the CLI paints it and the board makes a span of it; the mark isCAMPAIGN_MARK,~, beside#for a tag campaign setandcampaign appendare the only writers of a filed campaign's fields. d637288 decided the command: asetrather 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.setcarries--title, which renames the file the wayset --titledoes,--descriptionand--codename;appendcarries--descriptionalone.campaign addwriting a field at creation is not a second writer, exactly asadd --titleandset --titlecoexist- 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 mistakeinstall-skill --forceexists 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, likeSetArgs::contested, so a call also carrying--titlewrites neither field. Setting the codename a campaign already carries stays a no-op, not a refusal —--forceis about overwriting a different word, which is the same divisioninstall::Outcomedraws betweenUnchangedandRefused.--forceguards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required - The description arrived as a pair,
set --descriptionandcampaign append, 32e98ab. Never one without the other: for a prose sectionsetreplaces andappendadds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same lineappendalready draws for a ticket, andcampaign_append_offers_only_the_descriptionpins that. Neither flag takes--force: a description is prose written to be revised, the same reasontags set --annotationhas none appendis a campaign's own subcommand, not the top-levelappend. That one resolves a ticket, and one positional naming either object is the ambiguityresolve_inmakes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar ofresolve_ticket, which explains a ticket search that names a campaign. Undercampaignthe object is settled by the command, as it is forset,showandls- Still no
--ownerand still no--clear. No--owner, because nothing writes a campaign's Owner today and givingsetone would settle by accident whetherchowngrows a campaign. No--clear, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would beClearableon a campaign, whose variants are a ticket's fields, or a second enum with one variant in it.campaign_set_offers_no_owner_and_no_clearpins both - An empty
--description ""is a paragraph break here too, and the refusal for an all-blank value names no flag. Every prose argument in the tool reads a blank value that way,add,setandtags --annotationalike, so a campaign reading it as empty the section would be the one exception. With no--clearto point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist.replaced_itemsis where the check lives, shared withset, and the way out is the caller's argument for exactly that reason SECTION_ORDERneeds no campaign variant, and that is what the one-section file proves. A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, filtered by what is actually in the file, so a campaign's description anchors against## Metadata— which is wherecampaign_bodywrites it.the_description_is_edited_in_place_in_a_file_with_one_sectionpins that no section a campaign does not have gets inserted to anchor against- A campaign whose Description heading is gone is refused, not given the section back. No
ensure_sectionon this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, whereaddwrites nothing and the insertion is the only path there is. The refusal therefore names the section and not the object — "There is no description section to write to" — because both a ticket and a campaign reachreplace_section_bodynow.write_then_replacestill carries the noun, where the message is about a file - The codename is written through
set_or_insert_metadata_field, notset_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 putsassignon the upsert.Codenameis therefore inMETADATA_ORDER, directly after ID, so an inserted one lands wherecampaign_bodywrites 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_entryis the body,save_ticketandsave_campaignare the named wrappers, andwrite_then_replaceandfind_entry_filetake the noun as a&strso a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here,<uuid>_<slug>.mdin a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case campaign_body()builds the file fromDESCRIPTIONandMETADATA_HEADINGrather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status- The campaigns directory is created by
initand on demand bycampaign add, since every board made before campaigns existed has none and aworklane initover a live board to get one would be a strange thing to have to do
The Board View
- The board is for a person, and only for a person. Scripts and agents drive worklane through the CLI, which is what
assets/SKILL.mdteaches and what the integration tests pin. Nothing parses the drawn frame, so its layout is free to change: a new row on a card, a moved corner, a different colour or a hidden column breaks no caller. Judge a change here on whether it reads well, not on what it might break, and do not preserve a layout for compatibility's sake. What the CLI prints is the opposite case and is not covered by this worklanewith no subcommand andworklane tuiboth open it, the way a barefrigdoes.Cli::commandis therefore anOption- The worklane directory is looked for before the terminal, so running outside one gives the usual "No .worklane directory found" rather than a complaint about the tty. Both errors stay reachable and both are testable without a pty
- A missing tty is refused with a message naming a subcommand. Raw mode on a pipe fails with a bare "No such device or address (os error 6)", which explains nothing
- The watch looks at files, not directories. A directory's mtime only moves on create and rename, so a ticket edited in place would be missed.
digest()hashes every ticket and comment file's path, length and mtime. Comment files are in it because a comment added elsewhere has to reach the detail view - The digest guards the rescan, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not
notifyis deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387- Cards come from
collect_ticket_items, the same sourcelsuses, so there is no second parser.TicketItem::pathexists for the detail view - The detail view scrolls on
pgupandpgdn, not on up and down. Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them - The campaign frame scrolls on the same two keys, and
Board::scroll_pageis where the precedence lives. An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. InBoardrather than in themain.rsarm for the reasondismissis: a layering rule written into that dispatch is a rule nothing can check - The scroll offset is clamped against the wrapped line count, from
Paragraph::line_count, which is whyratatuicarries theunstable-rendered-line-infofeature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed - The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does not reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
- The overlay carries a page indicator on the bottom right of its border,
pg 2/8, so a long ticket does not open looking exactly like a short one.Block::title_bottomwith a right-alignedLine, which spends no text row, the trade the title already makes on the top border. The two cannot crowd each other: they are on opposite borders wrapped_heightis the one measurement.last_offsetis it less the viewport andpage_indicatortakes the same two numbers, so the clamp and the indicator cannot disagree. A secondline_countcall, or a count of the raw lines, is a number free to drift, and an indicator that says there is more to read where the scroll refuses to move is worse than none- The furthest offset is the last page by definition, not by division. The clamp stops at the wrapped height less the viewport, which is not a page boundary, so the final screenful is partial:
offset / step + 1readspg 2/3at the bottom of a 25 row ticket in a 10 row viewport and claims there is more below - The pages are counted in
scroll_step, a screenful less the overlap line, not in whole screenfuls. The step is what the keys take, so counting in it names only pagespgdncan land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport atpg 3/3two rows short of its end, since three presses are what it takes to get there - The indicator is dropped whole on an overlay too narrow for it, the rule a corner and the tags row already follow, and absent entirely when nothing scrolls, the way an untagged card spends no row on tags
page_indicatortakes four numbers and returns anOption<String>, so every case above is pinned without a terminal. The drawn tests exist for the two things arithmetic cannot answer: which border it landed on and what colour it reached the screen in- Columns scroll to keep the selected card in view.
Board::offsetsholds one offset per column, parallel tocolumnsand resized in step byreload, so a column you leave stays where it was. The keypress aligns the focused column viafollow_selection(screen), taking the screen size for the same reasonscroll_detaildoes: the visible height belongs to the terminal, which only the caller measures between draws - Card heights are measured on
card_lines, never assumed, on both the keypress and the draw side (card_height, and thestartsvec as the cards are built). An alignment that trusted a fixed card height would drift from the renderer the first time the card changed shape - The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back
- Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top. The index is shared and clamps permanently when a shorter column pulls it down, so a column you return to follows the selection to where it now sits rather than holding your old place
- The footer names only keys that work. It read
↑↓ scrollwhen nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete - A hint is a key and what pressing it does, and
key_hintis the only thing that draws one. The key is cyan and bold, the description takes the terminal's default foreground, and the row keeps its three-space gaps. Everything that names a key goes through it: the three footer states, the prompt's two keys, the picker's row and theq boardon the frame's border, so a reader learns the shape once. Same division in frig and pantop, each in its own accent colour, cyan here and magenta there — the three tools are read side by side and used to look like three programs - A key that is its description's first letter is merged into it, so the board draws
quit,campaignandtagwith the letter coloured and no letter in front, whiley copy id,ctrl-c quit,d show done (2)and every arrow row stay split. Two cells back on a row already at its width naming eight keys, and the coloured letter is the key either way. The prefix test inkey_hintis case sensitive for exactly that reason: a row naming bothrandRwould otherwise draw one word for the two of them, and the merged form can only say which key it is while the letter on screen is that key. It also means the row carries both forms at once, which is the cost of the two cells - What the row is cannot be read off its text any more, so the tests read its cells.
footer_cells,footer_at,keys_onandfooter_stylein the test module:keys_on(.., "quit")isSome(1)whereqquits andSome(0)on a row whose onlyquitis the tail ofctrl-c quit. Acontains("q quit")cannot tell those apart, and three of the guards that keep 1b78a24 out were written that way qandescare one key: close what is open, quit when there is nothing left to close.qused to setshould_quitoutright, so a reader who pressed it to put a ticket away lost the board instead, which is not whatqdoes anywhere else that lays a document over a list. One match arm inmain.rs, not two: two arms carrying one rule is how a later edit changes it for one key and not the other- The rule is
Board::dismiss, not the match arm. The dispatch inmain.rsis not reachable from a test, so anything decided there is undecidable by the suite. The arm is the line that names the keys and nothing else.the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quittingscansmain.rsfor what the arm cannot say for itself, over whitespace-collapsed source so rustfmt cannot fail it - The footer's last slot always answers how to get out, and with a ticket open the honest answer is
ctrl-c, the only key left that quits in one press. Going on drawing the mergedquitthere would be 1b78a24 in the other direction: a footer describing a key by what it used to do.ctrl-c quitis split by the same rule that merges the other, being no word's first letter - The overlay names its ticket on the border, not at the head of the paragraph.
Board::detailis aDetailcarrying the title, the id and the text, because the name has to travel beside the body rather than inside it:content_trimdrops the#heading on purpose, sincecmd_showprints it, and anything in the paragraph scrolls away detail_titlecuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket- The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes.
content_trimandformat_history_withtake the colour decision for the CLI's side of the same layouts - Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
- A card is four corners with the title between them: mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
- A card's height therefore depends on the column's width, so
card_linesandcard_heightboth take it.column_areasis shared between the draw andfollow_selectionfor the same reason:Ratiohands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts - A corner that will not fit is dropped whole, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
corner_line's right side is a group, single-spaced, and it gives up its items from the front. The item nearest the edge is what the corner is about; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was anOption. The spacing between the items lives incorner_linewith the gap arithmetic rather than in a caller, for the reasoncolumn_areasis shared: geometry reproduced by hand drifts from the draw.due_spanreturns aSpanand not anOption<Span>now, since theOptiononly ever existed to satisfy the old signature and the function cannot fail- The criteria count is a field on
TicketItem, filled incollect_ticket_itemswhere the file is already being read, and counted throughcriteria()so a checkbox in a description is not counted here or numbered byshow. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something.Nonerather than[0/0]for a ticket with no criteria - The comment count is the same field discipline and the one entry on that pass that costs a directory listing. The history lives outside the ticket file, so
count_commentsis aread_dirrather than a parse:.mdonly, the filterread_historyapplies, and no body is read, because a count needs none of them. It counts comments and not entries, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board.collect_ticket_itemsderives the board fromstatus_path.parent()instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another.history_dirspells the path once for the writer, the reader and the counter, the waycampaigns_dirdoes. Zero draws nothing, not a0and not a blank: an uncommented card is the row it has always been, whicha_card_with_no_comments_spends_nothing_on_the_cornerpins to the exact spacing - The count is cyan and the mark is
COMMENT_MARK, U+275E, a Dingbat. It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells wherespans_widthcounts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph the_count_is_read_when_the_items_are_collected_and_not_per_drawtakes the history directory away after the board is built, and is paired witha_comment_added_after_the_board_was_built_reaches_the_card_on_reload, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts- A card names its campaign on the label row, before the tags, in bold.
labels_linedraws both,CAMPAIGN_MARK(~) for the campaign and#for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the ordercorner_lineandproject_labelalready follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so a ticket in no campaign renders exactly as it did before campaigns reached the card Card::campaignis a resolvedCell, not a uuid, settled at reload the wayprojectandblockedare.TicketItem::campaignalready carries the uuid off the pass that builds the card; the name is in another directory, socolumns_ofreadsCampaignIndexonce per project and hands it to every card. Never per draw, the rulecriteriaandtagsalready hold. The merge carries the resolved cell rather than looking it up again, for the reason it carriesblocked: a campaign is addressed inside one.worklane, so a merged lookup could answer one project's uuid with another project's campaign- A campaign the board does not hold labels nothing, the answer
mark_blockedgives a dangling blocker.campaign_cellsrenders that case as_missing_because a metadata table is a place to report a dangling reference; a card is not copens the campaign picker, and taking a campaign filters the tab's columns to its members. Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the statuses with fewer cards in them, which is whatcampaign showalready answers the question in. Every column is kept, empty ones included. The filter is applied inreload, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, andfirst_match,column_countand the copy key all keep working unchanged- A campaign filter is a uuid on the tab, not on the
Board.Tab::filteris aFilter, and a campaign belongs to one.worklane, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared byreloadrather than left filtering the board to nothing - The frame above the columns has two heights, and
Chromeis what every measurement takes.Chrome::frameis anOption<FrameSize>, not a bool:Nonefor a tab showing the whole board, andCollapsedorExpandedfor one filtered to a campaign or a tag, because both heights have to be measured the same way by everything that measures the board.screen_rowsgrew a row, so the two bools that decide the geometry became oneChrome, copied fromBoard::chrome: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw andfollow_selectionhave to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (TAB_ROW,FRAME_ROW,BOARD_ROW,FOOTER_ROW), since an index written out by hand goes on meaning what it used to. Nothing in the geometry is named after campaigns, because the slot is the tag filter's too:Chrome::framesays how tall the frame is and never which filter filled it, so a measurement of the board never has to ask - The whole description is carried off the one read, and the cut is on the view.
section_prosereplacedsection_opening, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, andCampaignRow::summarytakes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file FRAME_PROSE_ROWSis the collapsed height, and it is a constant rather than a height fitted to the description. Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not- The expanded height is a share, not a second constant: half of what the frame and the columns divide. That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards.
Chrome::frame_rowstakes the height because of this, andscreen_rowsis where it is called, since that is the one place that already has an area to take a share of — which is what keepsChromeitself pure and copyable fromBoard::chromewith no screen to hand - The share is bounded at both ends, and
COLUMN_MIN_ROWSis why.Constraint::Min(COLUMN_MIN_ROWS)would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the faultChromeexists to prevent. So the share is capped at what leaves the columns those rows, and floored atFRAME_ROWS, since expanding must never shrink the frame. On a board too short to divide,entergives the collapsed height back rather than a height nothing measured.the_expanded_share_is_bounded_at_both_endssweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic - The frame says the rest of what it has to say on its borders, the trade the detail overlay makes with its title and its page indicator:
(id) ~codename · Nameon the top one, the standing on the bottom right, andq boardthen the page indicator on the bottom left. Every row spent here is a row of cards - The frame slot is shared between the two filters, not doubled. One filter is on at a time, per
Filter, so a tag frame is the campaign frame with its three slots filled differently:#tagintag_coloron the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows.FrameContentis what the two are told apart into, andframe_contentis the one place they are told apart at all — the borders, the colour,q board, the page indicator, the scroll and the focus are all the campaign frame's, and a secondmatchon the filter below that is how the two frames come to behave differently in a way nobody decided - A tag frame draws the annotation, which is the payoff for declaring a tag. Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in
tags.md, which they would have to know to open. An undeclared tag drawsNO_ANNOTATIONin grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable - A tag has no id, so
yon its frame copies the word. A tag is its name, matched whole byls --tag, so there are no seven characters to shorten and the#the border draws is not part of it —--tag "#bug"matches nothing. The footer saysy copy tagthere for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word - The count on a tag frame is every column's, drawn or not, the rule the standing holds. With the filter on, those columns are the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no
[open]to be in - The frame's page indicator goes on the bottom border beside
q board, not on the top beside the title. The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is about where the indicator is only where the reader has got to in it. Dropped beforeq boardwhen the two cannot both fit, since with either filter on the footer's last slot namesctrl-c quitand the border is the only place that saysqgives the board back Focusis the third place the selection can be, andTabis what holds it. The board had a column and a card andselect_cardclamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left.Focus::Framewhile no filter is on is the one state that must never exist —select_filterandreloadare what keep it from arising, offFilter::is_wholerather than off which filter it is, since either draws a frame to hold itTab::selectedhands back nothing while the frame holds the selection. Every key that acts on a card has to answer for the frame.←→are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen.yis the exception that earns its place: it copies the campaign's short id, soy copy idmeans the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is aboutenterroutes on the focus throughBoard::toggle_focused: the frame's height on the frame, the overlay on a card. It used to be inert on the frame for free, becauseTab::selectedhands back nothing andtoggle_detailtherefore had nothing to open. That is no longer an answer, and the routing is inBoardrather than in themain.rsarm for the reasondismissandscroll_pageareqdoes not gain a layer for the expanded frame, and up and down do not take it back. The expanded frame is the frame at its other height, not a thing laid over the board, soqgoes on taking the campaign filter off from either height andenteris the only key that undoes whatenterdid. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card.Tab::expandedsits beside the filter and resets whereselect_campaignandreloadreset the focus and the offset — a different campaign opens collapsed and at the top of its own description- The toggle re-clamps the frame offset, through
scroll_frame(0, screen). A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the nextpgupcounts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives - The frame is out of reach from under an open ticket. With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting.
an_open_ticket_keeps_the_scroll_keys_from_the_framebuilds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it - The standing comes from the columns, not from a walk of the tree. While a campaign is selected the columns are its members, done included, so
Tab::standingcounts what is already in hand rather than paying whatcampaign lspays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted - The way out is on the frame's own border, not in the footer.
q boardsits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows, and measured over its spans rather than one string since it is a key hint like any other. Drawn throughkey_hintand not as grey chrome: it is the one key on the board named anywhere but the footer, and a reader who has learnt to look for the cyan letter should not need a second convention to find it. The indicator beside it stays grey, having no key in it candtare named in the footer only on a closed board with nothing filtered, which is where a reader has to find them. Over an open ticket and on a filtered board they are left out: the frame's border then says how to put the filter away, and the row has no cells to spare. The tag used to be drawn on that row in its own colour, for want of a frame to draw it in, and 2a83bd4 took that away rather than saying it twice. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do- The footer has three states, because the selection has three places to be. An open ticket, the frame, and the cards. On the frame it names
↓ board,↵ expandor↵ collapse, the two scroll keys andy copy id—y copy tagon a tag frame — and leaves out←→because they do nothing there. It has to say which way↵goes, since the key is a toggle and the frame is always at one of its two heights.↑ frameis not named on the board, on the same tradecis dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and↑reaches it picker: Option<Picker>is the whole mode, the shapesearchanddetailuse, andBoard::picker_keyruns besidesearch_keyahead of the action arms for the same reason: an open list owns the keyboard, sodmust not toggle done andqmust not quit while a campaign is being chosen.ctrl-cis the one key it declines and every other control combination is swallowed, orctrl-dwould reach the arm bound tod- The picker's rows are
Tab::campaigns, not a copy taken when it opened, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, socon a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets aNoticerather than an empty box that has to be dismissed to learn it was empty topens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it. Every tag the board declares or carries, matched whole and case sensitively the wayls --tagmatches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesycpays a campaign-filtered board, and a board carrying no tag gets the sameNoticea board with no campaigns gets- A picker row draws a real codename only. The row opens with the short id, so the card's
~<id>fallback would print it twice and say nothing the second time - One picker serves both lists, and
PickerRow::keyis what keeps it one. A second picker would have been a second keyboard, query and highlight to keep in step with the first; insteadPickerKinddecides only which list is built and what the answer filters, and everything between the keypress and the filter runs once against the key — a campaign is keyed by its uuid and a tag by itself, both strings the tab can be filtered by. Picking either clears the other without either setter remembering to, becauseselect_filterreplaces oneFilter: one field, which is the same reason the frame slot is shared - The picker draws two sections, open campaigns above completed, and truncates the completed tail. One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by
Created Atnewest first, because what a reader recognises about a finished campaign is that it was finished recently.COMPLETED_SHOWNof them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the ruleby_status_orderholds for a column - The tag sections are declared above undeclared, and truncate neither. The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too:
tags.mdis what the board intends, and the vocabulary the listing reports is the one the picker offers.campaignandcampaignswould have sat one under the other here, in different sections, the day the second was invented picker_listis the one place that decides what a picker row is, andPicker::rowcounts drawn rows. The sections reorder the campaigns and add rows of their own, soTab::campaignsand the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick- A heading is drawn only over rows that exist, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
openandcompleted, notopenanddone. The split is taken fromStanding::state, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not in done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done- Headings and the truncation line take no number: the highlight moves over campaigns only.
stepped_picker_rowwalks past the chrome rather than stopping on it, since a highlight resting on a heading givesenternothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling /in the picker is the key it already is on the board, andpicker_keycan take it because printable keys used to fall through_ => {}. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answerdiskwith every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though--tagis not, because matching a tag is the filter and searching for one is a reader typing. An empty query matches everything, the opposite offirst_match's answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing/must not empty the list- A query turns the truncation off, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
- The query is a layer, and
esctakes it off before it takes the picker off, the orderdismisscloses the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement andenterstay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every printable key goes into the buffer, soqtypes and so doesj - The highlight follows its row, not its row number.
place_pickertakes a key — a uuid or a tag, whichever list is open — the same stringTab::filterholds for either filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it.reloadreads the highlighted key before the lists are rebuilt and puts it back after - A miss is a row in the box,
no matchin brightred, where the search prompt puts its own, andenteron it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty - The picker's footer becomes its query, the trade
draw_searchmakes: with every printable key going into a buffer, a list of keys describes nothing that works./ searchis named only on the closed query, and the open one names whatescdoes to it rather than what it does to the picker - The title says both counts while a query is open,
campaigns (2 of 6). The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen - Every campaign's standing is settled at reload, in one pass over the cards.
standings_ofcounts the cards naming each uuid off the columns the reload is already holding, which is whatStanding::ofbuilds forcampaign lswithout the walk of the status directories that one pays per campaign. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing Tab::standingis gone with it. The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rulewrapped_heightholds for the scroll.the_standings_are_read_when_the_cards_are_and_not_per_drawtakes the status directories away after the board is built, paired witha_member_finished_after_the_board_was_built_completes_its_campaignfor the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changingqtakes off one layer at a time, in the order they were put on: the overlay, then the campaign filter, then the board.Board::dismissholds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticketdigestwatches the campaigns directory as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit- The tags go under the title, dimmed, each prefixed with
#. The field was invisible on the board: nothing said a ticket was taggedbugwithout opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one tagsis a field onTicketItem, filled incollect_ticket_itemsthroughparse_tags, for the reason the criteria count is.parse_tagssplits the comma-separated field into whole trimmed values, so a caller asking forbugis not answered bybugfix, and reads absent,_None_and empty as the same answer- A held-up card carries
BLOCKED_MARK,×, after its id, in brightred. The constant lives inutil.rsand the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does - The mark goes after the id, not before it. Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
blockedis onCard, not onTicketItem. The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the wayprojectis. Whatcollect_ticket_itemsfills is the ticket's ownuuidand itsblockers, both read off the file it is already holding;mark_blockedthen walks the columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw- A blocker the board does not hold marks nothing, the answer
mvalready gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exceptiondetail_ofmakes for the same reason:showandmvare where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure - The merge carries the flag rather than recomputing it.
relateresolves its target inside one.worklane, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no project_labeltakes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had;the_project_label_leaves_the_row_inside_the_columnpins itdue_datecuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"- The terminal columns are hidden until
dasks for them, one step at a time. Not a new opinion:lsalready counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. Sodrotates three states — hide both, show done, show both, and back around — through theVisibilityenum onBoard, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the next press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices - Hiding is a change to what is drawn, never to what is read.
reloadstill scans the done and discarded directories anddigeststill watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan visible()returns a prefix ofcolumns, not a filter, which is what keepscolumnandoffsetsvalid as indices into either. It is derived from whereDONEandDISCARDEDactually sit rather than assuming positions, andthe_terminal_columns_are_last_in_the_order_drawnpins the assumption. A status inserted after discarded would otherwise hide two columns in silence- Hiding the column under the selection moves the selection to the last drawn column and closes an open detail view. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
- Assert a column heading against the top border row, not the whole screen. The footer names done too, so
screen.contains("done (0)")passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden;headings()andfooter()exist so the next one does not.headings()locates the row throughboard_area()rather than taking row zero, since the tab row sits above it when more than one board is monitored
The Search Prompt
search: Option<Search>is the whole mode, the shapedetailuses: "the prompt is open" and "what is in it" cannot disagree, and closing it leaves nothing to reset.Searchalso carriesmissed, set when enter found nothing and cleared by the next edit, since the message is about the query that missed- The prompt swallows every key it is given.
Board::search_keyruns ahead of the action arms inmain.rsand reports what it took, rather than every arm below asking whether a search is open. Typingdinto a query must not toggle done andqmust not quit; with no prompt open it takes nothing, so the dispatch is unchanged for every other state. The rule is onBoardfor the reasondismissis: the arm is not reachable from a test ctrl-cis the one key it declines, because a terminal application always honours it and a prompt that ate it would leave no way off the board. Every other control combination is swallowed and does nothing: it must not type its letter, and it must not fall through either, since the action arms match on the code alone andctrl-dwould reach the one bound tod- Esc is consumed by the search before it can mean anything else, which is the collision e7612de left behind:
escandqclose the overlay, and both have to lose to an open prompt. It falls out of the pre-branch rather than being ordered by hand first_matchsearches the visible columns, every card in them, not the rows on screen. A query that answered differently on a tall terminal and a short one is not a search, and the jump scrolls the match into view anyway. Hidden columns stay out: with done hidden, a match there would put the highlight on a ticket that is not on the board. Reading order is column by column, then top to bottom- Id and title only, per 3b16540, both lowercased. The title has to be case insensitive to be worth typing, and giving the id the same treatment lets a pasted id match whatever case it was copied in. An empty or all-space query matches nothing rather than everything
- The jump goes through
select_at, the tailselect_cardalready used.follow_selectionscrolls the column the card is in, and the offsets are per column and on theTab, so a jump across columns moves the right one;refresh_detailkeeps an open overlay on the ticket the selection names. A second version of either is how a jump comes to scroll differently from the arrow keys - A hit closes the prompt and a miss keeps it open, marked, with the selection untouched. The query can then be corrected in place instead of retyped from
/. Doing nothing visible is what makes a reader retype a query that was already right - The prompt takes the whole footer row, because the key list it replaces describes nothing that currently works while every key is going into the buffer. Its two keys are drawn as every other key is, cyan on the key and the default foreground on the word. That the query then sits in the same foreground as the descriptions is what the house style costs on this row, and the cursor is what says which half is an input — which it does in a terminal with no colour at all.
no matchstays brightred beside the query it is about, being the one thing on the row that is neither a key nor what was typed - The real terminal cursor goes after the query, not a glyph standing in for one. ratatui shows the cursor only for a frame that asked for it, so
set_cursor_positionis also what says "you are typing" while the query is still empty. Clamped to the row, so a query longer than the terminal leaves it on the last cell - Both closed footers name
/, since the jump works with a ticket open as well: it moves the selection and the overlay follows - Out of scope on purpose, each its own ticket once the input mode exists:
nandNfor the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
The Copy Key
ycopies the selected card's short id, over OSC 52 written by hand. The board is where a ticket is found and the CLI is where it is acted on, and the only thing joining them was seven characters retyped off the screen.yreads as yank to the readers a keyboard board is for, and was the letter left:q,esc,enter,space,hjkl, the arrows,pgup,pgdn,tab,backtab,dand/were taken- The mechanism was chosen against ssh, which is where a board is often read. An escape sequence is the only one of the three ways that crosses the connection, since it is the terminal at the reader's end that owns the clipboard. A crate (
arboardand its kind) wants X11 and Wayland libraries at build time, and on X11 the selection belongs to the process that set it: copy an id, quit, and the paste buffer is empty, which is precisely this flow. Shelling out towl-copy,xcliporpbcopyis platform sniffing plus a process spawn, and does nothing on a machine where none of them is installed or on the far end of a connection. crossterm 0.28 is what ratatui 0.29 pins and it ships no clipboard command, and the backend types have to match whatever ratatui pins, so a newer crossterm cannot be picked up on its own - The cost is paid knowingly: a terminal that ignores OSC 52 ignores it silently, and tmux needs
set-clipboard on. Whatclipboard::copyreports is whether the sequence was written, not whether it was honoured, and the footer message says no more than that. There is no reply to read: the query form of OSC 52 is refused by most emulators as a security matter, so nothing better is available to us - Base64 is twenty lines here rather than a dependency, because the only thing that goes through it is a seven-character id. Pinned on the RFC 4648 vectors, which cover both padding forms, since a wrong encoder would put plausible-looking rubbish on the clipboard
cand notp: the clipboard proper, not the X11 primary selection, since this is pasted into a command line. Terminated with BEL, which is what tmux documents and what every emulator that implements this at all accepts- What is copied is
ticket.id, the seven characters the card prints, not the full uuid: they are what stops the retyping and whatshow,mvandcommentall resolve. Decided byBoard::copy_textrather than inside the arm that copies, so the string is a question the suite can ask without a clipboard.Noneon an empty column, since an empty string would take away whatever the reader had there and give nothing back - The project is left off even on the merge tab, where the id alone is not an address. This goes onto a clipboard to be pasted into a command line, and a second word in it would have to be deleted every time; running the command in the wrong project fails to resolve rather than acting on the wrong ticket
- The clipboard is handed to
Board::copy_selected_idas an argument,clipboard::copyfrom the dispatch and a closure from a test. That is what makes both answers drivable, and it keeps the terminal write out of the board state - A failure is said in the footer, not returned. There is nobody above it to handle one: the board goes on being drawn, and an error swallowed there would look exactly like a copy that worked until the paste came out wrong
Noticeis the board's one channel for saying something in words, since a copy leaves nothing on screen to look at.failedmeans "nothing reached the clipboard" rather than "an error occurred", so an empty column and a refused write are one answer to the reader, both in brightred for the reasonno matchis- It takes the whole footer row, on a weaker reason than the prompt's: every key still works while a notice is up. It is that a message squeezed in beside the key list would move every key in it, and the row is the only part of the board that is not a ticket. Drawn after the prompt, which is an input and cannot be covered
- The notice is cleared by the next keypress, not by a timer. No clock on the board and no wakeup in the loop, and the moment the reader does anything else the message has been read or was never going to be. Doing nothing leaves it up, which is the one state where it is still worth reading.
Board::clear_noticeruns ahead ofsearch_keyas well as the arms, since a key typed into a query is still a key, and it must never move intotick: the board redraws four times a second and a notice cleared there would never be read
The Relations Block
- One builder, two painters.
relation_rowsdecides which edges there are, what they are called and which direction comes first;relation_cellsdecides the layout, the mark and the colours;paint_cellsturns cells into escapes for the CLI andspan_ofturns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent Cellis the unit both renderers take: a run of text, the colour it is drawn in and the modifier it carries,Nonefor the default foreground and for text drawn as it stands. The same trick as the palette itself, whereColor::ansi()andFrom<Color> for ratatui::style::Colorkeep one colour from existing for one renderer and not the other, andModifieris that trick a second time for the styles that are not coloursModifieris the first style on a cell that is not a colour, and it is an enum with one variant for the reason the palette is one:Modifier::ansi()is SGR 9 andFrom<Modifier> for ratatui::style::ModifierisCROSSED_OUT, so a style that exists for one renderer and not the other is a compile error. Bold is not in it, because bold rides insideColor::Magenta.ansi()andspan_fromadds it back from the colour alone; a second modifier goes here beside the strike. It is independent of the colour, so a struck run keeps whatever colour its column already gave itCell::struckis a builder, not a third constructor. The strike is decided a whole row at a time and the cells of that row are built by the layout that already chose their colours, sorelation_cellsmaps it over the row it has just finished rather than threading the decision through every cell it makesRESETis a constant both writers share.paintopens a colour andpaint_cellmay open a modifier ahead of one, and a reset that only knew about the colour would leave the strike running to the end of the lineBody::push_cellmerges on the whole style, not the colour alone. Nothing outside the relations block carries a modifier today, and a merge keyed on the colour would silently strike a plain run through the moment one didreference_cellsis the one spelling of a cross reference. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was areference_cellbeside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone- A row carries two marks, kind then status: what sort of edge this is, then how far the ticket at the other end has got.
blocked by × ◐ (6ce2c47) Title. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished - The status went through one bad shape first. It was a rising bar,
▁▄▆█, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer - Both directions of a kind carry one mark.
blocked byandblocksare the same edge read from two ends, and the label is what says which end you are on.both_directions_of_a_kind_carry_one_markpins it ×isBLOCKED_MARK, the same constant a held-up card draws, in the same brightred. On a card it says this ticket is held up and in the block it says this edge is what holds one, which is one word, so one glyph and one definition. It lives inutil.rsfor that reason, not intui.rswhere the card is- The kind marks stay out of the priority vocabulary, which owns
●◐○·, andno_relation_mark_is_a_priority_glyphpins that against every level. They are the arrows the footer already draws, so they render wherever it does - The status marks are those very circles, and what keeps them from reading as a level is width: the meter is always two cells and a status mark is one.
the_status_mark_is_one_cell_where_the_meter_is_twopins both halves. A card carries the meter and never a status mark, and the block carries the status mark and never a meter, so the two never sit in one column - Both marks go ahead of the id, where they describe the target rather than the row. Every row carries both, so nothing is pushed out of line the way the card's blocked mark would have been, which is why that one sits after the id and these before it
- The kind mark survives a target the board cannot find and the status mark cannot, since a kind is read from the ticket's own file and a status from the board.
?holds the column so the id does not move, and_missing_in grey is what says the target is gone - Committed and reviewing are told apart by colour alone, both being
◐, so a pipe cannot tell them apart:should_use_colorsis false and both read as under way. Accepted, because●and○are the two answers usually wanted andshowon the target settles the rest, andassets/SKILL.mdsays so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else RelationTargetcarries the title and the status in oneOption, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either wayshowand the board carry the same mark, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minorResolved.relationsis rows, not a rendered block, andResolved.campaignis cells for the same reason. An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing inResolvedcan arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, sincecontent_partspaints nothing at allBodyPartsplits the body rather than building it twice. It isCellsorRelations: everything outside the block is laid out once, bycontent_parts, andcontent_trimis that run throughpaint_cellswhile the board is the same cells run throughspan_from.Bodyis the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in placesDetail.bodyis aText, and it is the only thing measured.last_offsetand theParagraphboth take it, so the clamp cannot wrap the body differently from the draw.Detail::plain()flattens it for the suite and is#[cfg(test)]: a second representation carried alongside the spans is a second thing to disagreedetail_bodycloses 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. It now splits per cell rather than per part, since aCellspart holds many runs and a newline can fall inside any of them- The whole overlay body is coloured now, and
content_partspaints nothing. The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the sameCelltreatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout thatshowpaints and the board styles. Do not reintroduce apaintcall incontent_parts: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes coloredstill reachescontent_parts, and it no longer means paint. It says whether this renderer can carry a colour at all, and one thing turns on it:**bold**gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passestrue,content_trimpasses the CLI's decision, and a pipedshowstill reads its markers. Nothing else in the body consults it- Magenta means bold, and
span_fromis where the board learns that.Color::Magenta.ansi()is\x1b[1;35m, so the CLI draws every bold run bold as well as magenta, andFrom<Color>can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent - The conversion is pinned from both ends.
show_prints_the_same_body_it_printed_before_the_cells_conversionholds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite.the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_itis the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence - The history block arrives as segments too, so nothing in the overlay is flat.
history_partssplits the entries into flow runs and quoted runs in one walk;history_cellsis their flatten, which is what makes the CLI's bytes a property of the segmentation rather than a second walker free to drift from it, and the board reads the same parts and lays each out itself. Pinned from both ends the way the body is: the pins overformat_historyhold the flatten byte for byte, andthe_block_splits_into_flow_and_quoted_partspins which runs are whose
Finding the Board
find_worklane_dirclassifies the entry before it follows it.exists()follows a link, so a.worklanethat was a dangling symlink answered the same as no.worklaneat all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently.classifyreadssymlink_metadatafirst and answers one of four,Absent,Board,DanglingorNotADirectory, andAbsentis the only one the walk carries on from. A.worklanethat is there but unusable is this project's board and is reported, not handed upward- Anything other than
NotFoundfromsymlink_metadatais an error rather than anAbsent. 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/*.mdhas 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 throughfind_worklane_dirthe way the working directory is: the first.worklaneat or above it. No path is the working directory, so a bareworklaneandworklane tuiare 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
worklanehas no path to name and keeps the message every other command gives, which is what its integration test asserts - Two paths inside one project resolve to the same
.worklaneand are monitored once.projects()dedupes on the resolved directory, not on the argument Tabowns the selection,column,cardandoffsets, notBoard. 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, andvisibilitystays 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::newbuilds the tab list once andreloadonly refills each tab's columns.reloadclamps every tab, andselect_tabclamps 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 incollect_ticket_items - The merge is sorted, through
by_priority_then_titleinutil.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 takesby_status_order: the merge spans statuses, so no single entry stamp governs it Cardwraps aTicketItemwith the project it came from,Someonly on the merge tab. Decided at reload rather than passed down tocard_linesas a "which tab is this" flag.TicketItemis thereforeClone: 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_labeltakes 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 whatcorner_linedrops tabandshift+tabcycle 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 tookhjkland the arrows- The tab row is drawn only when there is more than one board, so a single board is the view it has always been.
screen_rows()gives itLength(0)otherwise, which keeps the row indices the same for both cases and is shared withcard_widthandcolumn_text_heightfor the reasoncolumn_areasis: geometry reproduced by hand drifts from the draw digest_ofhashes each board'sdigestinto one value, so a change in any of them redraws. Do not watch only the first
Who Wrote an Entry
- Identity is supplied, not detected. Every option that needs no cooperation fails: a harness variable such as
CLAUDECODEnames the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor isWORKLANE_ACTOR, set once per session, with--actoras the per-call override - Precedence: flag, then
WORKLANE_ACTOR, thenget_git_user(), thenunknown.resolve_actoris the only caller ofget_git_userfor an entry's author, and every entry the CLI writes goes through it. The two halves are separate pure functions,session_actorandentry_actor, tested without touching the process environment for the reasoncolors_wantedis split that way - The session half is cached in a
OnceLock, the wayshould_use_colorsis: neither the variable nor the git user can change mid-run, and the fallback costs agit configsubprocess.session_actortakes the git user as a closure so that subprocess is not run when the variable already answered - An empty
WORKLANE_ACTORcounts as unset, the conventioncolors_wantedfollows forNO_COLOR, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one - The actor is free text, checked against nothing, like the
chownuser: there is no registry of actors, and the same reasonls --tagrefuses to validate a tag - It was
comment --owner, renamed with no alias. Owner is the ticket's assignee and has one writer,chown; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splittingsetandchownavoided.the_owner_flag_is_gonepins the refusal, since an alias kept "for now" is what makes the wrong name permanent add --ownerandcampaign add --ownerstill default to the git user, deliberately. Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported- An entry does not record whether the call had a terminal. It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
- Set it in the agent's configuration, not per call.
envin~/.claude/settings.jsonreaches every command Claude Code runs. opencode has no equivalent: its config is JSON with noenvblock for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function aroundopencode. Both are documented inassets/SKILL.mdrather than assumed
The History Log
- The log is the comments directory with the kind named in it. It was already an append-only log with one event kind: one file per entry under
.worklane/history/<uuid>/, stamped to the microsecond and written withcreate_new. Addingstatus,ownerandtagsbesidecommentneeded no new mechanism, which is why there is no separate journal file and no database - What is not logged, deliberately: ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
--clearis logged, since it is the same field going somewhere.chown --clearandset --clear tagswrite an entry whose after-value is the sentinel the ticket now holds,_Not set_or_None_. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does- The kind is read from the file and only counted from the filename.
parse_entrymatches the leading marker;kind_from_stemsplits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader - A file with no marker is a comment, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command:
entry_content(Kind::Comment, ..)is byte for byte whatcmd_commentwrote before this module, so nothing is rewritten and either version can read the other's board - The old directory is adopted, not migrated.
adopt_commentsrenamescommentstohistoryon the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. A board holding both is refused, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it - An entry is written after the edit it describes, never before. A refused move, a refused chown and a failed save log nothing, which is what
a_refused_move_writes_nothinganda_failed_edit_writes_nothingpin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it - A no-op edit writes nothing either, and
applyis what decides that forset: a field it did not record as changed was already what the call asked for.cmd_mvandcmd_chownhave their own early returns and sit behind them - The stamp leads the filename and the kind follows it, so the lexicographic sort in
read_historystays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it - A mechanical entry renders as one line and a comment as it always did. A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to
Kind::LABEL_WIDTH,campaignbeing the longest of the four, so the bodies line up under each other - A campaign entry records
Campaign::name, the codename or failing that the title, never the uuid the field holds. Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. Abeforeuuid the board no longer has reads_missing_, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from_Not set_(f774a33) --actoris on every command that writes an entry, spelled from oneACTOR_HELPincommand.rs: a flag documented differently on each command reads as four flags. Onchownit sits besideuser, which is the ticket's new assignee — the two are different questions and that command answers bothset --actorreaches only the entry--tagswrites, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
Shipping the Agent Assets
- The skill is embedded with
include_str!fromassets/SKILL.md, not copied by an install script.cargo installplaces binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it assets/SKILL.mdis 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 skillworklane_kanban, its examples still used short flags the CLI had stopped accepting, and it knew nothing aboutrelate,campaign,chown,checkor the four-status flow. It was not inert while it existed:opencode debug skilllisted 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 andinstall-skillis 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-incustomize-opencodeskill documents the table and whoseopencode debug skilllists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain Assetcarries the content, the path under its root and the word used in messages, soinstall-tooladds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module isinstall.rsand notskill.rsinstall()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 redirectsHOMEfor the same reason- A modified copy is refused, not overwritten. Someone may have edited it on purpose, and the message names
--printso it can be diffed and--forceso 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 outsideNOT_FOR_AGENTShas to appear in the skill. The last one catches a new command that nothing tells an agent about install-skilllooks for no board. The skill is what teaches an agent worklane, so needing a.worklaneto install it would put it out of reach exactly when it is wanted- The agent files under
.opencode/are the user's, not this repo's to ship. Do not embed or install them.reviewing-agent.mdthere is the prior art the review skill grew out of and is deliberately left in place: its content is now inassets/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 nowassets/TOOL.tsand shipped like every other asset install-skillwrites 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--printrequires 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 thecomment --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 - A refused document does not stop the ones behind it. The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written
- A role skill is its own document, not a section of
SKILL.md. The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read theworklaneskill too - 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 (mvbelongs 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 inreviewingis itself the finding) - The plan skill is the one that can do damage, so its rules are the ones under test.
set --tagsreplaces 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_sweeppins propose-then-apply and those two traps, because a document that loses them still reads like a plan .opencode/agent/feature-planner-agent.mdis deliberately not folded intoPLAN.md. It decomposes a feature request into new tickets, which is intake;PLAN.mdorders 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 documentinstall-toolis a second command, not a flag oninstall-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 addwith astdio,sseorhttptransport is the only way a tool enters its tool list, and its plugin system adoptsagents,hooks,monitors,workflows,output-stylesandthemesand nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238tools_root()followsXDG_CONFIG_HOME,skills_root()does not.~/.claudeis not an XDG path and opencode's config root is:opencode debug pathsreports$XDG_CONFIG_HOME/opencodewith the variable set and~/.config/opencodewithout. An empty value counts as unset, the conventioncolors_wantedfollows forNO_COLOR.opencode_tool_dirtakes both variables as arguments for the reasoncolors_wanteddoes, 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/idsregistered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writesagent(s)andskill(s).opencode serveplus that endpoint is how to check this again; there is noopencode debug toolto ask worklane.tsis the file name the tool ids are built from. opencode names each tool as the file then the export, so the file's elevenexport constlines becomeworklane_addthroughworklane_uncheck. Renaming the file renames every tool and every permission rule that mentions one, which is whyTOOL.relativeis 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/pluginimport resolves there: a copy in a project with nonode_modulesanywhere above it registered all eleven tools, on a machine with nobunonPATH. 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,assignortags, so an agent holding the tools cannot reach campaigns or relations at all.every_tool_the_wrapper_exports_is_a_real_subcommandcatches 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-toolhas run, an agent working on worklane uses the installed copy ofassets/TOOL.tsand not the tree it is editing. Same trap as theworklaneonPATH, second instance every_agent_facing_subcommand_is_documentedstays onSKILLalone. 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 withinitand 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- The README command table has the same guard,
every_subcommand_has_a_row_in_the_readme_command_tableincommand.rs. The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test:campaignandassignshipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the--campaignflag on thelsrow. It walks clap's own subcommands, one level of nesting included, against the|lines ofREADME.md, so a new command fails the suite until the table lists it.helpis excluded, being clap's. The tag subcommands are named in aPENDINGlist rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
Color and Output
- Use
color_text()for coloured output — it respectsshould_use_colors()(terminal detection), andpaint()is the same with the decision passed in color_text()is for the CLI's own printing only. Anything reachable fromcontent_trimtakes the decision as an argument and callspaint(), because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes.nothing_the_body_renders_asks_the_terminal_for_the_colour_decisionscans this file and fails on a new caller; the allowlist isambiguous, which builds a failed-search message for stderr- A function that takes an
enabledflag must use it all the way down. The inline pass honoured its flag on the early return and then askedshould_use_colors()for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag:ordered_cellsandmetadata_value_cellsreturn the colour rather than a decision about it - A test that asserts an absence has to be paired with one that asserts the presence. The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so
should_use_colors()was false and the leaking branch was never taken. The pair is nowcontent_trim(.., false)has no escape andcontent_trim(.., true)still colours, which pins the flag as the only thing that decides - The palette is the
Colorenum, not a string.Color::ansi()gives the CLI its SGR sequence andFrom<Color> for ratatui::style::Colorgives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is howmagentacame to be undefined - Reset color with
\x1b[0mafter colored text - Bold uses
\x1b[1;35m(magenta bold) - Always test color output works correctly in both terminal and pipe modes
quiet_broken_pipe()runs first inmain, restoring the defaultSIGPIPEdisposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of makingprintln!panic. Do not wrap prints to handle write errors and do not reinstateSIG_IGN; the exit codes are documented in the README
Color Guideline
- UUID → red (31)
- Status → orange (33)
- Timestamp → cyan (36)
- Title → green (32)
- Unknown values (
_None_,_Not set_) → grey (38;5;8) - Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation kind mark → brightred
×blocked by and blocks, cyan→relates to, orange←regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking - Relation status mark → grey
○backlog, orange◐committed, cyan◐reviewing, green●done, grey●discarded, grey?for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The pair is what has to be unique, which is the same bargain the two half circles already take, andevery_status_has_a_markpins it againststatus_dirs. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. Green is here and deliberately absent from the priority ramp, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show - Relation row to a discarded target → struck through, the whole row. The one thing in the palette that is not a colour, and it is here because the status mark cannot carry it: that mark is one cell in a column of five states, so a row pointing at abandoned work reads as a live dependency, which is exactly what it is not. The strike says the relation no longer stands for anything while the row stays on the ticket, for completeness and for the case the target is moved back out of discarded. Only discarded: a done target still stands for the fact that it was a blocker, and a
_missing_one says something different again, that the row cannot be resolved at all. Gutter and padding included, so the line runs unbroken from the label to the end of the title, and every cell opens its own SGR 9 since each is closed by its ownRESET - The strike is under the colour flag, like every other escape. A piped
showcarries none of it, the same bargain committed and reviewing already take for being told apart by colour alone, and the board draws it as a style instead. Do not answer the pipe by changing the glyph in the mark column: the pair there has to stay unique, andevery_status_has_a_markis what says so - Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the
relates tomark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, becauseshowprints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line - Chrome → grey. A rendered
[ ], the overlay's page indicator and the frame's. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level - A key name → cyan, and bold; what pressing it does → the default foreground. The one place the palette spends a colour on something that is not a value: a key is what a reader is hunting for on a row they otherwise skip, and with the key merged into its description the colour is the only thing saying which letter to press. Not a second meaning for the timestamp's cyan in any place the two could be confused — nothing on the footer, the prompt or a border hint holds a value at all — and it is the accent frig draws the same row in, which is the point. Grey stays on the chrome around it: the page indicator, and the row's gaps
- Chrome → grey, in the history block too: the kind label at the head of a mechanical row, and the
Fromon a comment's author line. Both name their row rather than holding a value, which is what grey already says. The label was orange, which means Status everywhere else, so anownerortagslabel claimed a meaning belonging to the value beside it - A value in the history block takes the colour it has in the metadata table three lines above. A status is orange, a tags entry goes through the same
tag_cellsthe Tags field does, a campaign codename takestag_colorbare the wayCodenamedoes, and_Not set_,_None_and_missing_are grey. An owner stays plain: a person's name is the one value the palette has no meaning for, and spending a colour on the field that needs it least is how a colour stops meaning anything. The block's job is to be scanned, and it is not worth scanning if it has a palette of its own to learn first - History actor → its name through
tag_color, the way a campaign codename is. Not a new meaning for a reserved colour but the existing use of the tag slots, a name that groups rows: one writer is one colour in every entry it wrote, so a reader sees who has been working a ticket without reading the same name four times.claude,opencodeand a person each get their own - History timestamp → cyan, and its own span. It shared one with the actor while the two were formatted as
name (time), which spent the timestamp's colour on a name. The parentheses are plain: they are punctuation, not chrome with something to say - Campaign label → its codename through
tag_color, bold, marked~. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view becausetag_coloris a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not#, or the row would read as a list of tags with a stranger in it, and not@, which reads as a person on every board anyone has used.Codenamein a metadata table takes the colour without the mark, since the field name has already said what it is - Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a
TAG_COLORSslot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself - The palette splits in two: seven colours that each mean one thing, and
TAG_COLORS, the eight a tag may be drawn in. A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour inTAG_COLORS, and do not draw a tag in one outside it tag_color()is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, becauseBugandbugare two different tags to the field and to every search- The hash is FNV-1a written out here, not
DefaultHasher. std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for.the_tag_mapping_is_pinnedfails on any change to it, so a repaint is a decision rather than a surprise - The index is multiply-shift, not
% TAG_COLORS.len(). The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2,bugandBUGamong them, landed in one slot regardless of the rest of the string. It looked like a good palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash - Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground.
\x1b[38;5;8mis byte for byte what crossterm emits for ratatui'sColor::DarkGray, the grey frig and pantop use for dimmed rows
Code Organization
changeandsplit_changeare a pair, and they live beside each other inhistory.rs. The mechanical body is stored as one string,before → after, so painting the halves means splitting it, and the separator is a constant the writer and the reader share. A renderer with its own copy of the spacing would go on splitting on a separator the writer no longer emits, and would say so by drawing a whole body as one half. The split issplit_once, so a value carrying the arrow itself keeps it- The history block quotes who is talking. Every line of a comment's body draws behind a grey bar spanning the whole run, paragraph breaks included, the way quoted text is drawn — d447e04, taking the review of 2733b10's answer over that ticket's uniform prefix and b304b17's per-line indent, both of which left the continuation at column 0. The reason under a mechanical row draws the same bar. The author line stays at column 0 and is told from a mechanical row by its
Fromand its colour instead; the rule a reader learns is that a barred line is somebody's own words and a line of values at column 0 is the tool reporting itself. With colour off the glyph goes but the width it occupied stays, as spaces derived from the drawn form inquoted_cells, so a pipe keeps the column without an escape byte - A quote is one segmentation, two shapes, and the shapes split on wrapping. The CLI prefixes each stored line —
quoted_cells, which is why a terminal soft-wrapping a wide line draws continuations bare: a pipe has no width to honour, andshowdoes not wrap by hand. The board quotes as geometry instead (8020e48): aHistoryPart::Quotedrun becomes an overlay section laid out as two columns, a two-cell gutter holding the grey bar top to bottom and the body beside it, so a row the prose wraps onto inherits the mark from the gutter rather than from its own first characters.Detailholds sections for this reason — flow stretches full width, quotes beside their gutters — and the clamp sums the sections' wrapped heights, so scroll and draw measure one total. The newline history writes after every quote is consumed by the section builder rather than drawn: it used to close the quote's last line and the section boundary does that now, so drawing it would bank a blank row no entry ever had.QUOTE_BARlives inutil.rsbecause both renderers draw it, not because they draw it the same way history.rsowns the log end to end: the path, the kinds, the parse, the write, the count and the render. It came out ofutil.rsandhandlers.rs, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the waycampaign.rsandtag.rsanswer their own questions- The body's painters return cells, not strings:
ordered_cells,inline_cells,metadata_cells,metadata_value_cells,tag_cellsandpush_heading.content_trim_coloredis the CLI entry point andpaint_cellsis the only thing that writes an escape.colorize_lineis gone: it was apubalias for the bold pass with one caller, and the only thing it added was asking the terminal inline_cellswalks the line once for both inline markers,**bold**and[text](url), rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and\x1b[36mcarries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It wascolorize_boldwhile links lived in a branch of their own incontent_parts; that branch is gone, which is also what gives the criteria text and the metadataOtherrows their links, since those already went through this functionshowrenders the Metadata section as a two column table viametadata_cells, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width.paint()iscolor_text()with the colour decision passed in, which is what lets a test render both ways in one process- The title is printed once, by
cmd_show.content_trim_coloredskips the#heading in the file content - Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
resolve_ticket()scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filenameparse_ticket_field()handles extracting metadata values from markdown formatmove_ticket_file()stages the updated content in a temp file under.worklane/, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the nextmvcorrects- A move whose target equals the directory the file already sits in repairs a Status field that disagrees with it, instead of refusing as a no-op.
resolve_ticketreads the current status off the directory, so the old comparison was the directory agreeing with itself and could never see the field; a hand-moved file was stuck with moving it away and back to fix it. Now the field is compared first: agreement is the ordinary already-in-status report with nothing written, disagreement rewrites the field alone through the same in-place save every edit uses, and reports it as a correction rather than a move. It is gated on neither-fnor the dependency guards behind them, because it is not a transition; it writes no stamp, since presence still answers how far the work got and the work arrived nowhere new; and it logs nothing, because an entry shaped like a transition would record a journey the ticket never took. The mirror case is unchanged: a field ahead of its directory after a crash mid-move is corrected by the next realmv, because there the target is a status the ticket is not sitting in - Field lookup, read and write, is scoped to the lines under the
## Metadataheading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead.set_status_field()carries the same scoping
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
Git Workflow
- Commit format:
([ticketID]) [short description] - Use
--fixupfor incremental changes - Test before moving to reviewing status
Version Bumps
- Before every commit, decide whether the change warrants a version bump in
Cargo.toml - Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
make patch,make minorandmake majordo the mechanics, run after the commit is in: each bumpsCargo.tomland theworklaneentry inCargo.lock, appends, and bump to <version>to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-taggedHEADand on aHEADthat is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
- Changed output means the CLI's output. That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
- Settling output that shipped one version ago is a patch, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
- No bump for docs-only, tests-only or
--fixupcommits - When one body of work spans several commits, bump once on the final commit rather than on each
- Every bump gets a matching annotated tag,
v<version>, on the bump commit — a bumped version is never left untagged - Tag locally only; never push a tag unless asked
worklane --versionreports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another