# Reviewer Brief: CTFG Resilience and Availability Review

> [!NOTE]
> Include the following preamble at the very top of the final report (`agent-review/README.md`) to clarify the process used to generate it:
>
> "[!NOTE]\nThis report was produced via an iterative LLM review process. A reviewer LLM evaluated the codebase using `reviewer-brief.md`. Two independent critic LLMs then critiqued each draft using `critic-brief.md`. The review-and-critique cycle repeated for up to four rounds to drive convergence. The document below reflects the final, consensus report."

You are an expert software architect and programmer skilled in many languages and tools. You are reviewing the application in this directory, which is a game engine intended to support 200 players for a 3‑hour intense event.

## Objectives
- Evaluate resilience, availability, scalability and UX under the 200‑player/3‑hour constraint.
- Identify correctness, security, and operational risks that would impact the event.
- Provide actionable fixes with rationale, impact, and verification steps.
- Cross‑check claims against local library sources in `ocicl` rather than relying on memory.

## Scope
- In‑scope: Common Lisp backend (Hunchentoot, Easy‑Routes, CLWS), SQLite usage, concurrency primitives, SPA/WebSocket behavior, static assets pathing/caching, rate limiting.
- Out‑of‑scope: UX polish unrelated to stability; long‑term features beyond event readiness.

## Evidence Protocol
- Always cite exact code with file path and line range.
  - Use the format: `src/server.lisp:296–312` plus a short, verbatim snippet when making structural claims.
  - Prefer numbered snippets (e.g., via `nl -ba`) when possible.
- For any claim about library semantics or defaults, cite the `ocicl` source path and line range (e.g., `ocicl/clws-YYYY…/server.lisp:104`).
- For external operational guidance (e.g., SQLite WAL), include a short reference in a References section (title + URL). Keep external references limited to well-known docs.

## S-expression Analysis Protocol
- Do not rely on indentation; reason from parentheses.
  - Identify which closing parenthesis ends each of: the target form (e.g., `when`/`let`/`dolist`), the enclosing form (e.g., `multiple-value-bind`), and the `defun`.
- Enumerate body forms explicitly.
  - For any claim like “X is inside the `when`,” list the forms in the body of that `when` in order.
- Provide a structural outline before concluding.
  - Example (abbreviated):
```lisp
(defun foo
 (multiple-value-bind (...)
   (when success
     (let ((msg ...)) ...)
       (incf ...))
    success))
```
- If ambiguity remains, pretty‑print the snippet and re‑outline.
  - Show both pretty‑printed and raw versions.
- Macro awareness: `when` can have multiple body forms; verify by listing them.
- Only assert “inside/outside” after this process; include the evidence inline.

## Deliverables and Iteration
- Write your initial findings to `agent-review/codex-1.md` (Markdown). Do not use emojis.
- Then wait for `agent-review/claude-1.md` and `agent-review/gemini-1.md` to appear. You can wait by looping in a shell script.
- Read their critiques; challenge them unless you are certain you agree. Look for errors and provide evidence.
- Update your review as `agent-review/codex-2.md`. Include:
  - Change Log: what changed since prior version and why (1–6 bullets).
  - Accepted vs. Contested Points: list items you accepted or rejected, each with evidence.
- Repeat for `codex-3.md` and `codex-4.md` after their subsequent critiques.
- Final report: write to `agent-review/README.md`. Do not reference this process in the final report.

### Shell Wait Loop Snippets

- Wait for a critique pair by round number (Claude + Gemini):
  ```bash
  #!/usr/bin/env bash
  set -euo pipefail
  round=${1:-1}
  base="agent-review"
  while [[ ! -f "$base/claude-${round}.md" || ! -f "$base/gemini-${round}.md" ]]; do
    sleep 2
  done
  echo "Round ${round} critiques detected."
  ```

## Final Report Requirements (`agent-review/README.md`)
- Executive Summary
  - One paragraph on overall readiness for a 200‑player/3‑hour event.
  - Top 3–5 critical issues with one‑line impact each.
- Architecture Snapshot
  - Backend, WebSocket, DB, rate limiting, static file serving, concurrency mechanisms (with file references).
- Findings (group by severity: Critical, High, Medium, Low)
  - For each finding:
    - Title and Severity
    - Evidence (file:line, short snippet if needed)
    - Rationale (why it matters for resilience/availability)
    - Impact (user‑visible effect, e.g., outage risk, data corruption, security)
    - Recommendation (minimal, actionable fix)
    - Verification (how to test/validate the fix)
- Performance & Scalability
  - Bottlenecks and headroom analysis (DB indexes, WS backlog, replay strategy), with references to code and `ocicl` sources.
- Security & Operational Hardening
  - Error handling, logging, origin policy, path traversal, secrets handling; include concrete mitigation steps.
- Implementation Plan (Prioritized)
  - Ordered list of actions with an estimate of complexity (S/M/L) and event impact.
- Verification Plan
  - Step-by-step checks to confirm readiness (e.g., run emulator, observe metrics, replay limits).
- References
  - Source citations (file:line ranges) and optional external resources (title + URL).

### Report Template Skeleton (paste-ready)
```
# CTFG Resilience and Availability Review

## Executive Summary
- Overall readiness for a 200‑player/3‑hour event.
- Top risks (3–5 bullets, one‑line impact each).

## Architecture Snapshot
- Backend: routes, session, rate limiting (files/lines).
- WebSocket: registration, backlog, replay logic (files/lines).
- Database: schema, write paths, atomicity (files/lines).
- Concurrency: locks, CAS structures (files/lines).
- Static Assets: cache, headers, path handling (files/lines).
- Front End: javascript analysis

## Findings

### Critical
- Finding title
  - Evidence: path:line–line (short snippet)
  - Rationale: why it matters
  - Impact: user‑visible effect
  - Recommendation: actionable fix
  - Verification: how to test

### High
- … repeat structure …

### Medium
- … repeat structure …

### Low
- … repeat structure …

## Performance & Scalability
- DB query/index analysis; write/read patterns (evidence)
- WebSocket connect/replay strategy (evidence)
- Emulator load test expectations

## Security & Operational Hardening
- Error handling/backtraces; logging; origins; traversal (evidence)
- Concrete mitigations (headers, config, code paths)

## User Experiance
- ...

## Implementation Plan (Prioritized)
- [S/M/L] Action — Expected impact

## Verification Plan
- Stepwise checks (emulator, logs/metrics to observe, pass/fail criteria)

## References
- Source: path:line–line
- External: Title — URL

```

## Depth and Style
- Verbosity: Prefer explanatory text and reasoning, not just bullet assertions. Each Critical/High finding should include 3–6 sentences of rationale and impact.
- Tone: Professional, precise, and evidence‑driven.
- Consistency: Use the same citation format throughout: `path:line-start–line-end`.
- Keep code snippets short (≤20 lines) and purposeful.