From c03f47c52dbfb458c508ac8b467f8f5f1b87fc36 Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Mon, 24 Aug 2026 15:49:50 +0200 Subject: [PATCH] (f774a33) Record a campaign move in the history log, and bump to 0.30.0 assign was the only field writer without an entry: a ticket could leave one campaign for another with nothing recording it. Kind gains Campaign, assign gains the --actor flag the other four writers carry, and the entry is written after the save and behind the no-change return, the rule every writer follows. The entry records Campaign::name, the codename or failing that the title, settled when the entry is written so a rename cannot change what an old entry means. The uuid the field holds says nothing in a log line, and a before-uuid the board no longer has reads _missing_, the way the Campaign field itself renders a dangling one. campaign is the longest mechanical label, so LABEL_WIDTH widens from 6 to 8 and every mechanical row moves two columns right, a deliberate output change that makes this a minor alongside the new flag. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 5 +- Cargo.lock | 2 +- Cargo.toml | 2 +- assets/SKILL.md | 16 +++--- src/campaign.rs | 15 ++++++ src/command.rs | 7 ++- src/handlers.rs | 27 +++++++++- src/history.rs | 45 ++++++++++++----- src/main.rs | 4 +- src/tui.rs | 2 +- tests/history.rs | 129 ++++++++++++++++++++++++++++++++++++++++++++++- 11 files changed, 224 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5a4495c..ff7dfeb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ - Format: `**Field Name**: value` - Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata` - A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign -- History entries stored in `.worklane/history//_.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`), then the body, then `**Author**` and `**Time**`. See The History Log +- History entries stored in `.worklane/history//_.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`, `**Campaign**`), then the body, then `**Author**` and `**Time**`. See The History Log ## Status Workflow `backlog` → `committed` → `reviewing` → `done` @@ -394,7 +394,8 @@ and this file is for what someone changing worklane's own code needs. - **An entry is written after the edit it describes, never before.** A refused move, a refused chown and a failed save log nothing, which is what `a_refused_move_writes_nothing` and `a_failed_edit_writes_nothing` pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it - **A no-op edit writes nothing either, and `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them - **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it -- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `status` being the longest of the three, so the bodies line up under each other +- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `campaign` being the longest of the four, so the bodies line up under each other +- **A campaign entry records `Campaign::name`, the codename or failing that the title, never the uuid the field holds.** Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A `before` uuid the board no longer has reads `_missing_`, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from `_Not set_` (f774a33) - **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both - **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries diff --git a/Cargo.lock b/Cargo.lock index 5e98a1d..e0ac501 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.29.1" +version = "0.30.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 3340a0f..a3d8670 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.29.1" +version = "0.30.0" edition = "2024" [dependencies] diff --git a/assets/SKILL.md b/assets/SKILL.md index 90dc9aa..54b4a78 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -273,20 +273,23 @@ existing ticket will have been written from a different angle. ## What the board records about your work `show` ends with a HISTORY block: every comment on the ticket and every change to its -status, owner or tags, oldest first, each naming who made it. You do not write these by -hand. `mv`, `chown` and `set --tags` record themselves, and a call that changes nothing -records nothing. +status, owner, tags or campaign, oldest first, each naming who made it. You do not write +these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call +that changes nothing records nothing. A campaign move is recorded by codename, or by +title for a campaign that has none, not by the uuid the field holds. ``` HISTORY ──────────────────── -status backlog → committed claude (2026-08-24 12:45:00) +status backlog → committed claude (2026-08-24 12:45:00) From claude (2026-08-24 13:10:22) The offset was never passed to the widget. -owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04) +owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04) + +campaign _Not set_ → v1 claude (2026-08-24 13:12:30) ``` Nothing else is logged: ticking a criterion, and editing the title, description, plan, @@ -312,7 +315,8 @@ Set it once where your session's environment is configured, not on each call: `e `~/.claude/settings.json` for Claude Code, and the environment opencode is started with for opencode, since it passes its own environment to the tools it runs. `--actor` overrides it for one call and is spelled the same on every command that writes an entry, -`comment`, `mv`, `chown` and `set`. An empty value counts as unset and falls back to the +`comment`, `mv`, `chown`, `set` and `assign`. An empty value counts as unset and falls +back to the git user, and with nothing at all the author is `unknown`. It is free text, checked against nothing: name yourself something a person reading the board will recognise. diff --git a/src/campaign.rs b/src/campaign.rs index 8a75758..764f0d7 100644 --- a/src/campaign.rs +++ b/src/campaign.rs @@ -50,6 +50,21 @@ pub struct Campaign { pub content: String, } +impl Campaign { + /// The name a reader knows the campaign by: the codename, or the title for a + /// campaign filed without one. + /// + /// What the history log records for a campaign move. The field holds a uuid, which + /// says nothing in a log line, and resolving at read time would let an entry change + /// meaning when a campaign is renamed, so the name is settled when the entry is + /// written. The codename over the title because it is the word the board and the + /// command line already use for the campaign, and a log row holds two of these + /// around an arrow. + pub fn name(&self) -> &str { + self.codename.as_deref().unwrap_or(&self.title) + } +} + /// The campaigns directory as [`resolve_in`] takes it. /// /// The name is empty because a campaign has no status: it is what makes the ambiguity diff --git a/src/command.rs b/src/command.rs index dae828d..73c1df6 100644 --- a/src/command.rs +++ b/src/command.rs @@ -182,8 +182,8 @@ fn annotation_line(raw: &str) -> Result { /// What `--actor` says on every command that writes a history entry. /// -/// One string, so the four spell it the same: a flag documented differently on each -/// command reads as four flags. +/// One string, so the five spell it the same: a flag documented differently on each +/// command reads as five flags. const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing"; /// Arguments that carry prose, and therefore have to accept a value starting with @@ -302,6 +302,9 @@ pub enum Command { /// Ticket UUID or title ticket: String, + + #[arg(long, help = ACTOR_HELP)] + actor: Option, }, /// The tag vocabulary: what the board carries, and what each tag means diff --git a/src/handlers.rs b/src/handlers.rs index c1f4391..9ac359a 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -1509,7 +1509,12 @@ pub fn cmd_campaign_show(search: &str, worklane_dir: &Path) -> Result<()> { /// /// No-op detection compares the whole file, the way `set` and `chown` do, so assigning /// a ticket to the campaign it already names writes nothing. -pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Result<()> { +pub fn cmd_assign( + campaign_search: &str, + ticket_id: &str, + actor: &Option, + start: &Path, +) -> Result<()> { let worklane_dir = find_worklane_dir(start)?; let campaign = resolve_campaign(campaign_search, &worklane_dir)?; let (status, title, original) = resolve_ticket(ticket_id, &worklane_dir)?; @@ -1528,6 +1533,26 @@ pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Resul save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?; + // Behind the no-change return above and after the save, the rule every writer + // follows. The entry records `Campaign::name`, not the uuid the field holds: what + // the reader should see is settled here, when the entry is written. A campaign the + // board no longer has reads `_missing_`, the way the Campaign field itself renders + // a dangling uuid. + let before = match parse_campaign(&original) { + None => NOT_SET.to_string(), + Some(old) => CampaignIndex::load(&worklane_dir)? + .get(&old) + .map(|was| was.name().to_string()) + .unwrap_or_else(|| "_missing_".to_string()), + }; + write_entry( + &worklane_dir, + &uuid, + Kind::Campaign, + &change(&before, campaign.name()), + &resolve_actor(actor.as_deref()), + )?; + println!( "Assigned '{}' to campaign '{}'", color_text(&title, Color::Green), diff --git a/src/history.rs b/src/history.rs index 7da2f34..fa2d364 100644 --- a/src/history.rs +++ b/src/history.rs @@ -3,8 +3,8 @@ //! The comments directory was already an append-only log with exactly one event kind: //! one file per entry under a directory named by the ticket's uuid, stamped to the //! microsecond and written with `create_new` so two writers cannot clobber each other. -//! This is that log with the kind named in it, so a status change, an owner change and a -//! tag change are recorded beside what somebody said about them. +//! This is that log with the kind named in it, so a status change, an owner change, a +//! tag change and a campaign move are recorded beside what somebody said about them. //! //! What is deliberately not logged: ticking or unticking a criterion, and edits to the //! title, description, plan, priority or due. Those change often and a log of them is @@ -59,25 +59,32 @@ pub fn history_dir(board: &Path, uuid: &str) -> PathBuf { /// What an entry records. /// /// An enum rather than a string, so a kind the reader does not know is a compile error -/// instead of a word that renders as itself. The variants are the four things worth -/// keeping: what somebody said, and the three fields whose history answers a question. +/// instead of a word that renders as itself. The variants are the five things worth +/// keeping: what somebody said, and the four fields whose history answers a question. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Kind { Comment, Status, Owner, Tags, + Campaign, } impl Kind { /// Every kind, which is what the reader matches a marker against and what the /// counter matches a filename against. - pub const ALL: [Kind; 4] = [Kind::Comment, Kind::Status, Kind::Owner, Kind::Tags]; + pub const ALL: [Kind; 5] = [ + Kind::Comment, + Kind::Status, + Kind::Owner, + Kind::Tags, + Kind::Campaign, + ]; - /// The width the mechanical labels are padded to, `status` being the longest of the - /// three. `comment` is longer and is not padded to: a comment renders as a header - /// and a body, not as a row. - const LABEL_WIDTH: usize = 6; + /// The width the mechanical labels are padded to, `campaign` being the longest of + /// the four. `comment` renders as a header and a body, not as a row, so it is not + /// among them. + const LABEL_WIDTH: usize = 8; /// The word in the filename, and the label a mechanical entry renders under. pub fn slug(self) -> &'static str { @@ -86,6 +93,7 @@ impl Kind { Kind::Status => "status", Kind::Owner => "owner", Kind::Tags => "tags", + Kind::Campaign => "campaign", } } @@ -100,6 +108,7 @@ impl Kind { Kind::Status => "**Status**", Kind::Owner => "**Owner**", Kind::Tags => "**Tags**", + Kind::Campaign => "**Campaign**", } } } @@ -560,7 +569,7 @@ mod tests { let rendered = format_history_with(&entries, false); assert!(rendered.contains("HISTORY"), "{rendered}"); assert!( - rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"), + rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"), "{rendered}" ); assert!( @@ -574,6 +583,9 @@ mod tests { /// The pin for the cells conversion: `show` prints the block exactly as it printed /// it before, every painted run spelled out, the way /// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body. + /// + /// Updated once since, deliberately: `campaign` widened the label column from 6 to + /// 8, and the campaign row itself joined the pin (f774a33). #[test] fn show_prints_the_same_history_it_printed_before_the_cells_conversion() { let entries = vec![ @@ -585,22 +597,28 @@ mod tests { "20260824_120001_000000_comment", "**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n", ), + parse_entry( + "20260824_120002_000000_campaign", + "**Campaign**\n_Not set_ → v1\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:02\n", + ), ]; let expected = format!( - "\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n", + "\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n\n{} _Not set_ → v1 {}\n", paint("HISTORY", Color::Orange, true), "─".repeat(20), paint("status", Color::Orange, true), paint("claude (2026-08-24 12:00:00)", Color::Cyan, true), paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true), + paint("campaign", Color::Orange, true), + paint("claude (2026-08-24 12:00:02)", Color::Cyan, true), ); assert_eq!(format_history_with(&entries, true), expected); assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true)); } - /// Padded to the longest of the three, so every body starts in the same column + /// Padded to the longest of the four, so every body starts in the same column /// however short the label above it is. #[test] fn the_mechanical_labels_are_aligned() { @@ -608,6 +626,7 @@ mod tests { ("status", "backlog → committed"), ("owner", "_Not set_ → alice"), ("tags", "bug → bug, cli"), + ("campaign", "v1 → beaver"), ]; let entries: Vec = bodies .into_iter() @@ -631,7 +650,7 @@ mod tests { at - line_start }) .collect(); - assert_eq!(columns.len(), 3); + assert_eq!(columns.len(), 4); assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}"); } diff --git a/src/main.rs b/src/main.rs index 3c1dc19..f4a3ed8 100644 --- a/src/main.rs +++ b/src/main.rs @@ -82,7 +82,9 @@ fn main() -> Result<()> { cmd_campaign_show(&campaign, &worklane_dir) } }, - Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start), + Some(Command::Assign { campaign, ticket, actor }) => { + cmd_assign(&campaign, &ticket, &actor, &start) + } // The bare form and `ls` are one arm: `worklane tags` was the listing before the // group existed and the fish completion still calls it that way, so the two // spellings cannot be allowed to drift into two behaviours. diff --git a/src/tui.rs b/src/tui.rs index f160759..281fd4a 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -4959,7 +4959,7 @@ mod tests { let plain = board.detail.as_ref().expect("no detail").plain(); assert!(plain.contains("HISTORY"), "{plain}"); - assert!(plain.contains("status backlog → committed claude ("), "{plain}"); + assert!(plain.contains("status backlog → committed claude ("), "{plain}"); let moved = plain.find("backlog → committed").expect("the move is missing"); let said = plain.find("And why.").expect("the comment is missing"); assert!(moved < said, "the board reordered the log:\n{plain}"); diff --git a/tests/history.rs b/tests/history.rs index 573c9fc..496f11f 100644 --- a/tests/history.rs +++ b/tests/history.rs @@ -164,6 +164,119 @@ fn clearing_the_tags_writes_a_tags_entry() { assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}"); } +/// The entry names the campaign the way a reader knows it, the codename, not the uuid +/// the field actually holds. A ticket never assigned starts from the sentinel an unset +/// field reads as everywhere else. +#[test] +fn assign_writes_a_campaign_entry_naming_the_codename() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog"); + run( + &temp, + &[ + "campaign", + "add", + "--title", + "First public release", + "--codename", + "v1", + ], + ); + + run(&temp, &["assign", "v1", UUID]); + + let entry = only_entry(&worklane, "campaign"); + assert!(entry.starts_with("**Campaign**\n_Not set_ → v1\n"), "{entry:?}"); +} + +/// A campaign filed without a codename is recorded by its title, the name `show` and +/// `campaign ls` fall back to. +#[test] +fn a_campaign_without_a_codename_is_recorded_by_its_title() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog"); + run(&temp, &["campaign", "add", "--title", "First public release"]); + + run(&temp, &["assign", "First public", UUID]); + + let entry = only_entry(&worklane, "campaign"); + assert!( + entry.starts_with("**Campaign**\n_Not set_ → First public release\n"), + "{entry:?}" + ); +} + +/// A ticket leaving one campaign for another records both ends, which is the move the +/// log exists to answer for: the field is rewritten, so nothing else remembers where the +/// ticket was. +#[test] +fn moving_between_campaigns_records_both_names() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog"); + run( + &temp, + &[ + "campaign", + "add", + "--title", + "First release", + "--codename", + "v1", + ], + ); + run( + &temp, + &[ + "campaign", + "add", + "--title", + "Second release", + "--codename", + "beaver", + ], + ); + + run(&temp, &["assign", "v1", UUID]); + run(&temp, &["assign", "beaver", UUID]); + + let found = entries(&worklane); + assert_eq!(found.len(), 2, "{found:?}"); + assert!(found[1].1.starts_with("**Campaign**\nv1 → beaver\n"), "{:?}", found[1].1); +} + +/// Assigning the campaign a ticket already names is reported as no change, and a log of +/// no change would be a log of nothing happening. +#[test] +fn a_no_op_assign_writes_nothing() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog"); + run( + &temp, + &[ + "campaign", + "add", + "--title", + "First release", + "--codename", + "v1", + ], + ); + + run(&temp, &["assign", "v1", UUID]); + let out = run(&temp, &["assign", "v1", UUID]); + + assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr)); + assert_eq!( + entries(&worklane).len(), + 1, + "a no-op assign logged a change it did not make" + ); +} + /// The fields that change often enough that a log of them is noise. `set` writing one of /// them is not an entry, and neither is a criterion being ticked. #[test] @@ -277,7 +390,7 @@ fn show_prints_the_comments_and_the_changes_in_one_sequence() { let owned = stdout.find("alice → bob").expect("the chown is missing"); assert!(said < moved && moved < owned, "out of order:\n{stdout}"); - for line in ["status backlog → committed", "owner alice → bob"] { + for line in ["status backlog → committed", "owner alice → bob"] { assert!(stdout.contains(line), "{line:?} not in:\n{stdout}"); } assert!(stdout.contains("From claude ("), "{stdout}"); @@ -337,14 +450,26 @@ fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() { let temp = TempDir::new().unwrap(); let worklane = setup_worklane(&temp); create_ticket(&worklane, "backlog"); + run( + &temp, + &[ + "campaign", + "add", + "--title", + "First release", + "--codename", + "v1", + ], + ); run(&temp, &["comment", UUID, "By hand.", "--actor", "opencode"]); run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]); run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]); run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]); + run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]); let found = entries(&worklane); - assert_eq!(found.len(), 4, "{found:?}"); + assert_eq!(found.len(), 5, "{found:?}"); for (name, content) in found { assert!(content.contains("**Author**: opencode"), "{name}: {content:?}"); }