huskies: merge 604_story_service_module_conventions_and_first_extraction

docs/architecture/future-extractions.md

@@ -0,0 +1,29 @@
+# Future Service Module Extractions
+
+Recommended order for extracting remaining HTTP handlers into `service/<domain>/`
+modules, following the conventions in [service-modules.md](service-modules.md).
+
+## Recommended Order
+
+1. **`settings`** — small surface, few dependencies, good warm-up
+2. **`oauth`** — reads/writes token files; pure validation logic separates cleanly
+3. **`wizard`** — stateless generation logic is already mostly pure; thin I/O layer
+4. **`project`** — project scaffolding; wraps `io::fs::scaffold`, clean separation
+5. **`io`** (search/shell) — wraps `io::search` and `io::shell`; pure query-building separable
+6. **`anthropic`** — token-proxy handler; pure request-shaping + thin HTTP I/O
+7. **`stories`** (workflow) — CRDT-backed story ops; typed errors for 400/404/409/500
+8. **`events`** — SSE handler; mostly framework wiring, but event filtering is pure
+
+## Special Case: `ws`
+
+The WebSocket handler (`http/ws.rs`) is a **dedicated harder extraction** because
+it mixes multiple concerns (chat dispatch, permission forwarding, SSE bridging)
+and depends on long-lived async streams. Extract it last, after the above list
+is complete and the service module pattern is well-established.
+
+## Notes
+
+- Each extraction should link back to `docs/architecture/service-modules.md`
+  in the story description to maintain consistency.
+- The `agents` extraction (story 604) is the reference implementation every
+  future extraction should follow.