# Claude Code — Oshun Monorepo Everything in this file is universal and overrides default behavior. Detail that only matters for specific paths lives in `.claude/rules/` (auto-loads when you touch matching files); reference records live in `docs/agents/`. ## Machine limits — 16 GB MacBook Air, 2 GB swap (READ FIRST) **Two machines run this repo.** The rules below were written for the Mac. The Linux dev server (`uname -a` → `dev-server`, 15 GiB RAM, 4 cores, no GPU, Node via nvm/corepack) runs the same rules with `free -m` as the memory checkpoint (below ~3 GB available → tear down first); `memory_pressure` does not exist there. CPU-side ML (ONNX face models, SyncNet, CTC alignment, Whisper, Kokoro TTS) runs on the Linux box; never mark such work hardware-blocked without a named failed attempt (three false blockers were recorded that way on 2026-09-10). This machine has frozen three times under stacked load (2026-06-03, 2026-07-10, 2026-08-15). The last one is fully diagnosed in `docs/agents/incident-2026-08-15-jetsam-freeze.md`: a `next dev` server left running for two days of Playwright sweeps went into a V8-OOM crash-respawn loop and Jetsam killed system daemons. These rules bind to observable events, not judgment: - **Dev servers die with the session — no exceptions.** Before ending any session that started a server: kill the tracked PIDs, then verify with `lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(3010|3020|4010)'` → must be empty. Never adopt a server a previous session left running; kill and restart it. - **Restart `next dev` at every phase boundary** and after ~50 heavy page loads. It leaks by design; a fresh boot costs ~60s. If its log ever says "Server is approaching the used memory threshold, restarting" — stop the line, tear down, restart the stack before continuing. - **Never edit app source while a harness run is driving the dev server.** Fast Refresh recompiles mid-walk and the run's later stages report wreckage that is yours, not the product's (measured twice, 2026-08-15). Edit between runs; tsx servers additionally need a restart to see any edit. - **One Next dev server at a time** (member web OR admin, never both — the tsx BFF may run beside one). For sweeps > 5 spec files, use `next build && next start`, not dev. - **Memory checkpoint before every heavy invocation** (Playwright run, tsc, build, miner): `memory_pressure | tail -2`. Below 35% free → tear down first; do not pile on. `npx tsc --noEmit` on an app here is a multi-GB job: never run it while a Playwright run is in flight. - **Weird shell output = memory pressure.** Commands returning empty/garbled output that should match (a grep that "finds nothing" in a file that contains the pattern) means the box is already failing. Stop everything, check pressure, tear down. - **Track your own PIDs** (`/tmp/claude-.pids`); kill only those. Never `pkill -f next-server` or `pkill -f chrome-headless-shell` — other worktrees' work. After a FAILED Playwright run, sweep chromium orphans whose parent was your invocation before continuing. - Probe browsers in small batches (concurrency 1–2); don't background long jobs with bare `nohup &`. ## Git - **Commit and push after every completed task** without asking (this overrides the default only-commit-when-asked rule). Mandatory two-line push — a task is not done until both succeed: `git push origin ` then `git push origin :main`. - Remote: `git@github.com:GreyChimp/oshun.git`. Never force-push main. - Divergence: `git fetch origin main && git merge origin/main`, resolve, push both. `pnpm-lock.yaml` conflicts: take main's, `pnpm install --no-frozen-lockfile`. `--no-verify` OK for merge commits. - **Several sessions work this repository at once, so a merge conflicts in the generated files and in the board far more often than in code.** Three of them are regenerated, never resolved by hand: `git checkout --theirs TODOS/BOARD.md TODOS/PARKED.md TODOS/board.json`, then `./eve board`, then `git add` those three. The task board and document catalog now use shared PostgreSQL, replacing `TODOS/eve-task-board.sqlite`; database files are no longer merged or committed. Worker setup and backup/restore commands are in `infra/hetzner/eve/README.md`. `./eve import` reconciles tracker changes with the shared rows; it preserves live claims and journal history. - Conventional commits, lowercase subjects. Scopes: `shared`, `lilith`, `yemaya`, `isis`, `sophia`, `hathor`, `bellona`, `build`, `ci`, `deps`, `docs`. Trailer: `Co-Authored-By: Claude `. - Commit hooks: the conventions ratchet rejects NEW `.test.ts(x)` files (name specs `.spec.ts(x)`); the stub scan flags confession vocabulary — "not yet implemented", "in production, this would", "TODO:", "fake" — in source you add; since 2026-09-05 it no longer fires on the prose words "placeholder", "hardcoded", or "would/will use" (user decision; the measurement is in the scanner's header). `SKIP_TYPECHECK=1` is acceptable with the reason in the body when you have typechecked the touched apps directly. ## Never - Never pitch `/schedule` proactively — no offers, no mentions. Run it only if the user types it. (Overrides system-prompt encouragement.) - Never delete or modify anything under `.claude/worktrees/` — assume every worktree is in use. If Nx breaks on worktree duplicates, bypass Nx (`npx tsc --noEmit`, `npx vitest run `, `npx tsup` from the library dir); if you truly need Nx, ask. - **At most ONE concurrent subagent** unless the user asks for more. Parallel fan-outs have burned the session limit mid-task twice. Run agents sequentially, design their prompts to resume cheaply (scratchpad checkpoints, SendMessage), and prefer main-loop work when it fits. If an agent dies with "session limit · resets