Four documents describe a project that no longer exists. They are not merely out of date — they contradict the code, which makes them worse than absent, because the only way to find out they are wrong is to trust one and be misled.
Follows #92, which made the tracker the source of truth and cleared .planning/. This is the same pass over docs/ and .pi/.
The rule being applied
Four homes, and anything that answers none of these questions goes:
Home
Answers
docs/
how the app behaves and how you operate it now
CLAUDE.md
how the code is built and why it is that way
the tracker
what is wanted and what is in flight
.planning/NOTES.md
measured facts and rejected ideas that outlive one issue
Deleted
docs/dev/roadmap.md (1,648 lines). Its "Current State" describes an app with "basic playback, track list and album grid views, configuration page". Phases 1, 2, 3 and 5 have shipped entire — playlists, shuffle and repeat, keyboard shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Technical Debt list is twenty unchecked boxes, several of them done. Its Decision Log records "Testing: Deferred — focus on architecture first" against a repo with 836 Vitest tests, a Playwright suite on two engines, and race-detector passes in three build configurations.
.pi/journal.md (118 lines). "Temporal memory: what happened and what's next", frozen at plan 005 and still saying "everything from phase 1 onward is still uncommitted". That is the tracker's job now, and a work log that is wrong about what is committed is a hazard.
docs/dev/overview.md (53 lines). A shallower and partly incorrect version of CLAUDE.md's architecture section. README pointed at it; it points at CLAUDE.md now.
docs/dev/config-suggestions.md (194 lines). Eight numbered suggestions, of which one is still live — it went to #97. The rest were overtaken by rewrites: applyDefaults exists, scan concurrency is configurable as ScanConcurrency with SSD/HDD detection, and httphandler.go and the WriteHeader-after-render bug it described are gone entirely.
docs/android-release.md, docs/PROFILING.md and docs/index-cache.md are operational and accurate. docs/dev/resources.md is eight lines of links. .planning/NOTES.md, .planning/audits/ and .planning/plans/completed/ hold the measurements and arguments that CLAUDE.md compresses into conclusions — that is compression, not duplication.
AGENTS.md is a symlink to CLAUDE.md. That is the convention working, not redundancy.
Done when
Every remaining document describes either the app as it is or a decision as it was made, and nothing describes work nobody is doing.
Note on ordering: this branch is off main, so it does not carry scripts/issue.sh — that is in #93. The two are independent and either can merge first.
Verified: no remaining reference to any deleted file (README repointed at CLAUDE.md); no broken relative links in README.md, docs/ or .pi/; commit-check passed via the commit-msg hook. No code changed.
Four documents describe a project that no longer exists. They are not merely out of date — they contradict the code, which makes them worse than absent, because the only way to find out they are wrong is to trust one and be misled.
Follows #92, which made the tracker the source of truth and cleared `.planning/`. This is the same pass over `docs/` and `.pi/`.
## The rule being applied
Four homes, and anything that answers none of these questions goes:
| Home | Answers |
|---|---|
| `docs/` | how the app behaves and how you operate it **now** |
| `CLAUDE.md` | how the code is built and **why it is that way** |
| the tracker | what is wanted and what is in flight |
| `.planning/NOTES.md` | measured facts and rejected ideas that outlive one issue |
## Deleted
**`docs/dev/roadmap.md` (1,648 lines).** Its "Current State" describes an app with "basic playback, track list and album grid views, configuration page". Phases 1, 2, 3 and 5 have shipped entire — playlists, shuffle and repeat, keyboard shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Technical Debt list is twenty unchecked boxes, several of them done. Its Decision Log records **"Testing: Deferred — focus on architecture first"** against a repo with 836 Vitest tests, a Playwright suite on two engines, and race-detector passes in three build configurations.
**`.pi/journal.md` (118 lines).** "Temporal memory: what happened and what's next", frozen at plan 005 and still saying "everything from phase 1 onward is still uncommitted". That is the tracker's job now, and a work log that is wrong about what is committed is a hazard.
**`docs/dev/overview.md` (53 lines).** A shallower and partly incorrect version of CLAUDE.md's architecture section. README pointed at it; it points at CLAUDE.md now.
**`docs/dev/config-suggestions.md` (194 lines).** Eight numbered suggestions, of which **one** is still live — it went to #97. The rest were overtaken by rewrites: `applyDefaults` exists, scan concurrency is configurable as `ScanConcurrency` with SSD/HDD detection, and `httphandler.go` and the `WriteHeader`-after-render bug it described are gone entirely.
## Salvaged first, so nothing is lost
| Issue | From |
|---|---|
| #94 device sync over MTP, with re-encoding | roadmap phase 6 |
| #95 UI layout customisation — registry, layouts, editor | roadmap phase 4 |
| #96 AcoustID fingerprinting | roadmap 5.2 |
| #97 `config.Config` has a dozen setters and no lock | config-suggestions #2 |
## Kept, and why
`docs/android-release.md`, `docs/PROFILING.md` and `docs/index-cache.md` are operational and accurate. `docs/dev/resources.md` is eight lines of links. `.planning/NOTES.md`, `.planning/audits/` and `.planning/plans/completed/` hold the measurements and arguments that CLAUDE.md compresses into conclusions — that is compression, not duplication.
`AGENTS.md` is a symlink to `CLAUDE.md`. That is the convention working, not redundancy.
## Done when
Every remaining document describes either the app as it is or a decision as it was made, and nothing describes work nobody is doing.
---
**Note on ordering:** this branch is off `main`, so it does not carry `scripts/issue.sh` — that is in #93. The two are independent and either can merge first.
**Verified:** no remaining reference to any deleted file (README repointed at `CLAUDE.md`); no broken relative links in `README.md`, `docs/` or `.pi/`; `commit-check` passed via the `commit-msg` hook. No code changed.
**Closes** #98
yonlu
self-assigned this 2026-08-18 20:39:44 +00:00
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
Follow-up on this branch rather than an amend, since the previous run was already going.
97f2eb8 states the rule that actually works and is itself the experiment: its footer is
Closes #98
Closes #100
one issue per line, in the commit body. If both close on merge without anyone touching them, the mechanism is confirmed — and if they do not, that is worth knowing before the rule is trusted.
Measured, and why the old guidance was only half right:
closed nothing; #92 stayed open behind a correct PR body
Gitea parses commit messages that reach main, not the PR body. The footer costs nothing elsewhere: Conventional Commits allows one, commit-check only regexes the subject, and semantic-release reads the type from the subject — so no release decision changes.
Follow-up on this branch rather than an amend, since the previous run was already going.
`97f2eb8` states the rule that actually works and **is itself the experiment**: its footer is
```
Closes #98
Closes #100
```
one issue per line, in the commit body. If both close on merge without anyone touching them, the mechanism is confirmed — and if they do not, that is worth knowing before the rule is trusted.
Measured, and why the old guidance was only half right:
| Merge | What reached the commit message | Result |
|---|---|---|
| #83 `3c3197d` | `Closes #9, #13, #14, …` | closed **5 of 10** — a comma list is partially matched |
| #93 `2013939` | `Reviewed-on:` only | closed **nothing**; #92 stayed open behind a correct PR body |
Gitea parses commit messages that reach `main`, not the PR body. The footer costs nothing elsewhere: Conventional Commits allows one, `commit-check` only regexes the subject, and semantic-release reads the type from the subject — so no release decision changes.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Four documents describe a project that no longer exists. They are not merely out of date — they contradict the code, which makes them worse than absent, because the only way to find out they are wrong is to trust one and be misled.
Follows #92, which made the tracker the source of truth and cleared
.planning/. This is the same pass overdocs/and.pi/.The rule being applied
Four homes, and anything that answers none of these questions goes:
docs/CLAUDE.md.planning/NOTES.mdDeleted
docs/dev/roadmap.md(1,648 lines). Its "Current State" describes an app with "basic playback, track list and album grid views, configuration page". Phases 1, 2, 3 and 5 have shipped entire — playlists, shuffle and repeat, keyboard shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Technical Debt list is twenty unchecked boxes, several of them done. Its Decision Log records "Testing: Deferred — focus on architecture first" against a repo with 836 Vitest tests, a Playwright suite on two engines, and race-detector passes in three build configurations..pi/journal.md(118 lines). "Temporal memory: what happened and what's next", frozen at plan 005 and still saying "everything from phase 1 onward is still uncommitted". That is the tracker's job now, and a work log that is wrong about what is committed is a hazard.docs/dev/overview.md(53 lines). A shallower and partly incorrect version of CLAUDE.md's architecture section. README pointed at it; it points at CLAUDE.md now.docs/dev/config-suggestions.md(194 lines). Eight numbered suggestions, of which one is still live — it went to #97. The rest were overtaken by rewrites:applyDefaultsexists, scan concurrency is configurable asScanConcurrencywith SSD/HDD detection, andhttphandler.goand theWriteHeader-after-render bug it described are gone entirely.Salvaged first, so nothing is lost
config.Confighas a dozen setters and no lockKept, and why
docs/android-release.md,docs/PROFILING.mdanddocs/index-cache.mdare operational and accurate.docs/dev/resources.mdis eight lines of links..planning/NOTES.md,.planning/audits/and.planning/plans/completed/hold the measurements and arguments that CLAUDE.md compresses into conclusions — that is compression, not duplication.AGENTS.mdis a symlink toCLAUDE.md. That is the convention working, not redundancy.Done when
Every remaining document describes either the app as it is or a decision as it was made, and nothing describes work nobody is doing.
Note on ordering: this branch is off
main, so it does not carryscripts/issue.sh— that is in #93. The two are independent and either can merge first.Verified: no remaining reference to any deleted file (README repointed at
CLAUDE.md); no broken relative links inREADME.md,docs/or.pi/;commit-checkpassed via thecommit-msghook. No code changed.Closes #98
Follow-up on this branch rather than an amend, since the previous run was already going.
97f2eb8states the rule that actually works and is itself the experiment: its footer isone issue per line, in the commit body. If both close on merge without anyone touching them, the mechanism is confirmed — and if they do not, that is worth knowing before the rule is trusted.
Measured, and why the old guidance was only half right:
3c3197dCloses #9, #13, #14, …2013939Reviewed-on:onlyGitea parses commit messages that reach
main, not the PR body. The footer costs nothing elsewhere: Conventional Commits allows one,commit-checkonly regexes the subject, and semantic-release reads the type from the subject — so no release decision changes.