Merge pull request 'Declare the track and disc totals when tagging' (#105 ) from fix/16-tagwriter-totals into main

Closes #16
Merge branch 'main' into fix/16-tagwriter-totals
2026-08-19 00:45:07 +00:00 · 2026-08-18 20:32:08 -04:00 · 2026-08-18 23:30:31 +00:00 · 2026-08-18 19:08:50 -04:00 · 2026-08-18 23:05:38 +00:00 · 2026-08-18 18:54:39 -04:00
32 changed files with 1511 additions and 2240 deletions
@@ -0,0 +1,107 @@
+name: Unclaim
+
+# A `Closes #N` footer in a commit body closes the issue on merge — and
+# leaves `Status/In Progress` on it, because Gitea's auto-close touches
+# state and nothing else.  So #100 was closed and simultaneously marked
+# as being actively worked on, and `scripts/issue.sh close` (which does
+# drop the label) is exactly the thing the footer exists to avoid
+# calling.
+#
+# **This hooks the close, not the merge.**  Stripping the label in the
+# PR would work and would be a per-PR habit; habits are what the footer
+# removed.  `issues: [closed]` covers every path an issue can close by —
+# the footer on merge, `issue.sh close`, someone clicking Close in the
+# web UI — and asks nothing of anyone at any of them.
+#
+# **Reopening deliberately does not restore it.**  Reopening says the
+# work was not finished, not that somebody is at a keyboard doing it
+# now; the claim gets re-made by whoever picks it up.
+#
+# **This is not instant, and should not be described as it.**  The
+# runner has capacity 1 and is shared with an index build that can hold
+# it for three hours, so a label tweak can queue behind one. Stale for
+# an afternoon beats stale forever, which is what it was.
+#
+# The audit that answers "is this still firing" stays in CLAUDE.md and
+# is one command:
+#
+#   ./scripts/issue.sh list --state closed --label "Status/In Progress"
+#
+# A workflow that silently stops working is the failure mode this whole
+# area has already produced once.
+
+on:
+  issues:
+    types: [closed]
+
+jobs:
+  unclaim:
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:24.04
+
+    steps:
+      - name: Drop the claim label
+        # **Inside a container the act runner selects `sh`, not bash**, so
+        # `set -o pipefail` fails the job on its second line with "Illegal
+        # option" and the step never reaches the API.  `homebrew-formula.yml`
+        # carries the same `set -euo pipefail` without trouble because it
+        # runs with **no container**, on the host image where bash is the
+        # default — so "another workflow does it" is not evidence here.
+        shell: bash
+        env:
+          # The automatic Actions token, as release.yml uses for the
+          # floor tag.  It needs no more than write access to this repo.
+          TOKEN: ${{ secrets.GITEA_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          ISSUE: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+
+          # `ca-certificates` is named because `--no-install-recommends`
+          # skips it, and `ubuntu:24.04` ships no CA bundle of its own —
+          # so curl comes up unable to verify TLS against our own Gitea
+          # and fails with "error setting certificate file" (exit 77).
+          # Every other containerised workflow here spells it out for the
+          # same reason; this one did not, and cost a release cycle.
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends \
+            ca-certificates curl jq >/dev/null
+
+          label_id=$(
+            curl -sSf -H "Authorization: token $TOKEN" "$API/labels?limit=100" |
+              jq -r '.[] | select(.name == "Status/In Progress") | .id'
+          )
+
+          # The label not existing is a repo somebody reorganised, not a
+          # failure of this run — say so and stop, rather than failing a
+          # job on every close from then on.
+          if [ -z "$label_id" ]; then
+            echo "unclaim: no 'Status/In Progress' label in this repo; nothing to do"
+            exit 0
+          fi
+
+          # DELETE is idempotent here: an issue that never carried the
+          # label answers the same as one that did, which is what makes
+          # this safe to run on *every* close rather than only the ones
+          # that were claimed.
+          # The body is captured, not discarded, so a refusal is
+          # diagnosable from this log alone.  Whether the automatic
+          # token carries issue-write scope is still unproven, and
+          # "DELETE returned 403" without Gitea's own sentence costs
+          # another merge to find out which of the two it is.
+          body=$(mktemp)
+          code=$(
+            curl -sS -o "$body" -w '%{http_code}' -X DELETE \
+              -H "Authorization: token $TOKEN" \
+              "$API/issues/$ISSUE/labels/$label_id"
+          )
+
+          case "$code" in
+            204) echo "unclaim: #$ISSUE is closed and unclaimed" ;;
+            *)
+              echo "unclaim: DELETE returned $code for #$ISSUE" >&2
+              cat "$body" >&2
+              exit 1
+              ;;
+          esac
@@ -1,118 +0,0 @@
-# Work log
-
-Temporal memory: what happened and what's next. Structure lives in
-`CLAUDE.md`, operational instructions in `.pi/skills/yellowjacket-dev/`,
-measured discoveries in `.planning/NOTES.md`. Don't duplicate those here.
-
-## Current state
-
-Plan 005 (agent development harness) is **complete — all seven
-phases**. Everything from phase 1 onward is still **uncommitted**: one
-large but coherent working-tree diff, nothing pushed.
-
-All four tiers verified green from a cold, cleaned state:
-`make ui-test` 313 passed, `make lint` 0 issues × 3 configurations,
-`make test` green × 3 passes, `make e2e` 19 passed. Both CI jobs
-verified green in a bare `ubuntu:24.04` container, including 19/19 on
-WebKit.
-
-**Committed and pushed** as `5ca6cad` (the harness) + `ccacd67` (a CI
-fix), and **green on the real runner**: job `check` ~4 min, job `e2e`
-~3 min with 19/19 chromium *and* 19/19 webkit. One commit rather than
-seven because the working tree was the end state, not per-phase
-snapshots — `Makefile`, `CLAUDE.md` and `lefthook.yml` are touched by
-nearly every phase, so a split would have been fabricated history.
-
-Still unverified, because no run has failed yet: the
-`actions/upload-artifact` step (`continue-on-error`, so it cannot mask
-a real failure) and whether pnpm honours `npm_config_store_dir` for
-store caching. Worth checking the next time a spec legitimately fails.
-
- [ ] `gitea_ci`'s `job_logs` returns 404 on Gitea 1.27.1 — the endpoint
-      is not exposed. Logs come from the VPS instead: `zstdcat` the file
-      under `gitea/actions_log/<owner>/<repo>/<xx>/<task_id>.log.zst`,
-      and note `zstdcat` is not in the gitea container, so
-      `docker cp` it out first. Job status is `action_run_job.status`
-      (1 success, 2 failure, 4 skipped, 5 waiting, 6 running).
-      Probably belongs in the `gitea` skill, not here.
-
-Open items deliberately not fixed: WAV tags are write-only
-(`TestWAVTagsAreNotReadableYet`), `themeStore.loadFromBackend`'s failure
-handler cannot recover, `backend/playlist` has no CRUD suite.
-
-## Log
-
-### 2026-08-11 — cold skill run, then phase 7 (CI)
-
- **Followed the skill cold first**, as the last session asked. It
-  works: app up from a wiped `.dev/`, an undocumented flow driven
-  (queue panel + shuffle, asserted on `QueueModeChanged`), stopped —
-  ~1 minute, no dead ends. One real config bug: `outputDir` in
-  `.playwright/cli.config.json` resolves against **cwd**, not the
-  config file's directory (only `initScript` does that), so snapshots
-  were landing above the repo and a *stale* one from the previous
-  session answered `ls -t` instead. That cost a DOM walk to disprove a
-  regression that did not exist. Four smaller doc gaps fixed
-  (`sandbox-seed` already runs `testdata`; `ui-setup`/`e2e-setup` were
-  undocumented prerequisites; `snapshot` prints a path; `dev-stop`
-  leaves the browser open), plus `dev-headless.sh`'s own banner, which
-  was suggesting the bare `window.go` call its next paragraph warns
-  against.
- **Built both CI jobs as container scripts before writing any YAML**,
-  then transcribed the YAML back out and re-ran it to prove the
-  transcription. Push-and-see is a bad loop on a self-hosted runner.
- **It found a real bug immediately**: `make lint` omitted
-  `webkit2_41` on all three passes, so it was linting configurations
-  nothing builds. Invisible on Arch (which still ships
-  `webkit2gtk-4.0.pc`), fatal on Ubuntu 24.04. Tag sets now match
-  `make test`.
- **Both open decisions settled by measurement**: ALSA `null` PCM for
-  audio (no daemon; the elapsed clock really advances), dead-address
-  stub for the explore artifact (and setting it for the *app* run, not
-  just seeding, is worth 8x on suite wall clock). **WebKit is a
-  required step** — it had never been run anywhere, so one throwaway
-  container run replaced a coin flip with 19/19 at +11 s.
-
-### 2026-08-10 — phase 6, pi affordances
-
- Added `.pi/skills/yellowjacket-dev/` as a directory rather than a flat
-  file: only the description is always in context, so `SKILL.md` stays
-  short enough that reading it whole is never a decision, and the deeper
-  material sits in `references/{harness,fixtures,ui-tier,schema-change}.md`.
- Settled the CLAUDE.md-vs-skill split **grammatically, not topically**,
-  because a topical split is what rots — every new fact gets two
-  plausible homes. Three docs, three tenses: NOTES.md is past
-  (measured, dated, append-only), CLAUDE.md is present (what the system
-  is), the skill is imperative (what to run). A new paragraph's tense
-  decides where it goes.
- The five gotchas (binding timeouts, first-run wizard, `pkill -f`,
-  seeds-by-running, WebKit-is-CI-only) went **inline in SKILL.md**, not
-  into a reference: you need them before the failure, not after.
- Trimmed CLAUDE.md's "Fixtures and the headless harness" section by
-  about half — the command sequences and gotchas it was carrying are now
-  the skill's, and leaving both would have created exactly the duplicate
-  description this repo has a standing rule against.
- Added `make skill-check` / `scripts/skill-check.sh` + a pre-commit
-  hook: every command in `.pi/**/*.md` must be a real `make` target, so
-  the Makefile stays the source of truth for invocation and a renamed
-  target fails a commit instead of misleading an agent later. Verified
-  it fails (it caught its own not-yet-created target) and passes.
- Added the `/e2e` prompt template: promoting a hand-driven
-  `playwright-cli` session into a spec is a transcription with four
-  fixed substitutions (refs → testids, sleeps → `waitForEvent`, raw
-  `window.go` → `callBinding`, short fixture → `LONG_TRACK`), plus three
-  runs — pass, pass again, pass after a DB restore — because the usual
-  failure is a spec depending on state the hand-driving left behind.
- One shell trap: under `set -euo pipefail`, `x="$(make -pqRr | …)"`
-  fails the whole assignment, because `make -q` exits non-zero when a
-  target is out of date and `pipefail` propagates it.
-
-### Earlier
-
-Phases 1–5 of plan 005: fixture generator and manifest, headless launch
-and seeds, the event bridge + `data-testid` pass + `backend/testctl` +
-`e2e/`, the Vitest component tier + `make bindings-check`, and the
-`events.Emit` wrapper with its in-process service-event tests. Recaps
-and the five "verified end to end" blocks are in
-`.planning/plans/active/005-agent-development-harness.md`; the lessons
-are in `.planning/NOTES.md`.
@@ -3483,3 +3483,26 @@ public tap.

 A guard added today does not protect a tag that points at yesterday. When
 re-pointing a tag, check what the workflows looked like *there*.
+
+## A tag reader looks at exactly one spelling of "total" (measured 2026-08-18)
+
+Writing #16's totals means matching the reader, which is
+`dhowden/tag`, and it is narrower than the specs are:
+
+- **Vorbis (FLAC, OGG): `TRACKTOTAL` and `DISCTOTAL` only.**
+  `vorbis.go`'s `Track()` reads `tracknumber` and `tracktotal` and
+  nothing else, so `TOTALTRACKS` — which several taggers write and
+  which xiph lists — and a `1/12` packed into `TRACKNUMBER` both read
+  back as *no total*. They write successfully. Nothing errors.
+- **ID3v2 (MP3): `TRCK`/`TPOS` as `n/N`**, via `parseXofN`. That is one
+  frame carrying two facts, which is why `applyPositionFrame` reads the
+  existing frame before writing either half.
+- **WAV: nothing at all.** There is no RIFF reader in the module, so a
+  WAV's `id3 ` chunk is invisible to `metadata.ExtractTags` — every
+  field, not just the totals. Filed as #104.
+
+The general shape, and the reason this is written down: a tag written
+under a name the reader does not look at is indistinguishable from one
+never written. So the tests assert the round trip through
+`metadata.ExtractTags` — the reader the *scan* uses — rather than
+through the bytes the writer produced.
@@ -13,7 +13,7 @@ reviews. Nothing was changed.

 Findings below are numbered `H-n` (hands-on) and cross-reference the
 static reports where they overlap. The reconciliation plan built from
-all four files is `.planning/plans/pending/007-ui-reconciliation.md`.
+all four files is `.planning/plans/completed/007-ui-reconciliation.md`.

 ---

@@ -1,5 +1,7 @@
 # 012 — What we ask the network for, and what we already had

+> **Completed.** Findings 1, 2 and 4 shipped. Finding 3 — the bound-but-uncalled methods — is now **#86**.
+
 **Status:** all four findings fixed. Lint (3 configs), Go tests (3
 configs), `tsc` and 752 Vitest tests pass; **not driven against the
 real app**, so the numbers below are read off the code, not measured.
@@ -1,5 +1,7 @@
 # 015 — Android release pipeline

+> **Completed.** The pipeline ships a signed APK from CI on every `v*` tag; `docs/android-release.md` is its operating document.
+
 Ship an Android APK from CI on every version tag, published to the Gitea
 generic package registry so Obtainium can poll a plain URL.

@@ -1,5 +1,7 @@
 # 015 — Multi-artist credits, navigable

+> **Completed.** Phases 1, 2 and 4 shipped. Running the ingest against the real dump and publishing an artifact that carries credits is **#88**; Phase 3 (`file_artists`) is **#89**, blocked on it.
+
 ## The problem

 A track credited to more than one artist has exactly one navigable
@@ -1,5 +1,7 @@
 # 016 — What Android parity would actually take

+> **Completed.** Sections A, B1, B2 and B4 shipped. B3, writing tags on the device, is now **#87**; the device-found UI faults are #51–#72, sequenced by #73.
+
 > **Status: all of section A is done.** A1–A3 landed with "let the app
 > reach the user's music"; A4 (MediaSession, transport notification,
 > audio focus) landed with "survive the screen locking". The direction
@@ -1,5 +1,7 @@
 # Autotag (v1.3) — MusicBrainz Autotagger

+> **Historical record.** Phases 008–010 shipped, and the scoring engine was subsequently overhauled (`recommend.go`, `rank.go`, `mixedbag.go`), which makes the 011/012 sections below stale in their details. What is actually left is **#90** (auto-accept and entry points) and **#91** (settings, and a way back from the dismissed file-write warning).
+
 The MusicBrainz autotagger, collectively **v1.3**. Builds on the explore-browser API client + cache foundation. Five sequential phases (008–012), each depending on the prior one.

 | Phase | Title | Status |
@@ -1,195 +0,0 @@
-# 010 — Owned albums, offline
-
-**Status:** not started — and **much smaller than when it was written**
-**Branch:** none yet
-**Created:** 2026-08-13
-**Depends on:** nothing
-**Related:** the `AlbumReleasesFailed` fix that prompted it, and the
-tag-derived completeness that landed after it (same session)
-
---
-
-## What already shipped, and what it leaves
-
-The common case is solved without this plan. `GetAlbumCompleteness`
-reads the "5/12" denominator off the files' own tags — persisted to
-`release_group_recordings.total_tracks`, having been extracted at every
-scan since forever and discarded — and an album that is **MBID-matched
-and complete** now opens with **no catalog call at all**. Identity from
-the MBID, tracklist from the tags; those were the two things the browse
-was being spent on.
-
-So the set this plan still has to serve is not "albums you own a track
-of". It is:
-
- albums that are genuinely **incomplete** (the catalog is the only way
-  to say *which* tracks are missing — tags give the count, not the
-  names), and
- albums whose tags **never declared a total**, where completeness is
-  unknowable locally and the catalog is the only source.
-
-On a well-tagged library that is a small minority, which changes the
-economics below considerably: the run is shorter, and the rate limiter
-contention that dominates this design is proportionally less severe.
-Re-measure before building — the answer may now be "the prefetch is
-enough".
-
---
-
-## The problem
-
-Opening an album detail page for an album **you already own** hits
-MusicBrainz. Every time it is not in the response cache, which for most
-of a library is every time, because nothing warms that cache except a
-capped prefetch on the artist page.
-
-The user's framing: *this is a classic example of an album we should
-have had locally.*
-
-## Why we do not have it, despite the discography backfill
-
-`BackfillLibraryDiscographies` / `EnsureArtistDiscography`
-(`backend/explore/searchindex.go:301`, `:397`) do less than the name
-suggests. Per artist, `indexOneArtist` fetches:
-
- `fetchTopReleaseGroups` — capped at `indexMaxRGs` (50)
- `fetchTopRecordings` — capped at `indexMaxRecs` (200)
-
-and writes them as **flat `explore_index` rows**. There is no release
-group → tracklist relation anywhere in the index, and no release-level
-rows at all. `explore_index` recordings carry `caa_release_mbid` and
-`release_name`, which name the release used for cover art — not a
-tracklist.
-
-So "we have full discographies for library artists" means *we know
-which albums the artist made, offline*. It has never meant we know
-what is on any of them.
-
-The only store of release-level catalog data in the app is `http_cache`
-under `mb:browse:releases:<rg>` (90-day TTL, `musicbrainz.go:27`),
-populated **only** by a live `BrowseReleases` with
-`Includes: ["recordings", "media"]` at `MaxLimit` — the most expensive
-call the app makes to MusicBrainz. It is warmed by exactly one thing:
-`PrefetchReleases` (`explore.go:746`), capped at 8, called only when an
-artist page renders.
-
-An album opened from the library grid therefore always browses live.
-
-## What to build
-
-**A post-scan backfill that warms the release cache for release groups
-that are owned but not known-complete** — bounded, resumable, and
-shaped exactly like `BackfillLibraryDiscographies`, which is the proven
-pattern for this in the codebase.
-
-The scoping rule is the user's and it is the right one: not "every
-album by every artist in the library" (50 release groups per artist,
-mostly never opened) but albums with owned tracks — narrowed further,
-now, to the ones a local answer cannot already cover. The query gains
-one clause: skip release groups whose `GetAlbumCompleteness` reports
-`complete`.
-
-Sketch:
-
-1. A query for release groups with ≥1 owned track and no warm release
-   cache entry. `release_groups.mbid` is the key; the owned-track join
-   is `audio_files → recordings → release_group_recordings`, the same
-   shape `unenrichedLibraryArtistMBIDs` already uses one table over.
-2. Order by owned-track count descending, so the albums the user has
-   most of are warmed first — same reasoning as the discography
-   backfill's ordering, same benefit if a run is cut short.
-3. Run through `releasesSF`, so it never double-fetches a release group
-   an interactive open is already handling.
-4. Bound a run (`discogBackfillMaxPerRun` has a value to copy) and make
-   it resumable: the resume marker is the response cache itself —
-   `BrowseReleasesCached` already answers "is this one done", so unlike
-   the discography path this needs **no new flag column**.
-5. Trigger it where `BackfillLibraryDiscographies` is triggered, and
-   register it with `jobs` so it has progress, pause and cancel like
-   every other long-running operation.
-
-### The rate limiter is the whole design constraint
-
-> **Update (2026-08-13): the priority half is built, and the sentence
-> below is wrong on a detail.** `e.mb` runs on `mbSearchLimiter`
-> (`NewRateLimiterBurst(3, 1)`); the 1 req/s `NewRateLimiter()` cited
-> here is the *artist image* limiter. Both are shared and both were
-> FIFO. `RateLimiter.WithBackgroundLane` + `WithBackgroundPriority(ctx)`
-> now make a marked caller yield to interactive work and pace at 1/s,
-> and `jobs.KindCatalogEnrich` + `startBackfillJob` give the existing
-> backfills progress and cancel. **"Do not start until the priority
-> question has an answer" is satisfied** — mark this backfill's context
-> and register it the way `BackfillLibraryDiscographies` now is.
-> `PrefetchReleases`' cap of 8 is still unrevisited.
-
-One shared `NewRateLimiter()` at 1 req/s (`explore.go:84`) serves this,
-`PrefetchReleases`, and every interactive browse. A backfill over a
-few thousand owned albums is *hours* of wall clock at that rate — which
-is fine for a background job, and not fine if it starves the album page
-the user is looking at right now.
-
-That is the real work in this plan, and it is not the query:
-
- Interactive browses need to **jump the queue**. Today they cannot;
-  there is one limiter and it is FIFO.
- `PrefetchReleases`' cap of 8 was sized when nothing else competed for
-  the limiter. Revisit it in the same change.
- The 60 s fallback the `AlbumReleasesFailed` fix installed is sized
-  for today's contention. If a backfill can queue behind it, that
-  number is wrong again — which is an argument for priority, not for a
-  bigger number.
-
-Do not start the query until the priority question has an answer.
-
-## The alternative that was considered and rejected
-
-**Project release-group tracklists in the dump build and ship them in
-the artifact.** The data is there: `canonical_musicbrainz_data.csv`
-carries `release_mbid` *and* `recording_mbid`
-(`dumpcatalog.go:520`), and `release_to_rg` already maps release →
-release group. It is derivable from bytes the index build already
-streams, with no new API surface at all, and it would work offline on
-first launch with no per-user backfill.
-
-It is rejected **for this plan** because the artifact is built
-centrally and is byte-identical for every user, so "albums the user
-owns a track of" cannot be a filter on it. Shipping tracklists for the
-whole catalog means per-recording rows against a ~900 MB artifact
-budget (~426 B/row measured), and gating on a popularity floor means it
-is absent for exactly the obscure albums a local backfill would have
-covered.
-
-Worse than absent, in fact — and this is the argument that actually
-kills it. The floor is not one number over artists; it is a **per
-artist track budget** (`dumpcatalog.go:58-89`): 50 tracks for a tier-A
-artist, 25 for tier B, 12 for tier C. A projected tracklist would
-therefore be *whichever* of an album's tracks survived that budget,
-with nothing marking the rest as absent — so the album page would count
-owned against a truncated denominator and render "Play 7 of 9" for a
-twelve-track album. That is a confident lie, where the honest states
-this plan's alternative produces (complete / incomplete / unknown) are
-at worst silent.
-
-Note that `markLibraryArtists` (`dumpcatalog.go:246`) already grants
-every library artist full coverage — 500 tracks, 100 release groups —
-by reading the local library, so the per-user tailoring this option
-supposedly cannot have does exist in code. It is a no-op in the CI
-build (empty library), and reaching it means a **local** dump build:
-the ~205 GB, half-a-day download the entire artifact design exists to
-avoid. Whoever finds that function next should read this paragraph
-before getting excited about it.
-
-Worth revisiting if the artifact ever gains per-user tailoring, or if a
-measurement shows the row count is smaller than feared. Note it also
-yields the *canonical* tracklist rather than MusicBrainz's full version
-list, so the versions dropdown would still browse live when opened.
-
-## Done when
-
- Opening an owned album that has never been opened before renders its
-  catalog tracklist with no network call, after one backfill run.
- An interactive browse issued while the backfill is running is not
-  delayed by it.
- The backfill appears in the jobs indicator, and can be paused and
-  cancelled there.
- A second run after a completed one does approximately nothing.
@@ -6,16 +6,121 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 YellowJacket is a cross-platform desktop music player built with Go (backend) and TypeScript/Lit (frontend), using the Wails framework to bridge them. It supports MP3, FLAC, OGG Vorbis, and WAV playback.

+## Issues
+
+**The tracker is the source of truth for what is wanted and what is
+already being worked on**, and it is shared with a collaborator who
+cannot see this session. `scripts/issue.sh` is the whole interface to
+it (`list`, `mine`, `search`, `show`, `new`, `claim`, `unclaim`,
+`comment`, `close`, `label`, `depends`, `labels`); it needs a
+`GITEA_TOKEN` with `write:issue`.
+
+**Search the tracker before starting any work, and claim what you
+find.** Fifty-odd issues make that a real lookup rather than a
+formality. `./scripts/issue.sh search <terms>` covers open and closed —
+closed matters, because "that was fixed three weeks ago" is the
+cheapest possible answer.
+
+**Claiming happens before the first edit, not before the commit.** The
+whole point is that the collaborator can see the work is taken *while
+it is being done*, so `claim` sets the assignee, applies
+`Status/In Progress` and posts a comment naming the branch and the
+approach — all three, or none. It refuses outright if somebody else
+already holds it, and that refusal is the feature: talk to them rather
+than working around it.
+
+**If no issue covers the work, open one first.** The issue exists
+before the branch does. That is what makes the tracker a description
+of the project rather than a description of the past.
+
+**Findings get filed.** A bug tripped over while doing something else
+is an issue with a reproduction, not a sentence in a chat message
+nobody can search. So is a piece of work deliberately not done — the
+issue is where "we decided not to, and here is why" survives.
+
+Four conventions are already established and are not up for
+reinvention:
+
+- **The labels are a taxonomy**, not tags: `Kind/*`, `Area/*`,
+  `Priority/*`, `Platform/*`, plus `Reviewed/Confirmed` (the code was
+  read and the defect confirmed) and the `Status/*` family. `Status/*`
+  and `Reviewed/*` are **exclusive scopes** — one of each at most, so
+  applying a second replaces the first.
+- **#73 is the roadmap.** It states the order the backlog should be
+  worked in and the soft relations that are not expressible as
+  blockers. Picking work off the open list by eye when a meta issue
+  states the sequence is how the sequence stops meaning anything.
+- **Hard blockers are real Gitea dependencies**, which render on the
+  issue itself, and the blocked issue carries `Status/Blocked`.
+- **A PR body carries a commit-to-issue table, the verification
+  actually run, and a `Closes` list** — PR #83 is the shape. That list
+  is for whoever reads the PR; what actually closes an issue is the
+  footer below.
+
+**The closing keyword goes in the commit body, one issue per line.**
+
+```
+docs: delete four documents that contradict the code
+
+<body>
+
+Closes #98
+```
+
+**Gitea parses commit messages that reach `main`; it does not parse the
+PR body**, which only closes anything if the merge happens to copy it
+into the merge commit. Both halves of that were measured. #83's merge
+commit carried `Closes #9, #13, #14, …` and closed **five of ten** — a
+comma list is partially matched. #93's merge commit body was one
+`Reviewed-on:` trailer, so #92 stayed open behind a perfectly correct
+`Closes` line in the PR description.
+
+A footer costs nothing elsewhere: Conventional Commits allows one,
+`scripts/commit-check.sh` only regexes the subject, and
+semantic-release reads the type from the subject — so this changes no
+release decision. The rule that the issue number stays out of the
+**subject** is unaffected, and was never about the body.
+
+**Check it anyway.** A squash, or a merge message edited by hand,
+still drops the footer. `./scripts/issue.sh list --state open` after a
+merge, looking for what you just shipped; `./scripts/issue.sh close
+<n>` for whatever did not take, with a comment naming the commit.
+
+**Unclaiming is automatic, and it is hooked to the close rather than
+to the merge.** Gitea's auto-close changes state and nothing else, so a
+footer left `Status/In Progress` on a closed issue — #100 was closed
+and marked as being actively worked on at the same time.
+`.gitea/workflows/unclaim.yml` runs on `issues: [closed]`, which covers
+the footer, `issue.sh close` and a click in the web UI alike; stripping
+the label in the PR instead would have been a per-PR habit, and habits
+are what the footer removed. It is not instant — the runner has
+capacity 1 — and reopening deliberately does not restore the label.
+`./scripts/issue.sh list --state closed --label "Status/In Progress"`
+is how you find out it has stopped firing.
+
 ## Planning

-Active and historical plans live in `.planning/`:
+`.planning/` is **design documents and measured history**, not a queue
+— the queue is the tracker, and a plan file that describes work nobody
+has started is a second, staler answer to "what are we doing next".

- `.planning/NOTES.md` — gotchas, deferred items, open architecture questions, the "we already considered and rejected" list.
- `.planning/plans/active/` — work currently in progress (read first).
- `.planning/plans/pending/` — sequenced future work.
- `.planning/plans/completed/` — one concise recap per shipped milestone.
+- `.planning/NOTES.md` — gotchas, measured facts, open architecture
+  questions, and the "we already considered and rejected" list. Dated,
+  because several are properties of someone else's server. **This is
+  where a decision reached on an issue gets written down** when it
+  outlives the issue.
+- `.planning/plans/completed/` — one recap per shipped milestone, kept
+  for the arguments in it. Where a plan shipped incompletely, its
+  header says which issue carries the remainder.
+- `.planning/audits/` — the read-only audits that produced the
+  reconciliation plans. Historical evidence; not a backlog.
+- `.planning/plans/active/` — a multi-phase design document for work
+  **in flight**, linked from the issue that tracks it. Empty is the
+  normal state. There is no `pending/`: a plan nobody is executing is
+  an issue.

-Numbering is sequential and stable across status moves (a plan keeps its `NNN-` prefix as it migrates between `pending → active → completed`). Abandoned plans are deleted; paused work stays in `pending/`.
+Numbering is sequential and stable across status moves (a plan keeps
+its `NNN-` prefix). Abandoned plans are deleted.

 ## Commands

@@ -1442,11 +1547,55 @@ shape as the encoding probe beside it.

 What neither side can give is *which* tracks are missing, only how many
 — so an incomplete album still browses, and that is now the exception
-rather than every album load. Two smaller consequences: existing databases
-read "unknown" until a rescan repopulates the column (which degrades to
-exactly the old behaviour, so nothing breaks), and our own `tagwriter`
-writes track and disc *numbers* but not totals, so autotagging a folder
-currently degrades the field this rests on.
+rather than every album load. One smaller consequence: existing databases
+read "unknown" until a rescan repopulates the column, which degrades to
+exactly the old behaviour, so nothing breaks.
+
+**And our own writers declare the total, because for a long time they
+did not.** `tagwriter` wrote track and disc *numbers* and dropped the
+totals, so autotagging an album actively **erased** the evidence this
+rests on: the release became MBID-matched — a green tick — while the
+field `GetAlbumCompleteness` reads stayed absent, which is exactly the
+"2 of 10 tracks, reported as in your library" the report described.
+`FieldTotalTracks` / `FieldTotalDiscs` are written by the autotag apply
+pass and by the download importer, and `dbsync` persists the track
+total to the row so the album page agrees with the file without waiting
+for a rescan.
+
+Five things about it are load-bearing, and four of them fail silently:
+
+- **The total is per *disc*, not per release**, because that is what
+  the tag form declares and what `GetAlbumCompleteness` **sums** per
+  disc — a release total written on every file multiplies a two-disc
+  album's expectation by two, and no library can then satisfy it.
+  `backend/tagtotals` is that derivation, once, because the two callers
+  must not import each other or the writer.
+- **The Vorbis names are `TRACKTOTAL` and `DISCTOTAL` and no other
+  spelling.** `dhowden/tag`'s Vorbis reader looks at exactly those two
+  keys, so a perfectly reasonable `TOTALTRACKS`, or a `1/12` inside
+  `TRACKNUMBER`, is written successfully and reads back as no total at
+  all. The tests assert the round trip through the reader the *scan*
+  uses rather than through the bytes, for that reason.
+- **ID3's number and total share one frame**, so writing either alone
+  has to read the other off the existing tag or it silently discards
+  it. A total with no number is not written: `/12` is what a reader
+  parses as track 0.
+- **The totals are written unconditionally, not on a diff.** The case
+  this exists for is a file that declares *no* total, which compares
+  equal to nothing and is exactly what a "only if it changed" guard
+  skips.
+- **A single-track download must not be totalled.** A `RecordingMBID`
+  anchor resolves `Expected` to that one track, so the same code would
+  tag a track off a twelve-track album "1 of 1" — and a declared total
+  outranks the catalog total that would otherwise have answered
+  correctly. Confidently wrong is worse than absent here, which is the
+  same rule `Known` exists for.
+
+One gap this did not close, and it is older: **`dhowden/tag` has no
+RIFF reader**, so nothing the tag writer puts in a WAV's `id3 ` chunk
+is visible to `metadata.ExtractTags` — not the totals and not the title
+either. `wav_test.go` reads that chunk itself, which is why no test
+ever noticed.

 **The absence is what gets marked, not the presence.** The tracklist
 put a green tick against every owned track and a legend underneath
@@ -2066,14 +2215,26 @@ branch** (`enable_push: false`, an empty push whitelist, and `CI / check*`
 the pre-receive hook. This file said otherwise for a long time. Tags are
 *not* protected, which is what lets `release.yml` push one.

+**A branch answers a claimed issue** — see "Issues" above. The commit
+grammar is unchanged and is load-bearing for a different reason
+(semantic-release reads it), so the issue number lives in the branch
+name and the PR body rather than in the commit subject.
+
+**A batch of small fixes can be one PR**, which is what #83 did: eight
+branches preserved as merges under one integration branch, so
+authorship survives and the batch lands as one release rather than
+eight. The cost is that its `Closes` list has to be checked afterwards
+— it half-worked.
+
 Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.

 ## CI

-Seven workflows in `.gitea/workflows/`. Five of them package and
+Eight workflows in `.gitea/workflows/`. Five of them package and
 publish (`arch-package`, `homebrew-formula`, `index-artifact`,
 `android-apk`, `desktop-assets`); `release.yml` decides *whether* four of
-those run at all; only `ci.yml` gates, and it is the one to look at when
+those run at all; `unclaim.yml` is housekeeping on the tracker and
+touches no code; only `ci.yml` gates, and it is the one to look at when
 deciding whether a push was healthy.

 **`release.yml` is the entry point for all of it.** On every push to
@@ -106,5 +106,8 @@ make dev          # run with hot-reload
 make build-prod   # produce a release binary
 ```

-More detail for contributors lives in
-[`docs/dev/overview.md`](./docs/dev/overview.md) and [`CLAUDE.md`](./CLAUDE.md).
+More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
+architecture, the conventions and the reasons behind them. What is
+being worked on is [the issue
+tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
+roadmap.
@@ -8,6 +8,7 @@ import (
 	"log/slog"

 	"yellowjacket/backend/database/sql/sqlcgen"
+	"yellowjacket/backend/tagtotals"
 )

 // TagChanges mirrors tagwriter.TagChanges — redefined here so the
@@ -28,6 +29,8 @@ const (
 	FieldYear        = "year"
 	FieldTrackNumber = "track_number"
 	FieldDiscNumber  = "disc_number"
+	FieldTotalTracks = "total_tracks"
+	FieldTotalDiscs  = "total_discs"
 	FieldCoverArt    = "cover_art"
 )

@@ -418,5 +421,32 @@ func buildChanges(
 		changes[FieldDiscNumber] = track.DiscNumber
 	}

+	// The totals are what says "2 of 10" rather than a bare tick, and
+	// dropping them here is what made autotagging an album *erase* the
+	// evidence: the release becomes MBID-matched while the field
+	// GetAlbumCompleteness reads stays absent.
+	//
+	// They are written unconditionally where the candidate has a
+	// tracklist, not only when they differ from the local value, because
+	// the common case is a file that declares no total at all -- which
+	// compares equal to nothing and would be skipped by a diff guard.
+	if tracks, discs := tagtotals.For(
+		candidatePositions(cand), track.DiscNumber,
+	); tracks > 0 {
+		changes[FieldTotalTracks] = tracks
+		changes[FieldTotalDiscs] = discs
+	}
+
 	return changes
 }
+
+// candidatePositions is the candidate's tracklist as bare positions.
+func candidatePositions(cand Candidate) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(cand.Tracks))
+
+	for _, t := range cand.Tracks {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}
@@ -0,0 +1,90 @@
+package autotag
+
+import "testing"
+
+// Autotagging an album used to *erase* the evidence that says "2 of 10":
+// the release became MBID-matched while the totals the files declared
+// went unwritten, so the album page showed a plain tick.  These pin the
+// two halves of the fix that are easy to get wrong silently.
+func TestBuildChanges_Totals(t *testing.T) {
+	t.Parallel()
+
+	twoDiscs := Candidate{
+		Tracks: []CandidateTrack{
+			{DiscNumber: 1, Position: 1},
+			{DiscNumber: 1, Position: 2},
+			{DiscNumber: 2, Position: 1},
+			{DiscNumber: 2, Position: 2},
+			{DiscNumber: 2, Position: 3},
+		},
+	}
+
+	tests := []struct {
+		name       string
+		cand       Candidate
+		local      LocalTrack
+		track      CandidateTrack
+		wantTracks any
+		wantDiscs  any
+	}{
+		{
+			// The common case, and the one a diff guard would skip: the
+			// file declares no total at all, so the total "has not
+			// changed" and would never be written.
+			name: "a file with no total gets one",
+			cand: Candidate{Tracks: []CandidateTrack{
+				{Position: 1}, {Position: 2}, {Position: 3},
+			}},
+			local:      LocalTrack{TrackNumber: 1},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: 3,
+			wantDiscs:  1,
+		},
+		{
+			// 5 here would be the release's track count.  Summed once
+			// per disc by GetAlbumCompleteness that claims a ten-track
+			// expectation for a five-track album, which no library can
+			// ever satisfy.
+			name:       "a multi-disc release totals the track's own disc",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 2, Position: 1},
+			wantTracks: 3,
+			wantDiscs:  2,
+		},
+		{
+			name:       "the other disc gets its own total",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 1, Position: 1},
+			wantTracks: 2,
+			wantDiscs:  2,
+		},
+		{
+			// A candidate with no tracklist knows nothing, and writing
+			// a zero would claim it did.
+			name:       "a candidate with no tracklist writes no total",
+			cand:       Candidate{},
+			local:      LocalTrack{},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: nil,
+			wantDiscs:  nil,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			changes := buildChanges(tc.local, tc.cand, tc.track)
+
+			if got := changes[FieldTotalTracks]; got != tc.wantTracks {
+				t.Errorf("%s: got %v, want %v", FieldTotalTracks, got, tc.wantTracks)
+			}
+
+			if got := changes[FieldTotalDiscs]; got != tc.wantDiscs {
+				t.Errorf("%s: got %v, want %v", FieldTotalDiscs, got, tc.wantDiscs)
+			}
+		})
+	}
+}
@@ -0,0 +1,38 @@
+package autotagservice
+
+import (
+	"testing"
+
+	"yellowjacket/backend/autotag"
+	"yellowjacket/backend/tagwriter"
+)
+
+// twAdapter passes the diff map through unchanged, so autotag's field
+// constants and tagwriter's are the same keys written down twice --
+// deliberately, to keep autotag out of the write pipeline's import
+// graph.  A key that drifts does not fail to compile and does not fail
+// to write: the writer simply finds no entry under the name it looks
+// for, and the field is silently dropped.  That is what this pins, and
+// this package is the one place that imports both.
+func TestAutotagAndTagwriterAgreeOnFieldNames(t *testing.T) {
+	t.Parallel()
+
+	pairs := map[string][2]string{
+		"title":        {autotag.FieldTitle, tagwriter.FieldTitle},
+		"artist":       {autotag.FieldArtist, tagwriter.FieldArtist},
+		"album":        {autotag.FieldAlbum, tagwriter.FieldAlbum},
+		"album artist": {autotag.FieldAlbumArtist, tagwriter.FieldAlbumArtist},
+		"year":         {autotag.FieldYear, tagwriter.FieldYear},
+		"track number": {autotag.FieldTrackNumber, tagwriter.FieldTrackNumber},
+		"disc number":  {autotag.FieldDiscNumber, tagwriter.FieldDiscNumber},
+		"total tracks": {autotag.FieldTotalTracks, tagwriter.FieldTotalTracks},
+		"total discs":  {autotag.FieldTotalDiscs, tagwriter.FieldTotalDiscs},
+		"cover art":    {autotag.FieldCoverArt, tagwriter.FieldCoverArt},
+	}
+
+	for name, pair := range pairs {
+		if pair[0] != pair[1] {
+			t.Errorf("%s: autotag says %q, tagwriter says %q", name, pair[0], pair[1])
+		}
+	}
+}
@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"

+	"yellowjacket/backend/tagtotals"
 	"yellowjacket/backend/tagwriter"
 )

@@ -275,6 +276,25 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 		changes[tagwriter.FieldDiscNumber] = p.Track.DiscNumber
 	}

+	// An imported file should arrive knowing how much of the album it
+	// is one of, or the album reads as "in your library" from its first
+	// imported track onward.
+	//
+	// A *track* download is the case this must not touch: a
+	// RecordingMBID anchor resolves Expected to exactly that one track,
+	// so totalling it would write "1 of 1" onto a track off a
+	// twelve-track album -- a confident lie, and one that outranks the
+	// catalog's own total, which is the fallback that would otherwise
+	// have answered correctly.
+	if dl.RecordingMBID == "" {
+		if tracks, discs := tagtotals.For(
+			expectedPositions(dl.Expected), p.Track.DiscNumber,
+		); tracks > 0 {
+			changes[tagwriter.FieldTotalTracks] = tracks
+			changes[tagwriter.FieldTotalDiscs] = discs
+		}
+	}
+
 	if err := i.tags.WriteUntrackedFileTags(p.Source, changes); err != nil {
 		return fmt.Errorf("write tags: %w", err)
 	}
@@ -282,6 +302,18 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 	return nil
 }

+// expectedPositions is the download's resolved tracklist as bare
+// positions.
+func expectedPositions(expected []ExpectedTrack) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(expected))
+
+	for _, t := range expected {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}
+
 // destinationFor computes a file's library path from the template.
 func (i *Importer) destinationFor(
 	p plannedFile,
@@ -446,3 +446,77 @@ func keysOf(m map[string]tagwriter.TagChanges) []string {

 	return out
 }
+
+// An imported album should arrive knowing its own size, or the album
+// page reads "in your library" from its first imported track onward --
+// which is the badge complaint this exists to answer.
+func TestImportWritesTheAlbumTotals(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t,
+		"01 - Airbag.flac",
+		"02 - Paranoid Android.flac",
+		"03 - Subterranean Homesick Alien.flac",
+		"04 - Exit Music (For a Film).flac",
+	)
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		fourTrackDownload(),
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded for the first track")
+	}
+
+	if got := changes[tagwriter.FieldTotalTracks]; got != 4 {
+		t.Errorf("%s: got %v, want 4", tagwriter.FieldTotalTracks, got)
+	}
+
+	if got := changes[tagwriter.FieldTotalDiscs]; got != 1 {
+		t.Errorf("%s: got %v, want 1", tagwriter.FieldTotalDiscs, got)
+	}
+}
+
+// A RecordingMBID anchor resolves Expected to exactly the one track it
+// asked for, so totalling it would tag a track off a twelve-track album
+// as "1 of 1" -- worse than saying nothing, because a declared total
+// outranks the catalog total that would have answered correctly.
+func TestImportWritesNoTotalsForATrackDownload(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t, "01 - Airbag.flac")
+
+	dl := Download{
+		ID:            "dl-track",
+		LibraryID:     1,
+		RecordingMBID: "mbid-recording",
+		Artist:        "Radiohead",
+		Album:         "OK Computer",
+		Expected:      []ExpectedTrack{{Position: 1, Title: "Airbag"}},
+	}
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		dl,
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded")
+	}
+
+	if _, ok := changes[tagwriter.FieldTotalTracks]; ok {
+		t.Errorf("%s written for a single-track download: %v",
+			tagwriter.FieldTotalTracks, changes[tagwriter.FieldTotalTracks])
+	}
+}
@@ -0,0 +1,56 @@
+// Package tagtotals derives the totals a tag's "5/12" form declares.
+//
+// It exists because the two writers that know a release's full
+// tracklist -- the autotag apply pass and the download importer --
+// must not import each other or the tag writer, and because getting
+// the denominator wrong is invisible: a total that is too large marks
+// a complete album incomplete forever, and nothing fails.
+package tagtotals
+
+// Position is one track's place in a release.  A zero Disc means the
+// release did not say, which is disc 1.
+type Position struct {
+	Disc  int
+	Track int
+}
+
+// For returns the totals to write on a file sitting on disc `disc`:
+// how many tracks that disc has, and how many discs the release has.
+//
+// The track total is **per disc** and not the release's track count,
+// because that is what the tag form means and what
+// GetAlbumCompleteness sums -- summing a release total once per disc
+// would multiply a two-disc album's expectation by two.
+//
+// Tracks are counted by distinct position rather than by row: a
+// tracklist that lists a position twice is a defect in the source, and
+// counting it twice would put an album permanently out of reach of its
+// own total.
+func For(all []Position, disc int) (tracks, discs int) {
+	disc = normaliseDisc(disc)
+
+	seenTracks := make(map[int]struct{}, len(all))
+	seenDiscs := make(map[int]struct{}, 1)
+
+	for _, p := range all {
+		d := normaliseDisc(p.Disc)
+		seenDiscs[d] = struct{}{}
+
+		if d != disc || p.Track <= 0 {
+			continue
+		}
+
+		seenTracks[p.Track] = struct{}{}
+	}
+
+	return len(seenTracks), len(seenDiscs)
+}
+
+// normaliseDisc treats an undeclared disc as disc 1.
+func normaliseDisc(d int) int {
+	if d <= 0 {
+		return 1
+	}
+
+	return d
+}
@@ -0,0 +1,92 @@
+package tagtotals_test
+
+import (
+	"testing"
+
+	"yellowjacket/backend/tagtotals"
+)
+
+func TestFor(t *testing.T) {
+	t.Parallel()
+
+	singleDisc := []tagtotals.Position{
+		{Disc: 0, Track: 1}, {Disc: 0, Track: 2}, {Disc: 0, Track: 3},
+	}
+
+	twoDiscs := []tagtotals.Position{
+		{Disc: 1, Track: 1},
+		{Disc: 1, Track: 2},
+		{Disc: 2, Track: 1},
+		{Disc: 2, Track: 2},
+		{Disc: 2, Track: 3},
+	}
+
+	tests := []struct {
+		name       string
+		all        []tagtotals.Position
+		disc       int
+		wantTracks int
+		wantDiscs  int
+	}{
+		{
+			name: "a single-disc release totals its own tracks",
+			all:  singleDisc, disc: 0, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// An undeclared disc is disc 1, on both sides of the
+			// question -- a file tagged "disc 1" and a tracklist that
+			// declares no disc describe the same disc.
+			name: "an undeclared disc is disc 1",
+			all:  singleDisc, disc: 1, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// The whole point: 5 here would be the release's track
+			// count, which summed once per disc claims a ten-track
+			// expectation for a five-track album.
+			name: "a multi-disc release totals the file's own disc",
+			all:  twoDiscs, disc: 2, wantTracks: 3, wantDiscs: 2,
+		},
+		{
+			name: "the other disc gets its own total",
+			all:  twoDiscs, disc: 1, wantTracks: 2, wantDiscs: 2,
+		},
+		{
+			// A disc the tracklist does not mention cannot be totalled,
+			// and 0 is how the caller is told to write nothing.
+			name: "a disc with no tracks totals nothing",
+			all:  twoDiscs, disc: 3, wantTracks: 0, wantDiscs: 2,
+		},
+		{
+			name: "an empty tracklist totals nothing",
+			all:  nil, disc: 1, wantTracks: 0, wantDiscs: 0,
+		},
+		{
+			// A source that lists a position twice would otherwise put
+			// the album permanently one track short of its own total.
+			name: "a repeated position counts once",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 1}, {Disc: 1, Track: 1}, {Disc: 1, Track: 2},
+			},
+			disc: 1, wantTracks: 2, wantDiscs: 1,
+		},
+		{
+			name: "a track with no position is not counted",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 0}, {Disc: 1, Track: 1},
+			},
+			disc: 1, wantTracks: 1, wantDiscs: 1,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			tracks, discs := tagtotals.For(tc.all, tc.disc)
+			if tracks != tc.wantTracks || discs != tc.wantDiscs {
+				t.Errorf("For(%v, %d) = (%d, %d), want (%d, %d)",
+					tc.all, tc.disc, tracks, discs, tc.wantTracks, tc.wantDiscs)
+			}
+		})
+	}
+}
@@ -183,6 +183,15 @@ func syncDatabase(
 		discNum = toNullInt64(v)
 	}

+	// The completeness evidence.  Without this the row keeps whatever
+	// the last scan read while the file on disk now declares a total,
+	// so the album stays "unknown" until a full rescan -- which is the
+	// state the report describes.
+	totalTracks := old.TotalTracks
+	if v, ok := asInt(params.changes[FieldTotalTracks]); ok {
+		totalTracks = toNullInt64(v)
+	}
+
 	composer := old.Composer
 	if v, ok := params.changes[FieldComposer].(string); ok {
 		composer = v
@@ -207,7 +216,7 @@ func syncDatabase(
 		AlbumID:            albumID,
 		TrackNumber:        trackNum,
 		DiscNumber:         discNum,
-		TotalTracks:        old.TotalTracks,
+		TotalTracks:        totalTracks,
 		Year:               year,
 		Composer:           composer,
 		Comment:            old.Comment,
@@ -101,6 +101,11 @@ func applyFlacTextChanges(cmt *flacvorbis.MetaDataBlockVorbisComment, changes Ta
 		{FieldYear, flacvorbis.FIELD_DATE, true},
 		{FieldTrackNumber, flacvorbis.FIELD_TRACKNUMBER, true},
 		{FieldDiscNumber, "DISCNUMBER", true},
+		// TRACKTOTAL/DISCTOTAL and no other spelling: dhowden/tag's
+		// Vorbis reader looks at exactly these two keys, so TOTALTRACKS
+		// or a "1/12" inside TRACKNUMBER reads back as no total at all.
+		{FieldTotalTracks, "TRACKTOTAL", true},
+		{FieldTotalDiscs, "DISCTOTAL", true},
 		{FieldComposer, "COMPOSER", false},
 	}

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"os"
 	"strconv"
+	"strings"

 	id3v2 "github.com/bogem/id3v2/v2"

@@ -66,17 +67,10 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 		tag.SetYear(strconv.Itoa(v))
 	}

-	if v, ok := asInt(changes[FieldTrackNumber]); ok {
-		trckID := tag.CommonID("Track number/Position in set")
-		tag.DeleteFrames(trckID)
-		tag.AddTextFrame(trckID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
-
-	if v, ok := asInt(changes[FieldDiscNumber]); ok {
-		tposID := tag.CommonID("Part of a set")
-		tag.DeleteFrames(tposID)
-		tag.AddTextFrame(tposID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
+	applyPositionFrame(tag, "Track number/Position in set", changes,
+		FieldTrackNumber, FieldTotalTracks)
+	applyPositionFrame(tag, "Part of a set", changes,
+		FieldDiscNumber, FieldTotalDiscs)

 	if v, ok := changes[FieldComposer].(string); ok {
 		tag.DeleteFrames("TCOM")
@@ -90,6 +84,64 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 	}
 }

+// applyPositionFrame writes an ID3v2 position frame (TRCK or TPOS) in
+// the "n/N" form the readers parse.
+//
+// The number and the total are separate diff entries and either may be
+// absent, so the frame's *existing* value is the base: writing a total
+// alone must not discard the number that is already there, and writing
+// a number alone must not discard a total the file already declared.
+// A total with no number at all is not written, since "/12" says
+// nothing a reader can use.
+func applyPositionFrame(
+	tag *id3v2.Tag, description string, changes TagChanges, numKey, totalKey string,
+) {
+	_, hasNum := changes[numKey]
+	_, hasTotal := changes[totalKey]
+
+	if !hasNum && !hasTotal {
+		return
+	}
+
+	frameID := tag.CommonID(description)
+
+	num, total := parseXofN(
+		strings.TrimRight(tag.GetTextFrame(frameID).Text, "\x00 \t\n\r"),
+	)
+
+	if v, ok := asInt(changes[numKey]); ok {
+		num = v
+	}
+
+	if v, ok := asInt(changes[totalKey]); ok {
+		total = v
+	}
+
+	if num <= 0 {
+		return
+	}
+
+	value := strconv.Itoa(num)
+	if total > 0 {
+		value += "/" + strconv.Itoa(total)
+	}
+
+	tag.DeleteFrames(frameID)
+	tag.AddTextFrame(frameID, id3v2.EncodingUTF8, value)
+}
+
+// parseXofN splits an ID3v2 "n/N" position value.  A bare "n" yields a
+// zero total, and anything unparseable yields zeros — the same reading
+// dhowden/tag gives the frame.
+func parseXofN(s string) (int, int) {
+	numText, totalText, _ := strings.Cut(s, "/")
+
+	num, _ := strconv.Atoi(strings.TrimSpace(numText))
+	total, _ := strconv.Atoi(strings.TrimSpace(totalText))
+
+	return num, total
+}
+
 // applyCoverArtChanges handles the FieldCoverArt entry in the diff map.
 //
 //   - []byte with len > 0: embed the given image as front cover.
@@ -166,6 +166,8 @@ var oggFieldMappings = []struct { //nolint:gochecknoglobals // field mapping tab
 	{FieldYear, "DATE", true},
 	{FieldTrackNumber, "TRACKNUMBER", true},
 	{FieldDiscNumber, "DISCNUMBER", true},
+	{FieldTotalTracks, "TRACKTOTAL", true},
+	{FieldTotalDiscs, "DISCTOTAL", true},
 	{FieldComposer, "COMPOSER", false},
 }

@@ -333,3 +333,31 @@ func TestWriteTrackTags_DBSync(t *testing.T) {
 		t.Error("expected FTS5 result for 'New Title'")
 	}
 }
+
+// The row is what the album page reads, and it is only refreshed by a
+// scan.  Leaving total_tracks at whatever the last scan saw means an
+// album autotagged just now stays "unknown" -- a plain tick on an album
+// the user holds two tracks of -- until a full rescan happens to run.
+func TestWriteTrackTags_PersistsTheTotal(t *testing.T) {
+	db := database.NewTestDB(t)
+	dir := t.TempDir()
+	trackID := seedTestTrack(t, db, createPipelineTestMP3(t, dir))
+
+	tw := NewTagWriter(testLogger(), db, &mockPlayer{}, &mockPipelineLocker{})
+
+	if err := tw.WriteTrackTags(trackID, TagChanges{
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+	}); err != nil {
+		t.Fatalf("WriteTrackTags: %v", err)
+	}
+
+	af, err := db.Queries.GetAudioFile(context.Background(), trackID)
+	if err != nil {
+		t.Fatalf("get audio file: %v", err)
+	}
+
+	if !af.TotalTracks.Valid || af.TotalTracks.Int64 != 10 {
+		t.Errorf("total_tracks: got %v, want 10", af.TotalTracks)
+	}
+}
@@ -26,6 +26,15 @@ const (
 	FieldDiscNumber  = "disc_number"
 	FieldComposer    = "composer"
 	FieldCoverArt    = "cover_art" // []byte for set, nil for clear
+
+	// FieldTotalTracks is how many tracks are on *this file's disc*, not
+	// in the whole release.  That is what the "5/12" form declares and
+	// what GetAlbumCompleteness sums per disc; a release total written
+	// here would multiply the expectation by the number of discs.
+	FieldTotalTracks = "total_tracks"
+
+	// FieldTotalDiscs is how many discs the release has.
+	FieldTotalDiscs = "total_discs"
 )

 // AudioFormat represents a supported audio file format.
@@ -0,0 +1,199 @@
+package tagwriter
+
+import (
+	"path/filepath"
+	"testing"
+
+	"yellowjacket/backend/metadata"
+)
+
+// The totals are the evidence GetAlbumCompleteness reads, and every way
+// of getting them wrong is silent: a tag written under a name the
+// reader does not look at reads back as no total at all, which is
+// indistinguishable from never having written one.  So these assert the
+// round trip through the *reader the scan uses*, not the bytes.
+//
+// WAV is the exception and it is not this change's: dhowden/tag has no
+// RIFF reader at all, so metadata.ExtractTags cannot see a WAV's ID3
+// chunk -- which is why every other test here reads that chunk itself.
+func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
+	t.Parallel()
+
+	changes := TagChanges{
+		FieldTitle:       "Some Song",
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+		FieldDiscNumber:  1,
+		FieldTotalDiscs:  2,
+	}
+
+	viaScanner := func(t *testing.T, path string) *metadata.TrackMetadata {
+		t.Helper()
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		return meta
+	}
+
+	tests := []struct {
+		name  string
+		write func(t *testing.T, dir string) string
+		read  func(t *testing.T, path string) *metadata.TrackMetadata
+	}{
+		{
+			name: "mp3",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestMP3(t, dir, "totals.mp3", nil)
+				if err := writeMp3Tags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeMp3Tags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "flac",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.flac")
+				makeMinimalFLAC(t, path)
+
+				if err := writeFlacTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeFlacTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "ogg",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.ogg")
+				createTestOGG(t, path)
+
+				if err := writeOggTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeOggTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "wav",
+			read: readWavID3Tags,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestWAV(t, dir, "totals.wav", nil)
+
+				if err := writeWavTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeWavTags: %v", err)
+				}
+
+				return path
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			meta := tc.read(t, tc.write(t, t.TempDir()))
+
+			assertIntField(t, "TrackNumber", meta.TrackNumber, 2)
+			assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+			assertIntField(t, "DiscNumber", meta.DiscNumber, 1)
+			assertIntField(t, "TotalDiscs", meta.TotalDiscs, 2)
+		})
+	}
+}
+
+// A number and a total are separate diff entries, so writing one must
+// not discard the other.  For ID3v2 they share a single "n/N" frame,
+// which is the only place this can go wrong -- and it goes wrong by
+// silently zeroing a total the file already declared.
+func TestWriteMp3Totals_PartialUpdateKeepsTheOtherHalf(t *testing.T) {
+	t.Parallel()
+
+	t.Run("writing the number keeps the total", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 2,
+			FieldTotalTracks: 10,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTrackNumber: 4,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 4)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+	})
+
+	t.Run("writing the total keeps the number", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 7,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 7)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 12)
+	})
+
+	// "/12" says nothing a reader can use, and dhowden/tag reads it as
+	// track 0 -- which the scan would store as a real track number.
+	t.Run("a total with no number writes nothing", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "bare.mp3", nil)
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 0)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 0)
+	})
+}
@@ -522,19 +522,20 @@ func readWavID3Tags(
 		}
 	}

-	// Track number (TRCK).
+	// Track number and total (TRCK), disc number and total (TPOS).
+	// Both carry the "n/N" form, so they are read the way a reader
+	// reads them rather than with Atoi -- which sees "2/10" as 0.
 	trckID := parsed.CommonID("Track number/Position in set")
 	if frames := parsed.GetFrames(trckID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.TrackNumber = atoiSafe(tf.Text)
+			meta.TrackNumber, meta.TotalTracks = parseXofN(tf.Text)
 		}
 	}

-	// Disc number (TPOS).
 	tposID := parsed.CommonID("Part of a set")
 	if frames := parsed.GetFrames(tposID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.DiscNumber = atoiSafe(tf.Text)
+			meta.DiscNumber, meta.TotalDiscs = parseXofN(tf.Text)
 		}
 	}

@@ -1,194 +0,0 @@
-# Config Improvement Suggestions
-
-Remaining suggestions for improving the configuration system in YellowJacket.
-
-## 2. Thread Safety Concerns
-
-The current `Config` struct lacks synchronization:
- `Load()` and `Save()` can race with concurrent reads
- `handleConfigUpdate()` in library mutates `l.conf.DirectoryPath` without locks
-
-**Suggestion:** Add a `sync.RWMutex` to protect config access, especially if config is read during scans.
-
-```go
-type Config struct {
-    mu       sync.RWMutex
-    ctx      context.Context
-    logger   *slog.Logger
-    // ...
-}
-
-func (c *Config) Load() error {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    // ...
-}
-```
-
-## 3. Nil Safety in Validation
-
-In `config.go`, validation only runs if `c.Library != nil`, but `handleConfigPost` dereferences `postedConfig.Library` without checking for nil:
-
-```go
-if postedConfig.Library != nil {
-    c.Library = postedConfig.Library
-    // ...
-}
-```
-
-**Status:** Partially addressed in the event refactor, but consider adding explicit nil checks in `Validate()` as well.
-
-## 4. Inconsistent Error Handling on HTTP Responses
-
-In `httphandler.go:28-31`, `WriteHeader` is called *after* rendering the error template, which won't work as expected (headers must be set before writing body):
-
-```go
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-w.WriteHeader(http.StatusInternalServerError)  // Too late!
-```
-
-**Fix:** Set the status code before rendering:
-
-```go
-w.WriteHeader(http.StatusInternalServerError)
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-```
-
-## 5. Make `scanWorkerCount` Configurable
-
-There's a TODO at `library.go:289`:
-```go
-// TODO: make configurable via Config.
-var scanWorkerCount = goruntime.NumCPU()
-```
-
-**Suggestion:** Add this to `library.Config`:
-
-```go
-type Config struct {
-    DirectoryPath Directory `form:"Directory" schema:"directory,required"`
-    ScanWorkers   int       `form:"ScanWorkers" schema:"scan_workers"`
-}
-```
-
-Then in `NewLibrary()` or `Scan()`:
-
-```go
-workers := l.conf.ScanWorkers
-if workers <= 0 {
-    workers = goruntime.NumCPU()
-}
-```
-
-## 6. Consider Config Defaults
-
-Currently if no config exists, an empty one is saved. Consider providing sensible defaults (e.g., common music directories like `~/Music`).
-
-```go
-func (c *Config) setDefaults() {
-    if c.Library == nil {
-        c.Library = &library.Config{}
-    }
-    if c.Library.DirectoryPath == "" {
-        // Try common music directories
-        home, _ := os.UserHomeDir()
-        musicDir := filepath.Join(home, "Music")
-        if info, err := os.Stat(musicDir); err == nil && info.IsDir() {
-            c.Library.DirectoryPath = library.Directory(musicDir)
-        }
-    }
-}
-```
-
-## 7. Config Reload/Watch Capability
-
-The config is only loaded at startup. Consider adding:
- File watcher for external config changes (using `fsnotify`)
- Explicit reload method callable from UI
-
-```go
-func (c *Config) Watch() error {
-    watcher, err := fsnotify.NewWatcher()
-    if err != nil {
-        return err
-    }
-    
-    go func() {
-        for event := range watcher.Events {
-            if event.Op&fsnotify.Write == fsnotify.Write {
-                c.Load()
-                // Emit event for listeners
-            }
-        }
-    }()
-    
-    return watcher.Add(c.filePath)
-}
-```
-
-## 8. Validation Should Return Structured Errors
-
-Currently validation returns combined errors. Consider returning a structured validation result that the UI can map to specific fields for better user feedback.
-
-```go
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-type ValidationResult struct {
-    Valid  bool
-    Errors []ValidationError
-}
-
-func (c *Config) ValidateStructured() ValidationResult {
-    var result ValidationResult
-    result.Valid = true
-    
-    if c.Library != nil {
-        if err := c.Library.Validate(); err != nil {
-            result.Valid = false
-            result.Errors = append(result.Errors, ValidationError{
-                Field:   "Library.DirectoryPath",
-                Message: err.Error(),
-            })
-        }
-    }
-    
-    return result
-}
-```
-
-## 9. Use Standard Library for Config Paths
-
-The path construction in `system/userdata.go` doesn't respect `$XDG_CONFIG_HOME` on Linux or use the standard Go `os.UserConfigDir()`.
-
-**Current implementation:**
-```go
-case "linux":
-    return fmt.Sprintf("/home/%s/%s/yellowjacket", username, unixSubdirs[dt]), nil
-```
-
-**Suggested improvement:**
-```go
-func GetUserConfigDirPath() (string, error) {
-    baseDir, err := os.UserConfigDir()  // Respects XDG_CONFIG_HOME
-    if err != nil {
-        return "", fmt.Errorf("could not get user config directory: %w", err)
-    }
-    
-    path := filepath.Join(baseDir, "yellowjacket")
-    
-    if err := os.MkdirAll(path, 0o755); err != nil {
-        return "", fmt.Errorf("could not create config directory: %w", err)
-    }
-    
-    return path, nil
-}
-```
-
-This approach:
- Respects `$XDG_CONFIG_HOME` on Linux
- Uses proper macOS paths (`~/Library/Application Support`)
- Uses `%AppData%` on Windows
- Is more portable and follows platform conventions
@@ -1,53 +0,0 @@
-# Development Overview
-
-YellowJacket is a moderately complex application. This document gives an overview of how development of it works.
-
-## Logical Breakdown
-
-YellowJacket can be thought about in a heirarchy of logical modules and components. The borders of these logical sections are mostly represented in the code and directory structure as well.
-
- Frontend
-  - UI Components (see [Lit](###lit-web-components))
- Backend
-  - App
-    - Asset Handler
-    - Logging
-    - System
-  - Player
-  - Library
-  - Config
-  - Database
-    - Queries (see [sqlc](###sqlc))
-
-## Dependencies
-
-YellowJacket uses many tools and libraries to provide its functionality. 
-This section lists each of these dependencies and explains how they are used.
-
-### [Wails](https://wails.io)
-
-Used to create desktop apps with Go and web technologies.
-
-### [SQLite](https://github.com/mattn/go-sqlite3?tab=readme-ov-file#go-sqlite3)
-
-Used for local database.
-
-### [sqlc](https://sqlc.dev/)
-
-Used to generate Go code from SQL.
-
-### [Templ](https://templ.guide/)
-
-Used to generate HTML templates with Go code.
-
-### [Beep](https://github.com/gopxl/beep?tab=readme-ov-file#beep)
-
-Used for audio playback.
-
-### [Lit Web Components](https://lit.dev/)
-
-Used for dynamic/reactive frontend components.
-
-### [HTMX](https://htmx.org/)
-
-Used for requesting HTML fragments from the backend and rendering them on the frontend.
@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+#
+# The tracker, from the command line.
+#
+# Issues are this project's source of truth for what is wanted and what is
+# already being worked on, which means "search the tracker" runs at the top
+# of every task rather than occasionally.  Fifty-odd open issues make that a
+# real lookup, and a lookup nobody can remember the shape of is a lookup that
+# gets skipped — so it is one command here instead of a curl re-derived from
+# prose each time.  See CLAUDE.md, "Issues".
+#
+# **Text reaches the API as JSON, never as shell.**  An issue body is
+# arbitrary prose carrying backticks, quotes and `$`, so bodies are read from
+# a file or from stdin and encoded by python3, on the same reasoning that
+# keeps release notes out of `gitea-release.sh`'s argument list.  Only issue
+# numbers and label names cross as arguments, and the numbers are validated.
+#
+# **Claiming is an assignment, a label and a comment, together.**  Any one of
+# them alone is a claim somebody else has to go looking for: the assignee is
+# what shows in the issue list, `Status/In Progress` is what filters, and the
+# comment is what says which branch and what approach.  `claim` does all
+# three, and refuses outright if somebody else already holds it.
+#
+# Usage:
+#   scripts/issue.sh list [--state open|closed|all] [--label L] [--assignee U]
+#   scripts/issue.sh mine
+#   scripts/issue.sh search <text...>
+#   scripts/issue.sh show <n>
+#   scripts/issue.sh new --title <t> [--labels A,B] [--body-file F]
+#   scripts/issue.sh claim <n> [--branch <name>] [--body-file F]
+#   scripts/issue.sh unclaim <n>
+#   scripts/issue.sh comment <n> [--body-file F]
+#   scripts/issue.sh close <n> [--body-file F]
+#   scripts/issue.sh label <n> +Kind/Bug -Status/Blocked
+#   scripts/issue.sh depends <n> <blocker-n>
+#   scripts/issue.sh labels
+#
+# Where a body is taken and no --body-file is given, it is read from stdin.
+#
+# Environment:
+#   GITEA_TOKEN   a PAT with write:issue (plus write:repository and read:user,
+#                 which the rest of this repo's tooling reaches for)
+#   GITEA_URL     defaults to https://git.ljones.me
+#   GITEA_REPO    defaults to yonlu/yellowjacket
+set -euo pipefail
+
+server="${GITEA_URL:-https://git.ljones.me}"
+repo="${GITEA_REPO:-yonlu/yellowjacket}"
+api="$server/api/v1/repos/$repo"
+
+: "${GITEA_TOKEN:?issue.sh: GITEA_TOKEN is not set}"
+command -v python3 >/dev/null || { echo "issue.sh: python3 is required" >&2; exit 1; }
+
+py="$(dirname "$0")/issue_fmt.py"
+
+# ---------------------------------------------------------------- plumbing
+
+call() {
+	local method="$1" path="$2"
+	if [ "$method" = GET ]; then
+		curl -sS -H "Authorization: token $GITEA_TOKEN" "$api$path"
+	else
+		curl -sS -X "$method" \
+			-H "Authorization: token $GITEA_TOKEN" \
+			-H "Content-Type: application/json" \
+			--data-binary @- "$api$path"
+	fi
+}
+
+num() {
+	printf '%s' "${1:-}" | grep -qE '^[0-9]+$' || {
+		echo "issue.sh: '${1:-}' is not an issue number" >&2
+		exit 1
+	}
+	printf '%s' "$1"
+}
+
+# Read a body from a file or stdin.  A file of "-" is stdin.
+read_body() {
+	local file="${1:--}"
+	if [ "$file" = "-" ]; then cat; else cat "$file"; fi
+}
+
+me() { curl -sS -H "Authorization: token $GITEA_TOKEN" "$server/api/v1/user" | python3 "$py" login; }
+
+label_id() { call GET "/labels?limit=100" | python3 "$py" label-id "$1"; }
+
+# Labels are resolved to ids rather than posted as names: Gitea accepts a list
+# of unknown *names* with 200 and applies none of them, so a typo — or a label
+# somebody renamed — reports success and does nothing.
+add_labels() {
+	local n="$1" ids
+	shift
+	ids="$(call GET "/labels?limit=100" | python3 "$py" label-ids "$(IFS=,; printf '%s' "$*")")"
+	python3 "$py" add-label-ids "$ids" | call POST "/issues/$n/labels" |
+		python3 "$py" check >/dev/null
+}
+
+drop_label() {
+	local n="$1" name="$2" id
+	id="$(label_id "$name" 2>/dev/null)" || return 0
+	curl -sS -o /dev/null -X DELETE -H "Authorization: token $GITEA_TOKEN" \
+		"$api/issues/$n/labels/$id"
+}
+
+post_comment() {
+	local n="$1" text
+	text="$(cat)"
+	# Checked here rather than left to the API, which answers an empty body
+	# with "[Body]: Required" and then this pipeline reports a second, more
+	# confusing error from the request that was built anyway.
+	if [ -z "${text//[[:space:]]/}" ]; then
+		echo "issue.sh: refusing to post an empty comment on #$n" >&2
+		exit 1
+	fi
+	printf '%s\n' "$text" | python3 "$py" wrap-body |
+		call POST "/issues/$n/comments" | python3 "$py" check >/dev/null
+}
+
+# ---------------------------------------------------------------- commands
+
+cmd_list() {
+	local state=open label="" assignee="" limit=100 q=""
+	while [ $# -gt 0 ]; do
+		case "$1" in
+		--state) state="$2"; shift 2 ;;
+		--label) label="$2"; shift 2 ;;
+		--assignee) assignee="$2"; shift 2 ;;
+		--limit) limit="$2"; shift 2 ;;
+		--q) q="$2"; shift 2 ;;
+		*) echo "issue.sh list: unknown option $1" >&2; exit 1 ;;
+		esac
+	done
+
+	local path="/issues?type=issues&state=$state&limit=$limit"
+	[ -n "$label" ] && path="$path&labels=$(python3 "$py" urlquote "$label")"
+	[ -n "$assignee" ] && path="$path&assigned_by=$assignee"
+	[ -n "$q" ] && path="$path&q=$(python3 "$py" urlquote "$q")"
+
+	call GET "$path" | python3 "$py" list
+}
+
+cmd_mine() { cmd_list --assignee "$(me)" "$@"; }
+
+cmd_search() {
+	[ $# -gt 0 ] || { echo "usage: issue.sh search <text...>" >&2; exit 1; }
+	echo "-- open --"
+	cmd_list --state open --q "$*"
+	echo "-- closed --"
+	cmd_list --state closed --q "$*"
+}
+
+cmd_show() {
+	local n; n="$(num "${1:-}")"
+	call GET "/issues/$n" | python3 "$py" show
+	echo "-- depends on --"
+	call GET "/issues/$n/dependencies" | python3 "$py" deps
+	echo "-- comments --"
+	call GET "/issues/$n/comments" | python3 "$py" comments
+}
+
+cmd_new() {
+	local title="" labels="" file="-"
+	while [ $# -gt 0 ]; do
+		case "$1" in
+		--title) title="$2"; shift 2 ;;
+		--labels) labels="$2"; shift 2 ;;
+		--body-file) file="$2"; shift 2 ;;
+		*) echo "issue.sh new: unknown option $1" >&2; exit 1 ;;
+		esac
+	done
+	[ -n "$title" ] || { echo "issue.sh new: --title is required" >&2; exit 1; }
+
+	# Label names are resolved to ids first, so a typo is an error here rather
+	# than an issue filed with a label silently absent.
+	local ids="[]"
+	if [ -n "$labels" ]; then
+		ids="$(call GET "/labels?limit=100" | python3 "$py" label-ids "$labels")"
+	fi
+
+	read_body "$file" | python3 "$py" new-issue "$title" "$ids" |
+		call POST "/issues" | python3 "$py" created
+}
+
+cmd_claim() {
+	local n; n="$(num "${1:-}")"; shift || true
+	local branch="" file=""
+	while [ $# -gt 0 ]; do
+		case "$1" in
+		--branch) branch="$2"; shift 2 ;;
+		--body-file) file="$2"; shift 2 ;;
+		*) echo "issue.sh claim: unknown option $1" >&2; exit 1 ;;
+		esac
+	done
+
+	local who holder note
+	who="$(me)"
+	holder="$(call GET "/issues/$n" | python3 "$py" assignees)"
+
+	# The whole point of the workflow, so it is a hard failure.
+	if [ -n "$holder" ] && [ "$holder" != "$who" ]; then
+		echo "issue.sh: #$n is already claimed by $holder — talk to them before starting" >&2
+		exit 1
+	fi
+
+	# The comment is resolved *before* anything is mutated.  Reading it after
+	# the assignment is how a claim ends up half-made: the assignee and the
+	# label land, the comment is rejected as empty, and the issue says it is
+	# taken without saying by what work.
+	if [ -n "$file" ]; then
+		note="$(read_body "$file")"
+	elif [ ! -t 0 ]; then
+		note="$(read_body -)"
+	fi
+	if [ -z "${note//[[:space:]]/}" ]; then
+		note="Starting work on this${branch:+ on \`$branch\`}."
+	fi
+
+	python3 "$py" assign "$who" | call PATCH "/issues/$n" | python3 "$py" check >/dev/null
+	add_labels "$n" "Status/In Progress"
+	printf '%s\n' "$note" | post_comment "$n"
+
+	echo "claimed #$n as $who${branch:+ (branch $branch)}"
+}
+
+cmd_unclaim() {
+	local n; n="$(num "${1:-}")"
+	python3 "$py" assign | call PATCH "/issues/$n" | python3 "$py" check >/dev/null
+	drop_label "$n" "Status/In Progress"
+	echo "unclaimed #$n"
+}
+
+cmd_comment() {
+	local n; n="$(num "${1:-}")"; shift || true
+	local file="-"
+	[ "${1:-}" = "--body-file" ] && file="$2"
+	read_body "$file" | post_comment "$n"
+	echo "commented on #$n"
+}
+
+cmd_close() {
+	local n; n="$(num "${1:-}")"; shift || true
+	local file=""
+	[ "${1:-}" = "--body-file" ] && file="$2"
+	if [ -n "$file" ]; then
+		read_body "$file" | post_comment "$n"
+	elif [ ! -t 0 ]; then
+		read_body - | post_comment "$n"
+	fi
+	printf '{"state":"closed"}' | call PATCH "/issues/$n" | python3 "$py" check >/dev/null
+	# A claim outlives the work if nothing takes the label off.
+	drop_label "$n" "Status/In Progress"
+	echo "closed #$n"
+}
+
+# Hard blockers are real Gitea dependencies, which render on the issue itself
+# — see #73, whose graph is the reason this is not just prose in a comment.
+#
+# The endpoint takes a whole IssueMeta, not an index: a body of {"index": 88}
+# answers **404**, which reads exactly like a missing endpoint on a Gitea
+# build that does not have the feature.
+cmd_depends() {
+	local n blocker
+	n="$(num "${1:-}")"
+	blocker="$(num "${2:-}")"
+	python3 "$py" issue-meta "$repo" "$blocker" |
+		call POST "/issues/$n/dependencies" | python3 "$py" check >/dev/null
+	echo "#$n now depends on #$blocker"
+}
+
+cmd_label() {
+	local n; n="$(num "${1:-}")"; shift
+	local add=() del=()
+	for spec in "$@"; do
+		case "$spec" in
+		+*) add+=("${spec#+}") ;;
+		-*) del+=("${spec#-}") ;;
+		*) echo "issue.sh label: expected +Name or -Name, got '$spec'" >&2; exit 1 ;;
+		esac
+	done
+	if [ ${#add[@]} -gt 0 ]; then
+		add_labels "$n" "${add[@]}"
+	fi
+	local name
+	for name in ${del[@]+"${del[@]}"}; do
+		drop_label "$n" "$name"
+	done
+	echo "relabelled #$n"
+}
+
+# ---------------------------------------------------------------- dispatch
+
+sub="${1:-}"
+[ $# -gt 0 ] && shift
+
+case "$sub" in
+list) cmd_list "$@" ;;
+mine) cmd_mine "$@" ;;
+search) cmd_search "$@" ;;
+show) cmd_show "$@" ;;
+new) cmd_new "$@" ;;
+claim) cmd_claim "$@" ;;
+unclaim) cmd_unclaim "$@" ;;
+comment) cmd_comment "$@" ;;
+close) cmd_close "$@" ;;
+label) cmd_label "$@" ;;
+depends) cmd_depends "$@" ;;
+labels) call GET "/labels?limit=100" | python3 "$py" labels ;;
+*)
+	sed -n '/^# Usage:/,/^# Environment:/p' "$0" | sed 's/^# \{0,1\}//'
+	exit 1
+	;;
+esac
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""JSON encoding and formatting for scripts/issue.sh.
+
+It is a separate file rather than a heredoc for one reason: an issue body is
+arbitrary prose, and every attempt to build that JSON inside the shell ends in
+nested quoting nobody can read or verify.  Here the shell passes only argv and
+stdin, and every string that reaches the API is encoded by json.dumps.
+
+A Gitea error is a JSON object with "message", and it arrives with HTTP 200 in
+enough cases that printing it as data is how a wrong token scope reads as an
+empty tracker.  check() is what turns it into a non-zero exit instead.
+"""
+
+import json
+import sys
+import urllib.parse
+
+
+def die(msg):
+    sys.exit("issue.sh: " + msg)
+
+
+def load():
+    raw = sys.stdin.read()
+    if not raw.strip():
+        die("empty response from the API")
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        die("unreadable response: " + raw[:200])
+
+
+def check(d):
+    if isinstance(d, dict) and "message" in d and "number" not in d:
+        die(d["message"])
+    return d
+
+
+def emit(d):
+    json.dump(d, sys.stdout)
+
+
+def names(items, key="name"):
+    return ", ".join(i[key] for i in items) or "-"
+
+
+def main(argv):
+    cmd = argv[1] if len(argv) > 1 else ""
+    args = argv[2:]
+
+    if cmd == "check":
+        emit(check(load()))
+
+    elif cmd == "urlquote":
+        print(urllib.parse.quote(args[0]))
+
+    elif cmd == "login":
+        print(check(load())["login"])
+
+    elif cmd == "list":
+        for i in check(load()):
+            labels = ",".join(x["name"] for x in i["labels"])
+            who = ",".join(a["login"] for a in (i.get("assignees") or [])) or "-"
+            title = i["title"][:62]
+            print("#%-4d %-6s %-8s %-62s [%s]" % (i["number"], i["state"], who, title, labels))
+
+    elif cmd == "show":
+        d = check(load())
+        print("#%d  %s" % (d["number"], d["title"]))
+        print("state:     " + d["state"])
+        print("labels:    " + names(d["labels"]))
+        print("assignees: " + names(d.get("assignees") or [], "login"))
+        print("url:       " + d["html_url"])
+        print()
+        print(d.get("body") or "(no body)")
+        print()
+
+    elif cmd == "deps":
+        d = check(load())
+        if not d:
+            print("  (none)")
+        for i in d:
+            print("  #%d [%s] %s" % (i["number"], i["state"], i["title"][:70]))
+
+    elif cmd == "comments":
+        d = check(load())
+        if not d:
+            print("  (none)")
+        for c in d:
+            print("  %s (%s): %s" % (c["user"]["login"], c["created_at"][:10], c["body"][:600]))
+
+    elif cmd == "labels":
+        for label in check(load()):
+            print("%-24s %s" % (label["name"], (label.get("description") or "")[:60]))
+
+    elif cmd == "label-id":
+        have = {label["name"]: label["id"] for label in check(load())}
+        if args[0] not in have:
+            die("no such label: " + args[0])
+        print(have[args[0]])
+
+    elif cmd == "label-ids":
+        want = [s.strip() for s in args[0].split(",") if s.strip()]
+        have = {label["name"]: label["id"] for label in check(load())}
+        missing = [w for w in want if w not in have]
+        if missing:
+            die("no such label(s): " + ", ".join(missing))
+        emit([have[w] for w in want])
+
+    elif cmd == "wrap-body":
+        body = sys.stdin.read().strip()
+        if not body:
+            die("refusing to post an empty comment")
+        emit({"body": body})
+
+    elif cmd == "new-issue":
+        title, ids = args[0], json.loads(args[1])
+        body = sys.stdin.read().strip()
+        if not body:
+            die("an issue needs a body — the tracker is the record, not the title")
+        emit({"title": title, "body": body, "labels": ids})
+
+    elif cmd == "created":
+        d = check(load())
+        print("created #%d  %s" % (d["number"], d["html_url"]))
+
+    elif cmd == "assignees":
+        print(",".join(a["login"] for a in (check(load()).get("assignees") or [])))
+
+    elif cmd == "assign":
+        emit({"assignees": list(args)})
+
+    elif cmd == "add-label-ids":
+        emit({"labels": json.loads(args[0])})
+
+    elif cmd == "issue-meta":
+        owner, _, name = args[0].partition("/")
+        emit({"owner": owner, "repo": name, "index": int(args[1])})
+
+    else:
+        die("unknown formatter command: " + cmd)
+
+
+if __name__ == "__main__":
+    main(sys.argv)
Author	SHA1	Message	Date
logan	a4777f26b6	Merge pull request 'Declare the track and disc totals when tagging' (#105 ) from fix/16-tagwriter-totals into main Release / release (push) Successful in 30s Details CI / e2e (push) Successful in 6m8s Details CI / check (push) Successful in 2m23s Details Build & publish the Android APK / apk (push) Successful in 1m25s Details Build & publish Arch package / arch-package (push) Successful in 2m31s Details Attach the desktop build to the release / linux (push) Successful in 54s Details Sync Homebrew formula / sync-formula (push) Successful in 6s Details Closes #16	2026-08-19 00:45:07 +00:00
logan	92faa9741b	Merge branch 'main' into fix/16-tagwriter-totals CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m22s Details CI / e2e (pull_request) Successful in 6m8s Details	2026-08-18 20:32:08 -04:00
yonlu	bf0a53e64c	Merge pull request 'Give the unclaim step a CA bundle' (#110 ) from fix/unclaim-ca-certs into main Release / release (push) Successful in 31s Details CI / e2e (push) Successful in 6m3s Details CI / check (push) Successful in 2m22s Details Build & publish the Android APK / apk (push) Successful in 1m24s Details Build & publish Arch package / arch-package (push) Successful in 2m29s Details Attach the desktop build to the release / linux (push) Successful in 52s Details Sync Homebrew formula / sync-formula (push) Successful in 6s Details Reviewed-on: #110	2026-08-18 23:30:31 +00:00
yonlu	7be4a02e31	fix(ci): give the unclaim step a CA bundle CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m27s Details CI / e2e (pull_request) Successful in 6m14s Details Second defect in the same workflow. The shell fix took -- the step ran under `bash --noprofile --norc -e -o pipefail` -- and got one layer further before failing: curl: (77) error setting certificate file: /etc/ssl/certs/ca-certificates.crt ubuntu:24.04 ships no CA bundle, and --no-install-recommends skips the ca-certificates that curl recommends, so curl came up unable to verify TLS against our own Gitea. This was avoidable by reading the repo rather than reasoning about it: ci.yml (twice), desktop-assets.yml, android-apk.yml and release.yml all spell out `ca-certificates curl ... jq` for exactly this reason. The convention was written down five times already. Validated in the real image this time rather than by extracting the script and running it on the host, which is what missed this: the step now succeeds inside `docker run ubuntu:24.04` against a scratch issue -- label present, 204, label gone -- and the previous version reproduces `curl: (77)` in the same image. Both checked, then the scratch issue was deleted. The DELETE also keeps its response body now and prints it on a non-204. Whether the automatic token carries issue-write scope is still unproven, because both failures happened before the API call, and "403" without Gitea's own sentence would cost another merge to interpret. Closes #102	2026-08-18 19:08:50 -04:00
yonlu	ad9c25a5a2	Merge pull request 'Run the unclaim step under bash' (#108 ) from fix/unclaim-shell into main Release / release (push) Successful in 32s Details CI / e2e (push) Successful in 6m10s Details CI / check (push) Successful in 2m23s Details Build & publish the Android APK / apk (push) Successful in 1m23s Details Build & publish Arch package / arch-package (push) Successful in 2m37s Details Attach the desktop build to the release / linux (push) Successful in 52s Details Sync Homebrew formula / sync-formula (push) Successful in 7s Details Reviewed-on: #108	2026-08-18 23:05:38 +00:00
yonlu	a83a127e31	fix(ci): run the unclaim step under bash CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m28s Details CI / e2e (pull_request) Successful in 6m14s Details The workflow shipped in #103 and failed on every close, on its second line, before reaching the API: shell: sh -e {0} /var/run/act/workflow/0.sh: 2: set: Illegal option -o pipefail Inside `container:` the act runner selects sh, not bash, and `set -o pipefail` is a bashism. homebrew-formula.yml carries the same line without trouble because it runs with no container, on the host image where bash is the default -- so "another workflow does it" was not the evidence it looked like, and the comment now says so where the next person will read it. pipefail is kept rather than dropped for POSIX's sake: the lookup is `curl -sSf ... \| jq`, so without it an API error yields empty output, an empty label id, and a cheerful "nothing to do" on every close. A silent no-op is the one outcome worse than a failing job here. Validated end to end against scratch issues rather than by reading it: with the label present the step returns 204 and the label is gone, and against an issue that never carried it the step also returns 204 and exits 0 -- which is what makes it safe to run on every close rather than only claimed ones. Still untested: whether secrets.GITEA_TOKEN carries issue-write scope. The old run never got far enough to find out. If it 403s, the fix is one line -- secrets.PACKAGE_TOKEN, which is a user PAT. Closes #102	2026-08-18 18:54:39 -04:00
logan	4b9114fd8d	fix(tagwriter): declare the track and disc totals when tagging CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m46s Details CI / e2e (pull_request) Successful in 6m18s Details An album the user holds 2 of 10 tracks of showed a green tick reading "is in your library", and the mechanism was our own writer. tagwriter wrote track and disc numbers and dropped the totals, so autotagging a folder made the release MBID-matched -- which is what earns the tick -- while erasing the one field GetAlbumCompleteness reads. The evidence for "2 of 10" was destroyed by the act that produced the tick. FieldTotalTracks and FieldTotalDiscs are written as the ID3 "n/N" form and as Vorbis TRACKTOTAL/DISCTOTAL; the autotag apply pass and the download importer fill them from the release's own tracklist; and dbsync persists the track total to audio_files.total_tracks so the album page agrees with the file without waiting for a rescan. Five things about it are load-bearing, and four fail silently: - The total is per disc, not per release, because that is what the tag form declares and what GetAlbumCompleteness sums per disc. A release total on every file multiplies a two-disc album's expectation by two, which no library can satisfy. backend/tagtotals is that derivation once, since the two callers must not import the writer or each other. - The Vorbis names are TRACKTOTAL and DISCTOTAL and no other spelling. dhowden/tag reads exactly those two keys, so TOTALTRACKS -- which xiph lists and several taggers write -- or a "1/12" packed into TRACKNUMBER writes successfully and reads back as no total at all. The tests therefore assert the round trip through the reader the scan uses, not through the bytes. - ID3's number and total share one frame, so writing either alone must read the other off the existing tag or discard it. A total with no number is not written: "/12" parses as track 0. - The totals are written unconditionally rather than on a diff. The case this exists for is a file declaring no total at all, which compares equal to nothing and is exactly what a "only if it changed" guard skips. - A single-track download is not totalled. A RecordingMBID anchor resolves Expected to that one track, so the same code would tag a track off a twelve-track album "1 of 1" -- and a declared total outranks the catalog total that would have answered correctly. autotag's field constants are a second copy of tagwriter's, deliberately so autotag stays out of the write pipeline's import graph. A key that drifts neither fails to compile nor fails to write -- the writer simply finds nothing under the name it looks for -- so autotagservice, the one package importing both, now pins them. Steps 2 and 3 of the issue stay open under #38: the catalog fallback already landed as completenessAnswer(), and the badge call-site audit is the part that overlaps it. Closes #16	2026-08-18 18:19:54 -04:00
yonlu	e049a71458	Merge pull request 'Drop the claim label when an issue closes' (#103 ) from ci/unclaim-on-close into main CI / check (push) Successful in 2m30s Details Release / release (push) Successful in 31s Details CI / e2e (push) Successful in 6m6s Details Reviewed-on: #103	2026-08-18 21:57:11 +00:00
yonlu	0c944f2382	ci: drop the claim label when an issue closes CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m27s Details CI / e2e (pull_request) Successful in 6m17s Details A `Closes #N` footer closes the issue on merge and leaves `Status/In Progress` on it, because Gitea's auto-close touches state and nothing else. #100 was closed and simultaneously marked as being actively worked on. `scripts/issue.sh close` does drop the label, and is exactly the call the footer exists to avoid making. This hooks the close rather than the merge. Stripping the label in the PR would work and would be a per-PR habit, which is what the footer removed in the first place; `issues: [closed]` covers the footer, issue.sh close and a click in the web UI alike, and asks nothing of anyone at any of them. Reopening deliberately does not restore the label: reopening says the work was not finished, not that somebody is at a keyboard now. Two costs, both stated in the file rather than discovered later. The runner has capacity 1 and is shared with an index build that can hold it for three hours, so this is not instant -- stale for an afternoon beats stale forever, which is what it was. And it is an eighth workflow, so CLAUDE.md's count moves with it. The audit stays, because a workflow that silently stops firing is the failure mode this area has already produced once: ./scripts/issue.sh list --state closed --label "Status/In Progress" Closes #102	2026-08-18 17:36:05 -04:00
yonlu	75525b67e4	Merge pull request 'Put the closing keyword where Gitea will actually read it' (#101 ) from docs/closing-keyword into main CI / check (push) Successful in 2m27s Details Release / release (push) Successful in 31s Details CI / e2e (push) Successful in 6m15s Details Reviewed-on: #101	2026-08-18 21:30:35 +00:00
yonlu	85768dc489	docs: put the closing keyword where Gitea will actually read it CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m27s Details CI / e2e (pull_request) Successful in 6m7s Details CLAUDE.md said the Closes list was unreliable and to close by hand. It is unreliable for a specific reason, and the rule can say what works. Gitea parses commit messages that reach main. It does not parse the PR body, which closes something only if the merge happens to copy it into the merge commit message. Both halves were measured here: #83's merge commit carried "Closes #9, #13, #14, ..." and closed five of the ten, because a comma list is only partially matched; #93's merge commit body was a lone Reviewed-on: trailer, so #92 stayed open behind a perfectly correct Closes line in the PR description. So the keyword goes in the commit body as a footer, one issue per line. That costs nothing elsewhere -- Conventional Commits allows a footer, commit-check only regexes the subject, and semantic-release reads the type from the subject, so no release decision changes. The existing rule that the issue number stays out of the subject is untouched and was never about the body. The verification step stays, because a squash or a hand-edited merge message still drops the footer. This commit is the experiment: if #98 and #100 close when this branch merges without anyone touching them, the mechanism is confirmed. Closes #98 Closes #100	2026-08-18 17:15:28 -04:00
yonlu	1a221a40d3	Merge pull request 'Delete four documents that contradict the code' (#99 ) from docs/retire-stale-planning-docs into main CI / check (push) Successful in 2m26s Details Release / release (push) Successful in 29s Details CI / e2e (push) Successful in 6m14s Details Reviewed-on: #99	2026-08-18 21:06:59 +00:00
yonlu	0821deb877	Merge branch 'main' into docs/retire-stale-planning-docs CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m26s Details CI / e2e (pull_request) Successful in 6m17s Details	2026-08-18 20:55:52 +00:00
yonlu	31ada14111	docs: delete four documents that contradict the code CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m27s Details CI / e2e (pull_request) Successful in 6m9s Details They do not merely lag it, they contradict it, which is worse than absent: the only way to find out one is wrong is to trust it. docs/dev/roadmap.md, 1648 lines. Its "Current State" describes an app with basic playback, a track list and an album grid. Phases 1, 2, 3 and 5 have shipped entire -- playlists, shuffle and repeat, shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Decision Log records "Testing: Deferred" against 836 Vitest tests, a Playwright suite on two engines and race-detector passes in three build configurations. .pi/journal.md, "what happened and what's next", frozen at plan 005 and still saying everything from phase 1 onward is uncommitted. That is the tracker's job now, and a work log that is wrong about what is committed is a hazard rather than a stale file. docs/dev/overview.md, a shallower and partly incorrect CLAUDE.md architecture section. README pointed at it and points at CLAUDE.md now. docs/dev/config-suggestions.md, eight suggestions of which one survived -- the rest were overtaken by rewrites: applyDefaults exists, scan concurrency is configurable with SSD/HDD detection, and httphandler.go and the WriteHeader-after-render bug it described are gone entirely. Nothing is lost: the genuinely unbuilt work was filed first, as #94 device sync, #95 layout customisation, #96 AcoustID and #97 the config setters that take no lock. Refs #98	2026-08-18 16:39:21 -04:00
yonlu	20139394f3	Merge pull request 'Make the issue tracker the source of truth' (#93 ) from docs/issue-driven-workflow into main CI / check (push) Successful in 2m27s Details CI / e2e (push) Successful in 6m14s Details Release / release (push) Successful in 30s Details Reviewed-on: #93	2026-08-18 20:35:44 +00:00
yonlu	eb139cf872	docs: make the issue tracker the source of truth CI / check (push) Skipped CI / e2e (push) Skipped CI / check (pull_request) Successful in 2m28s Details CI / e2e (pull_request) Successful in 6m9s Details Work has been starting from a chat message and a plan file, so two people could pick up the same thing and neither could see the other. The tracker is where that is visible. Search before starting, claim before the first edit -- not before the commit, since the point is that the other person can see the work is taken while it is being done. If no issue covers it, open one first: that is what makes the tracker a description of the project rather than a description of the past. The conventions were already right and are written down rather than reinvented -- the Kind/Area/Priority/Platform/Reviewed/Status taxonomy, its exclusive scopes, #73 as the roadmap, real Gitea dependencies for hard blockers, and PR #83's body shape. What #83 also demonstrated is that a Closes list closes nothing reliably: it listed ten and five of them sat open in main for a fortnight. So closing is a step you take and verify, not a keyword you trust. .planning/ stops being a queue and keeps design documents and measured history -- NOTES.md, the audits, the completed plans and the arguments in them. plans/pending/ is gone, because a plan nobody is executing is an issue; everything unimplemented in it is now #85-#91, and each completed plan says which issue carries its remainder. autotag.md is kept as a historical record, marked stale where the scoring overhaul overtook it. The commit grammar is unchanged and is load-bearing for a different reason, so the issue number lives in the branch name and the PR body rather than the commit subject. Refs #92	2026-08-18 16:23:52 -04:00
yonlu	ae82fd2233	chore(scripts): reach the issue tracker from the command line Issues become this project's source of truth for what is wanted and what is already being worked on, which puts "search the tracker" at the top of every task rather than occasionally. Fifty-odd open issues make that a real lookup, and a lookup nobody can remember the shape of is a lookup that gets skipped -- the same way the CI log endpoint cost two sessions to a tool that 404s. Text reaches the API as JSON and never as shell, which is why the formatting half is its own Python file: an issue body is arbitrary prose carrying backticks, quotes and $, and every attempt to build that JSON inside the shell ends in nested quoting nobody can verify. Same reasoning that keeps release notes out of gitea-release.sh's argument list. Claiming is an assignment, a label and a comment together, because any one alone is a claim somebody has to go looking for. It resolves the comment before it mutates anything -- reading it afterwards is how a claim ends up half-made, with the issue saying it is taken without saying by what work -- and refuses outright if somebody else holds it. Three API shapes are pinned here because each fails quietly: - Labels are resolved to ids rather than posted as names. Gitea accepts a list of unknown names with 200 and applies none of them, so a typo reports success and does nothing. - The dependency endpoint takes a whole IssueMeta, not an index. A body of {"index": 88} answers 404, which reads exactly like a Gitea build without the feature. - close drops Status/In Progress, or a claim outlives the work. Refs #92	2026-08-18 16:23:39 -04:00
logan	3c3197df4b	Small-fix batch: ten issues from the desktop backlog (#83 ) Release / release (push) Successful in 33s Details CI / e2e (push) Successful in 6m10s Details CI / check (push) Successful in 2m26s Details Build & publish the Android APK / apk (push) Successful in 1m26s Details Build & publish Arch package / arch-package (push) Successful in 2m36s Details Attach the desktop build to the release / linux (push) Successful in 56s Details Sync Homebrew formula / sync-formula (push) Successful in 6s Details Rolls up #82 (@yonlu) and #74, #75, #76, #77, #78, #79, #81 as one push, so the batch cuts one release rather than eight. Closes #9, #13, #14, #19, #26, #29, #33, #35, #37, #41.	2026-08-18 16:18:36 +00:00