docs: reconcile PRD + fix-wave with current code (ea0ba33)

The audit anchors had drifted from the implementation. Corrected against
the live source as of commit ea0ba33:

- PRD invariant #1: mode registry is now 24 handlers in _VALID_MODES,
  not "only extract". Added invariant #2: unknown modes fail with HTTP
  400 + valid_modes (was 200-with-error-body). Added SECURE to the
  session-cookie invariant.
- PRD known-gaps + change-axis: marked the mode-registration and
  unknown-mode items RESOLVED; flagged the live codereview-vs-code_review
  naming mismatch that still 400s lakehouse observer escalations.
- SCRUM_FIX_WAVE items 1-2 struck through as DONE; recorded the cookie +
  nginx security fixes under "Recently landed".

Machine-generated .memory/ state left untouched (regenerated by the
scrum pipeline, not hand-edited).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
2026-06-20 18:09:00 -05:00
co-authored by Claude Opus 4.8
parent ea0ba33212
commit 5ac2103a4b
2 changed files with 157 additions and 0 deletions
+58
View File
@@ -0,0 +1,58 @@
# LLM Team scrum-master fix wave
Concrete changes the scrum-master should propose when auditing this
repo. Evaluated at ~confidence level per item. Keep focused — only
things that are safely landable per review, not the full refactor.
Last reconciled 2026-06-20 against commit `ea0ba33`. Items 1–2 below have
shipped since this list was written; they're kept (struck through) so the
numbering of 3–8 stays stable.
## Recently landed (verified 2026-06-20)
- **Session cookie hardening** — `SESSION_COOKIE_SECURE` added (was only
HTTPONLY + SAMESITE=Lax). Commit `ea0ba33`.
- **nginx ban IP validation** — `_nginx_ban` now validates the IP via
`ipaddress.ip_address()` before writing the `deny` rule, closing a
config-injection path. Commit `ea0ba33`.
## High priority (start here)
1. ~~**Register the missing modes** — `run_code_review`, `run_patch`,
`run_refactor`.~~ **DONE.** The mode set is now 24 handlers
(`run_brainstorm` … `run_distill`) in `_VALID_MODES`. NB: the code mode
is `codereview`, not `code_review` — lakehouse observer escalations
using the underscored name still 400. Closing that naming gap is the
only remaining work here.
2. ~~**Mode-dispatch should 404 when mode is unknown.**~~ **DONE (as 400).**
`run_team()` validates `mode` against `_VALID_MODES` and returns HTTP
400 + `valid_modes` before streaming. Implemented as 400 rather than the
proposed 404 (reads as "bad request", not "route missing").
3. **Structured security logging.** Replace `sec_log.warning(f"...")`
with `sec_log.warning("event", extra={"fields": ...})` so the log
format is JSON-parseable by fail2ban + external tools.
## Medium priority
4. **Rate-limit decorators on login/register.** Currently an attacker
can hammer /login at full request rate. Add per-IP + per-user rate
limits via `flask-limiter` or a simple in-memory sliding window.
5. **Audit log gains per-step fields.** Extend the `runs` table with
per-phase timestamps and outcomes so downstream analysis can
reconstruct what happened without replaying the full run.
6. **Templates → separate files.** Extract `render_template_string(...)`
HTML into `templates/*.html` so HTML/CSS review can happen
separately from Python logic.
## Low priority (nice to have, not urgent)
7. **Type hints on all public routes.** Adds IDE completion + makes
auditor pattern-match easier.
8. **Split llm_team_ui.py into modules.** 13K lines in one file makes
scrum-master reviews expensive (must tree-split). Modules: `auth.py`,
`teams.py`, `runs.py`, `alerts.py`, `sse.py`, `templates.py`.