# Architecture Where the code lives and what each file owns. ## 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//` directories - History entries stored as `.md` in `.worklane/history//`, 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()` ## 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