docs: refresh stale references and archive completed plans

[slittycode]

Cross-checked repo documentation against the current code structure. The staleness that mattered was concentrated in a few places — most docs are already accurate or carry explicit "archived/historical" notes.

What changed

Living docs corrected against current code

apps/backend/README.md

• Tech Stack: Python 3.10+ → Python 3.11.x (matches every other doc and scripts/bootstrap.sh; Essentia 2.1b6 wheels are 3.11-only).
• CLI flag table now lists --standard, --pitch-note-only, --stem-dir, --stem-output-dir — already in analyze.py:1297, previously undocumented.
• phase1 normalized-scalar list expanded to match _build_phase1 in server_phase1.py (added plr, bpmDoubletime, bpmSource, bpmRawOriginal, lufsCurve, dynamicCharacter, textureCharacter, monoCompatible, …).

apps/ui/README.md

• Removed the "backend omits raw analyzer fields such as bpmPercival, bpmAgreement, dynamicCharacter, segmentStereo, and essentiaFeatures" note. server_phase1.py forwards all of these now; the README claimed the opposite.
• Phase 1 sections list rewritten to match Phase1Result in apps/ui/src/types/measurement.ts (added stemAnalysis, transientDensityDetail, saturationDetail, snareDetail, hihatDetail, acidDetail, reverbDetail, vocalDetail, supersawDetail, bassDetail, kickDetail, genreDetail, pitchDetail, …).

apps/backend/ARCHITECTURE.md

• Added POST /api/analysis-runs/{run_id}/interrupt to the route list (real route at server.py:2131, previously omitted).
• phase1 success-envelope field lists rewritten to match _build_phase1 — same expansion as the backend README.

Archived completed plans

Two completion records moved into docs/history/archive/ (the conventional resting place per docs/history/README.md):

• docs/acid-detection-implementation.md — 2026-03-18 implementation record. Referenced pre-split analyze.py (acid detection now lives in analyze_detection.py), used the obsolete EXPECTED_OUTPUT_KEYS name, and its "What's Next" detector list has fully shipped per BACKLOG.md.
• apps/ui/UI_UX_IMPROVEMENTS.md — three-tier UI/UX polish plan; all tiers shipped. The verification numbers (33 smoke / 73 unit) are also out of date (the suite has grown to 137+ unit tests per apps/ui/CHANGELOG.md).

Both files now carry archive notes at the top explaining their status, matching the existing pattern from other archived files.

Broken cross-doc links fixed

• docs/history/archive/phase1-hardening-plan-alt.md pointed at a non-existent PLAN-phase1-hardening.md at repo root. Now points at the sibling docs/history/phase1-hardening-plan.md.
• docs/history/phase1-hardening-plan.md and docs/history/optimization-plan.md had CHANGELOG.md relative paths that resolved to the wrong directory. Both now correctly target ../../CHANGELOG.md.
• BACKLOG.md acid-detection link updated to the archived path.
• apps/ui/CHANGELOG.md UI/UX-plan reference updated to the archived path.
• docs/history/archive/README.md index expanded to include the two newly archived entries.

Verification

• git status clean after commit; 11 files changed (2 renames + 9 modifications), +84/-59 lines.
• grep -rn for UI_UX_IMPROVEMENTS, docs/acid-detection-implementation, PLAN-phase1-hardening returns only the one explanatory mention inside the archive note itself.
• No code paths touched — docs-only change. No tests run; nothing in this PR can change behavior at runtime.

https://claude.ai/code/session_018QzzaW7NMzDdB3k9sYLFMb

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Docs-only housekeeping: stale field lists in the backend and UI READMEs updated against the live _build_phase1 / Phase1Result code, four broken cross-doc links fixed, and two completed-plan files archived with archive notes matching the established pattern. No code paths touched. No tests needed or expected.

Spot-checked all the headline accuracy claims against the actual source:

• Python 3.11.x constraint: matches every other reference and bootstrap.sh. ✓
• CLI flags --standard, --pitch-note-only, --stem-dir, --stem-output-dir: all present at analyze.py:1297. ✓
• POST /api/analysis-runs/{run_id}/interrupt: decorator at server.py:2131. ✓
• _build_phase1 scalar and forwarded-section lists: verified against server_phase1.py:126+. ✓
• _normalize_spectral_detail / _normalize_stem_analysis callout in ARCHITECTURE.md: functions exist. ✓
• Link fixes (phase1-hardening-plan-alt.md → ../phase1-hardening-plan.md, both CHANGELOG.md relative paths): all targets exist on disk. ✓

Findings

Worth considering:
docs/history/optimization-plan.md — while fixing the CHANGELOG.md relative path, _structure was dropped from the module list. The line now reads analyze_core/_detection/_rhythm/_segments/_transcription.py; analyze_structure.py exists in apps/backend/. The doc is a retired historical reference and already warns that line numbers are invalid, so this won't mislead anyone into doing something wrong — but it's a factual error introduced by the edit.

Test results

N/A — docs-only.

Phase boundary check

Clean. Zero code files changed.

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Docs-only cleanup: corrects the Python version constraint (3.10+ → 3.11.x) in apps/backend/README.md, expands the phase1 field lists in both READMEs and ARCHITECTURE.md to match _build_phase1 in server_phase1.py, fixes five broken cross-doc relative links, and moves two completed plan documents into docs/history/archive/ with archive notices. No code paths touched; CI passes on both sides.

Findings

None.

Test results

N/A — docs-only. CI: Backend ✅ Frontend ✅.

Phase boundary check

N/A — no code changes.

---

Generated by Claude Code