(a6023e2) Stamp the time a ticket entered its status, and bump to 0.17.1

mv writes Committed On, Submitted On or Completed On for the status it
enters, so the board answers how long a ticket has been where it is
without guessing from file mtimes.

The three are mutually exclusive: entering stamps, leaving removes and
re-entering restamps, so a backward move under -f leaves no stale
Completed On behind. These fields are current state, like Status itself;
the trail of how the ticket got there belongs to the history log.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-22 20:31:53 +02:00
co-authored by Claude Opus 5
parent 373ba519b3
commit 139c9b012f
9 changed files with 454 additions and 8 deletions
+3 -2
View File
@@ -21,7 +21,8 @@
## Ticket File Format
- Filenames: `<uuid_v4>_<slug>.md`
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Campaign`, `Status`. `Campaign` is the one no ticket is born with: `add` does not write it, so it is inserted on demand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it
- 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
@@ -86,7 +87,7 @@ and this file is for what someone changing worklane's own code needs.
### Editing a Ticket
- `set` replaces a field, `append` adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and `append` only offers the sections that hold multiple lines
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s). Do not add either
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them
- `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username
- `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.17.0"
version = "0.17.1"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.17.0"
version = "0.17.1"
edition = "2024"
[dependencies]
+6
View File
@@ -35,6 +35,12 @@ skipping move, for correcting a mistake.
A move is also refused while the ticket is blocked by one that is not done yet, see
[Relating tickets](#relating-tickets).
`mv` stamps the time as it goes: `Committed On`, `Submitted On` and `Completed On`, one
field for the status the ticket is in now, shown by `show` among the rest of the
metadata. Only the current one is kept, so the stamp says how long the ticket has been
where it is, not how long each earlier stage took. Nothing else writes them, and moving
a ticket back removes the stamp of the status it left.
## Reading the board
```
+10
View File
@@ -662,6 +662,16 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
// refused for that reason rather than for whatever the lookup notices first.
let content = set_status_field(&resolved, target_status, &title)?;
// Behind every refusal above, so a move that does not happen writes no stamp, and
// spliced in here rather than after the rename so it travels with the same
// crash-safe write the Status field does.
let content = set_status_stamp(
&content,
target,
&Local::now().format(TIMESTAMP_FORMAT).to_string(),
&title,
)?;
let found_filename =
find_ticket_file(&current_path, &parse_ticket_field(&resolved, "ID"), &title)?;
+199 -4
View File
@@ -1064,6 +1064,35 @@ fn set_metadata_line(
if found { Some(updated) } else { None }
}
/// Drop one field from the Metadata section, leaving every other line untouched.
///
/// Scoped to the section for the same reason as [`set_metadata_line`], and shaped like
/// it: nothing means there was no such field, so a caller that removes a field a ticket
/// never carried leaves the content exactly as it found it rather than rewriting it
/// into an identical string.
fn remove_metadata_line(content: &str, field: &str) -> Option<String> {
let prefix = format!("**{}**:", field);
let mut updated = String::with_capacity(content.len());
let mut in_metadata = false;
let mut found = false;
for line in content.lines() {
if line.starts_with("## ") {
in_metadata = is_metadata_heading(line);
}
if in_metadata && !found && metadata_field_body(line).starts_with(&prefix) {
found = true;
continue;
}
updated.push_str(line);
updated.push('\n');
}
if found { Some(updated) } else { None }
}
pub fn set_status_field(content: &str, target_status: &str, title: &str) -> Result<String> {
set_metadata_line(content, "Status", target_status, is_status_line).ok_or_else(|| {
anyhow!(
@@ -1136,20 +1165,26 @@ pub fn parse_tags(content: &str) -> Vec<String> {
.collect()
}
/// The metadata fields in the order `add` writes them, with `Campaign` in its place
/// among them.
/// The metadata fields in the order `add` writes them, with the fields no ticket is
/// born with in their places among them.
///
/// The anchor list for inserting a field the file does not have yet, exactly as
/// [`SECTION_ORDER`] is for a missing section. Campaign sits beside Status because the
/// two answer the same kind of question, where the ticket belongs rather than what it
/// is, and Status stays last, which is where every file already keeps it.
const METADATA_ORDER: [&str; 8] = [
/// is, and Status stays last, which is where every file already keeps it. The three
/// stamps follow `Created At`, since they answer the same question it does about a
/// later moment, and they are in flow order for a reader who sees one after another
/// across a board.
const METADATA_ORDER: [&str; 11] = [
"ID",
"Priority",
"Tags",
"Due",
"Owner",
"Created At",
COMMITTED_ON_FIELD,
SUBMITTED_ON_FIELD,
COMPLETED_ON_FIELD,
CAMPAIGN_FIELD,
"Status",
];
@@ -1228,6 +1263,52 @@ fn insert_metadata_field(content: &str, field: &str, value: &str, title: &str) -
Ok(join_lines(&out))
}
// The metadata fields `mv` stamps with the time a ticket entered a status. Backlog has
// none: a ticket is filed there, and `Created At` already records when, so a fourth
// field would say the same thing for every ticket that has never moved.
pub const COMMITTED_ON_FIELD: &str = "Committed On";
pub const SUBMITTED_ON_FIELD: &str = "Submitted On";
pub const COMPLETED_ON_FIELD: &str = "Completed On";
/// Stamp the field of the status being entered and drop the other two.
///
/// A stamp is present exactly while the ticket sits in its status, so the three are
/// mutually exclusive: entering writes one, leaving removes it, and re-entering
/// restamps rather than keeping the first value. That is what keeps a ticket moved
/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is
/// the line between these fields and d4ce964's history log. Metadata carries current
/// state, which is why `Status` is a field at all; the trail of how the ticket got here
/// belongs to the log, and a stamp left behind would be a second copy of that job.
///
/// The time comes in as a string rather than being read here, so the caller stamps the
/// same moment it reports and a test can pin the value.
pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result<String> {
let mut content = content.to_string();
// Every status but the target, so a skipping move under `-f` clears the stamps of
// the stages it jumped over as well as the one it left.
for status in Status::ALL {
if status == target {
continue;
}
let Some(field) = status.stamp_field() else {
continue;
};
if let Some(updated) = remove_metadata_line(&content, field) {
content = updated;
}
}
match target.stamp_field() {
// Inserted on demand, the way Campaign is: every ticket written before these
// fields existed carries none of them.
Some(field) => set_or_insert_metadata_field(&content, field, now, title),
None => Ok(content),
}
}
/// Rewrite the title heading, the first `# ` line in the file.
///
/// `## ` headings do not match: the second character has to be a space.
@@ -2190,6 +2271,20 @@ impl Status {
Status::Done,
];
/// The field `mv` stamps on entering this status, for the three that have one.
///
/// Derived from the status rather than spelled at the call site, so the mapping is
/// in one place and a fifth status either brings its own stamp or explicitly has
/// none.
pub const fn stamp_field(self) -> Option<&'static str> {
match self {
Status::Backlog => None,
Status::Committed => Some(COMMITTED_ON_FIELD),
Status::Reviewing => Some(SUBMITTED_ON_FIELD),
Status::Done => Some(COMPLETED_ON_FIELD),
}
}
/// The directory name, which is also what clap accepts and what the `Status` field
/// holds. A `const fn` so [`DONE`] can be defined from it.
pub const fn as_str(self) -> &'static str {
@@ -3059,6 +3154,106 @@ mod tests {
assert!(error.to_string().contains("Campaign"), "{error}");
}
/// The one stamp the target status carries, and nothing of the others: the fields
/// are current state, not a record of every stage the ticket has been through.
#[test]
fn entering_a_status_stamps_its_field_and_clears_the_rest() {
let content = with_metadata(
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n",
);
let updated =
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
assert!(
updated.contains("- **Submitted On**: 2026-08-22 10:11:12"),
"{updated}"
);
assert!(!updated.contains("**Committed On**"), "{updated}");
}
/// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket
/// carrying none rather than a Completed On for work it has undone.
#[test]
fn moving_back_to_backlog_leaves_no_stamp_behind() {
let content = with_metadata(
"- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n",
);
let updated =
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
assert!(!updated.contains("**Completed On**"), "{updated}");
assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}");
assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}");
}
/// Re-entry is the time of the move that brought it back, not the first one.
#[test]
fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() {
let content = with_metadata(
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: backlog\n",
);
let updated =
set_status_stamp(&content, Status::Committed, "2026-08-22 10:11:12", "T").unwrap();
assert_eq!(updated.matches("**Committed On**:").count(), 1, "{updated}");
assert!(!updated.contains("2026-08-01 09:00:00"), "{updated}");
}
/// Against METADATA_ORDER, like Campaign: after Created At, which answers the same
/// kind of question, and never past Status, which every file keeps last.
#[test]
fn a_stamp_is_inserted_in_its_place_on_a_ticket_that_predates_the_field() {
let content = with_metadata(
"- **ID**: abc\n\
- **Created At**: 2026-08-01 09:00:00\n\
- **Campaign**: c-uuid\n\
- **Status**: reviewing\n",
);
let updated =
set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap();
assert!(
updated.contains(
"- **Created At**: 2026-08-01 09:00:00\n\
- **Completed On**: 2026-08-22 10:11:12\n\
- **Campaign**: c-uuid\n\
- **Status**: reviewing\n"
),
"{updated}"
);
}
/// Removal is scoped to the section for the same reason the write is: a description
/// quoting a field marker is prose, and rewriting it would corrupt the ticket text
/// while leaving the real field in place.
#[test]
fn a_marker_in_the_description_is_not_the_field_being_removed() {
let content = "# T\n\n## Description\n- **Committed On**: not a field\n\n\
## Metadata\n\n- **ID**: abc\n- **Status**: backlog\n";
let updated =
set_status_stamp(content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
assert!(updated.contains("- **Committed On**: not a field"), "{updated}");
}
/// Nothing to remove is not a rewrite: the content comes back byte for byte, which
/// is what keeps a move that stamps nothing from touching the file's shape.
#[test]
fn removing_a_field_the_ticket_does_not_carry_leaves_the_content_alone() {
let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n");
assert_eq!(remove_metadata_line(&content, COMPLETED_ON_FIELD), None);
assert_eq!(
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(),
content
);
}
#[test]
fn a_campaign_field_that_is_unset_or_absent_reads_as_no_campaign() {
assert_eq!(parse_campaign(&with_metadata("- **ID**: abc\n")), None);
+31
View File
@@ -662,3 +662,34 @@ fn ls_names_the_four_statuses_when_given_another() {
assert!(stderr.contains(status), "{status} is not offered: {stderr}");
}
}
/// The listing reads the fields it prints and nothing else, so the stamps `mv` writes
/// do not reach it. Pinned against a ticket carrying one, since a listing that started
/// showing them would change the output every board and completion script parses.
#[test]
fn ls_output_is_unchanged_by_a_status_stamp() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "committed", "Stamped", "alice", "2026-06-01");
let path = worklane
.join("committed")
.join("00000000-0000-0000-0000-000000000001_stamped.md");
let before = {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("committed");
get_stdout(&mut cmd)
};
let stamped = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Committed On**: 2026-08-22 09:14:30\n- **Status**:");
fs::write(&path, stamped).unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls").arg("committed");
let after = get_stdout(&mut cmd);
assert_eq!(after, before);
assert!(!after.contains("Committed On"), "{after}");
}
+170
View File
@@ -888,3 +888,173 @@ fn mv_ignores_the_kinds_that_are_not_blockers() {
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(worklane.join("committed").join(&filename).exists());
}
/// The value of a metadata field, or nothing when the ticket does not carry it.
fn field(content: &str, name: &str) -> Option<String> {
let prefix = format!("- **{}**: ", name);
content
.lines()
.find_map(|line| line.strip_prefix(prefix.as_str()))
.map(str::to_string)
}
/// `%Y-%m-%d %H:%M:%S`, checked by shape. A test cannot pin the clock, so what it can
/// assert is that the stamp carries the same format `Created At` does.
fn is_timestamp(value: &str) -> bool {
value.len() == 19
&& value.chars().enumerate().all(|(index, c)| match index {
4 | 7 => c == '-',
10 => c == ' ',
13 | 16 => c == ':',
_ => c.is_ascii_digit(),
})
}
fn stamped_ticket(worklane: &Path, status: &str) -> String {
create_ticket(
worklane,
status,
"Stamped Task",
"Carries the stamps.",
"cccc3333cccc3333cccc3333cccc3333cccc",
"alice",
"_Not set_",
"test",
)
}
fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
}
/// One field per status, written with the time of the move, and only the current one:
/// the stamps are where the ticket is now, not the trail of how it got there.
#[test]
fn mv_stamps_the_field_of_the_status_it_enters() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
for (status, stamp, cleared) in [
("committed", "Committed On", "Submitted On"),
("reviewing", "Submitted On", "Committed On"),
("done", "Completed On", "Submitted On"),
] {
let out = move_ticket(&temp, "cccc3333", status, false);
assert!(out.status.success(), "{:?}", out);
let content = ticket_at(&worklane, status, &filename);
let value = field(&content, stamp)
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
assert_eq!(field(&content, cleared), None, "{content}");
}
}
/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all
/// rather than a Completed On for work that has been undone.
#[test]
fn mv_removes_the_stamp_of_the_status_it_leaves() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "done", true);
let done = ticket_at(&worklane, "done", &filename);
assert!(field(&done, "Completed On").is_some(), "{done}");
move_ticket(&temp, "cccc3333", "backlog", true);
let content = ticket_at(&worklane, "backlog", &filename);
for stamp in ["Committed On", "Submitted On", "Completed On"] {
assert_eq!(field(&content, stamp), None, "{content}");
}
}
/// Re-entry is the time of the move that brought the ticket back, not the first one.
#[test]
fn mv_restamps_a_status_the_ticket_is_re_entering() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "committed");
// Hand-written so the earlier value is old enough to tell from the move's own time,
// which two moves in the same second would not be.
let path = worklane.join("committed").join(&filename);
let seeded = fs::read_to_string(&path)
.unwrap()
.replace("- **Status**:", "- **Committed On**: 2020-01-01 00:00:00\n- **Status**:");
fs::write(&path, seeded).unwrap();
move_ticket(&temp, "cccc3333", "backlog", true);
move_ticket(&temp, "cccc3333", "committed", false);
let content = ticket_at(&worklane, "committed", &filename);
let value = field(&content, "Committed On").expect(&content);
assert!(is_timestamp(&value), "{value}");
assert_ne!(value, "2020-01-01 00:00:00");
assert_eq!(content.matches("**Committed On**:").count(), 1, "{content}");
}
/// The fixture predates the fields, as every ticket on a real board does, so the line
/// is inserted rather than rewritten. Against METADATA_ORDER, which keeps Status last.
#[test]
fn mv_inserts_the_stamp_before_the_status_field() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "backlog");
move_ticket(&temp, "cccc3333", "committed", false);
let content = ticket_at(&worklane, "committed", &filename);
let value = field(&content, "Committed On").expect(&content);
assert!(
content.contains(&format!(
"- **Owner**: alice\n- **Committed On**: {}\n- **Status**: committed\n",
value
)),
"{content}"
);
assert!(content.ends_with("- **Status**: committed\n"), "{content}");
}
/// Behind the refusals, all of them: a move that does not happen leaves the file exactly
/// as it was, stamp included.
#[test]
fn mv_writes_no_stamp_when_the_move_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let backward = stamped_ticket(&worklane, "committed");
let before = ticket_at(&worklane, "committed", &backward);
let out = move_ticket(&temp, "cccc3333", "backlog", false);
assert!(!out.status.success());
assert_eq!(ticket_at(&worklane, "committed", &backward), before);
// The blocked ticket takes the other refusal, which sits after the no-op return.
let blocked = create_gated_pair(&worklane, &temp, "backlog");
let before = ticket_at(&worklane, "backlog", &blocked);
let out = move_ticket(&temp, "aaaa1111", "committed", false);
assert!(!out.status.success());
assert_eq!(ticket_at(&worklane, "backlog", &blocked), before);
}
/// A move to the status the ticket is already in returns before anything is written, so
/// it does not restamp either.
#[test]
fn mv_does_not_restamp_a_no_op_move() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = stamped_ticket(&worklane, "committed");
let before = ticket_at(&worklane, "committed", &filename);
let out = move_ticket(&temp, "cccc3333", "committed", false);
assert!(out.status.success());
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
}
+33
View File
@@ -489,6 +489,39 @@ fn show_renders_the_metadata_as_an_aligned_table() {
assert!(content.contains("- **Owner**: alice"));
}
/// The stamps `mv` writes are fields like any other: the table renders what the file
/// holds, so nothing here knows their names, and the column widens to the longest of
/// them the way it does for anything else.
#[test]
fn show_renders_a_status_stamp_in_the_metadata_table() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let filename = "abc123def456789012345678901234567890_stamped.md";
fs::write(
worklane.join("committed").join(filename),
"# Stamped Ticket\n\n## Metadata\n\n\
- **ID**: abc123def456789012345678901234567890\n\
- **Created At**: 2026-08-20 15:51:01\n\
- **Committed On**: 2026-08-22 09:14:30\n\
- **Status**: committed\n",
)
.unwrap();
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("show").arg("Stamped");
let stdout = get_stdout(&mut cmd);
assert!(
stdout.contains(
"Created At 2026-08-20 15:51:01\n\
Committed On 2026-08-22 09:14:30\n\
Status committed\n"
),
"{stdout:?}"
);
}
/// 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(