From 5a7cfeb849008d798be0c465f376499524874cef Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Thu, 20 Aug 2026 23:38:29 +0200 Subject: [PATCH] (b8aa66b) Evaluate ticket resolution in tiers, from four characters up, and bump to 0.4.0 resolve_ticket ORed the uuid prefix, title and filename predicates into one flat list, so an exact prefix match was reported as ambiguous against any title that merely mentioned that id. Reproduced: `show 641e3d5` on a board where another ticket's title quoted it failed with "Multiple tickets found", and told the user to use the displayed id, which was the id they had just used. The three tiers are now evaluated in order and the first non-empty one wins outright, which is what AGENTS.md always claimed. The ticket also asked for prefix matching to require eight characters, and that is not implemented. The guard it replaced read short_id.len() >= 8 where short_id was always the full uuid, so it was always true and any length already worked. Eight would have regressed that: ls prints seven characters, so the id the tool displays would drop out of the uuid tier and lose to any title quoting it, which is the very bug above. MIN_ID_SEARCH is four, so a short search is still text and `show 641` remains a title search. Docs corrected in four places that all stated the eight character rule: README, AGENTS.md, the opencode tool descriptions and the kanban skill. Co-Authored-By: Claude Opus 5 (1M context) --- .../skill/worklane-kanban-skill/SKILL.md | 4 +- .opencode/tools/worklane.ts | 6 +- AGENTS.md | 4 +- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 2 +- src/util.rs | 56 ++++-- tests/cmd_show.rs | 190 ++++++++++++++++++ 8 files changed, 243 insertions(+), 23 deletions(-) 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:?}"); +}