(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) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-20 15:36:19 +02:00
co-authored by Claude Opus 5
parent b7781a830c
commit ddbd45e332
10 changed files with 325 additions and 34 deletions
@@ -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.
+11 -1
View File
@@ -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<string, any>, 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<string, any>, 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) {
+1 -1
View File
@@ -8,7 +8,7 @@
## Ticket File Format
- Filenames: `<uuid_v4>_<slug>.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/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
+2 -2
View File
@@ -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 <id>` | Shows ticket by UUID prefix (8+ chars) or title substring |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
+22
View File
@@ -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<u8, String> {
match raw.parse::<u8>() {
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<String>,
/// Priority, 1 (most urgent) to 5 (least). Left unset if omitted.
#[arg(long, value_parser = priority_level)]
priority: Option<u8>,
},
/// List tickets, optionally filtered by status
Ls {
/// Filter by status (backlog, committed, reviewing, done)
status: Option<String>,
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
priority: Option<u8>,
},
/// Show a ticket by UUID or title
+26 -5
View File
@@ -29,7 +29,11 @@ pub fn cmd_init(start: &Path) -> Result<()> {
Ok(())
}
pub fn cmd_ls(status_filter: &Option<String>, worklane_dir: &Path) -> Result<()> {
pub fn cmd_ls(
status_filter: &Option<String>,
priority_filter: Option<u8>,
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<String>, 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<String>, 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<String>, 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<String>, 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<TicketItem>, level: Option<u8>) -> Vec<TicketItem> {
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<String>,
owner: &Option<String>,
priority: Option<u8>,
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 {
+4 -2
View File
@@ -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)?;
+130 -20
View File
@@ -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<u8> = 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::<u8>() {
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<TicketItem>) {
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<Path>) -> Result<Vec<TicketI
let due = parse_ticket_field(&content, "Due");
let filename = e.path().file_stem()?.to_string_lossy().to_string();
let created_at = parse_ticket_field(&content, "Created At");
let short_date = format_created_at(&created_at);
Some((
Some(TicketItem {
title,
owner,
due,
short_id(&filename).to_string(),
short_date,
))
id: short_id(&filename).to_string(),
created: format_created_at(&created_at),
priority: parse_priority(&content),
})
})
.collect();
items.sort_by(|a, b| a.0.to_lowercase().cmp(&b.0.to_lowercase()));
// Priority first, title as the tiebreak, which is what the sort used to be.
items.sort_by(|a, b| {
a.priority
.rank()
.cmp(&b.priority.rank())
.then_with(|| a.title.to_lowercase().cmp(&b.title.to_lowercase()))
});
Ok(items)
}
@@ -610,6 +673,53 @@ mod tests {
}
}
fn ticket_with_priority(raw: &str) -> 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"] {
+63
View File
@@ -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");
}
+58
View File
@@ -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"));
}