cmd_mv renamed the ticket into its new directory and only then wrote the updated content, so a write that failed left the ticket in the target directory still claiming the old status. Reproduced with a read-only ticket file: the move reported a bare "Permission denied" and left the file in committed/ carrying "Status: backlog". move_ticket_file now stages the content in a temp file, renames it over the source, and only then renames the file into the target directory. Two atomic steps, so a partial write is discarded and the original is untouched. The other obvious order, writing to the target and deleting the source afterwards, was rejected because it has the ticket in two directories at once. The worst case left is a ticket still in its old directory with a Status one move ahead, which the next mv corrects since the directory is what decides the current status. Tested, including the retry. The temp file is staged under .worklane/ rather than beside the ticket, so a leftover from a hard kill is invisible to ticket lookup and to the listing instead of appearing as a stray untitled ticket. IO errors now name the ticket and the path rather than propagating bare. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7.7 KiB
7.7 KiB
AGENTS.md
Project Structure
src/main.rs- All application logicsrc/command.rs- CLI argument definitions using clap derivetests/- Integration tests usingassert_cmdandassert_fs- Ticket files stored as
.mdin.worklane/<status>/directories
Ticket File Format
- Filenames:
<uuid_v4>_<slug>.md - 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>.mdwith**Comment**,**Author**,**Time**fields
Status Workflow
backlog → committed → reviewing → done
Testing
- Run:
cargo test - Tests use
assert_cmdandassert_fsfor CLI testing setup_worklane()creates temp.worklane/with all four status folders pre-createdcreate_ticket()writes fully-formed markdown files directly (no--separator for positional args in test commands)
Coding Guidelines
Rust Style
- Use
if matches!(expr, Variant)instead ofif let Some(Variant) = exprfor enum variant matching - Use
if let Some(x) = exprinstead ofif let Some(Some(x)) = expr— drop unnecessary nesting - Prefer explicit
matchoverunwrap_or_default()for clarity - Use
unwrap_or_else(|| expr)for lazy defaults,unwrap_or(val)for eager defaults - Use
anyhow!()with context strings that include identifying info (e.g. UUID, title) not bare values
CLI Arguments
- The prose arguments carry
allow_hyphen_values, via thePROSEconstant incommand.rs:add --title,--description,--acceptance,--plan, and thecommentbody. Ticket text quotes flag names constantly, and without it a criterion reading--print is supportedis parsed as a flag and the whole ticket is refused with nothing written - The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why
due,priority,tags,ownerandstatusare deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not addPROSEto a new argument unless it holds prose - The ticket positionals (
show <id>,mv <ticket>,comment <ticket>) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with--, as inmv --status committed -- -leading-title - A bare
--is a value when it follows an option (--title --stores--) and clap's end-of-options marker when it sits in a positional. So acommentbody of exactly--needs its own separator,comment <ticket> -- --. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop addhas no positionals, so anything after a bare--is an unexpected argument and fails
Color and Output
- Use
color_text()helper for colored output — it respectsshould_use_colors()(terminal detection) - Color codes are defined in
get_color(): red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9) - Reset color with
\x1b[0mafter colored text - Bold uses
\x1b[1;35m(magenta bold) - Always test color output works correctly in both terminal and pipe modes
quiet_broken_pipe()runs first inmain, restoring the defaultSIGPIPEdisposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of makingprintln!panic. Do not wrap prints to handle write errors and do not reinstateSIG_IGN; the exit codes are documented in the README
Color Guideline
- UUID → red (31)
- Status → orange (33)
- Timestamp → cyan (36)
- Title → green (32)
- Unknown values (
_None_,_Not set_) → grey (38;5;8) - Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground.
\x1b[38;5;8mis byte for byte what crossterm emits for ratatui'sColor::DarkGray, the grey frig and pantop use for dimmed rows
Code Organization
- Colorization functions (
colorize_line,colorize_ordered,content_trim_colored) handle markdown formatting showrenders the Metadata section as a two column table viarender_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()iscolor_text()with the colour decision passed in, which is what lets a test render both ways in one process- The title is printed once, by
cmd_show.content_trim_coloredskips the#heading in the file content - Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
resolve_ticket()scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filenameparse_ticket_field()handles extracting metadata values from markdown formatmove_ticket_file()stages the updated content in a temp file under.worklane/, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the nextmvcorrects- Field lookup, read and write, is scoped to the lines under the
## Metadataheading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead.set_status_field()carries the same scoping
Ticket Resolution
resolve_ticket()returns(status, title, content)tuple- Priority: exact UUID prefix (8+ chars) > title substring > filename substring
- 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
--fixupfor incremental changes - Test before moving to reviewing status
Version Bumps
- Before every commit, decide whether the change warrants a version bump in
Cargo.toml - Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
- 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
--fixupcommits - When one body of work spans several commits, bump once on the final commit rather than on each
- Bump
Cargo.tomland theworklaneentry inCargo.locktogether, 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 --versionreports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another