Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 3085b0226f (4179958) Add a Relations section for blocked by, regression of and relates to, and bump to 0.11.0
`relate` is the only writer of the section, the way `chown` is the only writer of
Owner: a relation names a target that has to be resolved to a uuid first, so `set`
and `append` are deliberately kept out of it. One flag per kind, so an unknown kind
is a usage error rather than a line refused on the way back out.

One direction is stored and the inverse is derived by a scan. `blocked by` goes on
the gated ticket, whose move `mv` now refuses while the target is not done, naming
every open blocker; `-f` bypasses it beside the backward and skipping moves. A
target that is not on the board warns and allows the move.

The rendered block is built outside `content_trim` and passed in, since half of it
comes from other tickets. The section is created on demand rather than by `add`, so
a ticket written before it existed gains it without being regenerated.

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

34 KiB

AGENTS.md

Project Structure

  • src/main.rs - dispatch, the SIGPIPE reset, and the TUI event loop
  • src/command.rs - CLI argument definitions using clap derive
  • src/handlers.rs - one cmd_* per subcommand
  • src/util.rs - the ticket format, resolution, rendering and the palette
  • src/tui.rs - board state, the change digest, and the ratatui draw
  • src/install.rs - the embedded agent assets and the compare-and-refuse install
  • assets/SKILL.md - the agent skill install-skill ships, embedded with include_str!
  • tests/ - Integration tests using assert_cmd and assert_fs, one file per command
  • Unit tests live beside the code in #[cfg(test)] mod tests, in util.rs, handlers.rs and tui.rs
  • Ticket files stored as .md in .worklane/<status>/ directories

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, Status
  • Format: **Field Name**: value
  • Ticket structure: # Title → ## Description → ## Acceptance Criteria → ## Implementation Plan → ## Metadata
  • Comments stored in .worklane/comments/<ticket_uuid>/<timestamp>.md with **Comment**, **Author**, **Time** fields

Status Workflow

backlog → committed → reviewing → done

How to use worklane is in assets/SKILL.md, not here. That document is what worklane install-skill ships, so it is the one place the flow, the move-as-you-work rule and the argument traps are written down. Read it before working a ticket in this repo. Do not restate any of it in this file: a second copy is a copy that goes stale, and this file is for what someone changing worklane's own code needs.

Testing

  • Run: cargo test
  • Tests use assert_cmd and assert_fs for CLI testing
  • setup_worklane() creates temp .worklane/ with all four status folders pre-created
  • create_ticket() writes fully-formed markdown files directly (no -- separator for positional args in test commands)
  • cargo clippy --all-targets is clean. Keep it clean, and do not silence a lint that is pointing at something real. The only two allows in the tree sit on the create_ticket fixtures in cmd_mv.rs and cmd_show.rs, each carrying the reason and what would replace it

Coding Guidelines

Rust Style

  • Use if matches!(expr, Variant) instead of if let Some(Variant) = expr for enum variant matching
  • Use if let Some(x) = expr instead of if let Some(Some(x)) = expr — drop unnecessary nesting
  • Prefer explicit match over unwrap_or_default() for clarity
  • Use unwrap_or_else(|| expr) for lazy defaults, unwrap_or(val) for eager defaults
  • Use anyhow!() with context strings that include identifying info (e.g. UUID, title) not bare values
  • A command whose arguments run past a handful takes a clap Args struct, not an inline variant with a matching parameter list: AddArgs, SetArgs, AppendArgs, CheckArgs. add was nine positional parameters threaded from main before it became AddArgs, and the handler destructures the struct so the body reads the same as before

CLI Arguments

  • The prose arguments carry allow_hyphen_values, via the PROSE constant in command.rs: add --title, --description, --acceptance, --plan, and the comment body. Ticket text quotes flag names constantly, and without it a criterion reading --print is supported is parsed as a flag and the whole ticket is refused with nothing written
  • The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why due, priority, tags, owner and status are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add PROSE to a new argument unless it holds prose
  • 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

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). Do not add either
  • 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
  • Sections are a table in util.rs: DESCRIPTION, ACCEPTANCE, PLAN, each with a heading, a label, the placeholder add writes when empty, and a SectionKind. 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 in command.rs. Clearing a field is not supported yet, and the error says so rather than guessing
  • 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_criterion() splices only the character between the brackets. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox
  • The criterion argument is an index first, a substring second, so a criterion whose text is literally 2 is reachable only by substring
  • 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
  • show numbers the criteria as 1. [x] text, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it

Relating Tickets

  • The Relations section is relate's alone. RELATIONS is in the section table but deliberately out of section_args, so set and append cannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer
  • add does not write the section. The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A _No relations._ block in every new ticket is noise in every show, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two
  • The full uuid is stored, not the seven characters ls prints. It resolves without a scan and cannot turn ambiguous as the board grows. show renders the short id and the target's title instead: the file is the machine's copy, the output is the reader's
  • One direction is stored and the inverse is derived. blocked by goes on the gated ticket rather than blocks on the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency. relates to is symmetric and is written once, on whichever end the caller ran it from. RelationIndex::inbound finds the far end by scanning, which is what keeps relate a single-file write
  • A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but relate writes there, so a bad line means a hand-edited file. The TUI is the deliberate exception: detail_of falls back to no block, since one corrupt ticket must not take the whole board down
  • The block is built outside content_trim and passed in. Half of it comes from other tickets and content_trim has only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show
  • ensure_section inserts against SECTION_ORDER, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten ## Notes between the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to
  • The blocker check runs on every move, after the already-in-that-status return and behind force. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused. -f now bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true
  • A blocker that is not on the board warns and allows the move. Refusing would wedge the ticket with no way out but -f, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names every open blocker, since clearing the one that happened to be printed would leave the ticket blocked
  • Left out on purpose: removing a relation, which 4179958 assigns to 74904dc, and a blocked marker on the TUI card, which is its own ticket. Nothing on a card is worth a scan of the board per tick until the card is designed for it

The Board View

  • worklane with no subcommand and worklane tui both open it, the way a bare frig does. Cli::command is therefore an Option
  • The worklane directory is looked for before the terminal, so running outside one gives the usual "No .worklane directory found" rather than a complaint about the tty. Both errors stay reachable and both are testable without a pty
  • A missing tty is refused with a message naming a subcommand. Raw mode on a pipe fails with a bare "No such device or address (os error 6)", which explains nothing
  • The watch looks at files, not directories. A directory's mtime only moves on create and rename, so a ticket edited in place would be missed. digest() hashes every ticket and comment file's path, length and mtime. Comment files are in it because a comment added elsewhere has to reach the detail view
  • The digest guards the rescan, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not
  • notify is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
  • Cards come from collect_ticket_items, the same source ls uses, so there is no second parser. TicketItem::path exists for the detail view
  • The detail view scrolls on pgup and pgdn, not on up and down. Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
  • The scroll offset is clamped against the wrapped line count, from Paragraph::line_count, which is why ratatui carries the unstable-rendered-line-info feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
  • The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
  • The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does not reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
  • 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
  • The overlay names its ticket on the border, not at the head of the paragraph. Board::detail is a Detail carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: content_trim drops the # heading on purpose, since cmd_show prints it, and anything in the paragraph scrolls away
  • detail_title cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
  • The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. content_trim and format_comments_with take the colour decision for that reason
  • Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
  • A card is four corners with the title between them: mark and short id top left, due top right, owner bottom left, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both were invisible at the end of a line of prose
  • The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
  • A card's height therefore depends on the column's width, so card_lines and card_height both take it. column_areas is shared between the draw and follow_selection for the same reason: Ratio hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
  • A corner that will not fit is dropped whole, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
  • The criteria count is a field on TicketItem, filled in collect_ticket_items where the file is already being read, and counted through criteria() so a checkbox in a description is not counted here or numbered by show. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. None rather than [0/0] for a ticket with no criteria
  • due_date cuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"
  • Done is hidden until d asks for it. Not a new opinion: ls already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line
  • Hiding is a change to what is drawn, never to what is read. reload still scans the done directory and digest still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan
  • visible() returns a prefix of columns, not a filter, which is what keeps column and offsets valid as indices into either. It is derived from where DONE actually sits rather than assuming the last slot, and the_done_column_is_last pins the assumption. A status inserted after done would otherwise hide two columns in silence
  • Hiding the column under the selection moves the selection to the last drawn column and closes an open detail view. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted
  • The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
  • Assert a column heading against the top border row, not the whole screen. The footer names done too, so screen.contains("done (0)") passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; headings() and footer() exist so the next one does not. headings() locates the row through board_area() rather than taking row zero, since the tab row sits above it when more than one board is monitored

Monitoring Several Boards

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

Shipping the Agent Assets

  • The skill is embedded with include_str! from assets/SKILL.md, not copied by an install script. cargo install places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
  • One install path serves both agents: ~/.claude/skills/worklane/SKILL.md. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own ~/.config/opencode/skill/. Verified against opencode 1.15.10, whose built-in customize-opencode skill documents the table and whose opencode debug skill lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
  • Asset carries the content, the path under its root and the word used in messages, so install-tool adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is install.rs and not skill.rs
  • install() takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects HOME for the same reason
  • A modified copy is refused, not overwritten. Someone may have edited it on purpose, and the message names --print so it can be diffed and --force so it can be replaced. A read error is not treated as absent either: the write reports the real reason
  • Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every worklane <x> the skill shows has to be a real subcommand, and every subcommand outside NOT_FOR_AGENTS has to appear in the skill. The last one catches a new command that nothing tells an agent about
  • install-skill looks for no board. The skill is what teaches an agent worklane, so needing a .worklane to install it would put it out of reach exactly when it is wanted
  • The assets under .opencode/ are the user's, not this repo's to ship. Do not embed or install them

Color and Output

  • Use color_text() for coloured output — it respects should_use_colors() (terminal detection), and paint() is the same with the decision passed in
  • color_text() is for the CLI's own printing only. Anything reachable from content_trim takes the decision as an argument and calls paint(), because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. nothing_the_body_renders_asks_the_terminal_for_the_colour_decision scans this file and fails on a new caller; the allowlist is ambiguous, which builds a failed-search message for stderr
  • A function that takes an enabled flag must use it all the way down. colorize_bold honoured its flag on the early return and then asked should_use_colors() for the bold run, which made the flag a lie in half the function
  • A test that asserts an absence has to be paired with one that asserts the presence. The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so should_use_colors() was false and the leaking branch was never taken. The pair is now content_trim(.., false) has no escape and content_trim(.., true) still colours, which pins the flag as the only thing that decides
  • The palette is the Color enum, not a string. Color::ansi() gives the CLI its SGR sequence and From<Color> for ratatui::style::Color gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how magenta came to be undefined
  • Reset color with \x1b[0m after colored text
  • Bold uses \x1b[1;35m (magenta bold)
  • Always test color output works correctly in both terminal and pipe modes
  • quiet_broken_pipe() runs first in main, restoring the default SIGPIPE disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making println! panic. Do not wrap prints to handle write errors and do not reinstate SIG_IGN; the exit codes are documented in the README

Color Guideline

  • UUID → red (31)
  • Status → orange (33)
  • Timestamp → cyan (36)
  • Title → green (32)
  • Unknown values (_None_, _Not set_) → grey (38;5;8)
  • Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
  • Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. \x1b[38;5;8m is byte for byte what crossterm emits for ratatui's Color::DarkGray, the grey frig and pantop use for dimmed rows

Code Organization

  • Colorization functions (colorize_ordered, colorize_bold, content_trim_colored) handle markdown formatting. colorize_line is gone: it was a pub alias for colorize_bold with one caller, and the only thing it added was asking the terminal
  • show renders the Metadata section as a two column table via render_metadata_table, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. paint() is color_text() with the colour decision passed in, which is what lets a test render both ways in one process
  • The title is printed once, by cmd_show. content_trim_colored skips the # heading in the file content
  • Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
  • resolve_ticket() scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
  • parse_ticket_field() handles extracting metadata values from markdown format
  • move_ticket_file() stages the updated content in a temp file under .worklane/, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the next mv corrects
  • Field lookup, read and write, is scoped to the lines under the ## Metadata heading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead. set_status_field() carries the same scoping

Ticket Resolution

  • resolve_ticket() returns (status, title, content) tuple
  • Three tiers, evaluated in order: 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 three reported an exact prefix match as ambiguous against whichever title mentioned it
  • 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 _Not set_ or _None_ as defaults

Git Workflow

  • Commit format: ([ticketID]) [short description]
  • Use --fixup for incremental changes
  • Test before moving to reviewing status

Version Bumps

  • Before every commit, decide whether the change warrants a version bump in Cargo.toml
  • Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
  • Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
  • No bump for docs-only, tests-only or --fixup commits
  • When one body of work spans several commits, bump once on the final commit rather than on each
  • Bump Cargo.toml and the worklane entry in Cargo.lock together, in the commit that carries the bump
  • Every bump gets a matching annotated tag, v<version>, on the bump commit — a bumped version is never left untagged
  • Tag locally only; never push a tag unless asked
  • worklane --version reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another