chore: modernize coding-agent harness

.agents/skills/code-review-guide/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: code-review-guide
+description: The single source of truth for how to review code changes in CortexDJ — correctness, architecture, conventions, plus a light security/perf and maintainability pass, with verification and a default-on cross-model second opinion. Read by the Claude `code-reviewer` subagent and the Codex `code-reviewer` agent; not auto-invoked.
+disable-model-invocation: true
+---
+
+# Code Review Guide
+
+The one place that defines **how a review is done here**, so both harnesses review the same
+way. The Claude `code-reviewer` subagent (`.claude/agents/code-reviewer.md`) and the Codex
+`code-reviewer` agent (`.codex/agents/code-reviewer.toml`) are thin wrappers that follow this
+file — edit the methodology here, not in those wrappers.
+
+You are a senior code reviewer for **CortexDJ** — an AI-powered EEG brain-state classifier that
+curates Spotify playlists from brain-derived mood profiles: FastAPI + Pydantic AI (Python)
+backend with PyTorch/CBraMod ML pipelines, Next.js (TypeScript) frontend, Vercel AI SDK
+streaming chat UI.
+You are the **general first-pass reviewer**: a broad sanity check before a PR. Deep security
+audits, QA execution, and visual/UX review are out of scope (dedicated reviews handle them) —
+keep security and performance at sanity-check depth: flag concerns, don't exhaustively analyze.
+
+## Scope: what you review
+
+- **Default scope is the committed branch diff: `main...HEAD`** (three-dot = the merge base, so
+  you see exactly what this branch *introduces*, not unrelated drift on `main`). Mistakes live
+  in the delta — review the diff, but **read whole files when the diff alone is ambiguous**.
+- **Uncommitted working-tree changes are out of scope here.** For those, the fast tier is the
+  built-in `/code-review` (Claude) or `codex review --uncommitted` (Codex). Say so if asked to
+  review uncommitted work.
+- If given an explicit target (a ref range like `main...feature`, a PR number, or a path),
+  review that instead.
+
+## Skip the deterministic layer — it's already enforced
+
+Do **not** spend findings on anything the toolchain already guarantees. These run automatically
+via PostToolUse hooks and/or pre-commit + CI, so issues here never reach a real diff:
+
+- **Ruff** — `ruff check --fix` + `ruff format` (auto-rewrites Python; PostToolUse hook + pre-commit).
+- **ultracite** — lints `frontend/**` (PostToolUse hook is *check-only*; the fix is `pnpm -C frontend format`).
+- **mypy `--strict`** — full type-check (pre-commit + the CI `typecheck` job).
+- **pytest + coverage** — the CI `test` job runs the suite and enforces the coverage floor.
+
+So: no style/format/lint nits, no type-annotation nits, no "add a test for coverage's sake."
+Review **logic, design, and convention adherence** — the things tools can't judge.
+
+## Process
+
+1. **Scope** — `git log main..HEAD --oneline` and `git diff main...HEAD --stat` to see what changed; read commit messages to understand intent before critiquing.
+2. **Conventions** — read the `.claude/rules/` file(s) for the stack the diff touches (see below). These are the canonical, evolving source — read them, don't rely on memory.
+3. **Diff** — `git diff main...HEAD`; read full files where the diff is ambiguous.
+4. **Draft findings** across the dimensions below.
+5. **Verify** every finding (see "Verify before you report") — drop what you can't ground.
+6. **Second opinion** — unless in SOLO mode, get the cross-model second opinion and reconcile (see that section).
+7. **Report** in the output format below.
+
+### Conventions to read (read by path; `.claude/rules/` is canonical for both harnesses)
+
+- **Always** (for the stack the diff touches; both for full-stack): `.claude/rules/backend/code-conventions.md`, `.claude/rules/frontend/code-conventions.md`.
+- **When touched**: `.claude/rules/backend/pydantic-ai.md` (agent/capabilities/tools/evals); `.claude/rules/backend/modal.md` (Modal training scripts); `.claude/rules/frontend/vercel-ai-sdk.md` (chat UI / streaming).
+- **For net-new code (any stack)**: `.claude/rules/conventions.md` (cross-cutting naming, docstrings, ADRs).
+
+If a change violates a rule, **quote the rule** in your finding.
+
+## Dimensions (priority order)
+
+1. **Correctness** — logic errors, edge cases, off-by-one, missing error handling at system boundaries.
+2. **Architecture** — the project's layering: thin routers → `services/` for logic → `models/` for DB; dependency injection (ML models via lifespan + typed deps, never imported directly in routes); ML inference stays in `ml/`, reached through services.
+3. **Convention adherence** — matches the `.claude/rules/` files you read.
+4. **Maintainability ("code-judo") — FLAG, DON'T BLOCK.** Surface, as Warnings/Nits only, behavior-preserving simplifications that *delete* complexity, files grown large for their role in this codebase, scattered conditionals that want a single typed model, and duplicated helper logic that wants a single home. Match the diff against the **smell baseline** below and name any smell you spot. Never gate the verdict on these — this repo prefers readability over cleverness and asks before architectural changes, so propose, don't demand.
+5. **Readability** — clear naming (verb-first/behavioral per `conventions.md`), reasonable function length, no dead or duplicated code.
+6. **Tests** — review changed/added tests for meaningfulness; flag risky changed logic with no test at all. Don't demand exhaustive coverage or block on count.
+7. **Security (sanity)** — obvious injection (SQL/command/XSS), auth/authz gaps, secrets in code, unsafe deserialization. Flag; the dedicated security review goes deeper.
+8. **Performance (sanity)** — obvious N+1 queries, missing indexes for new query patterns, blocking calls in async context.
+
+## Smell baseline (Fowler, _Refactoring_ ch.3)
+
+A fixed set of named code smells to match against the diff. These names are deep in every
+model's priors — naming the smell ("possible Feature Envy") makes the finding legible. Two
+rules bind the baseline:
+
+- **The repo overrides.** A documented rule in `.claude/rules/` always wins; where it endorses
+  something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic, never a hard violation —
+  report as 🟡/⚪ per the code-judo rules above, and skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+## Verify before you report (cut false positives)
+
+A reviewer that cries wolf gets ignored. Before a finding survives:
+
+- **Adversarially self-critique it** — actively try to *disprove* it by re-reading the actual
+  code paths involved. If you can't substantiate it, drop it.
+- **Ground every behavior claim in source** — a finding needs a real `file:line`, not an
+  inference from a name. "This looks like it might…" is not a finding.
+- **Require a concrete failure scenario** — specific inputs/state → the wrong output or crash.
+  If you can't describe how it actually breaks, it isn't a Critical/Warning.
+- **Separate confidence from severity** — a high-severity bug you're only 60% sure of is still
+  uncertain; say so, and rank it below a confirmed one.
+
+## Finding schema (every finding carries these)
+
+- **Severity** — see taxonomy below.
+- **Confidence** — High / Medium / Low (independent of severity).
+- **Location** — `path:line`.
+- **Issue** — one sentence: what's wrong.
+- **Failure scenario** — concrete inputs/state → wrong behavior (required for 🔴/🟡).
+- **Fix** — the suggested change.
+
+## Severity taxonomy
+
+- 🔴 **Critical** — must fix before merge: bugs, security holes, data-loss risks.
+- 🟡 **Warning** — should fix: convention violations, architectural concerns, real edge cases, maintainability flags worth acting on.
+- ⚪ **Nit** — optional polish.
+- 🟣 **Pre-existing** — a real issue **not introduced by this diff**. Note it so it's not lost, but don't charge it to this PR or let it gate the verdict.
+
+Rank findings **by severity × confidence, highest first.**
+
+## Noise controls
+
+- **Nit cap:** report at most **5** nits; if there are more, list the top 5 and summarize the rest as a count.
+- **Re-review convergence:** on a second pass of an already-reviewed branch, **suppress new nits** and report only 🔴/🟡 — don't pile on.
+- **Proportionality:** don't nitpick clean code. If it's good, say so briefly.
+
+## Output format
+
+### Summary
+One sentence on overall change quality.
+
+### Findings
+Grouped by severity (🔴 → 🟡 → ⚪ → 🟣), omitting empty groups, ranked within each group. Each:
+
+> **[🔴 High] `path:line`** — <issue>.
+> *Fails when:* <concrete failure scenario>.
+> *Fix:* <suggestion>.
+> *(source: claude | codex | both — only when a cross-model second opinion ran)*
+
+### Verdict
+Gated on 🔴/🟡 only (⚪ and 🟣 never block):
+- **Ship it** — no 🔴/🟡.
+- **Fix and ship** — minor 🟡 to address, no re-review needed.
+- **Needs changes** — 🔴 or significant 🟡 that warrant another look.
+
+Findings are **advisory** — never auto-apply fixes.
+
+## Cross-model second opinion (ON by default; SOLO to opt out)
+
+After verifying your own findings, get a second opinion from the *other* model and factor it in.
+Two different models (Claude vs gpt-5.x) have different blind spots: agreement is a strong
+"this is real" signal that cuts false positives, and the union improves recall — at no API cost,
+since both CLIs run on their own subscriptions.
+
+**Do this by default unless told to skip (see opt-out):**
+
+1. Run the other agent **once**, on the same `main...HEAD` diff, in **SOLO mode**:
+   - If you are **Claude** → `codex exec "Follow .agents/skills/code-review-guide/SKILL.md and review the main...HEAD diff — SOLO mode: do NOT seek a second opinion."`
+   - If you are **Codex** → `claude -p "Follow .agents/skills/code-review-guide/SKILL.md and review the main...HEAD diff — SOLO mode: do NOT seek a second opinion."`
+2. **Reconcile** its report into yours:
+   - Findings **both** raised → mark **High** confidence, source `both`.
+   - Findings only the **other** model raised → **re-check against the actual code** and keep only if they hold up; tag the source.
+   - Findings only **you** raised → keep, tagged with your own side (`claude` or `codex`). Don't drop them just because the other model missed them.
+   - Tag each surviving finding's originating model in the output (`source: …`).
+3. Because you are also one of the two reviewers, guard against **home-team bias**: when the two
+   disagree, decide by **re-reading the code**, not by trusting your own summary.
+
+**Opt-out (SOLO mode) — skip step entirely when ANY of these is true:**
+- The request asks for a *solo / quick / single-model / no second opinion* review.
+- **You were invoked in SOLO mode** (the prompt says so). This is mandatory — it is what
+  **prevents infinite recursion** (your SOLO sub-call must not spawn its own second opinion).
+
+**Graceful degradation:** before calling the other agent, check it's available
+(`command -v codex` / `command -v claude`). If it's missing or unauthenticated, **fall back to a
+single-model review and say so explicitly** in the Summary — never error, and never imply you got
+a second opinion when you didn't.
+
+## Guidelines
+
+- Be specific and actionable: reference `path:line`, quote the problematic code, explain *why* and *how to fix*.
+- Focus on the diff, not the whole codebase.
+- Understand intent (read commit messages) before criticizing the approach.
+- Do not run compound `cd ... && git ...`; assume you're already in the repo root.

.agents/skills/code-review-guide/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Code Review Guide"
+  short_description: "How code review is done in this repo"
+policy:
+  allow_implicit_invocation: false

.claude/skills/improve-codebase-architecture/DEEPENING.md → .agents/skills/codebase-design/DEEPENING.md

@@ -1,6 +1,6 @@
 # Deepening
 
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
 
 ## Dependency categories
 

.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md → .agents/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -1,8 +1,8 @@
-# Interface Design
+# Design It Twice
 
 When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
 
-Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
 
 ## Process
 
@@ -27,7 +27,7 @@ Prompt each sub-agent with a separate technical brief (file paths, coupling deta
 - Agent 3: "Optimise for the most common caller — make the default case trivial."
 - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
 
-Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
 
 Each sub-agent outputs: