Chatroom pivot: spec, black-box notes, Jev strategies; roadmap rewritten

CLAUDE.md

@@ -1,11 +1,13 @@
 # So Many Crows: handoff for the next agent
 
-Read this whole file before changing anything. It is the single source of truth for where the project stands, why it is built this way, and what comes next. Last updated 2026-10-27 by the agent that built v1 through personas.
+Read this whole file before changing anything. It is the single source of truth for where the project stands, why it is built this way, and what comes next. Last updated 2026-10-27: same day, the roadmap pivoted toward the chatroom spec (section 8) — the pivot came from `CHATROOM_SPEC.md`, `GROKBOT_NOTES.md` and `JEV_STRATEGIES.md`.
 
 ## 1. What this is
 
 So Many Crows is a multi-agent app for one owner, Smokey (Jacob Madsen). You hand a "flock" of AI agents ("crows") a todo list in a chat-room web UI. A **Sentry** crow triages each item, worker crows do the work, an **Elder** crow merges multi-crow results, and **the human approves or rejects** until crows earn trust. It belongs to So Many Crows LLC, a Utah LLC Smokey is registering that builds marketing communications (marcomm) tools.
 
+**That pipeline is what runs today, but the direction has changed** (2026-10-27): the target is a conversation-driven chatroom where crows claim work in a nest, two new roles appear (assistant crow, Chief of Staff crow), and Jev audits expectations and nudges stalled work. Read `CHATROOM_SPEC.md` (the design, with `[decided]`/`[proposed]` marks), `GROKBOT_NOTES.md` (its evidence base) and `JEV_STRATEGIES.md` (what the classifier can do). The pipeline isn't deleted — it stays the working app until chatroom work replaces it, and nests, the trust ledger, guardrails, SSE, personas and the flight log all carry over.
+
 Working copy: `~/Projects/so-many-crows` on Smokey's Mac (Apple silicon, macOS). There is **no Git remote yet** (see section 8). Do not confuse it with `~/Projects/crows`, an unrelated older folder: never touch it.
 
 ## 2. How to work with Smokey
@@ -35,7 +37,7 @@ These are his stated preferences. Follow them every time.
 - **The main LLM is switchable** via `CROWS_PROVIDER`: `openrouter` (default model `openrouter/free`, a router that picks a different free model per call) or `anthropic` (default `claude-sonnet-5-5`). Every flight logs which model actually answered.
 - **Jev (TypeSafe) is a classifier, run in tandem with the LLM** for the Sentry's triage, called **directly from TypeSafe** (`https://api.typesafe.ai/v1/systemone`), not via OpenRouter. Jev answers mode and task type with calibrated confidence. Its call stands when both confidences are at least 0.7 and the mode is not `split`. Otherwise the LLM Sentry decides: when Jev is unsure, when it calls a split (Jev can't write subtasks), or when Jev errors. Jev never blocks a list.
 - **Smokey's comparison plan:** a free model first, then Claude over OpenCode Zen, then Claude direct from Anthropic. Status: OpenRouter free works (live-tested). Zen is **not built**: Zen's own docs say its free models only work inside the OpenCode app, so only paid Zen models can be used from this app. Claude direct is **built but never live-tested** (no Anthropic key has been provided).
-- **OpenRouter free tier limits** (key is on the free tier): 50 free-model requests per day, 20 per minute. Each todo item costs about 2 to 6 requests (Sentry, crows, Elder, banter). Jev triage saves one request per confidently-triaged item.
+- **OpenRouter limits** (corrected 2026-10-27: the account is paid, $50 in credits bought, `is_free_tier: false`): 1,000 free-model requests per day, 20 per minute (https://openrouter.ai/docs/api-reference/limits). Check live with `GET /api/v1/key` (never print the label or key). **Pinned model: `CROWS_MODEL=google/gemma-4-26b-a4b-it:free` (switched from gemma-4-31b-it:free after upstream 429s)**; keep it until Smokey says otherwise. Each todo item costs about 2 to 6 requests (Sentry, crows, Elder, banter). Jev triage saves one request per confidently-triaged item.
 
 ### Stack
 - **Go backend, standard library only**, Go 1.24 (`go.mod`, module `somanycrows`). Smokey's team prefers Go or Rust, hosted on Firebase or Google Cloud (GCP) later.
@@ -73,8 +75,11 @@ These are his stated preferences. Follow them every time.
 | `jev.go` | Jev classifier client and the guarded `classify` call |
 | `personas.go`, `banter.go` | Personas and policies; retrieval-then-generation banter |
 | `ledger.go`, `guardrails.go`, `nests.go`, `flightlog.go` | Trust ledger and requester strikes; limits; nests; JSON Lines flight log |
-| `*_test.go` | 26 tests; run with `-race` |
+| `*_test.go` | 31 tests; run with `-race` |
 | `EVENTS.md` | **The server and UI contract**: every event, payload and endpoint. Change it first, then the code. |
+| `CHATROOM_SPEC.md` | **The pivot target**: the chatroom design (message kinds, roles, expectation ledger, build plan). |
+| `GROKBOT_NOTES.md` | Black-box observations of Grok Bot that the spec is built from. |
+| `JEV_STRATEGIES.md` | What Jev can do (question types, bands, calibration) and strategies for using it. |
 | `RIVE_CONTRACT.md` | Spec for the animator's `crows.riv` (data binding, one `Crow` artboard for v1) |
 | `PERSONAS.md` | Generated persona sheet. Regenerate with `./crows personas > PERSONAS.md` after editing `personas.go` |
 | `ui/` | Vite + TypeScript source (`src/main.ts`, `crow.ts`, `api.ts`, `style.css`). Builds into `web/` (git-ignored) |
@@ -105,10 +110,10 @@ Guardrail defaults (`guardrails.go`): 5 crows in flight, murder of 3, 20 items p
 
 ## 6. Verified state (2026-10-27)
 
-- All 26 tests pass with `-race`.
+- All 31 tests pass with `-race`.
 - Live test with real keys: Jev triaged "Should we launch a CLI or a web app first" as murder (91%) and analysis (100%) in 195 ms; Hugin, Munin and Corvina answered on three different free models; the Elder merged in character; after a rejection, Soot generated: *"Hugin, another grand scheme foiled? Perhaps the CLI is the tiny bird worth chasing."* Total 6,257 tokens.
 - UI end-to-end tested headless at desktop and phone widths: nests, borrowing, approvals, reactions, prank cooldown, banter asides. No console errors.
-- **Not yet done:** Smokey has not yet used the app himself through `start.command` with real crows. That is the next thing to support.
+- **Not yet done:** Smokey has not yet used the app himself through `start.command` with real crows. It still matters (section 8, step 6), but the chatroom work leads now.
 
 ## 7. Known gaps and gotchas
 
@@ -123,19 +128,16 @@ Guardrail defaults (`guardrails.go`): 5 crows in flight, murder of 3, 20 items p
 
 ## 8. What happens next (in order)
 
-Do one at a time. Show the result. Ask before starting the next.
+The roadmap pivoted (2026-10-27): the chatroom spec is now the direction. Do one step at a time. Show the result. Ask before starting the next. **Contracts first** still applies: change `EVENTS.md` before UI or server code for any chatroom message kind or event.
 
-1. **Support Smokey's first hands-on session.** He starts `start.command` and uses the app with real crows. Watch the Terminal window and `./crows log` for errors, and fix what he hits. Keep an eye on the 50-a-day free limit.
-2. **Print banter on the command line.** Small: handle `crow.banter` in the command line's printing emitter (`main.go`).
-3. **Provider comparison.** Smokey wants to compare (a) a free model, (b) Claude over OpenCode Zen, (c) Claude direct from Anthropic. Steps: pin one model per run with `CROWS_MODEL` for fair comparisons (the free router randomizes); add an OpenCode Zen provider to `NewBrain` (base `https://opencode.ai/inference/`, Claude models via `anthropic/v1/messages`, open models via `openai/v1/chat/completions`; confirm the auth header in Zen's docs first, since they didn't state it for these endpoints); get keys from Smokey; then add a small `crows stats` summary of the flight log (per model: calls, average tokens, average milliseconds, approval and rejection rates). Ask Smokey which model to pin before running.
-4. **Review queue for "regular" trust:** a way to review outputs that were auto-accepted while unreviewed.
-5. **Rive.** An animator builds `crows.riv` per `RIVE_CONTRACT.md`; then add a Rive-backed `CrowView` in `ui/src/crow.ts` (the interface is already shaped for it). Smokey's crow art is the character.
-6. **Threads per item** (Slack-style): asked of Smokey, not answered yet. Ask before building.
-7. **Persona strengths in crow picking** (for example, Munin for retrieval). Not requested; propose only.
-8. **First real capability (likely web search):** write its guardrail spec first (scope, limits, what needs approval), get Smokey's approval, then build.
-9. **Login and real requester identity** before the server ever leaves localhost.
-10. **GitHub:** Smokey deferred it. When he's ready: he creates an empty repo `jacisjake/so-many-crows`, then push. Commit email must be `150986568+jacisjake@users.noreply.github.com` (pushes with his real email are rejected).
-11. **Hosting on Google Cloud** later; not started.
+1. **Resolve the spec's open blockers before code** (Smokey decides, not the agent): message-kind tagging (Jev can tag it — see `JEV_STRATEGIES.md` strategy 1), the nudge loop guard (nudges count against the nest budget; a miss must not restart work forever), first-claim-wins arbitration when two crows claim at once, and Sentry/Elder's fate (spec open question 4).
+2. **Chatroom build plan step 1** (`CHATROOM_SPEC.md` section 12): one nest, owner plus two crows, event-driven; `say`, `request`, `claim`, `deliver` with @-addressing; mock brain first, live models after it works.
+3. **The assistant crow** as the owner's default chat, relaying into the nest.
+4. **The expectation ledger plus nudges**, two checks first (promise kept, single owner), Jev questions per `JEV_STRATEGIES.md`. The "log-only experiment" there (kind + who-responds, no acting) can run beside current pipeline traffic to collect calibration data.
+5. **The COS crow** spinning up crows on request. Then opt-in debate mode, then visible budgets.
+6. **Smokey's first hands-on session** with the current pipeline stays worth supporting — if he runs `start.command`, watch the Terminal and `./crows log` and fix what he hits (1,000-a-day free-model limit).
+
+Paused by the pivot (resume only if Smokey asks): provider comparison beyond pinning a model (the pinned `CROWS_MODEL` stays); CLI banter printing; review queue for "regular" trust; threads; Rive; web-search capability; login; GitHub; GCP. GitHub note for when it happens: Smokey creates an empty repo `jacisjake/so-many-crows`, commit email must be `150986568+jacisjake@users.noreply.github.com`.
 
 ## 9. Conventions