From ddbd45e332b815ada42531f90eee61c992b86a7b Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Thu, 20 Aug 2026 15:36:19 +0200 Subject: [PATCH] (dca0b61) Add priority as a ticket field Priority lived in tags, as p1 to p3, which ls could neither sort nor filter on, nothing validated, and a typo like P1 passed silently. ls sorted by title only, so a backlog of any size gave no ordering signal. Levels are 1 to 5 with 1 most urgent, matching what the tags meant. Omitting the flag leaves the field _Not set_, like Due and Owner: there is no implicit middle level, because a priority nobody chose is worse than none. clap rejects anything outside the range before a ticket is written. Priority parses to three states rather than two. A stored value outside the range is Invalid, kept distinct from Unset, so a typo cannot read as "no priority": it shows as ? and sorts just ahead of the unset tail. ls sorts on priority and falls back to the old title sort, and --priority filters, composing with the status filter in both the grouped and the filtered listing. TicketItem becomes a struct, since a sixth tuple field was past reading. Migrated the 31 tickets already carrying p1 to p3 tags: the level moves to the field and the tag is dropped. Co-Authored-By: Claude Opus 5 (1M context) --- .../skill/worklane-kanban-skill/SKILL.md | 11 +- .opencode/tools/worklane.ts | 12 +- AGENTS.md | 2 +- README.md | 4 +- src/command.rs | 22 +++ src/handlers.rs | 31 +++- src/main.rs | 6 +- src/util.rs | 150 +++++++++++++++--- tests/cmd_add.rs | 63 ++++++++ tests/cmd_ls.rs | 58 +++++++ 10 files changed, 325 insertions(+), 34 deletions(-) diff --git a/.opencode/skill/worklane-kanban-skill/SKILL.md b/.opencode/skill/worklane-kanban-skill/SKILL.md index 3d0e683..295adc3 100644 --- a/.opencode/skill/worklane-kanban-skill/SKILL.md +++ b/.opencode/skill/worklane-kanban-skill/SKILL.md @@ -37,6 +37,7 @@ Add a new ticket to the backlog. - `--tags` (or `-g`): Tags (comma-separated) - `--due` (or `--due`): Due date in YYYY-MM-DD format - `--owner` (or `-o`): Owner name +- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted ```bash worklane add -t "Implement login" -d "Add user login page" -t login,auth -p "Design UI" "Build backend" "Write tests" --due 2026-06-01 --owner "ilya" @@ -56,11 +57,15 @@ List tickets, optionally filtered by status. **Valid statuses:** `backlog`, `committed`, `reviewing`, `done` ``` -worklane ls # List all tickets -worklane ls backlog # List tickets in backlog -worklane ls done # List completed tickets +worklane ls # List all tickets +worklane ls backlog # List tickets in backlog +worklane ls done # List completed tickets +worklane ls --priority 1 # Only the most urgent, any status +worklane ls backlog --priority 2 # Composes with the status filter ``` +Tickets are listed priority first, then by title. Tickets with no priority sort last. + ### `worklane show` Show the full details of a single ticket by UUID or title. diff --git a/.opencode/tools/worklane.ts b/.opencode/tools/worklane.ts index 3fc21d8..798982e 100644 --- a/.opencode/tools/worklane.ts +++ b/.opencode/tools/worklane.ts @@ -76,6 +76,10 @@ export const add = tool({ owner: tool.schema .string() .describe("Ticket owner name. If omitted, defaults to the git user."), + priority: tool.schema + .string() + .describe("Priority level, 1 (most urgent) to 5 (least). Left unset if omitted.") + .optional(), }, async execute(args: Record, context: ToolContext) { if (!args.title) { @@ -109,6 +113,7 @@ export const add = tool({ if (args.tags) cmd.push("--tags", args.tags); if (args.due) cmd.push("--due", args.due); if (args.owner) cmd.push("--owner", args.owner); + if (args.priority) cmd.push("--priority", String(args.priority)); try { return await run(cmd, context); @@ -120,15 +125,20 @@ export const add = tool({ export const ls = tool({ description: - "List all worklane tickets. Optionally filter by status (backlog, committed, reviewing, done).", + "List all worklane tickets, sorted by priority then title. Optionally filter by status and by priority.", args: { status: tool.schema .enum(["backlog", "committed", "reviewing", "done"]) .describe("Filter by status") .optional(), + priority: tool.schema + .string() + .describe("Only show tickets at this priority, 1 (most urgent) to 5 (least)") + .optional(), }, async execute(args: Record, context: ToolContext) { const cmd = args.status ? ["ls", args.status] : ["ls"]; + if (args.priority) cmd.push("--priority", String(args.priority)); try { return await run(cmd, context); } catch (err: any) { diff --git a/AGENTS.md b/AGENTS.md index 0afe902..55705bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ ## Ticket File Format - Filenames: `_.md` -- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Tags`, `Due`, `Owner`, `Created At`, `Status` +- 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//.md` with `**Comment**`, `**Author**`, `**Time**` fields diff --git a/README.md b/README.md index caafdfe..ba3be74 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ Worklane is a local Kanban flow for agentic software development. | Command | Description | |---------|-------------| | `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories | -| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner` flags | -| `worklane ls` | Lists tickets, optionally filtered by `--status` | +| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags | +| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>` | | `worklane show ` | Shows ticket by UUID prefix (8+ chars) or title substring | | `worklane mv --status [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions | | `worklane comment ` | Adds a comment to a ticket by UUID or title | diff --git a/src/command.rs b/src/command.rs index 444c105..da78245 100644 --- a/src/command.rs +++ b/src/command.rs @@ -1,5 +1,19 @@ use clap::Parser; +use crate::util::PRIORITY_RANGE; + +/// Reject a level outside the range at parse time, so no command has to. +fn priority_level(raw: &str) -> Result { + match raw.parse::() { + Ok(level) if PRIORITY_RANGE.contains(&level) => Ok(level), + _ => Err(format!( + "priority must be a whole number from {} to {}", + PRIORITY_RANGE.start(), + PRIORITY_RANGE.end() + )), + } +} + /// What `--version` prints: the crate version and the commit it was built from. /// /// The sha is the part that matters. Two binaries built weeks apart both call @@ -51,12 +65,20 @@ pub enum Command { /// Owner #[arg(short, long)] owner: Option, + + /// Priority, 1 (most urgent) to 5 (least). Left unset if omitted. + #[arg(long, value_parser = priority_level)] + priority: Option, }, /// List tickets, optionally filtered by status Ls { /// Filter by status (backlog, committed, reviewing, done) status: Option, + + /// Only show tickets at this priority, 1 (most urgent) to 5 (least) + #[arg(long, value_parser = priority_level)] + priority: Option, }, /// Show a ticket by UUID or title diff --git a/src/handlers.rs b/src/handlers.rs index 432736a..0f15b28 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -29,7 +29,11 @@ pub fn cmd_init(start: &Path) -> Result<()> { Ok(()) } -pub fn cmd_ls(status_filter: &Option, worklane_dir: &Path) -> Result<()> { +pub fn cmd_ls( + status_filter: &Option, + priority_filter: Option, + worklane_dir: &Path, +) -> Result<()> { if let Some(status) = status_filter { let status_path = worklane_dir.join(status); if !status_path.exists() { @@ -39,7 +43,7 @@ pub fn cmd_ls(status_filter: &Option, worklane_dir: &Path) -> Result<()> )); } - let items = collect_ticket_items(&status_path)?; + let items = filter_by_priority(collect_ticket_items(&status_path)?, priority_filter); if items.is_empty() { println!("No tickets in '{}' status.", status); @@ -57,8 +61,8 @@ pub fn cmd_ls(status_filter: &Option, worklane_dir: &Path) -> Result<()> if !status_path.exists() { continue; } - let entries: Vec<_> = fs::read_dir(&status_path)?.filter_map(|e| e.ok()).collect(); - let count = entries.len(); + let items = filter_by_priority(collect_ticket_items(&status_path)?, priority_filter); + let count = items.len(); let label = if count == 1 { "ticket" } else { "tickets" }; println!(" [{}] {} {}", status.to_uppercase(), count, label); } @@ -73,7 +77,7 @@ pub fn cmd_ls(status_filter: &Option, worklane_dir: &Path) -> Result<()> continue; } let items = match collect_ticket_items(&status_path) { - Ok(items) => items, + Ok(items) => filter_by_priority(items, priority_filter), Err(_) => continue, }; if items.is_empty() { @@ -88,6 +92,17 @@ pub fn cmd_ls(status_filter: &Option, worklane_dir: &Path) -> Result<()> Ok(()) } +/// Keep only the tickets at `level`, or everything when no level was asked for. +fn filter_by_priority(items: Vec, level: Option) -> Vec { + match level { + Some(level) => items + .into_iter() + .filter(|item| item.priority == Priority::Level(level)) + .collect(), + None => items, + } +} + pub fn cmd_add( title: &str, description: &[String], @@ -96,6 +111,7 @@ pub fn cmd_add( tags: &[String], due: &Option, owner: &Option, + priority: Option, start: &Path, ) -> Result<()> { let owner = match owner { @@ -141,6 +157,7 @@ pub fn cmd_add( ## Metadata\n\ \n\ - **ID**: {}\n\ + - **Priority**: {}\n\ - **Tags**: {}\n\ - **Due**: {}\n\ - **Owner**: {}\n\ @@ -168,6 +185,10 @@ pub fn cmd_add( .join("\n") }, id, + match priority { + Some(level) => level.to_string(), + None => "_Not set_".to_string(), + }, if tags.is_empty() { "_None_".to_string() } else { diff --git a/src/main.rs b/src/main.rs index d737372..7756165 100644 --- a/src/main.rs +++ b/src/main.rs @@ -24,6 +24,7 @@ fn main() -> Result<()> { tags, due, owner, + priority, } => cmd_add( &title, &description, @@ -32,11 +33,12 @@ fn main() -> Result<()> { &tags, &due, &owner, + priority, &start, ), - Command::Ls { status } => { + Command::Ls { status, priority } => { let worklane_dir = find_worklane_dir(&start)?; - cmd_ls(&status, &worklane_dir) + cmd_ls(&status, priority, &worklane_dir) } Command::Show { id } => { let worklane_dir = find_worklane_dir(&start)?; diff --git a/src/util.rs b/src/util.rs index 2042363..72def90 100644 --- a/src/util.rs +++ b/src/util.rs @@ -496,7 +496,54 @@ pub fn status_dirs() -> Vec<&'static str> { vec!["backlog", "committed", "reviewing", "done"] } -pub type TicketItem = (String, String, String, String, String); +/// Lowest and highest level a ticket can carry. 1 is the most urgent, which is +/// what the `p1` to `p3` tags this replaced already meant. +pub const PRIORITY_RANGE: std::ops::RangeInclusive = 1..=5; + +/// A ticket's priority as it comes off disk. +/// +/// Three states, not two: a value outside the range has to stay distinguishable +/// from no value at all, or a typo silently reads as "no priority". +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Priority { + Level(u8), + Unset, + Invalid, +} + +impl Priority { + /// Sort weight. Levels first in order, then anything wrong, then anything + /// absent, so a typo surfaces above the long tail of unset tickets. + pub fn rank(&self) -> u8 { + match self { + Priority::Level(level) => *level, + Priority::Invalid => u8::MAX - 1, + Priority::Unset => u8::MAX, + } + } +} + +pub fn parse_priority(content: &str) -> Priority { + let raw = parse_ticket_field(content, "Priority"); + + if is_unknown_value(&raw) { + return Priority::Unset; + } + + match raw.trim().parse::() { + Ok(level) if PRIORITY_RANGE.contains(&level) => Priority::Level(level), + _ => Priority::Invalid, + } +} + +pub struct TicketItem { + pub title: String, + pub owner: String, + pub due: String, + pub id: String, + pub created: String, + pub priority: Priority, +} /// Grey for a value that is not set, per the colour guideline. /// @@ -510,22 +557,32 @@ fn dim_if_unset(value: &str) -> String { } } -pub fn display_ticket_items(items: &Vec) { - for (title, owner, due, uuid, ts) in items { - let uuid_colored = color_text(uuid, "red"); - let owner = dim_if_unset(owner); - let due = dim_if_unset(due); +/// How a level reads in a listing. +fn show_priority(priority: Priority) -> String { + match priority { + Priority::Level(level) => level.to_string(), + Priority::Unset => color_text("-", "grey"), + Priority::Invalid => color_text("?", "red"), + } +} - if ts.is_empty() { - println!( - " ({}) {} | Owner: {} | Due: {}", - uuid_colored, title, owner, due - ); - } else { - let ts_colored = color_text(ts, "cyan"); +pub fn display_ticket_items(items: &[TicketItem]) { + for item in items { + let id = color_text(&item.id, "red"); + let owner = dim_if_unset(&item.owner); + let due = dim_if_unset(&item.due); + let priority = show_priority(item.priority); + + if item.created.is_empty() { println!( " {} ({}) {} | Owner: {} | Due: {}", - ts_colored, uuid_colored, title, owner, due + priority, id, item.title, owner, due + ); + } else { + let created = color_text(&item.created, "cyan"); + println!( + " {} {} ({}) {} | Owner: {} | Due: {}", + priority, created, id, item.title, owner, due ); } } @@ -547,19 +604,25 @@ pub fn collect_ticket_items(status_path: impl AsRef) -> Result String { + format!("# T\n\n## Metadata\n\n- **Priority**: {}\n", raw) + } + + #[test] + fn a_level_in_range_parses() { + for level in 1..=5u8 { + let content = ticket_with_priority(&level.to_string()); + assert_eq!(parse_priority(&content), Priority::Level(level)); + } + } + + #[test] + fn a_missing_or_unset_level_is_unset() { + assert_eq!(parse_priority("# T\n\n## Metadata\n"), Priority::Unset); + assert_eq!(parse_priority(&ticket_with_priority("_Not set_")), Priority::Unset); + assert_eq!(parse_priority(&ticket_with_priority("_None_")), Priority::Unset); + } + + /// Distinct from unset on purpose: a typo must not read as "no priority". + #[test] + fn an_out_of_range_or_unparseable_level_is_invalid() { + for raw in ["0", "6", "42", "high", "-1", "1.5", "999999999999"] { + assert_eq!( + parse_priority(&ticket_with_priority(raw)), + Priority::Invalid, + "for {raw:?}" + ); + } + } + + #[test] + fn levels_sort_ahead_of_invalid_which_sorts_ahead_of_unset() { + let mut ranks = [Priority::Unset, Priority::Level(5), Priority::Invalid, Priority::Level(1)] + .map(|p| p.rank()); + ranks.sort(); + assert_eq!( + ranks, + [ + Priority::Level(1).rank(), + Priority::Level(5).rank(), + Priority::Invalid.rank(), + Priority::Unset.rank() + ] + ); + } + #[test] fn every_colour_the_code_asks_for_exists() { for colour in ["red", "cyan", "orange", "green", "grey", "magenta"] { diff --git a/tests/cmd_add.rs b/tests/cmd_add.rs index 2e41bcc..51ce760 100644 --- a/tests/cmd_add.rs +++ b/tests/cmd_add.rs @@ -199,3 +199,66 @@ fn add_file_has_uuid_prefix() { assert_eq!(parts[0].len(), 36); assert_eq!(parts[0].chars().filter(|c| c.is_ascii_hexdigit()).count(), 32); } + +#[test] +fn add_writes_the_priority_field() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + Command::cargo_bin(BIN_NAME) + .unwrap() + .current_dir(&temp.path()) + .args(["add", "--title", "Urgent thing", "--priority", "1"]) + .assert() + .success(); + + let files: Vec<_> = fs::read_dir(temp.child(".worklane").join("backlog")) + .unwrap() + .filter_map(|e| e.ok()) + .collect(); + let content = fs::read_to_string(files[0].path()).unwrap(); + assert!(content.contains("- **Priority**: 1"), "was {content:?}"); +} + +#[test] +fn add_leaves_priority_unset_when_omitted() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + Command::cargo_bin(BIN_NAME) + .unwrap() + .current_dir(&temp.path()) + .args(["add", "--title", "Whenever"]) + .assert() + .success(); + + let files: Vec<_> = fs::read_dir(temp.child(".worklane").join("backlog")) + .unwrap() + .filter_map(|e| e.ok()) + .collect(); + let content = fs::read_to_string(files[0].path()).unwrap(); + assert!(content.contains("- **Priority**: _Not set_"), "was {content:?}"); +} + +/// Rejected at parse time, so no ticket is written at all. +#[test] +fn add_rejects_a_level_outside_the_range() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + // The `=` form, so a negative value reaches the validator instead of being + // read as a flag. + for bad in ["0", "6", "high", "-1"] { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title", "Bad level", &format!("--priority={bad}")]) + .assert() + .failure(); + + let stderr = String::from_utf8(cmd.assert().get_output().stderr.clone()).unwrap(); + assert!(stderr.contains("priority must be"), "for {bad}: {stderr}"); + } + + let count = fs::read_dir(worklane.join("backlog")).unwrap().count(); + assert_eq!(count, 0, "a ticket was written despite a bad level"); +} diff --git a/tests/cmd_ls.rs b/tests/cmd_ls.rs index 2d8cacc..b6447ee 100644 --- a/tests/cmd_ls.rs +++ b/tests/cmd_ls.rs @@ -216,3 +216,61 @@ fn ls_survives_a_malformed_created_at() { // Unparseable, so the timestamp column is dropped rather than printed raw assert!(!stdout.contains("日本語")); } + +fn create_ticket_with_priority(worklane_dir: &std::path::PathBuf, title: &str, priority: &str) { + let slug: String = title.to_lowercase().replace(' ', "-"); + let body = format!( + "# {}\n\n## Metadata\n\n- **ID**: 00000000-0000-0000-0000-00000000000{}\n\ + - **Priority**: {}\n- **Tags**: test\n- **Due**: _Not set_\n\ + - **Owner**: alice\n- **Status**: backlog\n", + title, + slug.len() % 10, + priority + ); + let filename = format!("0000000{}-0000-0000-0000-000000000001_{}.md", slug.len() % 10, slug); + fs::write(worklane_dir.join("backlog").join(filename), body).unwrap(); +} + +#[test] +fn ls_sorts_by_priority_then_title() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket_with_priority(&worklane, "Zebra urgent", "1"); + create_ticket_with_priority(&worklane, "Apple later", "4"); + create_ticket_with_priority(&worklane, "Middle one", "2"); + create_ticket(&worklane, "backlog", "No priority at all", "alice", "_Not set_"); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()).arg("ls").arg("backlog"); + let stdout = get_stdout(&mut cmd); + + let at = |needle: &str| stdout.find(needle).unwrap_or_else(|| panic!("{needle} missing")); + assert!(at("Zebra urgent") < at("Middle one"), "priority 1 must lead"); + assert!(at("Middle one") < at("Apple later"), "2 before 4"); + // Unset sorts last even though its title would come first alphabetically + assert!(at("Apple later") < at("No priority at all"), "unset must trail"); +} + +#[test] +fn ls_filters_by_priority_and_composes_with_status() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket_with_priority(&worklane, "Urgent one", "1"); + create_ticket_with_priority(&worklane, "Lower one", "3"); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["ls", "backlog", "--priority", "1"]); + let stdout = get_stdout(&mut cmd); + assert!(stdout.contains("Urgent one")); + assert!(!stdout.contains("Lower one"), "filter let a level 3 through"); + + // Same filter without a status, through the grouped listing + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()).args(["ls", "--priority", "3"]); + let stdout = get_stdout(&mut cmd); + assert!(stdout.contains("Lower one")); + assert!(!stdout.contains("Urgent one")); +}