Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 cbc20848f6 (1845355) Order each status column by its entry stamp, and bump to 0.23.0
Every view read its rows out of `collect_ticket_items`, which sorts by
`by_priority_then_title` because it sees one directory and no status. That
is the right order for the backlog, where priority is the clock. Past the
backlog the question changes: committed asks what has waited longest,
reviewing what was handed over first, done what just landed. All four
columns answering the first question is why a finished p5 sat above the p1
nobody had read yet.

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

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

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

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:58:34 +02:00

102 KiB
Raw Blame History

AGENTS.md

Project Structure

  • src/main.rs - dispatch, the SIGPIPE reset, and the TUI event loop
  • src/command.rs - CLI argument definitions using clap derive
  • src/completions.rs - the generated completion script and the fish half that asks the board
  • src/handlers.rs - one cmd_* per subcommand
  • src/util.rs - the ticket format, resolution, rendering and the palette
  • src/campaign.rs - the campaign file format, its resolution, its index and its members
  • src/tui.rs - board state, the change digest, and the ratatui draw
  • src/clipboard.rs - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
  • src/install.rs - the embedded agent assets and the compare-and-refuse install
  • assets/SKILL.md - the agent skill for the CLI itself, embedded with include_str!
  • assets/REVIEW.md - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; SKILL.md keeps its name because the role it teaches is the CLI
  • assets/PLAN.md - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
  • tests/ - Integration tests using assert_cmd and assert_fs, one file per command
  • Unit tests live beside the code in #[cfg(test)] mod tests, in util.rs, handlers.rs and tui.rs
  • Ticket files stored as .md in .worklane/<status>/ directories
  • Campaign files stored as .md in .worklane/campaigns/, which is beside the status directories and deliberately not in status_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 06 lands as <uuid>_ticket-06.md. Derive fixture filenames through slug(), never by hand
  • Metadata fields parsed by parse_ticket_field(): ID, Priority, Tags, Due, Owner, Created At, Committed On, Submitted On, Completed On, Campaign, Status. The last four are the ones no ticket is born with: add writes none of them, so they are inserted on demand, against METADATA_ORDER, which is also what keeps Status last
  • The three stamps are mv's, written by set_status_stamp from Status::stamp_field, and they accumulate: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status after the target. One arrival rule keyed off Status::ALL, not a case per move, which is why a backward move truncates the journey at the target (done back to reviewing drops Completed On, anything back to backlog drops all three) and a forward skip under -f stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with Created At, Committed On, Submitted On and Completed On side by side, so presence means got this far and has not been sent back past it, not is here now — Status is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. backlog has no stamp, Created At already answers for it
  • Each status column is ordered by its own entry stamp, through by_status_order. Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by Committed On ascending, reviewing by Submitted On ascending, and done by Completed On descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to by_priority_then_title. One function keyed on the Status, taken by both cmd_ls branches, list_ids, columns_of and campaign::members, which is why those loops walk Status::ALL rather than status_dirs(). The stamps are read in collect_ticket_items' existing pass, the rule criteria and tags already hold, and compared as strings: %Y-%m-%d %H:%M:%S is lexicographic in chronological order, the property Due already relies on, so nothing parses a date at sort time
  • Format: **Field Name**: value
  • Ticket structure: # Title → ## Description → ## Acceptance Criteria → ## Implementation Plan → ## Metadata
  • A campaign file carries ID, Codename, Owner and Created At, in that order, and no Status. Codename sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by campaign add --codename alone and is _Not set_ when the flag was not given. It is not in METADATA_ORDER, which is the anchor list for the upsert on a ticket, and nothing upserts a campaign
  • Comments stored in .worklane/comments/<ticket_uuid>/<timestamp>.md with **Comment**, **Author**, **Time** fields

Status Workflow

backlog → committed → reviewing → done

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_cmd and assert_fs for CLI testing

  • setup_worklane() creates temp .worklane/ with all four status folders pre-created, plus campaigns/ in cmd_campaign.rs, which is also where the on-demand creation is tested from a board without it

  • create_ticket() writes fully-formed markdown files directly (no -- separator for positional args in test commands)

  • In tui.rs, write_member_card is write_tagged_card plus a Campaign field and write_campaign puts 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_rows cuts the picker's list out of the frame by its own geometry, for the reason overlay_title_row exists: a card carries the same campaign label, so a search over every row finds the board rather than the list

  • cargo clippy --all-targets is clean. Keep it clean, and do not silence a lint that is pointing at something real. The only two allows in the tree sit on the create_ticket fixtures in cmd_mv.rs and cmd_show.rs, each carrying the reason and what would replace it

  • cargo fmt --check is clean too, and rustfmt.toml is 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_width 100 The tree's own habit, and the measured optimum: 90 costs 268 hunks and 120 costs 194, against 161 at 100
    fn_call_width 75 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_width 65 The same for a method chain
    struct_lit_width 30 A small struct literal stays whole, so Size { width: 120, height: 20 } is not six lines

    The 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-lining if/else and 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, with cargo 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 fmt on 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_strings is deliberately left at its default: turning it on would let the formatter rewrite message text, and a message is prose. So max_width is where rustfmt breaks lines, not a limit the tree keeps
    • The reformat is 73ffcad, and .git-blame-ignore-revs names it so git blame looks through it. Turn that on once per clone with git config blame.ignoreRevsFile .git-blame-ignore-revs. A commit belongs in that file only if its diff is pure layout

Coding Guidelines

Rust Style

  • Use if matches!(expr, Variant) instead of if let Some(Variant) = expr for enum variant matching
  • Use if let Some(x) = expr instead of if let Some(Some(x)) = expr — drop unnecessary nesting
  • Prefer explicit match over unwrap_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 Args struct, not an inline variant with a matching parameter list: AddArgs, SetArgs, AppendArgs, CheckArgs. add was nine positional parameters threaded from main before it became AddArgs, and the handler destructures the struct so the body reads the same as before

CLI Arguments

  • The prose arguments carry allow_hyphen_values, via the PROSE constant in command.rs: add --title, --description, --acceptance, --plan, and the comment body. Ticket text quotes flag names constantly, and without it a criterion reading --print is supported is 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, owner and status are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add PROSE to a new argument unless it holds prose
  • --due is validated at parse time by iso_date, the way --priority is by priority_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 without PROSE. One parser serves add and set: the field has one definition of what it accepts, and validating only add would leave set open, which is the command a grooming sweep actually uses
  • The shape is checked before chrono is asked. %Y-%m-%d accepts an unpadded 2026-8-9, which would be stored exactly as typed and sort before 2026-10-01 in 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_date still cuts 2026-12-31T09:30:00Z down 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 --due keeps 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 --codename is validated at parse time by codename, which is non_empty plus one word. The board draws it as a label with a mark and no quoting, so ~beaver release on 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 reason ls --tag refuses 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_empty says only that the value cannot be empty, for the arguments with no empty form: the ls filters, relate's targets, and set --title, which addresses the ticket and names its file. clearable names --clear, for the arguments whose field does have one: set --tags, --due through iso_date, and the chown user. One message for both would either lie about ls --tag or leave the useful half unsaid. add --due takes the second one because iso_date is 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 --status and the ls positional 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 --due and --priority take, and it is what lets the shells complete the four for free. Status::ALL is the flow order, which status_dirs() and cmd_mv both read rather than spelling the names again, and DONE is 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 in mv --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 a comment body 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
  • add has no positionals, so anything after a bare -- is an unexpected argument and fails
  • A paragraph break in a description is an empty --description value. cmd_add joins 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
  • --acceptance and --plan are lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only --description preserves blanks

Completions

  • Two halves, and the split is the point. clap_complete generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching completions.rs. Only fish gets the second half, appended by fish_dynamic(), and it holds exactly what clap cannot know: the tickets on the board
  • The dynamic values come from worklane itself, as worklane ls --ids in 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 --ids completes 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 the ls status and the completions shell are listed in the fish half. Both lists are read off the enums with possible_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, because campaign ls and campaign show are also an ls and a show that fish has seen, and because matching against the ticket list would run worklane again inside the condition. first_arg_of and second_arg_of count a top-level command's arguments, nested_arg_of matches a parent and a child so campaign show <TAB> can be told from chown alice <TAB>, which sit at the same token count, and command_is asks only which command this is, at any position in it
  • Every rule carrying -l needs a __worklane_command_is, and every_rule_naming_an_option_is_scoped_to_a_command is what enforces it. A bare complete -c worklane -l tag does not just complete that option's values, it tells fish the whole tool accepts --tag: worklane init --<TAB> offered six options that only relate and ls have. Fixed in 55ee6e3. __fish_seen_subcommand_from ls is 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_COMMANDS and TICKET_SECOND_COMMANDS by position, TICKET_FLAGS, CAMPAIGN_COMMANDS, CAMPAIGN_NESTED_COMMANDS, CAMPAIGN_FLAGS and TAG_FLAGS likewise. 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 of campaign show and campaign set, and ls --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 --ids is 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 reads cut -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 --campaign is still refused
  • campaign ls --ids is 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 candidates
  • worklane tags is the third, and it is a command rather than a mode on ls. 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 --tags beside a --tag is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so bug and Bug list 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.md used to tell the agent to count tags with a show per ticket, and now points here

Filtering the Listing

  • The filters are one call, filtered, because ls collects 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 an Option and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair
  • --tag matches whole values, not the field. parse_tags has already split the comma-separated field, so the filter compares against those trimmed values: --tag bug is not answered by a ticket tagged bugfix, 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_color draws Bug and bug in 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.md tells the agent to check the spelling when a listing comes back empty, and worklane tags is what it checks against, since that is the failure this trades for
  • An emptied status keeps the message ls already gives, No tickets in '<status>' status., rather than one per filter naming what excluded them. That is pre-existing behaviour for --priority and --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_ls takes an LsArgs, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent Option<String> values a caller could swap silently. --ids was the argument that tipped it, the way add became AddArgs. A new filter is a field there, not a parameter

Editing a Ticket

  • set replaces a field, append adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and append only offers the sections that hold multiple lines
  • One field, one writer. set has no --owner (that is chown's) and no --status (that is mv's), and neither add, set, append nor chown can reach the three status stamps, which mv writes as a side effect of the move. Do not add any of them
  • chown takes the user first and the ticket second, after Unix chown, 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 to resolve_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 username
  • cmd_chown is set_metadata_field plus save_ticket, with the same whole-file no-op comparison set uses and the same report() output, so nothing about writing a field lives twice
  • apply() is the one place an edit is taken or dropped, shared by set'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 placeholder add writes when empty, a SectionKind and the --clear value 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 ## Notes section 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_empty and clearable in command.rs. Neither spells clearing, and both errors name the flag that does

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 likes
  • Clearable is a ValueEnum in util.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, Tags and Priority clear to a sentinel, Description, Acceptance and Plan to their section's placeholder. Title is absent because it addresses the ticket and names its file, so there is no state to go back to; Owner, Status, Campaign and the stamps because clearing them through set is exactly the second writer the missing set --owner exists to prevent
  • What is written is NOT_SET and NONE, the constants add writes. 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_fields compares 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_body runs its items through Section::render, which would write - [ ] _No acceptance criteria provided._. Both are replace_section_body underneath, so the line surgery and the trailing blank line live once
  • The pairing between a section and its --clear value is stored on both, Clearable::unset one way and Section::clear the 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_it keeps the two directions from drifting. RELATIONS.clear is None, the same rule that keeps it out of section_args
  • Cleared fields are reported apart from replaced ones, as Cleared due on '...' beside Updated priority on '...'. One list would say Updated of a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the ones set already 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 --clear carries the ticket. Owner has one writer and clearing it cannot introduce a second, so it lives on chown; but the ticket is chown'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::target returns 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. add falls 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 title
  • write_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

  • check and uncheck are separate commands, not one verb with a flag. They share CheckArgs and cmd_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 number
  • set_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 all first, an index second, a substring third. So a criterion whose text is literally 2 is reachable only by substring, and one whose text merely contains "all" only by its number or a longer substring. is_all_criteria() and is_index() sit beside each other in util.rs for that reason
  • The keyword wins over the text on purpose. Ticking every box is the reason the word is typed, and a board where all sometimes 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_text pins 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_ticket makes 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 --acceptance does. 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 both all and 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 reads Already checked 2: text and 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 against show
  • show numbers the criteria as 1. [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. RELATIONS is in the section table but deliberately out of section_args, so set and append cannot 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
  • add does 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 every show, 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 ls prints. It resolves without a scan and cannot turn ambiguous as the board grows. show renders 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 by goes on the gated ticket rather than blocks on the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency. relates to is symmetric and is written once, on whichever end the caller ran it from. RelationIndex::inbound finds the far end by scanning, which is what keeps relate a single-file write
  • A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but relate writes there, so a bad line means a hand-edited file. The TUI is the deliberate exception: detail_of falls back to no block, since one corrupt ticket must not take the whole board down
  • The block is built outside content_trim and passed in. Half of it comes from other tickets and content_trim has 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_section inserts against SECTION_ORDER, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten ## Notes between 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. -f now 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 Standing from the members. A Status field 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 no campaign mv and no forward-only ruleset beside mv's
  • A campaign with no members is neither open nor done. Standing::state() returns None there, and both callers print no 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, Campaign in the ticket Metadata, written only by assign. 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. So add has no --campaign and set has 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_cell is shared between the two, so a dangling campaign and a dangling relation target are both spelled _missing_ rather than each inventing a spelling
  • add does not write the field. Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of add means one path that is always exercised rather than two. Same reasoning as the Relations section
  • set_or_insert_metadata_field() is the upsert, and METADATA_ORDER is its anchor list, the way SECTION_ORDER is ensure_section's. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no ## Metadata heading 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.dir is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
  • An exact Codename is the top tier, and it lives in the shared resolver rather than in a campaign-only path. Only campaigns carry the field, so parse_codename returns None for every ticket and the tier is always empty for one: ticket resolution is unchanged, which a_ticket_search_is_unaffected_by_the_codename_tier pins. 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 like v1 is below MIN_ID_SEARCH and would never be tried as an id at all. A codename that a title also contains, v2 against v2 release, has to win outright rather than be reported ambiguous against it
  • resolve_ticket explains a search that names a campaign, rather than each command doing it. One place, so mv, show, chown and 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 mentioned
  • Resolved carries what content_trim cannot 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 site
  • campaign show lists done members, unlike ls, 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 --campaign is the other way round: it is the ordinary board filtered, and keeps every rule ls already has
  • campaign ls scans 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 c for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in columns_of and is what names the label; see The Board View
  • A campaign is named by its codename on the board, and by its short id when it has none. The uuid does not fit on a card and the title is a sentence, which is the gap Codename fills. campaign_label builds it in one place, as a Cell, so the CLI paints it and the board makes a span of it; the mark is CAMPAIGN_MARK, ~, beside # for a tag
  • campaign set is the only writer of a filed campaign's fields, and it carries the two scalars. d637288 decided it: a set rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. --title, which renames the file the way set --title does, and --codename. campaign add writing a field at creation is not a second writer, exactly as add --title and set --title coexist
  • Replacing a codename the campaign already has needs --force. Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake install-skill --force exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like SetArgs::contested, so a call also carrying --title writes neither field. Setting the codename a campaign already carries stays a no-op, not a refusal — --force is about overwriting a different word, which is the same division install::Outcome draws between Unchanged and Refused. --force guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
  • No campaign set --description, and that is the line, not an oversight. set and append are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line append already draws for a ticket. campaign_set_offers_no_description_and_no_owner pins it. No --owner either, because nothing writes a campaign's Owner today and giving set one would settle by accident whether chown grows a campaign; and no --clear, because a wrong codename is replaced rather than emptied and Clearable is SetArgs's, its variants being a ticket's fields
  • The codename is written through set_or_insert_metadata_field, not set_metadata_field. Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts assign on the upsert. Codename is therefore in METADATA_ORDER, directly after ID, so an inserted one lands where campaign_body writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
  • One write path for tickets and campaigns. save_entry is the body, save_ticket and save_campaign are the named wrappers, and write_then_replace and find_entry_file take the noun as a &str so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, <uuid>_<slug>.md in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
  • campaign_body() builds the file from DESCRIPTION and METADATA_HEADING rather 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 init and on demand by campaign add, since every board made before campaigns existed has none and a worklane init over 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.md teaches 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
  • worklane with no subcommand and worklane tui both open it, the way a bare frig does. Cli::command is therefore an Option
  • 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
  • notify is 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 source ls uses, so there is no second parser. TicketItem::path exists for the detail view
  • The detail view scrolls on pgup and pgdn, 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 scroll offset is clamped against the wrapped line count, from Paragraph::line_count, which is why ratatui carries the unstable-rendered-line-info feature. 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_bottom with a right-aligned Line, 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_height is the one measurement. last_offset is it less the viewport and page_indicator takes the same two numbers, so the clamp and the indicator cannot disagree. A second line_count call, 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 + 1 reads pg 2/3 at 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 pages pgdn can land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport at pg 3/3 two 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_indicator takes four numbers and returns an Option<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::offsets holds one offset per column, parallel to columns and resized in step by reload, so a column you leave stays where it was. The keypress aligns the focused column via follow_selection(screen), taking the screen size for the same reason scroll_detail does: 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 the starts vec 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 ↑↓ scroll when 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
  • q and esc are one key: close what is open, quit when there is nothing left to close. q used to set should_quit outright, so a reader who pressed it to put a ticket away lost the board instead, which is not what q does anywhere else that lays a document over a list. One match arm in main.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 in main.rs is 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_quitting scans main.rs for 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 saying q quit there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
  • The overlay names its ticket on the border, not at the head of the paragraph. Board::detail is a Detail carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: content_trim drops the # heading on purpose, since cmd_show prints it, and anything in the paragraph scrolls away
  • detail_title cuts 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 with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. content_trim and format_comments_with take the colour decision for that reason
  • 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, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both 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_lines and card_height both take it. column_areas is shared between the draw and follow_selection for the same reason: Ratio hands 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
  • The criteria count is a field on TicketItem, filled in collect_ticket_items where the file is already being read, and counted through criteria() so a checkbox in a description is not counted here or numbered by show. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. None rather than [0/0] for a ticket with no criteria
  • A card names its campaign on the label row, before the tags, in bold. labels_line draws 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 order corner_line and project_label already 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::campaign is a resolved Cell, not a uuid, settled at reload the way project and blocked are. TicketItem::campaign already carries the uuid off the pass that builds the card; the name is in another directory, so columns_of reads CampaignIndex once per project and hands it to every card. Never per draw, the rule criteria and tags already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries blocked: 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_blocked gives a dangling blocker. campaign_cell renders that case as _missing_ because a metadata table is a place to report a dangling reference; a card is not
  • c opens 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 four statuses with fewer cards in them, which is what campaign show already answers the question in. Every column is kept, empty ones included. The filter is applied in reload, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and first_match, done_count and the copy key all keep working unchanged
  • Tab::campaign is a uuid on the tab, not on the Board. 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 by reload rather than left filtering the board to nothing
  • The frame above the columns is three rows, and Chrome is what every measurement takes. frame_rows grew a row, so the two bools that decide the geometry became one Chrome, copied from Board::chrome: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and follow_selection have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (TAB_ROW, CAMPAIGN_ROW, BOARD_ROW, FOOTER_ROW), since an index written out by hand goes on meaning what it used to
  • 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 · Name on the top one, the standing on the bottom right, and q board on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards
  • 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::standing counts what is already in hand rather than paying what campaign ls pays 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 board sits 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
  • c is named in the footer only on a closed board with nothing selected, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. 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
  • picker: Option<Picker> is the whole mode, the shape search and detail use, and Board::picker_key runs beside search_key ahead of the action arms for the same reason: an open list owns the keyboard, so d must not toggle done and q must not quit while a campaign is being chosen. ctrl-c is the one key it declines and every other control combination is swallowed, or ctrl-d would reach the arm bound to d
  • 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, so c on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a Notice rather than an empty box that has to be dismissed to learn it was empty
  • 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
  • q takes off one layer at a time, in the order they were put on: the overlay, then the campaign filter, then the board. Board::dismiss holds 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 ticket
  • digest watches the campaigns directory as well as the statuses and the comments. 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 tagged bug without 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
  • tags is a field on TicketItem, filled in collect_ticket_items through parse_tags, for the reason the criteria count is. parse_tags splits the comma-separated field into whole trimmed values, so a caller asking for bug is not answered by bugfix, 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 in util.rs and 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
  • blocked is on Card, not on TicketItem. The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way project is. What collect_ticket_items fills is the ticket's own uuid and its blockers, both read off the file it is already holding; mark_blocked then walks the four 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 mv already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception detail_of makes for the same reason: show and mv are 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. relate resolves 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_label takes 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_column pins it
  • due_date cuts 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"
  • Done is hidden until d asks for it. Not a new opinion: ls already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line
  • Hiding is a change to what is drawn, never to what is read. reload still scans the done directory and digest still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan
  • visible() returns a prefix of columns, not a filter, which is what keeps column and offsets valid as indices into either. It is derived from where DONE actually sits rather than assuming the last slot, and the_done_column_is_last pins the assumption. A status inserted after done 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 done again 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() and footer() exist so the next one does not. headings() locates the row through board_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 shape detail uses: "the prompt is open" and "what is in it" cannot disagree, and closing it leaves nothing to reset. Search also carries missed, 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_key runs ahead of the action arms in main.rs and reports what it took, rather than every arm below asking whether a search is open. Typing d into a query must not toggle done and q must not quit; with no prompt open it takes nothing, so the dispatch is unchanged for every other state. The rule is on Board for the reason dismiss is: the arm is not reachable from a test
  • ctrl-c is 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 and ctrl-d would reach the one bound to d
  • Esc is consumed by the search before it can mean anything else, which is the collision e7612de left behind: esc and q close 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_match searches 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 tail select_card already used. follow_selection scrolls the column the card is in, and the offsets are per column and on the Tab, so a jump across columns moves the right one; refresh_detail keeps 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. The typed query is drawn in the default foreground and the keys in grey: one is content, the other is chrome. no match is brightred beside the query it is about, since grey chrome is what a reader skips
  • 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_position is 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: n and N for 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

  • y copies 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. y reads 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, d and / 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 (arboard and 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 to wl-copy, xclip or pbcopy is 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. What clipboard::copy reports 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
  • c and not p: 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 what show, mv and comment all resolve. Decided by Board::copy_text rather than inside the arm that copies, so the string is a question the suite can ask without a clipboard. None on 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_id as an argument, clipboard::copy from 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
  • Notice is the board's one channel for saying something in words, since a copy leaves nothing on screen to look at. failed means "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 reason no match is
  • 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_notice runs ahead of search_key as well as the arms, since a key typed into a query is still a key, and it must never move into tick: the board redraws four times a second and a notice cleared there would never be read

The Relations Block

  • One builder, two painters. relation_rows decides which edges there are, what they are called and which direction comes first; relation_cells decides the layout, the mark and the colours; paint_cells turns cells into escapes for the CLI and span_of turns 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
  • Cell is the unit both renderers take: a run of text and the colour it is drawn in, None for the default foreground. The same trick as the palette itself, where Color::ansi() and From<Color> for ratatui::style::Color keep one colour from existing for one renderer and not the other
  • reference_cells is the one spelling of a cross reference, and reference_cell is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
  • 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 by and blocks are 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_mark pins it
  • × is BLOCKED_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 in util.rs for that reason, not in tui.rs where the card is
  • The kind marks stay out of the priority vocabulary, which owns ●◐○·, and no_relation_mark_is_a_priority_glyph pins 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_two pins 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_colors is false and both read as under way. Accepted, because ● and ○ are the two answers usually wanted and show on the target settles the rest, and assets/SKILL.md says 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
  • RelationTarget carries the title and the status in one Option, 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 way
  • show and 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 minor
  • Resolved.relations is rows, not a rendered block. That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. content_parts hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
  • BodyPart splits the body rather than building it twice. Everything outside the relations block is rendered once, by content_parts; content_trim is that with the rows painted, and the board is that with the rows styled. Body is the accumulator, so a caller pushes text and rows without tracking which it pushed last
  • Detail.body is a Text, and it is the only thing measured. last_offset and the Paragraph both 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 disagree
  • detail_body closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
  • The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight. The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by show and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in content_parts the Cell treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not

Monitoring Several Boards

  • worklane tui <path>... takes any number of paths, each resolved through find_worklane_dir the way the working directory is: the first .worklane at or above it. No path is the working directory, so a bare worklane and worklane tui are unchanged
  • The failure names the path that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare worklane has no path to name and keeps the message every other command gives, which is what its integration test asserts
  • Two paths inside one project resolve to the same .worklane and are monitored once. projects() dedupes on the resolved directory, not on the argument
  • Tab owns the selection, column, card and offsets, not Board. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. Board::current() is the tab in view, and show_done stays on the board because it is a preference about the flow rather than about a project
  • The tabs are fixed for the run: a project cannot be added or dropped without restarting, so Board::new builds the tab list once and reload only refills each tab's columns. reload clamps every tab, and select_tab clamps again on arrival, because done may have been hidden while another tab was in view
  • The merge tab goes first and is where the view opens: it is the reason to monitor several boards at once. It is materialised in reload, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in collect_ticket_items
  • The merge is sorted, through by_priority_then_title in util.rs, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes by_status_order: the merge spans statuses, so no single entry stamp governs it
  • Card wraps a TicketItem with the project it came from, Some only on the merge tab. Decided at reload rather than passed down to card_lines as a "which tab is this" flag. TicketItem is therefore Clone: the merge holds a second copy rather than re-reading every tree
  • The project follows the id, on the card and on the overlay border. Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. project_label takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what corner_line drops
  • tab and shift+tab cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took hjkl and the arrows
  • The tab row is drawn only when there is more than one board, so a single board is the view it has always been. frame_rows() gives it Length(0) otherwise, which keeps the row indices the same for both cases and is shared with card_width and column_text_height for the reason column_areas is: geometry reproduced by hand drifts from the draw
  • digest_of hashes each board's digest into one value, so a change in any of them redraws. Do not watch only the first

Shipping the Agent Assets

  • The skill is embedded with include_str! from assets/SKILL.md, not copied by an install script. cargo install places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
  • One install path serves both agents: ~/.claude/skills/worklane/SKILL.md. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own ~/.config/opencode/skill/. Verified against opencode 1.15.10, whose built-in customize-opencode skill documents the table and whose opencode debug skill lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
  • Asset carries the content, the path under its root and the word used in messages, so install-tool adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is install.rs and not skill.rs
  • install() takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects HOME for the same reason
  • A modified copy is refused, not overwritten. Someone may have edited it on purpose, and the message names --print so it can be diffed and --force so it can be replaced. A read error is not treated as absent either: the write reports the real reason
  • Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every worklane <x> the skill shows has to be a real subcommand, and every subcommand outside NOT_FOR_AGENTS has to appear in the skill. The last one catches a new command that nothing tells an agent about
  • install-skill looks for no board. The skill is what teaches an agent worklane, so needing a .worklane to install it would put it out of reach exactly when it is wanted
  • The assets under .opencode/ are the user's, not this repo's to ship. Do not embed or install them. reviewing-agent.md there is the prior art the review skill grew out of and is deliberately left in place: its content is now in assets/REVIEW.md, but deleting a file under .opencode/ is not this repo's call. Whether the stale copies there go is b2c5531's question
  • install-skill writes every shipped document, and the name narrows it. One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog
  • --print requires the name. It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the comment -- body makes
  • The refusal message names the document it is about, install-skill worklane --print, since with several installed "compare with --print" does not say compare what
  • 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 the worklane skill 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 (mv belongs to whoever does the work, the reviewer's half is the recommendation), and never reviews the working tree when no commit names the ticket (it says what it searched for and stops, since an untraceable ticket in reviewing is itself the finding)
  • The plan skill is the one that can do damage, so its rules are the ones under test. set --tags replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. the_plan_skill_keeps_the_rules_that_bound_a_sweep pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
  • .opencode/agent/feature-planner-agent.md is deliberately not folded into PLAN.md. It decomposes a feature request into new tickets, which is intake; PLAN.md orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
  • every_agent_facing_subcommand_is_documented stays on SKILL alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with init and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist

Color and Output

  • Use color_text() for coloured output — it respects should_use_colors() (terminal detection), and paint() is the same with the decision passed in
  • color_text() is for the CLI's own printing only. Anything reachable from content_trim takes the decision as an argument and calls paint(), 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_decision scans this file and fails on a new caller; the allowlist is ambiguous, which builds a failed-search message for stderr
  • A function that takes an enabled flag must use it all the way down. colorize_bold honoured its flag on the early return and then asked should_use_colors() for the bold run, which made the flag a lie in half the function
  • 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 now content_trim(.., false) has no escape and content_trim(.., true) still colours, which pins the flag as the only thing that decides
  • The palette is the Color enum, not a string. Color::ansi() gives the CLI its SGR sequence and From<Color> for ratatui::style::Color gives 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 how magenta came to be undefined
  • Reset color with \x1b[0m after 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 in main, restoring the default SIGPIPE disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making println! panic. Do not wrap prints to handle write errors and do not reinstate SIG_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 ? for a target the board does not hold. 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
  • Chrome → grey. The footer's key names, a rendered [ ], and the overlay's page indicator. 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
  • 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 because tag_color is 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. Codename in 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_COLORS slot 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 in TAG_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, because Bug and bug are 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_pinned fails 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, bug and BUG among 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;8m is byte for byte what crossterm emits for ratatui's Color::DarkGray, the grey frig and pantop use for dimmed rows

Code Organization

  • Colorization functions (colorize_ordered, colorize_bold, content_trim_colored) handle markdown formatting. colorize_line is gone: it was a pub alias for colorize_bold with one caller, and the only thing it added was asking the terminal
  • show renders the Metadata section as a two column table via render_metadata_table, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. paint() is color_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_colored skips 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 filename
  • parse_ticket_field() handles extracting metadata values from markdown format
  • move_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 next mv corrects
  • Field lookup, read and write, is scoped to the lines under the ## Metadata heading 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: ls prints SHORT_ID_WIDTH (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so show 641 is a title search
  • The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
  • Ambiguous matches (multiple results) print options and exit(1)
  • Never return empty strings for required fields — use the NOT_SET and NONE constants in util.rs, which are what add writes and what --clear puts back. is_unknown_value reads those two and nothing else
  • -None- and -Not set- are not unset, and re-adding them would be a mistake with a plausible story behind it. They were accepted by is_unknown_value from the day it was written, by analogy with the **-Status** field name the mv splicing bug really did produce, c230d2c. But no version of this tool ever wrote a hyphenated value: git log -S finds both spellings in exactly one commit, the one that added them to the check. Dead from birth, and dropped by bdddc09. a_hyphenated_marker_is_not_unset is what stops the analogy being drawn a second time
  • The **-Status** repair in is_status_line is the opposite case and stays. That corruption was real, mv wrote it, and the repair is what fixes a damaged ticket as it moves. Do not tidy the two away together on the grounds that they look alike

Git Workflow

  • Commit format: ([ticketID]) [short description]
  • Use --fixup for 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
  • 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 --fixup commits
  • When one body of work spans several commits, bump once on the final commit rather than on each
  • Bump Cargo.toml and the worklane entry in Cargo.lock together, in the commit that carries the bump
  • 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 --version reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another