Files
worklane/AGENTS.md
T

196 KiB
Raw Blame History

AGENTS.md

Project Structure

  • src/main.rs - dispatch, the one mapping from a parsed command to its handler, 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/history.rs - the history log: the path, the kinds, the reader, the writer, the card's counter and the block show and the board both render
  • src/board.rs - the shared-board layout: the machine config, the boards directory, the .worklane.toml pointer and the init decision table that decides which layout a project is on
  • src/tui.rs - board state, the change digest, and the ratatui draw
  • src/split.rs - one pure function turning a typed line into arguments the way a shell does, plus what the half-typed line is still inside and where the cursor sits among them
  • 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
  • assets/ADMIN.md - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against PLAN.md in both directions: this one decides the vocabulary, that one applies it
  • assets/TOOL.ts - the opencode tool definitions wrapping the CLI, embedded the same way and installed by install-tool. The only asset that is not a document and the only one that reaches a single agent
  • 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, history.rs and tui.rs
  • Ticket files stored as .md in .worklane/<status>/ directories
  • History entries stored as .md in .worklane/history/<ticket_uuid>/, one file per entry, beside the status directories for the reason campaigns are
  • 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, Discarded On, Campaign, Status. The last five are the ones no ticket is born with: add writes none of them, so they are inserted on demand, against METADATA_ORDER, which is also what keeps Status last
  • The four stamps are mv's, written by set_status_stamp from Status::stamp_field, and they accumulate: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status after the target. One arrival rule keyed off Status::ALL, not a case per move, which is why a backward move truncates the journey at the target (done back to reviewing drops Completed On, anything back to backlog drops all three) and a forward skip under -f stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with Created At, Committed On, Submitted On and Completed On side by side, so presence means got this far and has not been sent back past it, not is here now — Status is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. backlog has no stamp, Created At already answers for it
  • Discarded is last in Status::ALL, and that placement is what makes the stamp rule fall out right. Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps Committed On and Submitted On, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs -f without a rule of its own. Discarded On is its stamp, and Completed On stays untouched, because a discarded ticket was never done
  • Each status column is ordered by its own date, through by_status_order. Past the backlog that date is the entry stamp, so committed sorts by Committed On ascending, reviewing by Submitted On ascending, and done and discarded by their stamp descending. The backlog has no stamp of its own, so it sorts by Due ascending, through TicketItem::due_key. Said once: the head of every column is what the reader acts on next, and in the backlog that is the nearest deadline rather than the loudest priority — priority alone sat a p1 nobody had promised above a p3 due tomorrow. A ticket carrying no date sinks below every dated one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal dates and both-undated fall through to by_priority_then_title, which is still the whole order among undated backlog tickets. One function keyed on the Status, taken by both cmd_ls branches, list_ids, columns_of and campaign::members, which is why those loops walk Status::ALL rather than status_dirs(). The dates are read in collect_ticket_items' existing pass, the rule criteria and tags already hold, and compared as strings: %Y-%m-%d %H:%M:%S and %Y-%m-%d are both lexicographic in chronological order, so nothing parses a date at sort time. due_key answers None for a Due that is not a plain YYYY-MM-DD after due_date has cut a legacy datetime back — free text is unknown, not a date, and sorting on its spelling would rank it against real deadlines
  • Format: **Field Name**: value
  • Ticket structure: # Title → ## Description → ## Acceptance Criteria → ## Implementation Plan → ## Metadata
  • A campaign file carries ID, Codename, Owner and Created At, in that order, and no Status. Codename sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by campaign add --codename alone and is _Not set_ when the flag was not given. It is not in METADATA_ORDER, which is the anchor list for the upsert on a ticket, and nothing upserts a campaign
  • History entries stored in .worklane/history/<ticket_uuid>/<stamp>_<kind>.md, with the kind's marker (**Comment**, **Status**, **Owner**, **Tags**, **Campaign**), then the body, then **Author** and **Time**. See The History Log

Status Workflow

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

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

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.

Shared Boards

  • A project's board is on one of two layouts, and src/board.rs is the whole of the second one. The local layout is the .worklane directory a project has always had. The shared layout answers .worklane being gitignored and not a git repo so a clone elsewhere has no board: the project commits a .worklane.toml naming its board by uuid, one boards repo is cloned once per machine, and .worklane in the project becomes a symlink into it. The symlink is the point: with no .worklane directory cat .worklane/backlog/*.md and ls .worklane/reviewing would stop working, and that is the belief the whole file format exists to serve. Because the link is transparent, find_worklane_dir gains no resolution code at all (c6a61b4 AC 14).
  • The machine config lives at $XDG_CONFIG_HOME/worklane/config.toml (default ~/.config, empty counts as unset). It carries a [boards] section holding the url of the boards repo and an optional dir overriding where the boards directory sits — the config is this machine's answer, and the pointer carries no server address, so a client repo never holds an internal hostname. The boards directory itself defaults to $XDG_DATA_HOME/worklane/boards (~/.local/share without it).
  • The pointer is .worklane.toml, committed at the project root: [worklane] board = "<uuid>", and nothing else. Read and written by read_pointer / write_pointer. write_pointer leaves a pointer that already names the same board alone — it is a committed file and rewriting it writes nothing new, which is what keeps "init symlinks it and creates nothing" true for a fresh clone.
  • A board directory is <uuid>_<slug>, named after the ticket files. The slug is util::slug of the project's directory name, and resolution (resolve_board) is a uuid prefix match, the bargain the ticket filenames already make: the directory stays readable to ls, identity is stable, and renaming a board breaks no committed pointer.
  • The decision table is decide_init, one match. The reason it is a table rather than a fallback is that no branch may fall through into creating a board, so each row returns its own outcome. The rows:
    • no pointer, no [boards] config → local .worklane, exactly as init always made it (AC 12);
    • no pointer, config present → create the board, write the pointer, symlink .worklane to it (AC 4);
    • pointer present, board found → symlink it and create nothing (AC 5);
    • pointer present, board absent → refuse. A committed pointer is proof the board exists somewhere, so a missing board is an unsynced machine, and creating a second board there produces two boards with one name and a manual merge — the worst outcome in the design. The refusal says so and names init --create as the only way to make one (AC 6/7). The fetch-and-look-again half of the ticket is deferred: nothing pulls the boards repo yet, and the refusal names it rather than doing it. --create is the create field on Command::Init, the escape hatch under that row;
    • the boards directory itself missing → a distinct refusal saying the boards repo is not cloned here (AC 8);
    • the correct symlink already in place → no change, nothing written (AC 9);
    • a symlink to a different board → refuse rather than repoint it: changing what a project is on without asking is how two machines come to disagree about the work (AC 10);
    • a symlink that dangles → refuse rather than replace it without asking;
    • a real .worklane directory under a pointer → refuse and name the adopt path (aa80db4), never walk over it (AC 11).
  • The three symlink states are told apart by classify_worklane: Absent, RealDir, Symlink, Dangling and NotADirectory. The Symlink comparison is canonicalized, the Dangling one is lexical (a dangling link cannot be canonicalized) and checks for the relative spelling this tool writes or the absolute board path.
  • The symlink target is relative to the link's own parent, so it uses no home directory path and the link is portable in that limited sense; an absolute target appearing anywhere is how a home directory leaks into a write. Because a relative target depends on how deep a repo sits, init still runs once per project per machine, which is the price of transparent access.
  • Everything under .worklane is layout-agnostic. create_board_contents makes the same status directories, campaigns/ and tags.md for a local and a shared board, and every reader below find_worklane_dir works through the link unchanged.

Testing

  • Run make check before committing: cargo fmt --check, then cargo clippy --all-targets -- -D warnings, then cargo test, cheapest first. That is the whole of the enforcement, and it is deliberate rather than a stopgap: this repo has no CI and does not want any, and a git hook is a per-clone opt-in the way blame.ignoreRevsFile is, so neither can be relied on. What was missing was one name to type, so the two rules below are a command and not a memory. -D warnings is what makes clippy's opinion an exit code; a warning printed into a wall of cargo output is unread, not clean. The completion checks are inside cargo test rather than a target of their own, since a second thing to remember is the problem this solves

  • Run one suite: cargo test

  • Tests use assert_cmd and assert_fs for CLI testing

  • setup_worklane() creates temp .worklane/ with the four flow 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. The fixtures deliberately do not create discarded/, so every discard test runs against a board that predates the status and mv_creates_the_discarded_directory_on_a_board_that_predates_it is not the only thing exercising the on-demand creation

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

  • Every unit-test fixture directory goes through util::Fixture, and nothing calls remove_dir_all at the end of a test. Fixture::new(prefix) makes a uuid-named directory under the system temp dir and its Drop removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: /tmp reached 18363 of these and filled the disk, failing a link step and then a git add with "No space left on device", an error naming neither the tests nor what they left behind

  • Fixture derefs to Path and also implements AsRef<Path>, because the two reach different call sites: a parameter typed &Path is a coercion site and one bound by impl AsRef<Path> is not. Fixture::child(name) points the fixture at a directory inside itself while still removing the parent, which is the tree project_tree needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than assert_fs::TempDir — that names its directories .tmpXXXXXX, which says nothing about whose they are

  • WORKLANE_KEEP_FIXTURES=1 cargo test keeps the fixtures and prints each path. Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and Fixture::swept() turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment

  • Verify a claim about leaked fixtures against a clean temp dir, not against /tmp. TMPDIR=/tmp/scratch cargo test then count what is left in it: /tmp still holds the historical leak, so counting there measures the past rather than the change

  • 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, and make check is what says so. 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, make check runs it first, 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, MvArgs. 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. mv was the last inline variant to carry an --actor, and --actor-from-git pushed its list past the line

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. append --tags is the one place the field has an empty form and the argument still takes non_empty: append has no --clear of its own, so naming one would send the caller looking on this command for a flag that is set's
  • 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 strongest completion check loads the script into fish and asks it for candidates. fish_offers_the_commands_the_statuses_and_the_values in tests/cmd_completions.rs sources the generated script into a throwaway shell standing in a real board, with this build's directory on the front of PATH, and compares complete -C against the ticket and the tag it put there. Every other test in the file reads the script as text, which cannot tell a rule that fires from one whose condition stopped matching, and that is how a completion actually breaks. Assert the values, not the flag names: clap emits every option's name on its own, so --tags and --blocked-by are offered with every hand-written rule deleted; what the dynamic half adds is what comes after the flag. Two traps, both paid for once: the shell must have fish_complete_path emptied, or complete -C autoloads ~/.config/fish/completions/worklane.fish and answers from whatever version wrote that, which is a guard that cannot fail; and the script is written beside the board rather than in it, since a rule that fires nothing falls back to listing the directory
  • fish --no-execute is the floor under that, not an oracle. It catches a script that does not parse, quotes still open at the end of the file or an unclosed block. Measured, not assumed: an apostrophe interpolated into a -d description partway down re-balances against the next quote and parses, corrupting every rule in between while the check passes; the same apostrophe in the last rule reaches the end unbalanced and is caught. Only fish gets this, because only fish gets a hand-written half
  • The rule counts in the completion tests are hardcoded on purpose. The walkers go clap → list and never see an entry naming something that does not exist, so a bogus pair in TAG_FLAGS is caught by every_tag_rule_takes_the_annotation_as_its_description counting one rule too many. Deriving that number from the lists it checks would grow with the bogus entry and pass. The seen totals in the walkers are hardcoded for the mirror reason, and both carry the note
  • 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 last against the test-local TAG_LIST_FLAGS and TAG_NEW_COMMANDS for the tag arguments that deliberately get no rule. 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
  • TAG_FLAGS holds pairs where the others hold names, because the two options that take one tag are spelled differently: ls --tag filters on one and append --tags adds them, so a single rule naming both would tell fish that each command accepts the other's flag. One rule per pair, generated in fish_dynamic. add --tags and set --tags are in the test's TAG_LIST_FLAGS instead and get no rule: they take the whole list, so the token at the cursor is bug,tui and fish replaces a token entire, which would throw away what is already typed. The test walks both tag and tags, so the next one has to say which of the two it is
  • 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
  • A call whose values are every one blank is refused, by replaced_items for set and appended_items for append. The check is the section's rather than the object's, so campaign set --description shares it. What differs is the way out, which is why replaced_items takes it as an argument: a ticket's section is emptied with --clear <field> and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two

Clearing a Field

  • set --clear <field> is the one way to take a value away, and it is a flag with the field as its value. Not a per-field --clear-due, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it 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
  • relate --clear <kind> <target> is the removal, and it is on relate rather than on set for the same reason the section is absent from section_args: one writer owns both directions, the way chown owns setting an owner and clearing one. It names the target and not just the kind, because a ticket can hold several relations of one kind and emptying all of them is not what anybody is asking for. That is also why it is not spelled like set --clear, which names a field and empties the whole of it
  • The two values are one flag, so clap cannot type them apart. num_args = 2 is per occurrence, which is what makes an odd number a usage error and every chunk a full pair; RelateArgs::cleared splits the pairs and parses the kind, so a bad kind is refused before the ticket is resolved. It exits 1 rather than clap's 2, which is the price of a two-value flag and the reason RelationKind::parse_value names the three in its message
  • Both spellings of the kind are accepted, blocked-by from the flag and blocked by from the label. Both are in front of the reader: the flag is what recorded the relation and the label is what show prints and what the file stores, so refusing the printed form would be a trap for anyone clearing a row they just read. RelationKind::flag is a match rather than label().replace(' ', "-"), so the flag, the --clear value and the completion list cannot drift apart
  • find_relation searches the ticket's own edges before the board, and that order is the feature. A dangling edge is the case most likely to need clearing, and no search of the board can reach a target whose ticket is gone, so the id-prefix tier over the stored targets is the only one that finds it. MIN_ID_SEARCH is the floor resolve_in puts under its own id tier and the comparison is case insensitive for the same reason. Two stored targets under one prefix name the candidates rather than guessing, which is what an ambiguous ticket search already does
  • An edge the ticket does not hold reports no change; a target naming nothing at all is an error. The two are different facts: the first is the state the caller asked for, and the second is a typo that reporting no change would swallow. The resolver's own reason is carried through, so an ambiguous search says so instead of being reported as nothing found
  • Recording and clearing the same relation in one call is refused, and the check runs on what was asked for. items drops the additions already in the file, so comparing against that would let --blocked-by X --clear blocked-by X quietly remove an existing X. requested is the full list for exactly that reason. The refusal is set --clear's: nothing is written rather than one direction silently winning
  • Removals rewrite the section and additions are appended to the result, in that order. Two passes rather than one rebuild, so a call with no --clear takes exactly the path it always took and append_section_body goes on deciding where a new line lands. Rewriting from the parsed relations is lossless because a line that is not a relation is already an error. The last edge leaves clear_section_body's placeholder, which is the line append treats as no content, so the next relate replaces it instead of writing under it
  • A relation is not logged, either direction. relate writes no history entry and neither does --clear, which keeps the two consistent; per the history rule, an edge that matters enough to explain gets a comment. Do not add an entry for the removal alone: a log that recorded only the destructive half would read as though the additions had never happened
  • 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 derived row that reads exactly like a stored one is dropped, and the stored one is kept. Both ends of a symmetric relation could hold a line, since nothing stopped it until 03bdc76, and the block then drew the same neighbour twice under the same label. The stored row survives because it is the line relate --clear can address; the derived one is on a file this ticket does not own
  • The dedupe keys on the label and the target, not the kind and the target. Two tickets each blocking the other is two facts and the block says both, blocked by from this end and blocks from the other; keying on the kind would fold them into one row and lose half of what the ticket says. Only a symmetric kind can collide with its own stored line, and RelationKind::is_symmetric derives that from label() == inverse_label() rather than naming RelatesTo, so a kind added later answers by construction
  • relate also refuses to store the mirror, which is the other half of the same fix. The dedupe repairs a board that already holds both directions; the refusal stops it recurring. mirrored in cmd_relate reads the target's own relations and reports no change, gated on is_symmetric because a target holding blocked by <this> is a cycle rather than a duplicate. 4179958 decided relates to is written once and not onto both files; for six months nothing enforced it
  • A symmetric edge is cleared from the end that stores it. With both ends holding a line, --clear on one leaves the other's, which then draws as the derived row: correct, since the far end still asserts the relation, and the reason the dedupe keeps the stored row rather than the derived one
  • A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but 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_cells 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 and campaign append are the only writers of a filed campaign's fields. d637288 decided the command: 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. set carries --title, which renames the file the way set --title does, --description and --codename; append carries --description alone. 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
  • The description arrived as a pair, set --description and campaign append, 32e98ab. Never one without the other: for a prose section set replaces and append adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line append already draws for a ticket, and campaign_append_offers_only_the_description pins that. Neither flag takes --force: a description is prose written to be revised, the same reason tags set --annotation has none
  • append is a campaign's own subcommand, not the top-level append. That one resolves a ticket, and one positional naming either object is the ambiguity resolve_in makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of resolve_ticket, which explains a ticket search that names a campaign. Under campaign the object is settled by the command, as it is for set, show and ls
  • Still no --owner and still no --clear. No --owner, because nothing writes a campaign's Owner today and giving set one would settle by accident whether chown grows a campaign. No --clear, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be Clearable on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. campaign_set_offers_no_owner_and_no_clear pins both
  • An empty --description "" is a paragraph break here too, and the refusal for an all-blank value names no flag. Every prose argument in the tool reads a blank value that way, add, set and tags --annotation alike, so a campaign reading it as empty the section would be the one exception. With no --clear to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. replaced_items is where the check lives, shared with set, and the way out is the caller's argument for exactly that reason
  • SECTION_ORDER needs no campaign variant, and that is what the one-section file proves. A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, filtered by what is actually in the file, so a campaign's description anchors against ## Metadata — which is where campaign_body writes it. the_description_is_edited_in_place_in_a_file_with_one_section pins that no section a campaign does not have gets inserted to anchor against
  • A campaign whose Description heading is gone is refused, not given the section back. No ensure_section on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where add writes nothing and the insertion is the only path there is. The refusal therefore names the section and not the object — "There is no description section to write to" — because both a ticket and a campaign reach replace_section_body now. write_then_replace still carries the noun, where the message is about a file
  • 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 campaign frame scrolls on the same two keys, and Board::scroll_page is where the precedence lives. An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In Board rather than in the main.rs arm for the reason dismiss is: a layering rule written into that dispatch is a rule nothing can check
  • The scroll offset is clamped against the wrapped line count, from Paragraph::line_count, which is 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
  • A hint is a key and what pressing it does, and key_hint is the only thing that draws one. The key is cyan and bold, the description takes the terminal's default foreground, and the row keeps its three-space gaps. Everything that names a key goes through it: the three footer states, the prompt's two keys, the picker's row and the q board on the frame's border, so a reader learns the shape once. Same division in frig and pantop, each in its own accent colour, cyan here and magenta there — the three tools are read side by side and used to look like three programs
  • A key that is its description's first letter is merged into it, so the board draws quit, campaign and tag with the letter coloured and no letter in front, while y copy id, ctrl-c quit, d show done (2) and every arrow row stay split. Two cells back on a row already at its width naming eight keys, and the coloured letter is the key either way. The prefix test in key_hint is case sensitive for exactly that reason: a row naming both r and R would otherwise draw one word for the two of them, and the merged form can only say which key it is while the letter on screen is that key. It also means the row carries both forms at once, which is the cost of the two cells
  • What the row is cannot be read off its text any more, so the tests read its cells. footer_cells, footer_at, keys_on and footer_style in the test module: keys_on(.., "quit") is Some(1) where q quits and Some(0) on a row whose only quit is the tail of ctrl-c quit. A contains("q quit") cannot tell those apart, and three of the guards that keep 1b78a24 out were written that way
  • 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 drawing the merged quit there would be 1b78a24 in the other direction: a footer describing a key by what it used to do. ctrl-c quit is split by the same rule that merges the other, being no word's first letter
  • The overlay names its ticket on the border, not at the head of the paragraph. Board::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 from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. content_trim and format_history_with take the colour decision for the CLI's side of the same layouts
  • Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
  • A card is four corners with the title between them: mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
  • The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
  • A card's height therefore depends on the column's width, so card_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
  • corner_line's right side is a group, single-spaced, and it gives up its items from the front. The item nearest the edge is what the corner is about; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an Option. The spacing between the items lives in corner_line with the gap arithmetic rather than in a caller, for the reason column_areas is shared: geometry reproduced by hand drifts from the draw. due_span returns a Span and not an Option<Span> now, since the Option only ever existed to satisfy the old signature and the function cannot fail
  • 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
  • The comment count is the same field discipline and the one entry on that pass that costs a directory listing. The history lives outside the ticket file, so count_comments is a read_dir rather than a parse: .md only, the filter read_history applies, and no body is read, because a count needs none of them. It counts comments and not entries, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. collect_ticket_items derives the board from status_path.parent() instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. history_dir spells the path once for the writer, the reader and the counter, the way campaigns_dir does. Zero draws nothing, not a 0 and not a blank: an uncommented card is the row it has always been, which a_card_with_no_comments_spends_nothing_on_the_corner pins to the exact spacing
  • The count is cyan and the mark is COMMENT_MARK, U+275E, a Dingbat. It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where spans_width counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
  • the_count_is_read_when_the_items_are_collected_and_not_per_draw takes the history directory away after the board is built, and is paired with a_comment_added_after_the_board_was_built_reaches_the_card_on_reload, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
  • A card names its campaign on the label row, before the tags, in bold. labels_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_cells 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 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, column_count and the copy key all keep working unchanged
  • A campaign filter is a uuid on the tab, not on the Board. Tab::filter is a Filter, and a campaign belongs to one .worklane, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by reload rather than left filtering the board to nothing
  • The frame above the columns has two heights, and Chrome is what every measurement takes. Chrome::frame is an Option<FrameSize>, not a bool: None for a tab showing the whole board, and Collapsed or Expanded for one filtered to a campaign or a tag, because both heights have to be measured the same way by everything that measures the board. screen_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, FRAME_ROW, BOARD_ROW, FOOTER_ROW), since an index written out by hand goes on meaning what it used to. Nothing in the geometry is named after campaigns, because the slot is the tag filter's too: Chrome::frame says how tall the frame is and never which filter filled it, so a measurement of the board never has to ask
  • The whole description is carried off the one read, and the cut is on the view. section_prose replaced section_opening, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and CampaignRow::summary takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
  • FRAME_PROSE_ROWS is the collapsed height, and it is a constant rather than a height fitted to the description. Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
  • The expanded height is a share, not a second constant: half of what the frame and the columns divide. That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. Chrome::frame_rows takes the height because of this, and screen_rows is where it is called, since that is the one place that already has an area to take a share of — which is what keeps Chrome itself pure and copyable from Board::chrome with no screen to hand
  • The share is bounded at both ends, and COLUMN_MIN_ROWS is why. Constraint::Min(COLUMN_MIN_ROWS) would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault Chrome exists to prevent. So the share is capped at what leaves the columns those rows, and floored at FRAME_ROWS, since expanding must never shrink the frame. On a board too short to divide, enter gives the collapsed height back rather than a height nothing measured. the_expanded_share_is_bounded_at_both_ends sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
  • The frame says the rest of what it has to say on its borders, the trade the detail overlay makes with its title and its page indicator: (id) ~codename · Name on the top one, the standing on the bottom right, and q board then the page indicator on the bottom left. Every row spent here is a row of cards
  • The frame slot is shared between the filters, not doubled. One filter is on at a time, per Filter, so a tag frame is the campaign frame with its three slots filled differently: #tag in tag_color on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. FrameContent is what they are told apart into, and frame_content is the one place they are told apart at all — the borders, the colour, q board, the page indicator, the scroll and the focus are all the campaign frame's, and a second match on the filter below that is how the frames come to behave differently in a way nobody decided
  • A tag frame draws the annotation, which is the payoff for declaring a tag. Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in tags.md, which they would have to know to open. An undeclared tag draws NO_ANNOTATION in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
  • A tag has no id, so y on its frame copies the word. A tag is its name, matched whole by ls --tag, so there are no seven characters to shorten and the # the border draws is not part of it — --tag "#bug" matches nothing. The footer says y copy tag there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
  • The count on a tag frame is every column's, drawn or not, the rule the standing holds. With the filter on, those columns are the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no [open] to be in
  • The frame's page indicator goes on the bottom border beside q board, not on the top beside the title. The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is about where the indicator is only where the reader has got to in it. Dropped before q board when the two cannot both fit, since with either filter on the footer's last slot names ctrl-c quit and the border is the only place that says q gives the board back
  • Focus is the third place the selection can be, and Tab is what holds it. The board had a column and a card and select_card clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. Focus::Frame while no filter is on is the one state that must never exist — select_filter and reload are what keep it from arising, off Filter::is_whole rather than off which filter it is, since either draws a frame to hold it
  • Tab::selected hands back nothing while the frame holds the selection. Every key that acts on a card has to answer for the frame. ←→ are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. y is the exception that earns its place: it copies the campaign's short id, so y copy id means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
  • enter routes on the focus through Board::toggle_focused: the frame's height on the frame, the overlay on a card. It used to be inert on the frame for free, because Tab::selected hands back nothing and toggle_detail therefore had nothing to open. That is no longer an answer, and the routing is in Board rather than in the main.rs arm for the reason dismiss and scroll_page are
  • q does not gain a layer for the expanded frame, and up and down do not take it back. The expanded frame is the frame at its other height, not a thing laid over the board, so q goes on taking the campaign filter off from either height and enter is the only key that undoes what enter did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. Tab::expanded sits beside the filter and resets where select_campaign and reload reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
  • The toggle re-clamps the frame offset, through scroll_frame(0, screen). A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next pgup counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
  • The frame is out of reach from under an open ticket. With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. an_open_ticket_keeps_the_scroll_keys_from_the_frame builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
  • The standing comes from the columns, not from a walk of the tree. While a campaign is selected the columns are its members, done included, so Tab::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, and measured over its spans rather than one string since it is a key hint like any other. Drawn through key_hint and not as grey chrome: it is the one key on the board named anywhere but the footer, and a reader who has learnt to look for the cyan letter should not need a second convention to find it. The indicator beside it stays grey, having no key in it
  • c and t are named in the footer only on a closed board with nothing filtered, which is where a reader has to find them. Over an open ticket and on a filtered board they are left out: the frame's border then says how to put the filter away, and the row has no cells to spare. The tag used to be drawn on that row in its own colour, for want of a frame to draw it in, and 2a83bd4 took that away rather than saying it twice. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
  • The footer has three states, because the selection has three places to be. An open ticket, the frame, and the cards. On the frame it names ↓ board, ↵ expand or ↵ collapse, the two scroll keys and y copy id — y copy tag on a tag frame — and leaves out ←→ because they do nothing there. It has to say which way ↵ goes, since the key is a toggle and the frame is always at one of its two heights. ↑ frame is not named on the board, on the same trade c is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and ↑ reaches it
  • picker: Option<Picker> is the whole mode, the 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
  • t opens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it. Every tag the board declares or carries, matched whole and case sensitively the way ls --tag matches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesy c pays a campaign-filtered board, and a board carrying no tag gets the same Notice a board with no campaigns gets
  • A picker row draws a real codename only. The row opens with the short id, so the card's ~<id> fallback would print it twice and say nothing the second time
  • One picker serves both lists, and PickerRow::key is what keeps it one. A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead PickerKind decides only which list is built, and everything between the keypress and the filter runs once against the key — which since the pile arrived is a PickerKey enum rather than a bare string, because one of the answers filters on an absence and carries no string to hand back. take_picked reads the kind off the answer rather than off which list was open. Picking any of them clears the others without either setter remembering to, because select_filter replaces one Filter: one field, which is the same reason the frame slot is shared
  • The campaign picker opens with a row for the tickets in no campaign, above both sections and never truncated: the pile is the one question about a board of campaigns that no single campaign answers, and on a board whose completed tail is being kept back it would be pushed off the box if it listed among them. It draws its count where a campaign row draws its standing, so picking an empty pile is seen coming; under a query it answers "no campaign" and "none" and hides like any other row. It selects Filter::NoCampaign, its own variant — retain_campaign compares the field to the uuid it is given, so the absence case is a different predicate beside it (retain_no_campaign) and not a different value in it, and a magic uuid meaning none is exactly the thing that later matches a real one. A dangling uuid is set wrongly and stays out of the view, as it draws _missing_ on its card rather than nothing at all
  • The pile crosses boards where a campaign cannot, so it is pickable on the merge tab. An unset field means the same thing in every .worklane, the property that lets a tag filter travel there; the count adds across boards, taken at reload off the unfiltered columns like the standings are (Tab::no_campaign), never per draw and never off the filtered columns, which would answer zero about themselves
  • The opening highlight still lands on the first campaign, not on the pile. Campaigns are what this list opens for; the row sits above the list without claiming it — one step up reaches it, it holds the highlight whenever it was the row selected, and only when every campaign is hidden does it take the opening one
  • The frame speaks for the pile in its own words, because the frame question stays is_whole(). Exempting one variant from either half of that rule would be a state where the selection rests on a frame that is not drawn — the one thing Focus exists to make unrepresentable. So the title is grey no campaign (no id to shorten and no mark, which keeps ~ meaning a campaign and # a tag), the standing corner takes the count, and the prose is one grey sentence the board owns, since no file holds words for an absence
  • y has nothing to copy from the pile's frame — no id to shorten and no word a command line takes, ls --campaign being unable to say none — so the footer leaves the key out rather than naming it into a notice, and pressing it anyway still answers "nothing to copy"
  • The picker draws two sections, open campaigns above completed, and truncates the completed tail. One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by Created At newest first, because what a reader recognises about a finished campaign is that it was finished recently. COMPLETED_SHOWN of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule by_status_order holds for a column
  • The tag sections are declared above undeclared, and truncate neither. The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too: tags.md is what the board intends, and the vocabulary the listing reports is the one the picker offers. campaign and campaigns would have sat one under the other here, in different sections, the day the second was invented
  • picker_list is the one place that decides what a picker row is, and Picker::row counts drawn rows. The sections reorder the campaigns and add rows of their own, so Tab::campaigns and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
  • A heading is drawn only over rows that exist, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
  • open and completed, not open and done. The split is taken from Standing::state, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not in done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
  • Headings and the truncation line take no number: the highlight moves over campaigns only. stepped_picker_row walks past the chrome rather than stopping on it, since a highlight resting on a heading gives enter nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
  • / in the picker is the key it already is on the board, and picker_key can take it because printable keys used to fall through _ => {}. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer disk with every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though --tag is not, because matching a tag is the filter and searching for one is a reader typing. An empty query matches everything, the opposite of first_match's answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing / must not empty the list
  • A query turns the truncation off, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
  • The query is a layer, and esc takes it off before it takes the picker off, the order dismiss closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and enter stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every printable key goes into the buffer, so q types and so does j
  • The highlight follows its row, not its row number. place_picker takes a key — whichever answer PickerRow::key hands back, the same shape Tab::filter holds for any of them: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. reload reads the highlighted key before the lists are rebuilt and puts it back after
  • Both ends bring the highlight into the window. Opening aligns against the screen the dispatch hands open_picker, and the draw follows the highlight again through aligned_offset on the geometry it is actually drawing — a resize between that keypress and the frame, or a tick that put the highlight back without touching the scroll, cannot leave it below the fold until some later keypress fixes it. The stored offset is left alone, the way a column's is: what is drawn is corrected immediately and the next navigation writes the correction back
  • A miss is a row in the box, no match in brightred, where the search prompt puts its own, and enter on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
  • The picker's footer becomes its query, the trade draw_search makes: with every printable key going into a buffer, a list of keys describes nothing that works. / search is named only on the closed query, and the open one names what esc does to it rather than what it does to the picker
  • The title says both counts while a query is open, campaigns (2 of 6). The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
  • Every campaign's standing is settled at reload, in one pass over the cards. standings_of counts the cards naming each uuid off the columns the reload is already holding, which is what Standing::of builds for campaign ls without the walk of the status directories that one pays per campaign. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
  • Tab::standing is gone with it. The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule wrapped_height holds for the scroll. the_standings_are_read_when_the_cards_are_and_not_per_draw takes the status directories away after the board is built, paired with a_member_finished_after_the_board_was_built_completes_its_campaign for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
  • 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 history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
  • The tags go under the title, dimmed, each prefixed with #. The field was invisible on the board: nothing said a ticket was 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 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"
  • The terminal columns are hidden until d asks for them, one step at a time. Not a new opinion: ls already counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. So d rotates three states — hide both, show done, show both, and back around — through the Visibility enum on Board, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the next press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices
  • Hiding is a change to what is drawn, never to what is read. reload still scans the done and discarded directories and digest still watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan
  • visible() returns a prefix of columns, not a filter, which is what keeps column and offsets valid as indices into either. It is derived from where DONE and DISCARDED actually sit rather than assuming positions, and the_terminal_columns_are_last_in_the_order_drawn pins the assumption. A status inserted after discarded would otherwise hide two columns in silence
  • Hiding the column under the selection moves the selection to the last drawn column and closes an open detail view. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
  • The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
  • Assert a column heading against the top border row, not the whole screen. The footer names done too, so screen.contains("done (0)") passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; headings() 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. Its two keys are drawn as every other key is, cyan on the key and the default foreground on the word. That the query then sits in the same foreground as the descriptions is what the house style costs on this row, and the cursor is what says which half is an input — which it does in a terminal with no colour at all. no match stays brightred beside the query it is about, being the one thing on the row that is neither a key nor what was typed
  • The real terminal cursor goes after the query, not a glyph standing in for one. ratatui shows the cursor only for a frame that asked for it, so set_cursor_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 Command Prompt

  • prompt: Option<Prompt> is the whole mode, the shape search and detail use: open and content cannot disagree, and closing it leaves nothing to reset. Prompt carries the line, the cursor as a byte offset into it, and refused, which is Search::missed with something to say
  • Board::prompt_key is third in the pre-dispatch, beside search_key and picker_key and on the same contract: while a command is being typed q is a letter, d leaves the columns alone and tab stays out of the project tabs, and ctrl-c is the one key declined. It takes a Size for enter's sake: running a command reloads the board and then has to bring the ticket it moved back into view, which is the measurement follow_selection takes. Only one of the two prompts can be open at once: : is reachable from the action arms alone, and while either has the keyboard the other's key is a character in a line
  • esc and enter are the mode's own keys and are answered in prompt_key; everything else belongs to the line and goes to Prompt::key. That is also what keeps the borrow straight, since closing the prompt takes the whole board and editing takes only the prompt. Left, right, home, end, backspace and ctrl-w behave as they do in a shell, and ctrl-w eats the separators behind the cursor before the word behind those, so one press at the end of mv 1b78a24 takes the id. There is deliberately no tab: suggesting the selected ticket is 00a14e7, and until then it is a key that must not reach the tabs
  • The grammar is clap's, with nothing restated. The line is tokenised by split_line, the binary's own name goes in front, and the arguments go to the same Cli definition the shell reaches, so a flag added to a command is typeable here the day it is added. Through Cli::command().try_get_matches_from_mut rather than try_parse_from, for what the matches give back: command_name walks the subcommands to name what resolved (campaign show, not campaign) instead of a match over every variant, which would be a second list of every verb the CLI has and one that goes stale silently
  • refused is cleared by an edit and not by a movement. The message is about the line, and moving the cursor does not change the line. Prompt::key clears it in the three arms that write to the line
  • A line that ends inside a quote never reaches clap. That is what Unclosed is for: a grammar complaint about a sentence nobody finished describes the wrong thing. Enter on an empty line, or one of nothing but separators, closes the prompt with nothing said, the way esc does — the bare form of the CLI opens a board and there is one on the screen
  • Enter runs it, through main.rs's dispatch and never through a handler this file names. That match is the one mapping from a parsed command to the function that performs it: main calls it with its own stdout and the working directory, Board::run calls it with a buffer and the selected tab's root. A second copy inside tui.rs would drift the first time a command was added, and it would drift silently, since both halves go on compiling. The match is exhaustive so a new verb cannot fall into an _ arm and do nothing, and main_and_the_prompt_run_one_dispatch_table reads both files as text to pin it. Only tui is matched outside the table, in main, because the board is that table's caller rather than an entry in it; reached from the prompt it is refused in those words
  • from_arg_matches on the same matches gives run the typed values. One parse, two readings: command_name walks the subcommands to name what resolved and from_arg_matches reconstructs the Cli. A match over every Command variant to get one or the other would be a second list of every verb the CLI has
  • The handler's own words are what the board reports, word for word. Those messages are written for a person already, and a second set kept here would go stale the first time one of them changed. The sink is a buffer, so the words come back as text and the board styles them; it is plain for the same reason Detail holds spans, since a ratatui paragraph prints an escape rather than obeying it. An error never goes through a sink at all — color_text asks the process about its stdout, which under the board answers yes about a terminal the message is not going to — so error_lines runs without_escapes over it and puts each cause on a line of its own
  • A handler that errors leaves the prompt open with the line intact. The usual cause is an ambiguous id, and the fix is two more characters rather than the whole line retyped from :. Ambiguity is an Err carrying the candidates, not a print and an exit, which is what makes it safe to reach from here at all
  • The reload after a command is unconditional, and runs whether it failed or not. tick reloads on the digest, which is right for a change made in another pane and needless latency for one the board just made: the reader would watch their own mv take up to a poll interval to appear. Either way, because a handler that failed part way through has still written
  • The selection is restored by uuid across that reload, never by index. mv puts the card in another column, set --title renames its file, and a filter can drop it out of view entirely, so the slot is not the ticket. Board::reselect has three answers: the card is in a drawn column and the selection goes to it; it is on the board but in a column the rotation is hiding, which is where --status done lands by default, so the notice says where it went and which key shows it; or the filter no longer holds it, which is said too, since a card vanishing from under the highlight reads as a bug in the board
  • The merge tab is refused, for now. It is the one tab that is not a board — its cards came from several .worklane directories and it is none of them — so Board::current_project answers None there and the command is refused rather than landing on whichever project came first. Routing by the card a command names is ebc5755. The project is resolved by index and not by the tab's name, which is a label two projects can share: e1d79c3 is exactly that, and a write routed by name would be that bug with a file changing at the end of it
  • Notice holds as many lines as the command used, and Board::notice_on_row decides where they go. One line with nothing else holding the row draws on the footer, where a copy's notice has always drawn. Anything else — several lines, or any answer at all while the prompt is still open on an error — draws as a box at the foot of the columns, cut to what the columns leave with the dropped count on its last row. A box rather than more rows of footer, and that is the whole reason it is an overlay: a footer that grew and shrank as notices came and went would reflow the columns on every keypress, moving every card the reader is looking at. draw and draw_footer both ask notice_on_row, so the two cannot come to disagree and draw the message twice or not at all
  • What a refused line shows is clap's own message with the usage block cut off, which is also what drops the --help line after it. --help is the exception: it parses as an error of the kind that means print this and what it would print is a page, so it is caught and answered in a row's worth of words, or clap's help lands on the alternate screen the way an unsunk println! would. --version goes through the ordinary path, because what it prints is one line by construction. ColorChoice::Never on the command, so nothing that reaches the row carries an escape
  • The keys' width comes off the row before the line is windowed, so a long command does not push them off the end; a message takes the row from the keys instead, since the reader has just been told something and esc and enter still do what they did. prompt_window anchors the window on the cursor's right edge, which costs the text after the cursor on a long line: keeping both ends needs a scroll offset in state, and the draw is where the width is known and the state is not writable
  • : command is named in every footer state, because the key works in every one of them, and the prompt's own key is drawn as ↵ run

The Prompt's Recall

  • up and down walk the lines already typed, and the lines are on disk. .wlhistory in the board's own folder, appended as each line is entered. It is the one file under .worklane the board writes rather than a command, and the only one that is not markdown, which is the cost of a recall worth having: a board is opened and closed all day, and one that emptied on quit would only help inside a single sitting
  • Recall is per tab, parallel to Board::tabs, so the tab in view decides which list up walks. A project's lines are the ones naming its ticket ids, and handing another board's mv back on this one would offer an id that resolves to nothing there. The tabs are fixed for the run, so the two vectors cannot drift, and the same index that picks the tab picks the recall
  • The merge tab has no file. It is the one tab that is not a board, current_project answers None there and a command typed there is refused for that reason, so there is nothing to attribute a line to. Those lines are still recalled for the run: every one of them was refused, and a refused line is the one most worth getting back. When ebc5755 routes a merge line to the board its card names, that board's file is the one to append to
  • The position is on Prompt and the lines are on Recall, so closing the prompt forgets the position and not the lines: the next : opens at the end of the list again, which is where a shell opens. pending holds the half typed line up walked away from, and walking down past the newest entry puts it back, so leaving a command to look for an older one never costs it
  • The ends are stops, not wraps. up on the oldest line leaves it up rather than cycling round to the newest, which is what a shell does with it; down with no walk under way does nothing, since there is nothing in front of a line still being typed and emptying the row would be a keypress that destroys work. An empty recall does nothing at all, and that includes leaving the line alone, or up on a board nobody has typed at would be a way to lose what is half written
  • The line is kept before anything can refuse it. A refused line never reached a handler and the fix is usually two characters, which is what the walk exists to save. Consecutive duplicates are kept once, against what is already held, so the rule spans runs as well as one sitting; a blank line is no command and is not kept. Nothing is trimmed
  • A failed write is silent, and an unreadable file is an empty recall. The line is in memory either way, so the walk works for the run on a board whose folder cannot be written, and a board with no history yet is the ordinary case rather than something to say. A notice about a history file would be about the one thing the reader did not ask for
  • .wlhistory is not in digest. Appending to it must not read as the tree moving, or every command typed would provoke a reload of every board on top of the one run already does

Splitting a Typed Line

  • split_line is the whole module, and it knows nothing about Board. The command prompt reads one string and clap reads an argv, so comment 1b78a24 the offset was never passed has to be tokenised before anything can parse it: split on whitespace it is five arguments and comment takes two. A pure function over the line and the cursor is what makes every rule reachable from a unit test, and it is in a file of its own rather than in tui.rs, which is eleven thousand lines already
  • The rules are the shell's, because that is what the prompt promises: the line is spelled there exactly as it is spelled in the shell. Runs of whitespace separate arguments, single and double quotes group one, a backslash escapes the next character except inside single quotes where it is a backslash, and an explicitly empty '' is an argument that exists and is empty — which is what --title "" being a usage error rather than a silent clear depends on. A leading hyphen is not special here: whether --foo is a flag or the text of a criterion is clap's question, and PROSE already answers it
  • Written rather than pulled in, for the two answers a shell's own splitter does not owe anybody. A line being typed is half finished, so an unterminated quote is a state to report and not an error to raise: Unclosed says which quote is open, or that the line ends on a backslash with nothing yet to escape, and the arguments up to that point are handed back anyway, because that is what a hint or a completion has to work from. And completion needs the cursor: which argument it is in counting from the verb, and whether nothing of that argument lies before it, which is the difference between completing an argument and starting one. Both fall out of the one scan and neither is reachable afterwards from the arguments alone
  • Some("") is an argument that has been opened and is still empty, which is the only thing that tells '' from nothing typed at all. The cursor's answer is taken before the last argument is pushed, so a cursor at the end of the line is in the argument being typed rather than one past it
  • The cursor is a byte offset, because that is what the prompt's own cursor is: a String inserts and removes at byte indices. Past the end reads as the end and inside a multi-byte character reads as after it, so nothing panics and no caller has to clamp first
  • Unclosed::Escape wins over an open quote, being the inner of the two, and either answer refuses the line
  • The binary's own name is not among the arguments: prepending it before Cli::try_parse_from is the caller's, since only the caller knows what it is calling

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, the colour it is drawn in and the modifier it carries, None for the default foreground and for text drawn as it stands. 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, and Modifier is that trick a second time for the styles that are not colours
  • Modifier is the first style on a cell that is not a colour, and it is an enum with one variant for the reason the palette is one: Modifier::ansi() is SGR 9 and From<Modifier> for ratatui::style::Modifier is CROSSED_OUT, so a style that exists for one renderer and not the other is a compile error. Bold is not in it, because bold rides inside Color::Magenta.ansi() and span_from adds it back from the colour alone; a second modifier goes here beside the strike. It is independent of the colour, so a struck run keeps whatever colour its column already gave it
  • Cell::struck is a builder, not a third constructor. The strike is decided a whole row at a time and the cells of that row are built by the layout that already chose their colours, so relation_cells maps it over the row it has just finished rather than threading the decision through every cell it makes
  • RESET is a constant both writers share. paint opens a colour and paint_cell may open a modifier ahead of one, and a reset that only knew about the colour would leave the strike running to the end of the line
  • Body::push_cell merges on the whole style, not the colour alone. Nothing outside the relations block carries a modifier today, and a merge keyed on the colour would silently strike a plain run through the moment one did
  • reference_cells is the one spelling of a cross reference. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was a reference_cell beside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone
  • A row carries two marks, kind then status: what sort of edge this is, then how far the ticket at the other end has got. blocked by × ◐ (6ce2c47) Title. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
  • The status went through one bad shape first. It was a rising bar, ▁▄▆█, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
  • Both directions of a kind carry one mark. blocked 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, and Resolved.campaign is cells for the same reason. An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing in Resolved can arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, since content_parts paints nothing at all
  • BodyPart splits the body rather than building it twice. It is Cells or Relations: everything outside the block is laid out once, by content_parts, and content_trim is that run through paint_cells while the board is the same cells run through span_from. Body is the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in places
  • 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. It now splits per cell rather than per part, since a Cells part holds many runs and a newline can fall inside any of them
  • The whole overlay body is coloured now, and content_parts paints nothing. The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the same Cell treatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout that show paints and the board styles. Do not reintroduce a paint call in content_parts: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes
  • colored still reaches content_parts, and it no longer means paint. It says whether this renderer can carry a colour at all, and one thing turns on it: **bold** gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passes true, content_trim passes the CLI's decision, and a piped show still reads its markers. Nothing else in the body consults it
  • Magenta means bold, and span_from is where the board learns that. Color::Magenta.ansi() is \x1b[1;35m, so the CLI draws every bold run bold as well as magenta, and From<Color> can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent
  • The conversion is pinned from both ends. show_prints_the_same_body_it_printed_before_the_cells_conversion holds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite. the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it is the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence
  • The history block arrives as segments too, so nothing in the overlay is flat. history_parts splits the entries into flow runs and quoted runs in one walk; history_cells is their flatten, which is what makes the CLI's bytes a property of the segmentation rather than a second walker free to drift from it, and the board reads the same parts and lays each out itself. Pinned from both ends the way the body is: the pins over format_history hold the flatten byte for byte, and the_block_splits_into_flow_and_quoted_parts pins which runs are whose

Finding the Board

  • find_worklane_dir classifies the entry before it follows it. exists() follows a link, so a .worklane that was a dangling symlink answered the same as no .worklane at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. classify reads symlink_metadata first and answers one of four, Absent, Board, Dangling or NotADirectory, and Absent is the only one the walk carries on from. A .worklane that is there but unusable is this project's board and is reported, not handed upward
  • Anything other than NotFound from symlink_metadata is an error rather than an Absent. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
  • The dangling failure names the target and says the boards repo may not be cloned, and deliberately does not say to run worklane init. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
  • A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target. .worklane/backlog/*.md has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
  • A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today

Monitoring Several Boards

  • worklane tui <path>... takes any number of paths, each resolved 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 visibility 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 date 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. screen_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

Who Wrote an Entry

  • Identity is supplied, not detected. Every option that needs no cooperation fails: a harness variable such as CLAUDECODE names the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor is WORKLANE_ACTOR, set once per session, with --actor as the per-call override
  • Precedence: flag, then WORKLANE_ACTOR, then get_git_user(), then unknown. With --actor-from-git and no explicit value the git user is lifted above the variable rather than added beneath it — the flag says attribute this to the human, and a machine with no git user configured reads unknown instead of quietly attributing back to the agent. An explicit --actor wins outright either way. resolve_actor is the only caller of get_git_user for an entry's author, and every entry the CLI writes goes through it. The halves are separate pure functions, session_actor (the variable alone now) and entry_actor, tested without touching the process environment for the reason colors_wanted is split that way
  • The variable half is cached in a OnceLock and the git user in another, the way should_use_colors is: neither input can change mid-run, and the git user costs a subprocess. Two caches rather than one is the whole point: baking the git user into the session's answer would make --actor-from-git read whatever the run's first call produced, since with the variable set that call never fetched git at all. entry_actor takes the git user as a closure so the subprocess is not run when something ahead of it already answered
  • The two flags are refused together at parse time, clap conflicts_with: both answer who the entry is attributed to, and last-wins would be a silent answer to a contradictory call. every_actor_command_takes_actor_from_git walks the clap definition so the pair travels together onto any command that grows an --actor
  • An empty WORKLANE_ACTOR counts as unset, the convention colors_wanted follows for NO_COLOR, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one
  • The actor is free text, checked against nothing, like the chown user: there is no registry of actors, and the same reason ls --tag refuses to validate a tag
  • It was comment --owner, renamed with no alias. Owner is the ticket's assignee and has one writer, chown; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splitting set and chown avoided. the_owner_flag_is_gone pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
  • add --owner and campaign add --owner still default to the git user, deliberately. Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported
  • An entry does not record whether the call had a terminal. It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
  • Set it in the agent's configuration, not per call. env in ~/.claude/settings.json reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no env block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around opencode. Both are documented in assets/SKILL.md rather than assumed

The History Log

  • The log is the comments directory with the kind named in it. It was already an append-only log with one event kind: one file per entry under .worklane/history/<uuid>/, stamped to the microsecond and written with create_new. Adding status, owner and tags beside comment needed no new mechanism, which is why there is no separate journal file and no database
  • What is not logged, deliberately: ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
  • --clear is logged, since it is the same field going somewhere. chown --clear and set --clear tags write an entry whose after-value is the sentinel the ticket now holds, _Not set_ or _None_. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does
  • The kind is read from the file and only counted from the filename. parse_entry matches the leading marker; kind_from_stem splits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader
  • A file with no marker is a comment, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command: entry_content(Kind::Comment, ..) is byte for byte what cmd_comment wrote before this module, so nothing is rewritten and either version can read the other's board
  • The old directory is adopted, not migrated. adopt_comments renames comments to history on the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. A board holding both is refused, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it
  • An entry is written after the edit it describes, never before. A refused move, a refused chown and a failed save log nothing, which is what a_refused_move_writes_nothing and a_failed_edit_writes_nothing pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it
  • A no-op edit writes nothing either, and apply is what decides that for set: a field it did not record as changed was already what the call asked for. cmd_mv and cmd_chown have their own early returns and sit behind them
  • The stamp leads the filename and the kind follows it, so the lexicographic sort in read_history stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it
  • A mechanical entry renders as one line and a comment as it always did. A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to Kind::LABEL_WIDTH, campaign being the longest of the four, so the bodies line up under each other
  • A campaign entry records Campaign::name, the codename or failing that the title, never the uuid the field holds. Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A before uuid the board no longer has reads _missing_, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from _Not set_ (f774a33)
  • --actor is on every command that writes an entry, spelled from one ACTOR_HELP in command.rs: a flag documented differently on each command reads as four flags. --actor-from-git rides beside it from its own one string, the same way. On chown it sits beside user, which is the ticket's new assignee — the two are different questions and that command answers both
  • set --actor reaches only the entry --tags writes, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries. append --actor is the same flag for the same reason: append --tags moves the same field, so it writes the same Kind::Tags entry, and a tag added without replacing the rest would otherwise be the one tag change the log missed

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
  • assets/SKILL.md is the only worklane skill document in this repo, and nothing may reintroduce a second. There was one: .opencode/skill/worklane-kanban-skill/SKILL.md, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill worklane_kanban, its examples still used short flags the CLI had stopped accepting, and it knew nothing about relate, campaign, chown, check or the four-status flow. It was not inert while it existed: opencode debug skill listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under .opencode/, in a second assets file, or in the README is the same mistake; the document has one home and install-skill is how it travels
  • One install path serves both agents: ~/.claude/skills/worklane/SKILL.md. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own ~/.config/opencode/skill/. Verified against opencode 1.15.10, whose built-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 agent files 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. The tool file is the exception and no longer lives there: it was .opencode/tools/worklane.ts, which meant it existed only inside a checkout, and it is now assets/TOOL.ts and shipped like every other asset
  • 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
  • install-tool is a second command, not a flag on install-skill, because the two artifacts are not alike. A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: claude mcp add with a stdio, sse or http transport is the only way a tool enters its tool list, and its plugin system adopts agents, hooks, monitors, workflows, output-styles and themes and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
  • tools_root() follows XDG_CONFIG_HOME, skills_root() does not. ~/.claude is not an XDG path and opencode's config root is: opencode debug paths reports $XDG_CONFIG_HOME/opencode with the variable set and ~/.config/opencode without. An empty value counts as unset, the convention colors_wanted follows for NO_COLOR. opencode_tool_dir takes both variables as arguments for the reason colors_wanted does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
  • Singular tool, and it was measured, not guessed. opencode 1.15.10 loads ~/.config/opencode/tool/ and ~/.config/opencode/tools/ both: each was served in turn from a directory outside any project and /experimental/tool/ids registered every worklane tool the file carried, eleven at the time and twenty-one at the recheck after the wrapper caught up with the CLI. The singular is the spelling opencode's own documentation puts first, the way it writes agent(s) and skill(s). opencode serve plus that endpoint is how to check this again; there is no opencode debug tool to ask
  • worklane.ts is the file name the tool ids are built from. opencode names each tool as the file then the export, so the file's twenty-one export const lines become worklane_add through worklane_tags_set. Renaming the file renames every tool and every permission rule that mentions one, which is why TOOL.relative is pinned by a test rather than left as a detail
  • The tool needs nothing installed beside opencode, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the @opencode-ai/plugin import resolves there: a copy in a project with no node_modules anywhere above it registered all of its tools, on a machine with no bun on PATH. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
  • The closing line differs from the skills', and that is not a wording choice. opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
  • The wrapper walks clap in both directions now; until this ticket nothing did. It was behind by four commands — relate, campaign, assign and tags had no tool, so an agent holding the tools could not reach campaigns or relations at all — and nothing compared the file to the CLI, which is how the gap opened and stayed open. every_tool_the_wrapper_exports_is_a_real_subcommand catches a tool for a command that has been renamed or dropped, which fails only when an agent finally calls it; every_subcommand_outside_the_exceptions_has_a_tool catches the other direction, a subcommand with no tool, through the same walk off clap the completion lists take. Its exception list carries a reason per entry rather than being bare, and one of those reasons was learned from the test's first run: a bare worklane campaign is refused by the CLI, its subcommand required, so there is no command for a campaign tool to wrap and the five campaign_* tools are the command
  • Installing it globally reproduces fb3dec6 for the wrapper. Global tools apply in every project including this one, so once install-tool has run, an agent working on worklane uses the installed copy of assets/TOOL.ts and not the tree it is editing. Same trap as the worklane on PATH, second instance
  • 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
  • The README command table has the same guard, every_subcommand_has_a_row_in_the_readme_command_table in command.rs. The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: campaign and assign shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the --campaign flag on the ls row. It walks clap's own subcommands, one level of nesting included, against the | lines of README.md, so a new command fails the suite until the table lists it. help is excluded, being clap's. The tag subcommands are named in a PENDING list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it

Color and Output

  • Use color_text() for coloured output — it 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. The inline pass 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. The better answer, where it fits, is to take no flag: ordered_cells and metadata_value_cells return the colour rather than a decision about it
  • A test that asserts an absence has to be paired with one that asserts the presence. The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so should_use_colors() was false and the leaking branch was never taken. The pair is 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 ● discarded, grey ? for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The pair is what has to be unique, which is the same bargain the two half circles already take, and every_status_has_a_mark pins it against status_dirs. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. Green is here and deliberately absent from the priority ramp, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
  • Relation row to a discarded target → struck through, the whole row. The one thing in the palette that is not a colour, and it is here because the status mark cannot carry it: that mark is one cell in a column of five states, so a row pointing at abandoned work reads as a live dependency, which is exactly what it is not. The strike says the relation no longer stands for anything while the row stays on the ticket, for completeness and for the case the target is moved back out of discarded. Only discarded: a done target still stands for the fact that it was a blocker, and a _missing_ one says something different again, that the row cannot be resolved at all. Gutter and padding included, so the line runs unbroken from the label to the end of the title, and every cell opens its own SGR 9 since each is closed by its own RESET
  • The strike is under the colour flag, like every other escape. A piped show carries none of it, the same bargain committed and reviewing already take for being told apart by colour alone, and the board draws it as a style instead. Do not answer the pipe by changing the glyph in the mark column: the pair there has to stay unique, and every_status_has_a_mark is what says so
  • Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the relates to mark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, because show prints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line
  • Chrome → grey. A rendered [ ], the overlay's page indicator and the frame's. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
  • A key name → cyan, and bold; what pressing it does → the default foreground. The one place the palette spends a colour on something that is not a value: a key is what a reader is hunting for on a row they otherwise skip, and with the key merged into its description the colour is the only thing saying which letter to press. Not a second meaning for the timestamp's cyan in any place the two could be confused — nothing on the footer, the prompt or a border hint holds a value at all — and it is the accent frig draws the same row in, which is the point. Grey stays on the chrome around it: the page indicator, and the row's gaps
  • Chrome → grey, in the history block too: the kind label at the head of a mechanical row, and the From on a comment's author line. Both name their row rather than holding a value, which is what grey already says. The label was orange, which means Status everywhere else, so an owner or tags label claimed a meaning belonging to the value beside it
  • A value in the history block takes the colour it has in the metadata table three lines above. A status is orange, a tags entry goes through the same tag_cells the Tags field does, a campaign codename takes tag_color bare the way Codename does, and _Not set_, _None_ and _missing_ are grey. An owner stays plain: a person's name is the one value the palette has no meaning for, and spending a colour on the field that needs it least is how a colour stops meaning anything. The block's job is to be scanned, and it is not worth scanning if it has a palette of its own to learn first
  • History actor → its name through tag_color, the way a campaign codename is. Not a new meaning for a reserved colour but the existing use of the tag slots, a name that groups rows: one writer is one colour in every entry it wrote, so a reader sees who has been working a ticket without reading the same name four times. claude, opencode and a person each get their own
  • History timestamp → cyan, and its own span. It shared one with the actor while the two were formatted as name (time), which spent the timestamp's colour on a name. The parentheses are plain: they are punctuation, not chrome with something to say
  • Campaign label → its codename through tag_color, bold, marked ~. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view 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

  • change and split_change are a pair, and they live beside each other in history.rs. The mechanical body is stored as one string, before → after, so painting the halves means splitting it, and the separator is a constant the writer and the reader share. A renderer with its own copy of the spacing would go on splitting on a separator the writer no longer emits, and would say so by drawing a whole body as one half. The split is split_once, so a value carrying the arrow itself keeps it
  • The history block quotes who is talking. Every line of a comment's body draws behind a grey bar spanning the whole run, paragraph breaks included, the way quoted text is drawn — d447e04, taking the review of 2733b10's answer over that ticket's uniform prefix and b304b17's per-line indent, both of which left the continuation at column 0. The reason under a mechanical row draws the same bar. The author line stays at column 0 and is told from a mechanical row by its From and its colour instead; the rule a reader learns is that a barred line is somebody's own words and a line of values at column 0 is the tool reporting itself. With colour off the glyph goes but the width it occupied stays, as spaces derived from the drawn form in quoted_cells, so a pipe keeps the column without an escape byte
  • A quote is one segmentation, two shapes, and the shapes split on wrapping. The CLI prefixes each stored line — quoted_cells, which is why a terminal soft-wrapping a wide line draws continuations bare: a pipe has no width to honour, and show does not wrap by hand. The board quotes as geometry instead (8020e48): a HistoryPart::Quoted run becomes an overlay section laid out as two columns, a two-cell gutter holding the grey bar top to bottom and the body beside it, so a row the prose wraps onto inherits the mark from the gutter rather than from its own first characters. Detail holds sections for this reason — flow stretches full width, quotes beside their gutters — and the clamp sums the sections' wrapped heights, so scroll and draw measure one total. The newline history writes after every quote is consumed by the section builder rather than drawn: it used to close the quote's last line and the section boundary does that now, so drawing it would bank a blank row no entry ever had. QUOTE_BAR lives in util.rs because both renderers draw it, not because they draw it the same way
  • history.rs owns the log end to end: the path, the kinds, the parse, the write, the count and the render. It came out of util.rs and handlers.rs, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way campaign.rs and tag.rs answer their own questions
  • The body's painters return cells, not strings: ordered_cells, inline_cells, metadata_cells, metadata_value_cells, tag_cells and push_heading. content_trim_colored is the CLI entry point and paint_cells is the only thing that writes an escape. colorize_line is gone: it was a pub alias for the bold pass with one caller, and the only thing it added was asking the terminal
  • inline_cells walks the line once for both inline markers, **bold** and [text](url), rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and \x1b[36m carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was colorize_bold while links lived in a branch of their own in content_parts; that branch is gone, which is also what gives the criteria text and the metadata Other rows their links, since those already went through this function
  • show renders the Metadata section as a two column table via metadata_cells, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. paint() 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
  • A move whose target equals the directory the file already sits in repairs a Status field that disagrees with it, instead of refusing as a no-op. resolve_ticket reads the current status off the directory, so the old comparison was the directory agreeing with itself and could never see the field; a hand-moved file was stuck with moving it away and back to fix it. Now the field is compared first: agreement is the ordinary already-in-status report with nothing written, disagreement rewrites the field alone through the same in-place save every edit uses, and reports it as a correction rather than a move. It is gated on neither -f nor the dependency guards behind them, because it is not a transition; it writes no stamp, since presence still answers how far the work got and the work arrived nowhere new; and it logs nothing, because an entry shaped like a transition would record a journey the ticket never took. The mirror case is unchanged: a field ahead of its directory after a crash mid-move is corrected by the next real mv, because there the target is a status the ticket is not sitting in
  • Field lookup, read and write, is scoped to the lines under the ## 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
  • make patch, make minor and make major do the mechanics, run after the commit is in: each bumps Cargo.toml and the worklane entry in Cargo.lock, appends , and bump to <version> to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-tagged HEAD and on a HEAD that is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push
  • Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
  • Changed output means the CLI's output. That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
  • Settling output that shipped one version ago is a patch, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
  • No bump for docs-only, tests-only or --fixup commits
  • When one body of work spans several commits, bump once on the final commit rather than on each
  • Every bump gets a matching annotated tag, v<version>, on the bump commit — a bumped version is never left untagged
  • Tag locally only; never push a tag unless asked
  • worklane --version reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another