[Hardening] Correct stale documentation: recording architecture, DB roles, stack versions #113
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Context
Several load-bearing docs describe a system that no longer exists. Since
CLAUDE.mdfiles steer both humans and coding agents, stale claims actively cause wrong implementations.Motivation
Four concrete divergences (all verified against current code):
(a) Recording architecture marked "not yet implemented" — it shipped. Root
CLAUDE.md("Recording architecture") says the audio pipeline is a target design with the bot still uploading a finished transcript, and describes a single mixed mono MP3. Reality:POST /api/bot/sessions/{session_id}/audioexists (webapp/backend/app/routers/bot.py:657-707) and queues theprocess_audioCelery task (:698-705).speakers.jsoninto a per-session dir onaudio_tempand calls the endpoint viapost_audio_tracks(bot/questboard_bot/cogs/recording.py:595); the endpoint docstring (bot.py:666-672) confirms the per-speaker design, transcribed per speaker and merged into an attributed transcript — not the documented mono-MP3 → single-file Whisper flow.(b) DB role claims are aspirational. Root
CLAUDE.mdandwebapp/CLAUDE.mddescribe a DML-onlyquestboardapp user; in reality the app user is the entrypoint superuser. The privilege enforcement itself is tracked in the "[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql" issue in this milestone — align the doc wording with that issue's outcome (and dropwebapp/CLAUDE.md's reference toinit.sql, which that issue deletes).(c) Frontend stack versions are stale.
webapp/CLAUDE.md:20claims "React 18, Vite 6, Tailwind 3, react-router-dom 6".webapp/frontend/package.jsonhas: react 19.2.7, react-router-dom 7.15.0, eslint 10.7.0, tailwindcss 4.3.2, vite 8.1.4.(d) Dockerfile comments contradict the base image. Section headers at
Dockerfile:14("Backend / Worker / Beat (Python 3.12)") and:97("Bot (Python 3.12 + FFmpeg)") say Python 3.12, but both stages buildFROM python:3.14-slim(:16,:99). RootCLAUDE.mdalso states Python 3.12 for both components.Fix / Spec
CLAUDE.md"Recording architecture" section to describe the shipped flow: bot captures per-speaker audio → writes 16 kHz WAVs +speakers.jsonto a per-session dir on theaudio_tempvolume →POST /api/bot/sessions/{session_id}/audiowith the dir path → Celeryprocess_audiotranscribes each speaker via the remote Whisper endpoint, merges an attributed transcript, summarises, saves, notifies the bot. Remove the "not yet implemented" status block and the mono-MP3 wording.CLAUDE.mdandwebapp/CLAUDE.mdto match the DB-privileges hardening issue: state the two-role model as enforced-by-init-script (or, if that issue hasn't merged yet, as "enforced from vX.X; earlier installs see docs/OPERATIONS.md"). Remove theinit.sqlmention fromwebapp/CLAUDE.md.webapp/CLAUDE.md:20to the actual versions (read them fromwebapp/frontend/package.jsonat edit time rather than copying from this issue).Dockerfile:14and:97(and the rootCLAUDE.mdPython claims) with whatever the CI/image Python version-alignment decision is. A dedicated issue on Python version alignment is planned for the v3.4.0 milestone (none filed at the time of writing — link it here once it exists); if it is still undecided when this issue is picked up, set the comments to match the current base image (3.14) and note the pending decision.Acceptance criteria
CLAUDE.mdgets the real recording flow (per-speaker WAV tracks,/audioendpoint, Celery pipeline) with no "not yet implemented" marker.webapp/CLAUDE.mdstack table matchespackage.jsonmajors; no reference toinit.sqlremains.Dockerfileheader comments match the actual base image version.References
CLAUDE.md("Recording architecture", "Shared infrastructure", repo-structure Python claims)webapp/CLAUDE.md:20(stack table);webapp/frontend/package.json:15/:18/:27/:30/:31webapp/backend/app/routers/bot.py:657-707(shipped audio endpoint),bot/questboard_bot/cogs/recording.py:523-595(per-speaker pipeline)Dockerfile:14/:16/:97/:99Filed from the July 2026 full-project review.
The Python version-alignment work referenced in item (d) is now filed as #87 (v3.4.0). Align the Dockerfile header comments with whatever #87 decides.
Picking this up as part of a v3.3.0 push. Landing on branch
hardening/infra-docstogether with #92 and #102, so the DB-role wording in item (b) can be written against what #102 actually enforces rather than left aspirational. Item (d) will set the Dockerfile header comments to the real base image (3.14) and reference #87 as the pending alignment decision, per the note above.Fixed on
main(commitsa9a35f7+c59cdf2, merged via9448593).CLAUDE.mdrewritten from the code (recording.py+process_audio) to describe the shipped flow: per-speaker 16 kHz WAVs +speakers.json→POST /api/bot/sessions/{id}/audio→ Celeryprocess_audiotranscribes per speaker, merges an attributed transcript, summarises, notifies the bot. "Not yet implemented" block and mono-MP3 wording removed. Also corrected the old "deletes the MP3" step — the per-session dir is kept until GM approval (this is the same lifecycle fact that reshaped #85).webapp/CLAUDE.mdnow describe the three-role split as actually enforced byinit.shper #102, pointing existing installs at the OPERATIONS.md runbook;init.sqlreference removed.webapp/CLAUDE.mdtable updated to the realpackage.jsonversions (React 19, Vite 8, Tailwind 4, react-router-dom 7).Dockerfileheader comments and rootCLAUDE.mdset to the real base image (3.14) with a pointer to #87 for the pending 3.12-vs-3.14 alignment decision. No base image or CI version changed (that's #87's job).