diff --git a/.huskies/specs/tech/STACK.md b/.huskies/specs/tech/STACK.md
index 99d0b47b..f7c5d68e 100644
--- a/.huskies/specs/tech/STACK.md
+++ b/.huskies/specs/tech/STACK.md
@@ -32,154 +32,141 @@ website/             — Static marketing/docs site
 
 ## Source Map
 
-### Backend roots
-| Path | Purpose |
-|------|---------|
-| `server/src/main.rs` | Binary entry; CLI parsing; server startup |
-| `server/src/config/` | `project.toml` parsing |
-| `server/src/state.rs` | Global mutable session state |
-| `server/src/store.rs` | JSON-backed KV store for settings |
-| `server/src/gateway.rs` | Multi-project gateway mode (route builder, MCP proxy) |
-| `server/src/agent_mode.rs` | Headless build-agent mode |
-| `server/src/services.rs` | Top-level service registry / wiring |
-| `server/src/workflow.rs` | Cross-cutting workflow helpers |
+One row per directory or top-level file. Descriptions are pulled from the module's `//!` doc-comment where present. **Use this to know where to look — do not re-discover the codebase via grep.**
 
-### Agents
-| Path | Purpose |
-|------|---------|
-| `server/src/agents/mod.rs` | Agent types and orchestration root |
-| `server/src/agents/pool/` | Coder/QA/mergemaster pool, auto-assign, lifecycle, retry |
-| `server/src/agents/pool/auto_assign/` | Auto-assigner: scans pipeline, spawns agents on free slots |
-| `server/src/agents/pool/pipeline/` | Stage transitions, completion, merge orchestration |
-| `server/src/agents/runtime/` | Per-provider runtimes: `claude_code.rs`, `gemini.rs`, `openai.rs` |
-| `server/src/agents/merge/` | Squash-merge mechanics, conflict detection |
-| `server/src/agents/pty.rs` | PTY pseudo-terminal spawning + output streaming |
-| `server/src/agents/lifecycle.rs` | Stage transitions and item movement |
-| `server/src/agents/gates.rs` | Quality-gate runner |
-| `server/src/agents/session_store.rs` | Per-agent session history |
-| `server/src/agents/token_usage.rs` | Per-agent token cost ledger |
+### Top-level backend files (`server/src/`)
 
-### CRDT + persistence
-| Path | Purpose |
+| File | Purpose |
 |------|---------|
-| `server/src/crdt_state/` | CRDT primitives — `lww_maps.rs`, `state.rs`, `read.rs`, `write.rs`, `ops.rs`, `types.rs`, `presence.rs`, `gateway_config.rs` |
-| `server/src/crdt_sync/` | WebSocket replication; `rpc.rs` holds the **read-RPC registry** |
-| `server/src/crdt_sync/server/` | Sync-server endpoint, keepalive |
-| `server/src/crdt_snapshot/` | Snapshot persistence |
-| `server/src/pipeline_state/` | Typed pipeline state machine + projections |
-| `server/src/db/mod.rs` | `content_store`, shadow writes, op persistence |
+| `server/src/agent_log.rs` | Agent log persistence — reads and writes JSONL agent event logs to disk. |
+| `server/src/agent_mode.rs` | Headless build-agent mode for distributed, rendezvous-based story processing. |
+| `server/src/cli.rs` | Command-line argument parsing for the huskies binary. |
+| `server/src/crdt_wire.rs` | CRDT wire codec — serialization format for `SignedOp` sync messages between nodes. |
+| `server/src/gateway.rs` | Multi-project gateway — entrypoint wiring and route tree.  When `huskies --gateway` is used, the server starts in gateway mode. B… |
+| `server/src/gateway_relay.rs` | Gateway relay task — pushes project status events to the gateway via WebSocket.  When `gateway_url` is configured in `project.tom… |
+| `server/src/log_buffer.rs` | Bounded in-memory ring buffer for server log output.  Use the [`slog!`] macro (INFO), [`slog_warn!`] (WARN), or [`slog_error!`] (… |
+| `server/src/main.rs` | Huskies server — entry point, CLI argument parsing, and server startup. |
+| `server/src/mesh.rs` | Peer mesh discovery — supplementary CRDT sync connections between build agents.  When mesh discovery is enabled, a build agent pe… |
+| `server/src/node_identity.rs` | Node identity — Ed25519 keypair foundation for distributed huskies.  Each huskies node has a stable identity derived from an Ed25… |
+| `server/src/rebuild.rs` | Server rebuild and restart logic shared between the MCP tool and Matrix bot command. |
+| `server/src/services.rs` | Shared services bundle — common state threaded through HTTP handlers and chat transports.  `Services` bundles the fields that eve… |
+| `server/src/state.rs` | Session state — global mutable state shared across the server (project root, cancellation). |
+| `server/src/store.rs` | Key-value store — JSON-backed persistent storage for user settings and preferences. |
+| `server/src/workflow.rs` | Workflow module: test result tracking and acceptance evaluation. |
 
-### HTTP / WS routes
-| Path | Purpose |
-|------|---------|
-| `server/src/http/mod.rs` | Top-level route registration |
-| `server/src/http/ws.rs` | Top-level WebSocket dispatcher |
-| `server/src/http/events.rs` | Event push endpoint |
-| `server/src/http/agents/` | Agent REST + tests |
-| `server/src/http/gateway/` | Gateway routes — `rest.rs`, `websocket.rs`, `mcp.rs`, `jsonrpc.rs` |
-| `server/src/http/mcp/` | MCP tool handlers (agent_tools, story_tools, merge_tools, qa_tools, status_tools, git_tools, wizard_tools, dispatch.rs) |
-| `server/src/http/workflow/` | Story-creation workflow endpoints (`bug_ops.rs`, `test_results.rs`) |
-| `server/src/http/anthropic.rs` | Anthropic API proxy |
-| `server/src/http/oauth.rs` | OAuth flows |
-| `server/src/http/bot_command.rs` | Bot command dispatch |
-| `server/src/http/bot_config.rs` | Bot config save/get |
-| `server/src/http/wizard.rs` | Setup wizard endpoint |
+### Backend modules (`server/src/`)
 
-### Chat (bot)
 | Path | Purpose |
 |------|---------|
-| `server/src/chat/mod.rs` | Chat module root |
-| `server/src/chat/commands/` | Slash commands — `status.rs`, `backlog.rs`, `run_tests.rs`, `depends.rs`, `freeze.rs`, `unblock.rs`, `move_story.rs`, `assign.rs`, `loc.rs`, `cost.rs`, `help.rs`, etc. |
-| `server/src/chat/commands/mod.rs` | Command dispatch |
-| `server/src/chat/transport/matrix/` | Matrix bot |
-| `server/src/chat/transport/slack/` | Slack bot |
-| `server/src/chat/transport/whatsapp/` | WhatsApp Business API |
-| `server/src/chat/transport/discord/` | Discord bot |
-| `server/src/chat/test_helpers.rs` | `write_item_with_content` and other CRDT-seeding test helpers |
-
-### Domain services (one folder per concern)
-| Path | Purpose |
-|------|---------|
-| `server/src/service/agents/` | Agent listing + selection |
-| `server/src/service/events/` | Event store + buffer |
-| `server/src/service/gateway/` | Gateway business logic |
-| `server/src/service/git_ops/` | git status/diff/add/commit primitives |
-| `server/src/service/merge/` | Merge orchestration |
-| `server/src/service/notifications/` | Notification dispatch |
-| `server/src/service/qa/` | QA lifecycle |
-| `server/src/service/story/` | Story CRUD + front matter |
-| `server/src/service/timer/` | Timer schedule |
-| `server/src/service/wizard/` | Setup wizard state machine |
-| `server/src/service/ws/` | WebSocket message dispatch + inbound RPC routing |
-| `server/src/service/oauth/` | OAuth flow + PKCE |
-| `server/src/service/file_io/` | Filesystem read/write helpers |
-| `server/src/service/shell/` | Shell command execution + path-guard |
-| `server/src/service/anthropic/` | Anthropic API client |
-| `server/src/service/bot_command/` | Bot command core logic |
-| `server/src/service/diagnostics/` | Server diagnostics |
-| `server/src/service/pipeline/` | Pipeline-level service helpers |
-| `server/src/service/project/` | Project loading and selection |
-| `server/src/service/settings/` | Settings persistence + validation |
-| `server/src/service/status/` | Status text formatting |
-| `server/src/service/common/` | Cross-cutting service helpers |
-
-### LLM
-| Path | Purpose |
-|------|---------|
-| `server/src/llm/providers/` | `anthropic.rs`, `ollama.rs` |
-| `server/src/llm/chat/` | LLM chat session (`run.rs`, `tools.rs`) |
-| `server/src/llm/oauth.rs` | LLM OAuth flow |
-| `server/src/llm/prompts.rs` | Prompt templates |
-
-### IO, watcher, worktrees
-| Path | Purpose |
-|------|---------|
-| `server/src/io/fs/` | Project file paths + scaffold |
-| `server/src/io/watcher/` | Filesystem watcher for `.huskies/work/` and `project.toml` |
-| `server/src/io/story_metadata.rs` | Story front-matter parsing/writing — `parse_front_matter`, `set_front_matter_field`, `write_*_in_content` setters |
-| `server/src/io/onboarding.rs` | First-run onboarding |
-| `server/src/io/wizard.rs` | Wizard IO |
-| `server/src/io/search.rs` | Repo search |
-| `server/src/io/test_helpers.rs` | Generic IO test helpers |
-| `server/src/worktree/` | Git worktree create/remove + git ops |
-
-### Utilities
-| Path | Purpose |
-|------|---------|
-| `server/src/rebuild.rs` | Server rebuild + restart |
-| `server/src/agent_log.rs` | JSONL agent event logs |
-| `server/src/log_buffer.rs` | In-memory log buffer |
-| `server/src/mesh.rs` | Mesh networking |
-| `server/src/node_identity.rs` | Node identity |
-| `server/src/gateway_relay.rs` | Gateway relay |
-
-### Frontend
-| Path | Purpose |
-|------|---------|
-| `frontend/src/api/rpc.ts` | **Shared read-RPC client** over `/ws` — `rpcCall<T>(method, params)` |
-| `frontend/src/api/agents.ts` | Agent listing + streaming (uses `rpcCall`) |
-| `frontend/src/api/gateway.ts` | Multi-project gateway client |
-| `frontend/src/api/client.ts` | HTTP client base |
-| `frontend/src/components/` | React UI components (Chat, AgentPanel, WorkItemDetailPanel, etc.) |
-| `frontend/src/components/selection/` | Selection-related components |
-| `frontend/src/hooks/` | React hooks (`useChatWebSocket`, etc.) |
-| `frontend/src/utils/` | Utility helpers |
+| `server/src/` |  |
+| `server/src/agents/` | Agent subsystem — types, configuration, and orchestration for coding agents. |
+| `server/src/agents/merge/` | Merge operations — rebases agent work onto master and runs post-merge validation. |
+| `server/src/agents/merge/squash/` | Squash-merge orchestration: rebase agent work onto master and run post-merge gates. |
+| `server/src/agents/pool/` | Agent pool — manages the set of active agents across all pipeline stages. |
+| `server/src/agents/pool/auto_assign/` | Auto-assign submodules: wires focused sub-files and re-exports public items. |
+| `server/src/agents/pool/auto_assign/watchdog/` | Watchdog task: detects orphaned agents, enforces turn/budget limits, and triggers auto-assign. |
+| `server/src/agents/pool/auto_assign/watchdog/tests/` | Shared test helpers for the watchdog module. |
+| `server/src/agents/pool/pipeline/` | Pipeline operations — stage advancement, completion handling, and merge orchestration. |
+| `server/src/agents/pool/pipeline/advance/` | Pipeline advance — moves stories forward through pipeline stages after agent completion. |
+| `server/src/agents/pool/pipeline/completion/` | Agent completion handling — processes exit results and triggers pipeline advancement. |
+| `server/src/agents/pool/start/` | Agent start — spawns a new agent process in a worktree for a given story. |
+| `server/src/agents/runtime/` | Agent runtimes — pluggable backends (Claude Code, Gemini, OpenAI) for running agents. |
+| `server/src/chat/` | Transport abstraction for chat platforms.  The [`ChatTransport`] trait defines a platform-agnostic interface for sending and edit… |
+| `server/src/chat/commands/` | Bot-level command registry shared by all chat transports.  Commands registered here are handled directly by the bot without invok… |
+| `server/src/chat/transport/` | Chat transports — pluggable backends (Matrix, Slack, WhatsApp, Discord) for bot messaging. |
+| `server/src/chat/transport/discord/` | Discord Bot integration.  Provides: - [`DiscordTransport`] — a [`ChatTransport`] that sends messages via the Discord REST API (`/… |
+| `server/src/chat/transport/matrix/` | Matrix bot integration for Story Kit.  When a `.huskies/bot.toml` file is present with `enabled = true`, the server spawns a Matr… |
+| `server/src/chat/transport/matrix/bot/` | Matrix bot — sub-modules for the Matrix chat bot implementation. |
+| `server/src/chat/transport/matrix/bot/messages/` | Matrix message handler — processes incoming room messages and dispatches commands. |
+| `server/src/chat/transport/matrix/config/` | Matrix transport configuration — deserialization of `bot.toml` Matrix settings. |
+| `server/src/chat/transport/slack/` | Slack Bot API integration.  Provides: - [`SlackTransport`] — a [`ChatTransport`] that sends messages via the Slack Web API (`api.… |
+| `server/src/chat/transport/slack/commands/` | Slack incoming message dispatch and slash command handling. |
+| `server/src/chat/transport/whatsapp/` | WhatsApp Business API integration.  Provides: - [`WhatsAppTransport`] — a [`ChatTransport`] that sends messages via the Meta Grap… |
+| `server/src/chat/transport/whatsapp/commands/` | WhatsApp command handling — processes incoming WhatsApp messages as bot commands. |
+| `server/src/config/` | Project configuration — parses `project.toml` for agents, components, and server settings. |
+| `server/src/crdt_snapshot/` | CRDT snapshot compaction with cross-node coordination.  This module implements full CRDT state snapshots for compacting the op jo… |
+| `server/src/crdt_state/` | CRDT state layer — manages pipeline state as a conflict-free replicated document backed by SQLite.  The CRDT document is the prim… |
+| `server/src/crdt_sync/` | CRDT sync — WebSocket-based replication of pipeline state between huskies nodes. WebSocket-based CRDT sync layer for replicating… |
+| `server/src/crdt_sync/server/` | Server-side `/crdt-sync` WebSocket handler. |
+| `server/src/db/` | SQLite storage layer — content store, shadow writes, and CRDT op persistence. |
+| `server/src/http/` | HTTP server — module declarations for all REST, MCP, WebSocket, and SSE endpoints. |
+| `server/src/http/agents/` | HTTP agent endpoints — thin adapters over `service::agents`.  Each handler: extracts payload → calls `service::agents::X` → shape… |
+| `server/src/http/gateway/` | Gateway HTTP handlers — thin transport shells for the gateway service.  Each handler calls `service::gateway::*` for business log… |
+| `server/src/http/mcp/` | HTTP MCP server module. |
+| `server/src/http/mcp/agent_tools/` | MCP agent tools — start, stop, wait, list, and inspect agents via MCP. |
+| `server/src/http/mcp/diagnostics/` | MCP diagnostic tools — server logs, CRDT dump, version, line counting, story movement. |
+| `server/src/http/mcp/shell_tools/` | MCP shell tools — run commands, execute tests, and stream output via MCP.  This file is a thin adapter: it deserialises MCP paylo… |
+| `server/src/http/mcp/story_tools/` | MCP story tools — create, update, move, and manage stories, bugs, refactors, and spikes via MCP.  This module is a thin adapter:… |
+| `server/src/http/mcp/story_tools/story/` | Story creation, listing, update, and lifecycle MCP tools. |
+| `server/src/http/mcp/tools_list/` | `tools/list` MCP method — returns the static schema for every tool the server exposes. |
+| `server/src/http/workflow/` | Workflow helpers — shared story/bug file operations used by HTTP and MCP handlers. |
+| `server/src/http/workflow/story_ops/` | Story operations — creates, updates, and manages acceptance criteria in story files. |
+| `server/src/io/` | I/O subsystem — filesystem, shell, search, onboarding, and story metadata operations. |
+| `server/src/io/fs/` | Filesystem I/O — module declarations and re-exports for file operations. |
+| `server/src/io/fs/scaffold/` | Project scaffolding — creates the `.huskies/` directory structure and default files. |
+| `server/src/io/fs/scaffold/detect/` | Stack detection — inspect the project root for marker files and emit TOML `[[component]]` entries plus `script/build\|lint\|test`… |
+| `server/src/io/watcher/` | Filesystem watcher for `.huskies/project.toml` and `.huskies/agents.toml`.  Watches config files for changes and broadcasts a [`W… |
+| `server/src/llm/` | LLM subsystem — chat orchestration, prompts, OAuth, and provider integrations. |
+| `server/src/llm/chat/` | LLM chat — orchestrates multi-turn conversations with tool-calling LLM providers. |
+| `server/src/llm/providers/` | LLM providers — module declarations for Anthropic, Claude Code, and Ollama backends. |
+| `server/src/llm/providers/claude_code/` | Claude Code provider — runs Claude Code CLI in a PTY and parses structured output. |
+| `server/src/pipeline_state/` | Typed pipeline state machine (story 520).  Replaces the stringly-typed CRDT views with strict Rust enums so that impossible state… |
+| `server/src/service/` | Service layer — domain logic extracted from HTTP handlers.  Each sub-module follows the conventions documented in `docs/architect… |
+| `server/src/service/agents/` | Agent service — public API for the agent domain.  This module orchestrates calls to `io.rs` (side effects) and the pure topic mod… |
+| `server/src/service/anthropic/` | Anthropic service — public API for Anthropic API-key management and model listing.  Exposes functions to check, store, and use th… |
+| `server/src/service/bot_command/` | Bot command service — domain logic for dispatching slash commands.  Extracted from `http/bot_command.rs` so that argument parsing… |
+| `server/src/service/common/` | Shared pure helpers used by multiple service modules.  All sub-modules here are pure (no I/O, no side effects). Any helper that d… |
+| `server/src/service/diagnostics/` | Diagnostics service — server logs, CRDT dump, permission management, and story movement.  Extracted from `http/mcp/diagnostics.rs… |
+| `server/src/service/events/` | Events service — public API for the events domain.  This module re-exports the pure buffer types from `buffer.rs` and the side-ef… |
+| `server/src/service/file_io/` | File I/O service — public API for filesystem and shell operations.  Exposes functions for reading, writing, and listing files sco… |
+| `server/src/service/gateway/` | Gateway service — domain logic for the multi-project gateway.  Follows the conventions in `docs/architecture/service-modules.md`:… |
+| `server/src/service/git_ops/` | Git operations service — worktree path validation and git command execution.  Extracted from `http/mcp/git_tools.rs` following th… |
+| `server/src/service/merge/` | Merge service — domain logic for merging agent work to master.  Extracted from `http/mcp/merge_tools.rs` following the convention… |
+| `server/src/service/notifications/` | Notifications service — pipeline-event fan-out to chat transports.  Subscribes to [`WatcherEvent`] broadcasts and posts human-rea… |
+| `server/src/service/notifications/io/` | I/O side of the notifications service.  This is the **only** file inside `service/notifications/` that may perform side effects:… |
+| `server/src/service/oauth/` | OAuth service — domain logic for the Anthropic OAuth 2.0 PKCE flow.  Extracts business logic from `http/oauth.rs` following the c… |
+| `server/src/service/pipeline/` | Pipeline service — shared pipeline-domain logic.  Contains pure functions for parsing and aggregating pipeline status data. Used… |
+| `server/src/service/project/` | Project service — public API for the project domain.  Exposes functions to open, close, query, and manage known projects. HTTP ha… |
+| `server/src/service/qa/` | QA service — domain logic for requesting, approving, and rejecting QA reviews.  Extracted from `http/mcp/qa_tools.rs` following t… |
+| `server/src/service/settings/` | Settings service — domain logic for project settings and editor configuration.  Extracts business logic from `http/settings.rs` f… |
+| `server/src/service/shell/` | Shell service — command safety, path sandboxing, and output helpers.  Extracted from `http/mcp/shell_tools.rs` following the conv… |
+| `server/src/service/status/` | Status broadcaster — unified pipeline-event fan-out for all consumers.  [`StatusBroadcaster`] lives on the [`crate::services::Ser… |
+| `server/src/service/story/` | Story service — domain logic for creating, updating, and managing pipeline work items.  Extracted from `http/mcp/story_tools.rs`… |
+| `server/src/service/timer/` | Timer service — deferred agent start via one-shot timers.  Provides [`TimerStore`] for persisting timers to `.huskies/timers.json… |
+| `server/src/service/wizard/` | Wizard service — domain logic for the multi-step project setup wizard.  Follows the conventions from `docs/architecture/service-m… |
+| `server/src/service/ws/` | WebSocket service — domain logic for real-time pipeline updates, chat, and permission prompts.  This module extracts the business… |
+| `server/src/worktree/` | Git worktree management — creates, lists, and removes worktrees for agent isolation. |
 
 ### Crates
+
 | Path | Purpose |
 |------|---------|
-| `crates/bft-json-crdt/src/` | Core CRDT library — JSON CRDT, lists, maps, registers |
-| `crates/bft-json-crdt/bft-crdt-derive/src/` | Derive macros |
+| `crates/bft-json-crdt/benches/` |  |
+| `crates/bft-json-crdt/bft-crdt-derive/src/` |  |
+| `crates/bft-json-crdt/src/` |  |
+| `crates/bft-json-crdt/tests/` |  |
 
-### Canonical examples (when adding new things, copy these patterns)
-- **New CRDT collection (LWW-map):** see `server/src/crdt_state/lww_maps.rs`
-- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs` (e.g. `handle_active_agents_list`); call from frontend with `rpcCall("method.name")`
-- **Migrate HTTP route → CRDT op:** delete the route from `gateway.rs` / `http/*`, add operation to `service/<area>/`, write through `crdt_state/`
-- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs`, plus a `write_<name>_in_content` helper
-- **New service module:** copy structure of `server/src/service/agents/` (`mod.rs` + `io.rs` + `selection.rs`)
-- **New chat command:** add file under `server/src/chat/commands/` and register in `chat/commands/mod.rs::dispatch_command`
+### Frontend (`frontend/src/`)
+
+| Path | Purpose |
+|------|---------|
+| `frontend/src/` |  |
+| `frontend/src/api/` |  |
+| `frontend/src/components/` |  |
+| `frontend/src/components/selection/` |  |
+| `frontend/src/hooks/` |  |
+| `frontend/src/utils/` |  |
+
+### Canonical patterns (copy these when adding new things)
+- **New CRDT LWW-map collection:** see `server/src/crdt_state/lww_maps.rs`
+- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs`; call from frontend via `rpcCall<T>("method.name")` from `frontend/src/api/rpc.ts`
+- **Migrate HTTP route → CRDT:** delete from `gateway.rs` / `http/*`, add op to `service/<area>/`, write through `crdt_state/`
+- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs` plus a `write_<name>_in_content` helper
+- **New service module:** copy `service/agents/` structure (`mod.rs` + `io.rs` + `selection.rs`)
+- **New chat command:** add a file under `chat/commands/` and register in `chat/commands/mod.rs::dispatch_command`
 - **New auto-assigner predicate:** add to `agents/pool/auto_assign/story_checks.rs`, wire in `auto_assign/auto_assign.rs`
-- **Test setup with CRDT seeding:** use `crate::db::write_item_with_content(story_id, stage, content)` — never `fs::write` to `.huskies/work/{stage}/`
+- **CRDT-seeding test helper:** `crate::db::write_item_with_content(story_id, stage, content)` — do not `fs::write` to `.huskies/work/{stage}/`
+
 
 ## Quality Gates
 All enforced by `script/test`: