chore: repo cleanup — archive stale top-level design docs, consolidate docs/ hierarchy, move root tests/

[Kpa-clawbot]

Background

Operator field observation, May 2026: the repo has accumulated cruft over the recent rapid-iteration phase that makes navigation and onboarding harder than it should be. External contributor feedback (#1382) cited "AI slop" and giant monolith files as one barrier; this issue tracks the broader repo-hygiene half of the same complaint that file-size refactoring (#1382) and typed-response refactoring (#1383) don't cover.

Concrete inventory (master HEAD as of this filing)

$ ls *.md            → 16 top-level Markdown files
$ ls *.md | grep -v '^README\|^CHANGELOG\|^LICENSE' → 13 design docs in root

Notably stale-looking root-level design docs:

• AUDIO-PLAN.md (apr 2)
• AUDIO-WORKBENCH.md (apr 2)
• BUILD_PLAN.md (apr 2)
• CUSTOMIZATION-PLAN.md (apr 2)
• DEDUP-DESIGN.md (apr 2)
• DEDUP-MIGRATION-PLAN.md (apr 2)
• NEW_USER_SPEC.md (apr 2)
• NODE-ANALYTICS-PLAN.md (apr 2)
• RELEASE-v2.6.0.md, RELEASE-v3.0.0.md, RELEASE-v3.1.0.md (release notes for shipped versions, now superseded by CHANGELOG.md + docs/release-notes/)
• Dockerfile.go, Dockerfile.node (presumably superseded by the unified Dockerfile)

These are mostly post-launch planning docs from April that have either shipped or been replaced by issue/PR threads. Burying them in docs/archive/ (or removing entirely with a git log reference) would cut visible top-level noise by ~75%.

Other observations:

• docs/superpowers/plans/2026-04-05-deep-linking-p1.md — one-file directory, plan from April. Either consolidate into docs/specs/ or remove if shipped.
• docs/proposals/, docs/specs/, docs/test-plans/, docs/release-notes/ — overlapping content axes. A single docs/<status>/ hierarchy (draft/, accepted/, shipped/, archived/) would be clearer.
• 21 test-*.js files in repo root (e.g. test-aging.js, test-channel-add-ux.js, test-customizer-v2.js, test-frontend-helpers.js, test-live.js, test-perf-go-runtime.js). Plus dozens more test-issue-*.js files. Consider moving all to tests/ (root sweep would meaningfully reduce visual noise on a fresh clone).
• 40 untracked _wt-* directories from past worktree work in the operator's local checkout. NOT in git (verified git ls-files --error-unmatch _wt-fix-789 → not found), but listed in .gitignore? Worth confirming and adding to a cleanup script if not.

What "cruft" means here (concrete)

1. Stale planning docs that describe features that shipped or were abandoned. They confuse new readers ("is DEDUP-MIGRATION-PLAN.md describing the current state?").
2. Top-level noise — README + CHANGELOG + LICENSE + AGENTS + DEPLOY + 11 other .md files. The first thing a contributor sees is a wall of unrelated planning artifacts.
3. Test-file scatter at the repo root (21 root-level + dozens more) makes the test surface hard to enumerate.
4. docs/ substructure overlap — proposals vs specs vs test-plans is a status-not-shape distinction; merge.
5. Dead Dockerfile.go / Dockerfile.node if not used by any CI workflow (verify before removal).
6. Anything else that surfaces during a git log --diff-filter=A --since=2026-04-01 --name-only --format= pass — files added during the rapid-iteration burst that never got referenced again.

Acceptance criteria

This is a CLEANUP issue with multiple PRs. Each PR must be pure-archive/pure-delete (no behavior change in cmd/server/, cmd/ingestor/, public/). PRs:

• PR-A: Archive root-level stale planning docs. Move AUDIO-PLAN.md, AUDIO-WORKBENCH.md, BUILD_PLAN.md, CUSTOMIZATION-PLAN.md, DEDUP-*.md, NEW_USER_SPEC.md, NODE-ANALYTICS-PLAN.md to docs/archive/<original-name>.md via git mv (preserves blame). Update README if any of them are linked.
• PR-B: Consolidate old release notes. Move RELEASE-v2.6.0.md, RELEASE-v3.0.0.md, RELEASE-v3.1.0.md to docs/release-notes/. Verify no link breakage.
• PR-C: Verify and remove dead Dockerfiles. Dockerfile.go / Dockerfile.node — search every workflow file in .github/workflows/ for references. If none, git rm with PR body noting the verification grep. If referenced, leave alone.
• PR-D: Move root test-*.js files to tests/ (or tests/frontend/). Update every CI workflow that references them by path. Run full CI before push to confirm no test gets silently dropped.
• PR-E: Consolidate docs/superpowers/plans/ — either merge with docs/specs/ or remove (single 1-month-old file).
• PR-F: Status-based docs/ hierarchy. Reorganize docs/proposals/, docs/specs/, docs/test-plans/, docs/superpowers/ into a single docs/{draft,accepted,shipped,archived}/ structure. Each existing doc gets classified.
• PR-G: .gitignore audit — ensure _wt-* and other transient worktree/buildtime artifacts are ignored (operator field-reported 40 untracked _wt-* dirs).

Out of scope

• Code refactoring (covered by refactor: split cmd/server/ monolith files (store.go 7389L, routes.go 2714L, db.go 2346L) — contributor onboarding cliff #1382, refactor: drive map[string]interface{} out of API response layer + internal data (694 occurrences in cmd/) — typed structs, codegen for frontend #1383).
• Renaming files or splitting cmd/server/ (covered by refactor: split cmd/server/ monolith files (store.go 7389L, routes.go 2714L, db.go 2346L) — contributor onboarding cliff #1382).
• Frontend reorganization beyond the test-file move.
• README rewrite (separate concern).

Refs

• refactor: split cmd/server/ monolith files (store.go 7389L, routes.go 2714L, db.go 2346L) — contributor onboarding cliff #1382 (file-size refactor — sibling)
• refactor: drive map[string]interface{} out of API response layer + internal data (694 occurrences in cmd/) — typed structs, codegen for frontend #1383 (typed-response refactor — sibling)
• External contributor feedback that catalyzed the broader hygiene push (Discord 2026-05-22)

[Kpa-clawbot]

Update to PR-D scope — audit before move

Concrete inventory (master HEAD as of now):

$ ls test-*.js | wc -l            → 21 root-level test files
$ grep -c "node test-" .github/workflows/deploy.yml → 75 test invocations in CI

Of the 21 files in repo root, 18 are NOT wired into any CI step — they sit at the top of every clone and run for nobody:

test-aging.js
test-anim-perf.js
test-channel-add-ux.js
test-channel-color-picker.js
test-channel-colors.js
test-channel-decrypt-m345.js
test-customizer-v2.js
test-drag-manager.js
test-frontend-helpers.js
test-hop-resolver-affinity.js
test-live-anims.js
test-live-dedup.js
test-live.js
test-packets.js
test-panel-corner.js
test-perf-go-runtime.js
test-show-neighbors.js
test-table-sort.js

CI runs only test-packet-filter.js, test-e2e-playwright.js, and test-home-coverage-e2e.js from this root-level set. The other 18 are bit-rotted from April, never picked up by any subagent's wiring step.

The 75 CI test invocations are mostly test-issue-NNNN-*.js files added by fix-issue subagents (today's set: #1356, #1357, #1360, #1361, #1364, #1366, #1370, #1374, #1375, etc.). Those ARE running. The legacy root tests aren't.

Updated PR-D acceptance criteria

PR-D is now a 3-step audit + move, not a flat mv:

1. Audit unwired files: for each of the 18 unwired root test-*.js files, decide:

   • DELETE: file references removed code (e.g. test-hop-resolver-affinity.js refers to functions that no longer exist), or duplicates a test-issue-*.js file that does the same thing in CI. Use node <file> 2>&1 to detect immediate import/reference errors as a signal.
   • WIRE: file still tests live code AND adds coverage CI doesn't already have. Add it to deploy.yml under "Run JS unit tests" before moving.
   • DOC: file is a manual/debug script, not a regression test. Move to scripts/manual/ with a note.

2. Audit wired files (test-packet-filter.js, test-e2e-playwright.js, test-home-coverage-e2e.js): move to tests/ (or tests/frontend/) AND update deploy.yml references in the SAME commit.

3. Audit test-issue-*.js files (the bulk): same treatment — move to tests/issues/, update deploy.yml. These are wired and current; just a relocation, no audit beyond "still wired? yes? move."

Each commit should be small and atomic — one move per logical group, all CI runs must stay green. Use git mv to preserve blame.

Expected outcome

• Root drops from ~80+ test-* files to 0.
• tests/ subtree clearly organized.
• 18 bit-rotted orphans either deleted (most likely outcome for ~12 of them) or properly wired into CI.
• deploy.yml paths updated cleanly.
• git blame preserved across the move.

Out of scope (file separately)

• Restructuring how subagents place new test files (need a convention update in AGENTS.md).
• Adding a CI gate that rejects new test-*.js at repo root.

[Kpa-clawbot]

Correction to previous comment — these tests are mostly real coverage, not bit rot

Apologies for the lazy "bit rot" framing. Actually checking each file:

test-aging.js                       ✅ PASS — tests node aging thresholds
test-channel-color-picker.js        ✅ PASS — channel color picker
test-customizer-v2.js               ✅ PASS — customizer core
test-drag-manager.js                ✅ PASS — DragManager (#608)
test-frontend-helpers.js            ✅ PASS — helper utilities
test-hop-resolver-affinity.js       ✅ PASS — disambiguator affinity
test-live.js                        ❌ FAIL — getParsedDecoded is not a function (real regression)
test-show-neighbors.js              ⚠️ needs CHROMIUM_PATH — manual browser script
... (others not exhaustively checked — likely similar pattern)

So the right framing isn't "delete bit rot." It's:

1. Most root tests are passing real coverage that CI silently isn't running — wiring them would have caught the test-live.js regression already.
2. A few are manual/debug scripts (browser-launching) that should move to scripts/manual/, not tests/.
3. test-live.js's current failure is a separate signal — file as a regression issue, fix it, then wire it.

Revised PR-D scope

1. Wire every passing root test-*.js into deploy.yml's "Run JS unit tests" step. Run each node <file> locally first; if it exits 0, wire it. If it exits non-zero or requires CHROMIUM_PATH/BASE_URL, classify per below.
2. Move browser-launching root tests (e.g. test-show-neighbors.js, test-live-anims.js if it needs a server) to scripts/manual/ with a one-line note in README explaining when to run them.
3. File a regression issue for test-live.js — assertion fails on getParsedDecoded is not a function. This is a real bug surfaced by the audit, deserves its own fix-issue PR.
4. Then move the wired-and-passing tests to tests/ with git mv, updating deploy.yml paths in the same commit. Blame preserved.

Net effect: from ~80+ test files at repo root → 0 at root, all either properly wired in CI or properly documented as manual scripts. Plus one new fix-issue.

(I shouldn't have written off live, real-coverage tests as cruft just because nobody wired them.)