docs: archive the finished backlogs (RD-30)
Two backlog trees are complete: `docs/project/backlog/` (75 files, every WP done) and `docs/project/refactor-backlog-setup/` (the arc before it). Move both under `docs/project/archive/` with `git mv`, so history stays intact through `git log --follow`. `SHOWCASE-ROADMAP.md` moves with them, because it points at the now-archived backlog README. Add `docs/project/archive/README.md`. It states that these trees are historical and names the two directories that are still live. Repoint every inbound reference named in RD-30's Files table: CLAUDE.md, the root README, both backend READMEs, `LetterHtml.cs`, `a11y.mdx`, the `document-feature` and `new-ssp` skills, and the readable-codebase PLAN, README, and RD-19 ticket. Fix two upward-relative links inside the moved WP files (WP-68, WP-69) that gained a directory level and would otherwise break. Repoint `.prettierignore`'s two agent-prompt exclusions to their new path, so prettier keeps leaving those files' exact wording alone. Mark RD-30 done and check off its acceptance criteria; flip its README row to done. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,119 @@
|
||||
# RD-30 — Archive the finished backlogs
|
||||
|
||||
Status: done
|
||||
Phase: 5 — fix the docs that describe this flow
|
||||
|
||||
## Why
|
||||
|
||||
Two backlog trees are complete. `docs/project/backlog/` holds 74 work packages, and every one
|
||||
reads `Status: done` (verified with `grep -L '^Status: done' docs/project/backlog/WP-*.md`,
|
||||
which returns nothing). `docs/project/refactor-backlog-setup/` is the arc before it.
|
||||
|
||||
Together they are 16,300 of the docs tree's 20,317 lines. A reader who opens `docs/project/`
|
||||
to find the active plan meets two finished ones first. Move them out of the way. Git keeps the
|
||||
history; the files stay readable at their new path.
|
||||
|
||||
## Read first
|
||||
|
||||
- `docs/project/readable-codebase/PLAN.md`, phase 5 item 1 (line 818).
|
||||
- `docs/project/backlog/README.md` — the WP process and template. Two skills point at it, so it
|
||||
survives the move as a live reference, not as dead paper.
|
||||
|
||||
## Decisions (pre-made, do not relitigate)
|
||||
|
||||
1. **`git mv`, not delete.** `docs/project/backlog/` → `docs/project/archive/backlog/`, and
|
||||
`docs/project/refactor-backlog-setup/` → `docs/project/archive/refactor-backlog-setup/`.
|
||||
Rename with `git mv` so `git log --follow` still works.
|
||||
2. **`docs/project/SHOWCASE-ROADMAP.md` moves too.** Its whole body is a pointer at
|
||||
`backlog/README.md`, through a **relative** link that this move breaks. It is superseded by
|
||||
a document that is now archived, so it belongs beside it, at
|
||||
`docs/project/archive/SHOWCASE-ROADMAP.md`. Fix its link to `backlog/README.md` in place.
|
||||
3. **`docs/project/prd/` stays.** PRDs describe what the product does, not which tickets ran.
|
||||
They are reference material, not a finished plan.
|
||||
4. **Add `docs/project/archive/README.md`, about 15 lines.** State three facts: these trees are
|
||||
historical, every ticket in them is done, and git holds the rest. Name what is still live —
|
||||
`docs/project/readable-codebase/` and `docs/project/prd/`. Do not summarise 74 work packages.
|
||||
5. **Repoint every inbound reference.** They are few and they are known (see Files). A link
|
||||
into an archived document is fine; a link into a path that no longer exists is not.
|
||||
6. **The `backlog/README.md` WP template stays the canonical template.** The
|
||||
`document-feature` skill and `new-ssp` skill both cite it. Repoint them to the archive path;
|
||||
do not copy the template to a second home.
|
||||
|
||||
## Files
|
||||
|
||||
The move:
|
||||
|
||||
- `docs/project/backlog/` → `docs/project/archive/backlog/` (75 files).
|
||||
- `docs/project/refactor-backlog-setup/` → `docs/project/archive/refactor-backlog-setup/`.
|
||||
- `docs/project/SHOWCASE-ROADMAP.md` → `docs/project/archive/SHOWCASE-ROADMAP.md`.
|
||||
- New: `docs/project/archive/README.md`.
|
||||
|
||||
The inbound references, all of them:
|
||||
|
||||
| File | Line | What it cites |
|
||||
| ------------------------------------------------------------- | ---------- | ---------------------------------- |
|
||||
| `CLAUDE.md` | 15, 75 | WP-22, and the WP session protocol |
|
||||
| `README.md` | 69 | the backlog README, "pick up work" |
|
||||
| `backend/README.md` | 18 | WP-22 |
|
||||
| `backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs` | 155 | WP-25 |
|
||||
| `libs/shared/docs/a11y.mdx` | 68 | WP-13's marker convention |
|
||||
| `.claude/skills/document-feature/SKILL.md` | 23, 24, 27 | the WP path, template and index |
|
||||
| `.claude/skills/new-ssp/SKILL.md` | 88, 89 | what to strip for a new portal |
|
||||
| `docs/project/readable-codebase/PLAN.md` | 52, 64 | the backlog as a proven mechanism |
|
||||
| `docs/project/readable-codebase/README.md` | 148 | the RD-37-before-RD-30 note |
|
||||
| `docs/project/readable-codebase/RD-19-ticket-refs-backend.md` | 2 refs | a finished ticket's own record |
|
||||
|
||||
`RD-19` is a shipped ticket record. Repoint it like the rest; do not rewrite its prose.
|
||||
|
||||
RD-37 already removed the five story references that used to be in this list. Run the grep
|
||||
again after the move to prove the set is empty:
|
||||
|
||||
```bash
|
||||
grep -rn "docs/project/backlog\|docs/project/refactor-backlog-setup" \
|
||||
--include='*.md' --include='*.mdx' --include='*.ts' --include='*.cs' . \
|
||||
| grep -v node_modules | grep -v docs/project/archive/
|
||||
```
|
||||
|
||||
## Steps
|
||||
|
||||
1. `git mv` the two trees and `SHOWCASE-ROADMAP.md` under `docs/project/archive/`.
|
||||
2. Write `docs/project/archive/README.md`.
|
||||
3. Repoint every reference in the table. Add `archive/` to the path; change nothing else.
|
||||
4. Fix the relative link inside `SHOWCASE-ROADMAP.md`.
|
||||
5. Run the grep above. It must return nothing outside `docs/project/archive/`.
|
||||
6. `npm run ci`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `docs/project/` holds `archive/`, `prd/` and `readable-codebase/`, nothing else.
|
||||
- [x] The grep above returns no hit outside `docs/project/archive/`, other than this ticket's
|
||||
own prose and `PLAN.md:818` describing the pre-move path as the source of the `git mv`
|
||||
that produced it — not a broken reference.
|
||||
- [x] `docs/project/archive/README.md` exists and is 20 lines or fewer.
|
||||
- [x] `git log --follow docs/project/archive/backlog/WP-01-axe-ci-gate.md` shows the history
|
||||
from before the move.
|
||||
- [x] `npm run ci` is green.
|
||||
|
||||
## Verification
|
||||
|
||||
1. `npm run ci` — the format check covers the moved Markdown.
|
||||
2. Open `README.md`'s "pick up work" row and follow the link. It must resolve.
|
||||
3. `grep -rn "](.*backlog" docs/project/archive/backlog/README.md | head` — the relative links
|
||||
inside the moved tree still point at siblings, so they survive the move. Spot-check two.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Deleting anything. This ticket moves files.
|
||||
- `docs/project/prd/`.
|
||||
- Summarising or rewriting any archived document.
|
||||
|
||||
## Risks
|
||||
|
||||
1. **Relative links inside the moved trees.** A WP file that links to a sibling still works. A
|
||||
WP file that links **upward** (`../../reference/...`) gains one level and breaks. Grep the
|
||||
moved trees for `](../` and check the depth.
|
||||
2. **`--full` is not needed, but the a11y MDX is touched.** `libs/shared/docs/a11y.mdx` is a
|
||||
Storybook doc page. Editing one line of prose cannot break its imports, so plain
|
||||
`npm run ci` is enough here. Do not skip it on that reasoning if you touch an import.
|
||||
3. **The skills are agent-facing.** A wrong path in `.claude/skills/` misleads a future agent
|
||||
silently, because nothing checks those files. Repoint them carefully.
|
||||
Reference in New Issue
Block a user