(9564ac9) Show the annotation in tags ls, and bump to 0.26.4

Since tags.md there are two vocabularies, the one the file declares and the one
the tickets carry, and the listing reported only the second. A tag declared and
never applied was invisible, and a word somebody invented in a hurry read
exactly like one the board had agreed on. Those two cases are the whole reason
to declare tags at all.

The listing is now the union: still alphabetical, still case sensitive, with the
annotation's opening line as a third tab-separated field and a count of zero for
a tag nothing carries.

**The absence of the third field is what marks a carried but undeclared tag.**
Nothing could be appended to the first field without a completion offering a tag
that does not exist, and nothing could be added to the second without it
stopping being a number. Absence costs neither, and it buys the property a
marker could not have: a board with no tags.md has every tag undeclared, so it
prints two fields a line, which is byte for byte what this printed before the
file existed. An older completion script on a newer binary keeps working, which
is the same compatibility 1db02e5 kept for the bare form.

A declared tag with nothing said about it answers the placeholder rather than an
empty string. An empty third field is a trailing tab and nothing else, so the
one difference between declared and not would have been invisible in a terminal
and in a completion alike. It is also what the file itself holds under that
heading, so the field is the section's opening line either way.

`TagIndex::summary` does the cut to one line, the way `CampaignRow::summary`
takes one line off a description the read carries whole: the annotation is prose
with paragraphs in it, and how much of it a view wants is the view's business.

The two fish rules pipe through `cut -f1,3`, since fish takes everything after
the *first* tab as one description and the count would otherwise land in the
middle of the prose. What is left is the annotation, and a tag the board has
never declared is offered with no description at all, which says what the count
used to say more weakly. `cut` rather than `string replace` because columns are
what is being picked, and `cut -f1` is how a script reads this listing anyway.
A test pins both rules rather than the script as a whole, so a rule added later
that reads `worklane tags` raw is caught.

`assets/ADMIN.md` claimed a declared and unapplied tag does not appear in the
listing, which is now the opposite of the truth; it lists at zero. Fixed here
rather than left to f7dd1a1, which does not list that file. The same stale
sentence in SKILL.md and PLAN.md is recorded on that ticket.

Filed on the way past: an annotation carrying a tab splits the listing into a
fourth field, 8f650fc, and the `tags set` completion offers the undeclared tags
it refuses, which only became filterable now that the listing tells them apart,
193f9be.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-24 03:58:04 +02:00
co-authored by Claude Opus 5
parent 07c783410c
commit 5dc087d49e
7 changed files with 234 additions and 31 deletions
+37 -9
View File
@@ -1217,27 +1217,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
Ok(())
}
/// Every tag on the board, with how many tickets carry it.
/// Every tag on the board: the ones the tickets carry, the ones the file declares, and
/// what each declared one means.
///
/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag
/// already known, and the decorated listing does not print tags at all. A grooming sweep
/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say
/// that the question could only be answered by reading the tickets.
///
/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are
/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing
/// carries lists at zero rather than being dropped, and a carried tag nothing declares
/// still lists. Those two cases are the whole reason to declare tags at all, so this is
/// the command that has to show them apart.
///
/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively,
/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter
/// came back short. Sorting puts them next to each other, which is where a near-duplicate
/// is spotted.
///
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count.
/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither
/// wants an escape sequence. Every status, done included, for the reason `ls --ids`
/// includes it: a tag retired months ago is still part of the answer to what the
/// vocabulary has been.
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and
/// a tab and the annotation's opening line for a tag the file declares. Fish reads what
/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an
/// escape sequence.
///
/// **A carried but undeclared tag is marked by the absence of the third field**, which is
/// where the shape comes from. Anything appended to the tag itself would have a completion
/// offer a tag that does not exist, and anything added to the count would stop the second
/// field being a number. Absence costs neither, and it buys the one property a marker
/// could not: a board with no `tags.md` has every tag undeclared, so it prints two fields
/// a line, which is byte for byte what this printed before the file existed. The shipped
/// fish completion of an older version is still reading that.
///
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
/// ago is still part of the answer to what the vocabulary has been.
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
// is an error here too. The listing is the one tag command that could go on without the
// file, and reporting a vocabulary while silently treating a broken file as no file is
// the wrong half of the answer.
let index = TagIndex::load(worklane_dir)?;
// BTreeMap rather than a sort afterwards: the order is the point, and the counting
// wants a map anyway.
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
// wants a map anyway. Seeded from the vocabulary rather than merged into afterwards,
// which is what puts a declared tag nothing carries in at zero.
let mut counts: BTreeMap<String, usize> =
index.names().map(|tag| (tag.to_string(), 0)).collect();
for status in status_dirs() {
let status_path = worklane_dir.join(status);
@@ -1253,7 +1278,10 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
}
for (tag, count) in counts {
println!("{}\t{}", tag, count);
match index.summary(&tag) {
Some(summary) => println!("{tag}\t{count}\t{summary}"),
None => println!("{tag}\t{count}"),
}
}
Ok(())