Repository navigation
Audit Phase 3: docs to one job per file (70 files → ~30, 9.3k lines → ~3k) #179
Description
Umbrella for Phase 3 of the 2026-11-09 codebase audit. Details in docs/audit/2026-11-09/backlog.md §Phase 3; the full old→new mapping, every stale claim at doc:line, the redundancy map, and the per-directory README stub contents are in docs/audit/2026-11-09/detail/docs.md §2, §3, §7 (branch claude/hopeful-fermi-cearzd). Do last, after the code has settled. Roughly 2–3 person-days.
Goal
One obvious place for each kind of fact. Operators read docs/, developers read docs/<Element>.md plus module docstrings, agents read AGENTS.md and follow links. No doc states something the code contradicts.
Items
| ID | Task | Effort | Depends on |
|---|---|---|---|
| P3-01 | docs/repo-map.md (≤50 lines, accurate tree, one line per dir) replaces docs/agents/architecture.md, whose tree omits ~12 directories |
S | Phase 0 |
| P3-02 | docs/osc-fabric.md (≤50): the one address table (today in 8 places), fire semantics, network.json schema; ADR-0007 keeps rationale only; delete the three stale verbatim copies of network.json |
S | P0-16 |
| P3-03 | Collapse docs/agents/ to conventions.md (coordinate + rotation + logging), firmware.md (index of all firmware dirs), git-workflow.md (absorbs issue-tracker.md, label table); delete configuration.md, running-and-testing.md, architecture.md after merging |
S | — |
| P3-04 | Element docs: fix every stale claim listed in backlog §P3-04 (FlowerBeds BlobTracker/Stabilizer confusion; TreeHouse four→five controllers and standalone ESP32s; FundingCAPTCHA monitoring page is JSON, .local.json is gitignored, 10 Hz not per-frame, cut to ≤200 lines; Dashboard relay reaches TreeHouse only) |
M | Phases 0, 2 |
| P3-05 | CONTEXT.md → glossary only (≤130): drop OSC table, duplicate GardenState list, Signal Bag, Bloom, "4–6 Branches", Games list; add the five location names (Swannatopia, Julia, Jess, Dormer, Garage); resolve the Show Mode and Bloom term collisions; drop the "Display (old name)" notes once P0-14 renames the classes |
S | P0-14 |
| P3-06 | ADRs: add a Status: line to the 10 that lack one; truncate superseded 0004/0009/0011; fix 0010 (says Accepted, is superseded by 0020); cut 0015's 110-line done implementation plan; fix 0017/0018 paths; renumber the two 0021s (shader player → 0023, blob records → 0024, three link edits); add docs/adr/README.md index |
S | — |
| P3-07 | showtime.md: fix step numbering, add --no-locations; bootstrap.md: add ESP32 controllers and their WiFi provisioning, drop "record serials in network.json" (no such field), fix maxpat path |
S | — |
| P3-08 | AGENTS.md ≤40 lines, links to repo-map and element docs |
S | P3-01 |
| P3-09 | Delete docs/audit/ once every item is tracked here |
S | last |
Done when
find docs -name '*.md' | wc -l≈ 30 and total ≈ 3,000 lines.- Every file path, class name, CLI flag, port, and OSC address named in a doc resolves with
grep.
Activity