diff --git a/.opencode/skill/worklane-kanban-skill/SKILL.md b/.opencode/skill/worklane-kanban-skill/SKILL.md index 295adc3..4db3e58 100644 --- a/.opencode/skill/worklane-kanban-skill/SKILL.md +++ b/.opencode/skill/worklane-kanban-skill/SKILL.md @@ -79,7 +79,7 @@ worklane show "ticket title or uuid" Move a ticket between statuses. **Positional arguments:** -- ``: Ticket UUID (8+ characters) or title +- ``: Ticket UUID prefix (4+ characters) or title **Required options:** - `--status `: Target status (`backlog`, `committed`, `reviewing`, `done`) @@ -103,7 +103,7 @@ worklane mv "My Ticket" --status done -f # Move by title with force Add a comment to a ticket. **Positional arguments:** -- ``: Ticket UUID (8+ characters) or title +- ``: Ticket UUID prefix (4+ characters) or title - ``: Comment text Comments are stored as timestamped markdown files in `.worklane/comments//` and include the git author and timestamp. diff --git a/.opencode/tools/worklane.ts b/.opencode/tools/worklane.ts index 798982e..7bea673 100644 --- a/.opencode/tools/worklane.ts +++ b/.opencode/tools/worklane.ts @@ -155,7 +155,7 @@ export const show = tool({ args: { id: tool.schema .string() - .describe("Ticket UUID (8+ chars) or title substring (required)"), + .describe("Ticket UUID prefix (4+ chars) or title substring (required)"), }, async execute(args: Record, context: ToolContext) { if (!args.id) { @@ -175,7 +175,7 @@ export const mv = tool({ args: { ticket: tool.schema .string() - .describe("Ticket UUID (8+ chars) or title substring (required)"), + .describe("Ticket UUID prefix (4+ chars) or title substring (required)"), status: tool.schema .enum(["backlog", "committed", "reviewing", "done"]) .describe("Target status (required)"), @@ -207,7 +207,7 @@ export const comment = tool({ args: { ticket: tool.schema .string() - .describe("Ticket UUID (8+ chars) or title substring (required)"), + .describe("Ticket UUID prefix (4+ chars) or title substring (required)"), body: tool.schema .string() .describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."), diff --git a/AGENTS.md b/AGENTS.md index 7a3f09e..1db79b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,7 +67,9 @@ ### Ticket Resolution - `resolve_ticket()` returns `(status, title, content)` tuple -- Priority: exact UUID prefix (8+ chars) > title substring > filename substring +- 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 diff --git a/Cargo.lock b/Cargo.lock index 3f42332..9033247 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1029,7 +1029,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.3.3" +version = "0.4.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 20e49a7..d53bf34 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.3.3" +version = "0.4.0" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 9d90e67..bb37e4a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Worklane is a local Kanban flow for agentic software development. | `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`, `--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 show ` | Shows ticket by UUID prefix (4+ chars), title substring, or filename 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/util.rs b/src/util.rs index dfb7503..69dded0 100644 --- a/src/util.rs +++ b/src/util.rs @@ -177,11 +177,28 @@ fn ambiguous(search: &str, matches: &[(String, String, String, String)]) -> anyh anyhow!(message) } -pub fn resolve_ticket(search: &str, worklane_dir: &Path) -> Result<(String, String, String)> { - let statuses = status_dirs(); - let mut matches: Vec<(String, String, String, String)> = Vec::new(); +/// Shortest search tried as a UUID prefix. Below it the search is text, so a one or +/// two character term is a title search rather than a prefix matching half the board. +/// +/// Four, not eight. The guard this replaces read `short_id.len() >= 8`, and `short_id` +/// there was always the full 36 character uuid, so it was always true and any length +/// already worked. Requiring eight would have broken the id the tool prints itself: +/// `ls` shows [`SHORT_ID_WIDTH`] characters, and pasting that back has to resolve. +pub const MIN_ID_SEARCH: usize = 4; - for status in &statuses { +pub fn resolve_ticket(search: &str, worklane_dir: &Path) -> Result<(String, String, String)> { + let search_lower = search.to_lowercase(); + let long_enough_for_an_id = search.chars().count() >= MIN_ID_SEARCH; + + // Three tiers, filled in one pass and consulted in order. A uuid prefix has to win + // outright rather than join a flat list: ticket titles reference other tickets by + // id, so an exact prefix match was reported as ambiguous against whichever title + // happened to mention it. + let mut by_id: Vec<(String, String, String, String)> = Vec::new(); + let mut by_title: Vec<(String, String, String, String)> = Vec::new(); + let mut by_filename: Vec<(String, String, String, String)> = Vec::new(); + + for status in status_dirs() { let status_path = worklane_dir.join(status); if !status_path.exists() { continue; @@ -206,23 +223,34 @@ pub fn resolve_ticket(search: &str, worklane_dir: &Path) -> Result<(String, Stri .file_stem() .map(|s| s.to_string_lossy().to_string()) .unwrap_or_default(); - let short_id = filename.split('_').next().unwrap_or(""); + let uuid = filename.split('_').next().unwrap_or(""); - let search_lower = search.to_lowercase(); - let title_lower = title.to_lowercase(); - let filename_lower = filename.to_lowercase(); + let by_prefix = long_enough_for_an_id && uuid.to_lowercase().starts_with(&search_lower); + let in_title = title.to_lowercase().contains(&search_lower); + // Still reaches the middle of a uuid, which the prefix tier cannot. + let in_filename = filename.to_lowercase().contains(&search_lower); - let id_match = - short_id.to_lowercase().starts_with(&search_lower) && short_id.len() >= 8; - let title_match = title_lower.contains(&search_lower); - let filename_match = filename_lower.contains(&search_lower); + if !(by_prefix || in_title || in_filename) { + continue; + } - if id_match || title_match || filename_match { - matches.push((status.to_string(), title, content, short_id.to_string())); + let found = (status.to_string(), title, content, uuid.to_string()); + if by_prefix { + by_id.push(found); + } else if in_title { + by_title.push(found); + } else { + by_filename.push(found); } } } + let mut matches = match (by_id.is_empty(), by_title.is_empty()) { + (false, _) => by_id, + (true, false) => by_title, + (true, true) => by_filename, + }; + if matches.is_empty() { return Err(anyhow!("No ticket found matching '{}'", search)); } diff --git a/tests/cmd_show.rs b/tests/cmd_show.rs index 1f88f11..46931b9 100644 --- a/tests/cmd_show.rs +++ b/tests/cmd_show.rs @@ -485,3 +485,193 @@ fn show_renders_the_metadata_as_an_aligned_table() { let content = fs::read_to_string(worklane.join("backlog").join(filename)).unwrap(); assert!(content.contains("- **Owner**: alice")); } + +/// Write a ticket with an exact uuid and title, since both matter to resolution. +fn ticket_with(worklane: &std::path::Path, status: &str, uuid: &str, title: &str, slug: &str) { + fs::write( + worklane.join(status).join(format!("{}_{}.md", uuid, slug)), + format!( + "# {}\n\n## Metadata\n\n- **ID**: {}\n- **Status**: {}\n", + title, uuid, status + ), + ) + .unwrap(); +} + +fn show(temp: &TempDir, search: &str) -> std::process::Output { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()).arg("show").arg(search); + cmd.assert().get_output().clone() +} + +/// The bug. A flat OR of the three predicates put an exact uuid prefix and a title +/// that merely mentions it in the same list, so the search reported as ambiguous +/// the very id the listing had just printed. +#[test] +fn show_prefers_a_uuid_prefix_over_a_title_that_mentions_it() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + ticket_with( + &worklane, + "backlog", + "641e3d5d-ef23-4213-8346-e8b0114b84e9", + "Alpha", + "alpha", + ); + ticket_with( + &worklane, + "backlog", + "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", + "Notes on 641e3d5 regression", + "notes", + ); + + let out = show(&temp, "641e3d5"); + let stdout = String::from_utf8_lossy(&out.stdout); + + assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr)); + assert!(stdout.contains("Alpha"), "{stdout:?}"); + assert!(!stdout.contains("Notes on"), "{stdout:?}"); +} + +/// `ls` prints SHORT_ID_WIDTH characters, so pasting that back has to resolve. This +/// is the guard against reinstating an eight character minimum. +#[test] +fn show_resolves_the_short_id_the_listing_prints() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let uuid = "641e3d5d-ef23-4213-8346-e8b0114b84e9"; + ticket_with(&worklane, "backlog", uuid, "Alpha", "alpha"); + + let mut ls = Command::cargo_bin(BIN_NAME).unwrap(); + ls.current_dir(&temp.path()).args(["ls", "backlog"]); + let listing = String::from_utf8(ls.assert().success().get_output().stdout.clone()).unwrap(); + + // Take the id exactly as printed, so this couples to the display width rather + // than to a hardcoded number + let printed = listing + .split('(') + .nth(1) + .and_then(|rest| rest.split(')').next()) + .expect("no id in the listing") + .to_string(); + assert!(printed.len() < 8, "the listing prints {} chars", printed.len()); + + // A decoy whose title quotes that id. Without it the search would still land on + // Alpha through the filename tier, since the filename contains the uuid, and the + // test would pass under a minimum longer than the printed id. + ticket_with( + &worklane, + "backlog", + "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", + &format!("Notes on {} regression", printed), + "notes", + ); + + let out = show(&temp, &printed); + let stdout = String::from_utf8_lossy(&out.stdout); + assert!(out.status.success(), "{printed} did not resolve"); + assert!(stdout.contains("Alpha"), "{stdout:?}"); + assert!(!stdout.contains("Notes on"), "{stdout:?}"); +} + +#[test] +fn show_resolves_a_four_character_uuid_prefix() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + ticket_with( + &worklane, + "backlog", + "641e3d5d-ef23-4213-8346-e8b0114b84e9", + "Alpha", + "alpha", + ); + + let out = show(&temp, "641e"); + assert!(out.status.success()); + assert!(String::from_utf8_lossy(&out.stdout).contains("Alpha")); +} + +/// Below four characters the search is text, so it must not be read as a prefix +/// matching a large slice of the board. +#[test] +fn show_treats_a_search_below_four_characters_as_text() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + ticket_with( + &worklane, + "backlog", + "641e3d5d-ef23-4213-8346-e8b0114b84e9", + "Alpha", + "alpha", + ); + ticket_with( + &worklane, + "backlog", + "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", + "Notes on 641 regression", + "notes", + ); + + // "641" prefixes Alpha's uuid, but it is too short to be read as one, so the + // title match is the only match + let out = show(&temp, "641"); + let stdout = String::from_utf8_lossy(&out.stdout); + + assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr)); + assert!(stdout.contains("Notes on"), "{stdout:?}"); + assert!(!stdout.contains("Alpha"), "{stdout:?}"); +} + +/// The last tier earns its place: it reaches the middle of a uuid, which the prefix +/// tier cannot. +#[test] +fn show_falls_back_to_the_filename_for_a_mid_uuid_substring() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + ticket_with( + &worklane, + "backlog", + "641e3d5d-ef23-4213-8346-e8b0114b84e9", + "Alpha", + "alpha", + ); + + let out = show(&temp, "ef23"); + assert!(out.status.success()); + assert!(String::from_utf8_lossy(&out.stdout).contains("Alpha")); +} + +/// Tiering removes false ambiguity across tiers, not real ambiguity inside one. +#[test] +fn show_still_reports_ambiguity_within_the_uuid_tier() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + ticket_with( + &worklane, + "backlog", + "5eeddeed-1111-2222-3333-444444444444", + "Beta", + "beta", + ); + ticket_with( + &worklane, + "backlog", + "5eedbeef-9999-8888-7777-666666666666", + "Gamma", + "gamma", + ); + + let out = show(&temp, "5eed"); + let stderr = String::from_utf8_lossy(&out.stderr); + + assert!(!out.status.success()); + assert!(stderr.contains("Multiple tickets found"), "{stderr:?}"); + assert!(stderr.contains("Beta") && stderr.contains("Gamma"), "{stderr:?}"); +}