From 407cb14fe60958096a970e6184d86681ecfb9c02 Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Mon, 24 Aug 2026 11:28:32 +0200 Subject: [PATCH] (e6e3a1b) Guard the README command table against a missing row The campaign and assign rows landed with 528566d. What was left was the checking, done here against the built binary rather than against the ticket that added them. The campaign ls row was incomplete: the listing also prints the derived state, [open] until every member is done and [done] after, and reads "no members" with no state for a campaign nothing has been filed against, which is neither. Corrected. every_subcommand_has_a_row_in_the_readme_command_table walks clap's own subcommands, one level of nesting included, against the table's rows. Two commands hid behind an otherwise complete table for two minor versions because the only thing walking it was somebody remembering to. The tag subcommands are named in a PENDING list rather than skipped, since f7dd1a1 rewrites that row. --- AGENTS.md | 1 + README.md | 2 +- src/command.rs | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b098db4..b514dca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -394,6 +394,7 @@ and this file is for what someone changing worklane's own code needs. - **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake - **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance - `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist +- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it ### Color and Output - Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in diff --git a/README.md b/README.md index 1172852..9b5447d 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Worklane is a local Kanban flow for agentic software development. | `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by | | `worklane campaign set ` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` | | `worklane campaign append ` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket | -| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion | +| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion | | `worklane campaign show ` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks | | `worklane assign ` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it | | `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known | diff --git a/src/command.rs b/src/command.rs index cc991a0..16deda0 100644 --- a/src/command.rs +++ b/src/command.rs @@ -881,3 +881,68 @@ pub struct CheckArgs { /// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted pub criteria: Vec, } + +#[cfg(test)] +mod tests { + use super::*; + + use clap::CommandFactory; + + /// The command names as the README table would have to spell them: `campaign add` + /// for a nested one, the bare name for a top level one. `help` is clap's own and + /// documents nothing. + fn documented_names() -> Vec { + let cli = Cli::command(); + let mut names = Vec::new(); + + for sub in cli.get_subcommands() { + if sub.get_name() == "help" { + continue; + } + + names.push(sub.get_name().to_string()); + for nested in sub.get_subcommands() { + if nested.get_name() == "help" { + continue; + } + + names.push(format!("{} {}", sub.get_name(), nested.get_name())); + } + } + + names + } + + /// Every subcommand has a row in the README's command table. + /// + /// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and + /// the `--campaign` flag went with them, because the only thing walking the table + /// was somebody remembering to. This is what walks it. A command whose row is + /// missing is a command a reader of the README cannot discover at all, which is a + /// worse failure than a row that is merely out of date. + #[test] + fn every_subcommand_has_a_row_in_the_readme_command_table() { + // The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row + // once the vocabulary work above it has landed. Listed rather than skipped, so + // emptying this is part of closing that ticket rather than something to + // rediscover. + const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"]; + + let readme = include_str!("../README.md"); + let table: String = readme.lines().filter(|line| line.starts_with('|')).collect(); + + let missing: Vec = documented_names() + .into_iter() + .filter(|name| !PENDING.contains(&name.as_str())) + .filter(|name| !table.contains(&format!("`worklane {}", name))) + .collect(); + + assert!( + missing.is_empty(), + "no row in the README command table for {missing:?}. A new command is not \ + shipped until the table lists it: that table is the only place a reader \ + discovers one, and two commands hid behind an otherwise complete table \ + for two minor versions." + ); + } +}