Bump version to 0.8.0

Skip the version bump commit if nothing changed, so re-running
script/release for the same version doesn't fail on empty commit.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -1,10 +1,10 @@
 {
-  "enabledMcpjsonServers": ["story-kit"],
+  "enabledMcpjsonServers": ["storkit"],
   "permissions": {
     "allow": [
-      "Bash(./server/target/debug/story-kit:*)",
+      "Bash(./server/target/debug/storkit:*)",
-      "Bash(./target/debug/story-kit:*)",
+      "Bash(./target/debug/storkit:*)",
-      "Bash(STORYKIT_PORT=*)",
+      "Bash(STORKIT_PORT=*)",
       "Bash(cargo build:*)",
       "Bash(cargo check:*)",
       "Bash(cargo clippy:*)",
@@ -54,9 +54,20 @@
       "WebFetch(domain:portkey.ai)",
       "WebFetch(domain:www.shuttle.dev)",
       "WebSearch",
-      "mcp__story-kit__*",
+      "mcp__storkit__*",
       "Edit",
-      "Write"
+      "Write",
+      "Bash(find *)",
+      "Bash(sqlite3 *)",
+      "Bash(cat <<:*)",
+      "Bash(cat <<'ENDJSON:*)",
+      "Bash(make release:*)",
+      "Bash(npm test:*)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(npx vite:*)",
+      "Bash(npm run dev:*)"
     ]
   }
 }

.dockerignore

@@ -0,0 +1,11 @@
+# Docker build context exclusions
+**/target/
+**/node_modules/
+frontend/dist/
+.storkit/worktrees/
+.storkit/logs/
+.storkit/work/6_archived/
+.git/
+*.swp
+*.swo
+.DS_Store

.gitignore

@@ -1,25 +1,14 @@
 # Claude Code
 .claude/settings.local.json
+.mcp.json
 
 # Local environment (secrets)
 .env
 
-# App specific
+# App specific (root-level; storkit subdirectory patterns live in .storkit/.gitignore)
 store.json
-.story_kit_port
+.storkit_port
-
+.storkit/bot.toml.bak
-# Bot config (contains credentials)
-.story_kit/bot.toml
-
-# Matrix SDK state store
-.story_kit/matrix_store/
-
-# Agent worktrees and merge workspace (managed by the server, not tracked in git)
-.story_kit/worktrees/
-.story_kit/merge_workspace/
-
-# Coverage reports (generated by cargo-llvm-cov, not tracked in git)
-.story_kit/coverage/
 
 # Rust stuff
 target
@@ -38,6 +27,7 @@ frontend/node_modules
 frontend/dist
 frontend/dist-ssr
 frontend/test-results
+frontend/serve
 frontend/*.local
 server/target
 

.ignore

@@ -3,6 +3,6 @@ frontend/
 node_modules/
 .claude/
 .git/
-.story_kit/
+.storkit/
 store.json
-.story_kit_port
+.storkit_port

.mcp.json

@@ -1,6 +1,6 @@
 {
   "mcpServers": {
-    "story-kit": {
+    "storkit": {
       "type": "http",
       "url": "http://localhost:3001/mcp"
     }

.storkit/.gitignore

@@ -0,0 +1,25 @@
+# Bot config (contains credentials)
+bot.toml
+
+# Matrix SDK state store
+matrix_store/
+matrix_device_id
+matrix_history.json
+
+# Agent worktrees and merge workspace (managed by the server, not tracked in git)
+worktrees/
+merge_workspace/
+
+# Intermediate pipeline stages (transient, not committed per spike 92)
+work/2_current/
+work/3_qa/
+work/4_merge/
+
+# Coverage reports (generated by cargo-llvm-cov, not tracked in git)
+coverage/
+
+# Token usage log (generated at runtime, contains cost data)
+token_usage.jsonl
+
+# Chat service logs
+whatsapp_history.json

.storkit/README.md

@@ -11,14 +11,14 @@ When you start a new session with this project:
 
 1. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
    ```bash
-   curl -s "$(jq -r '.mcpServers["story-kit"].url' .mcp.json)" \
+   curl -s "$(jq -r '.mcpServers["storkit"].url' .mcp.json)" \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```
    This returns the full tool catalog (create stories, spawn agents, record tests, manage worktrees, etc.). Familiarize yourself with the available tools before proceeding. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation.
 2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals.
 3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
-4. **Check Work Items:** Look at `.story_kit/work/1_upcoming/` and `.story_kit/work/2_current/` to see what work is pending.
+4. **Check Work Items:** Look at `.story_kit/work/1_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
 
 
 ---
@@ -52,7 +52,7 @@ project_root/
   ├── README.md          # This document
   ├── project.toml       # Agent configuration (roles, models, prompts)
   ├── work/              # Unified work item pipeline (stories, bugs, spikes)
-  │   ├── 1_upcoming/    # New work items awaiting implementation
+  │   ├── 1_backlog/    # New work items awaiting implementation
   │   ├── 2_current/     # Work in progress
   │   ├── 3_qa/          # QA review
   │   ├── 4_merge/       # Ready to merge to master
@@ -78,7 +78,7 @@ All work items (stories, bugs, spikes) live in the same `work/` pipeline. Items
 
 Items move through stages by moving the file between directories:
 
-`1_upcoming` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
+`1_backlog` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
 
 Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 
@@ -87,7 +87,7 @@ Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 The server watches `.story_kit/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket notification to the frontend. This means:
 
 *   MCP tools only need to write/move files — the watcher handles git commits
-*   IDE drag-and-drop works (drag a story from `1_upcoming/` to `2_current/`)
+*   IDE drag-and-drop works (drag a story from `1_backlog/` to `2_current/`)
 *   The frontend updates automatically without manual refresh
 
 ---
@@ -156,7 +156,7 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
 *   Performance issues with known fixes
 
 ### Bug Process
-1.  **Document Bug:** Create a bug file in `work/1_upcoming/` named `{id}_bug_{slug}.md` with:
+1.  **Document Bug:** Create a bug file in `work/1_backlog/` named `{id}_bug_{slug}.md` with:
     *   **Symptom:** What the user observes
     *   **Root Cause:** Technical explanation (if known)
     *   **Reproduction Steps:** How to trigger the bug
@@ -186,7 +186,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
 *   Need to validate performance constraints
 
 ### Spike Process
-1.  **Document Spike:** Create a spike file in `work/1_upcoming/` named `{id}_spike_{slug}.md` with:
+1.  **Document Spike:** Create a spike file in `work/1_backlog/` named `{id}_spike_{slug}.md` with:
     *   **Question:** What you need to answer
     *   **Hypothesis:** What you expect to be true
     *   **Timebox:** Strict limit for the research
@@ -209,7 +209,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
 1.  **Stop Coding.**
 2.  **Instruction:** Tell the user to open a new chat.
 3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`.
-    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_upcoming/` and `work/2_current/` to see what is pending."
+    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_backlog/` and `work/2_current/` to see what is pending."
 
 
 ---
@@ -221,14 +221,36 @@ If a user hands you this document and says "Apply this process to my project":
 1.  **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities.
 2.  **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
 3.  **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
-4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_upcoming/` through `work/6_archived/`).
+4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_backlog/` through `work/6_archived/`).
 5.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
 6.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
 7.  **Wait:** Ask the user for "Story #1".
 
 ---
 
-## 6. Code Quality
+## 6. Chat Bot Configuration
+
+Story Kit includes a chat bot that can be connected to one messaging platform at a time. The bot handles commands, LLM conversations, and pipeline notifications.
+
+**Only one transport can be active at a time.** To configure the bot, copy the appropriate example file to `.storkit/bot.toml`:
+
+| Transport | Example file | Webhook endpoint |
+|-----------|-------------|-----------------|
+| Matrix | `bot.toml.matrix.example` | *(uses Matrix sync, no webhook)* |
+| WhatsApp (Meta Cloud API) | `bot.toml.whatsapp-meta.example` | `/webhook/whatsapp` |
+| WhatsApp (Twilio) | `bot.toml.whatsapp-twilio.example` | `/webhook/whatsapp` |
+| Slack | `bot.toml.slack.example` | `/webhook/slack` |
+
+```bash
+cp .storkit/bot.toml.matrix.example .storkit/bot.toml
+# Edit bot.toml with your credentials
+```
+
+The `bot.toml` file is gitignored (it contains secrets). The example files are checked in for reference.
+
+---
+
+## 7. Code Quality
 
 **MANDATORY:** Before completing Step 3 (Verification) of any story, you MUST run all applicable linters, formatters, and test suites and fix ALL errors and warnings. Zero tolerance for warnings or errors.
 

.storkit/bot.toml.matrix.example

@@ -0,0 +1,26 @@
+# Matrix Transport
+# Copy this file to bot.toml and fill in your values.
+# Only one transport can be active at a time.
+
+enabled = true
+transport = "matrix"
+
+homeserver = "https://matrix.example.com"
+username = "@botname:example.com"
+password = "your-bot-password"
+
+# List one or more rooms to listen in.
+room_ids = ["!roomid:example.com"]
+
+# Users allowed to interact with the bot (fail-closed: empty = nobody).
+allowed_users = ["@youruser:example.com"]
+
+# Bot display name in chat.
+# display_name = "Assistant"
+
+# Maximum conversation turns to remember per room (default: 20).
+# history_size = 20
+
+# Rooms where the bot responds to all messages (not just addressed ones).
+# This list is updated automatically when users toggle ambient mode at runtime.
+# ambient_rooms = ["!roomid:example.com"]

.storkit/bot.toml.slack.example

@@ -0,0 +1,23 @@
+# Slack Transport
+# Copy this file to bot.toml and fill in your values.
+# Only one transport can be active at a time.
+#
+# Setup:
+#   1. Create a Slack App at api.slack.com/apps
+#   2. Add OAuth scopes: chat:write, chat:update
+#   3. Subscribe to bot events: message.channels, message.groups, message.im
+#   4. Install the app to your workspace
+#   5. Set your webhook URL in Event Subscriptions: https://your-server/webhook/slack
+
+enabled = true
+transport = "slack"
+
+slack_bot_token = "xoxb-..."
+slack_signing_secret = "your-signing-secret"
+slack_channel_ids = ["C01ABCDEF"]
+
+# Bot display name (used in formatted messages).
+# display_name = "Assistant"
+
+# Maximum conversation turns to remember per channel (default: 20).
+# history_size = 20

.storkit/bot.toml.whatsapp-meta.example

@@ -0,0 +1,33 @@
+# WhatsApp Transport (Meta Cloud API)
+# Copy this file to bot.toml and fill in your values.
+# Only one transport can be active at a time.
+#
+# Setup:
+#   1. Create a Meta Business App at developers.facebook.com
+#   2. Add the WhatsApp product
+#   3. Copy your Phone Number ID and generate a permanent access token
+#   4. Register your webhook URL: https://your-server/webhook/whatsapp
+#   5. Set the verify token below to match what you configure in Meta's dashboard
+
+enabled = true
+transport = "whatsapp"
+whatsapp_provider = "meta"
+
+whatsapp_phone_number_id = "123456789012345"
+whatsapp_access_token = "EAAx..."
+whatsapp_verify_token = "my-secret-verify-token"
+
+# Optional: name of the approved Meta message template used for notifications
+# sent outside the 24-hour messaging window (default: "pipeline_notification").
+# whatsapp_notification_template = "pipeline_notification"
+
+# Bot display name (used in formatted messages).
+# display_name = "Assistant"
+
+# Maximum conversation turns to remember per user (default: 20).
+# history_size = 20
+
+# Optional: restrict which phone numbers can interact with the bot.
+# When set, only listed numbers are processed; all others are silently ignored.
+# When absent or empty, all numbers are allowed (open by default).
+# whatsapp_allowed_phones = ["+15551234567", "+15559876543"]

.storkit/bot.toml.whatsapp-twilio.example

@@ -0,0 +1,29 @@
+# WhatsApp Transport (Twilio)
+# Copy this file to bot.toml and fill in your values.
+# Only one transport can be active at a time.
+#
+# Setup:
+#   1. Sign up at twilio.com
+#   2. Activate the WhatsApp sandbox (Messaging > Try it out > Send a WhatsApp message)
+#   3. Send the sandbox join code from your WhatsApp to the sandbox number
+#   4. Copy your Account SID, Auth Token, and sandbox number below
+#   5. Set your webhook URL in the Twilio console: https://your-server/webhook/whatsapp
+
+enabled = true
+transport = "whatsapp"
+whatsapp_provider = "twilio"
+
+twilio_account_sid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+twilio_auth_token = "your_auth_token"
+twilio_whatsapp_number = "+14155238886"
+
+# Bot display name (used in formatted messages).
+# display_name = "Assistant"
+
+# Maximum conversation turns to remember per user (default: 20).
+# history_size = 20
+
+# Optional: restrict which phone numbers can interact with the bot.
+# When set, only listed numbers are processed; all others are silently ignored.
+# When absent or empty, all numbers are allowed (open by default).
+# whatsapp_allowed_phones = ["+15551234567", "+15559876543"]

.storkit/problems.md

@@ -0,0 +1,28 @@
+# Problems
+
+Recurring issues observed during pipeline operation. Review periodically and create stories for systemic problems.
+
+## 2026-03-18: Stories graduating to "done" with empty merges (7 of 10)
+
+Pipeline allows stories to move through coding → QA → merge → done without any actual code changes landing on master. The squash-merge produces an empty diff but the pipeline still marks the story as done. Affected stories: 247, 273, 274, 278, 279, 280, 92. Only 266, 271, 277, and 281 actually shipped code. Root cause: no check that the merge commit contains a non-empty diff. Filed bug 283 for the manual_qa gate issue specifically, but the empty-merge-to-done problem is broader and needs its own fix.
+
+## 2026-03-18: Agent committed directly to master instead of worktree
+
+Multiple agents have committed directly to master instead of their worktree/feature branch:
+
+- Commit `5f4591f` ("fix: update should_commit_stage test to match 5_done") — likely mergemaster
+- Commit `a32cfbd` ("Add bot-level command registry with help command") — story 285 coder committed code + Cargo.lock directly to master
+
+Agents should only commit to their feature branch or merge-queue branch, never to master directly. Suspect agents are running `git commit` in the project root instead of the worktree directory. This can also revert uncommitted fixes on master (e.g. project.toml pkill fix was overwritten). Frequency: at least 2 confirmed cases. This is a recurring and serious problem — needs a guard in the server or agent prompts.
+
+## 2026-03-19: Auto-assign re-assigns mergemaster to failed merge stories in a loop
+
+After bug 295 fix (`auto_assign_available_work` after every pipeline advance), mergemaster gets re-assigned to stories that already have a merge failure flag. Story 310 had an empty diff merge failure — mergemaster correctly reported the failure, but auto-assign immediately re-assigned mergemaster to the same story, creating an infinite retry loop. The auto-assign logic needs to check for the `merge_failure` front matter flag before re-assigning agents to stories in `4_merge/`.
+
+## 2026-03-19: Coder produces no code (complete ghost — story 310)
+
+Story 310 (Bot delete command) went through the full pipeline — coder session ran, passed QA/gates, moved to merge — but the coder produced zero code. No commits on the feature branch, no commits on master. The entire agent session was a no-op. This is different from the "committed to master instead of worktree" problem — in this case, the coder simply did nothing. Need to investigate the coder logs to understand what happened. The empty-diff merge check would catch this at merge time, but ideally the server should detect "coder finished with no commits on feature branch" at the gate-check stage and fail early.
+
+## 2026-03-19: Auto-assign assigns mergemaster to coding-stage stories
+
+Auto-assign picked mergemaster for story 310 which was in `2_current/`. Mergemaster should only work on stories in `4_merge/`. The `auto_assign_available_work` function doesn't enforce that the agent's configured stage matches the pipeline stage of the story it's being assigned to. Story 279 (auto-assign respects agent stage from front matter) was supposed to fix this, but the check may only apply to front-matter preferences, not the fallback assignment path.

.storkit/project.toml

@@ -0,0 +1,277 @@
+# Project-wide default QA mode: "server", "agent", or "human".
+# Per-story `qa` front matter overrides this setting.
+default_qa = "server"
+
+# Default model for coder agents. Only agents with this model are auto-assigned.
+# Opus coders are reserved for explicit per-story `agent:` front matter requests.
+default_coder_model = "sonnet"
+
+# Maximum concurrent coder agents. Stories wait in 2_current/ when all slots are full.
+max_coders = 3
+
+# Maximum retries per story per pipeline stage before marking as blocked.
+# Set to 0 to disable retry limits.
+max_retries = 3
+
+# Base branch name for this project. Worktree creation, merges, and agent prompts
+# use this value for {{base_branch}}. When not set, falls back to auto-detection
+# (reads current HEAD branch).
+base_branch = "master"
+
+[[component]]
+name = "frontend"
+path = "frontend"
+setup = ["npm ci", "npm run build"]
+teardown = []
+
+[[component]]
+name = "server"
+path = "."
+setup = ["mkdir -p frontend/dist", "cargo check"]
+teardown = []
+
+[[agent]]
+name = "coder-1"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "coder-2"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "coder-3"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "qa-2"
+stage = "qa"
+role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+model = "sonnet"
+max_turns = 40
+max_budget_usd = 4.00
+prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+
+Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
+
+## Your Workflow
+
+### 1. Code Quality Scan
+- Run `git diff master...HEAD --stat` to see what files changed
+- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
+- Run `cargo clippy --all-targets --all-features` and note any warnings
+- If a `frontend/` directory exists:
+  - Run `npm run build` and note any TypeScript errors
+  - Run `npx @biomejs/biome check src/` and note any linting issues
+
+### 2. Test Verification
+- Run `cargo test` and verify all tests pass
+- If `frontend/` exists: run `npm test` and verify all frontend tests pass
+- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+
+### 3. Manual Testing Support
+- Build the server: run `cargo build` and note success/failure
+- If build succeeds: find a free port (try 3010-3020) and attempt to start the server
+- Generate a testing plan including:
+  - URL to visit in the browser
+  - Things to check in the UI
+  - curl commands to exercise relevant API endpoints
+- Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
+
+### 4. Produce Structured Report
+Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
+
+```
+## QA Report for {{story_id}}
+
+### Code Quality
+- clippy: PASS/FAIL (details)
+- TypeScript build: PASS/FAIL/SKIP (details)
+- Biome lint: PASS/FAIL/SKIP (details)
+- Code review findings: (list any issues found, or "None")
+
+### Test Verification
+- cargo test: PASS/FAIL (N tests)
+- npm test: PASS/FAIL/SKIP (N tests)
+- Test quality issues: (list any trivial/weak tests, or "None")
+
+### Manual Testing Plan
+- Server URL: http://localhost:PORT (or "Build failed")
+- Pages to visit: (list)
+- Things to check: (list)
+- curl commands: (list)
+
+### Overall: PASS/FAIL
+```
+
+## Rules
+- Do NOT modify any code — read-only review only
+- If the server fails to start, still provide the testing plan with curl commands
+- The server automatically runs acceptance gates when your process exits"""
+system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+
+[[agent]]
+name = "coder-opus"
+stage = "coder"
+role = "Senior full-stack engineer for complex tasks. Implements features across all components."
+model = "opus"
+max_turns = 80
+max_budget_usd = 20.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "qa"
+stage = "qa"
+role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+model = "sonnet"
+max_turns = 40
+max_budget_usd = 4.00
+prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+
+Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
+
+## Your Workflow
+
+### 1. Code Quality Scan
+- Run `git diff master...HEAD --stat` to see what files changed
+- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
+- Run `cargo clippy --all-targets --all-features` and note any warnings
+- If a `frontend/` directory exists:
+  - Run `npm run build` and note any TypeScript errors
+  - Run `npx @biomejs/biome check src/` and note any linting issues
+
+### 2. Test Verification
+- Run `cargo test` and verify all tests pass
+- If `frontend/` exists: run `npm test` and verify all frontend tests pass
+- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+
+### 3. Manual Testing Support
+- Build the server: run `cargo build` and note success/failure
+- If build succeeds: find a free port (try 3010-3020) and attempt to start the server
+- Generate a testing plan including:
+  - URL to visit in the browser
+  - Things to check in the UI
+  - curl commands to exercise relevant API endpoints
+- Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
+
+### 4. Produce Structured Report
+Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
+
+```
+## QA Report for {{story_id}}
+
+### Code Quality
+- clippy: PASS/FAIL (details)
+- TypeScript build: PASS/FAIL/SKIP (details)
+- Biome lint: PASS/FAIL/SKIP (details)
+- Code review findings: (list any issues found, or "None")
+
+### Test Verification
+- cargo test: PASS/FAIL (N tests)
+- npm test: PASS/FAIL/SKIP (N tests)
+- Test quality issues: (list any trivial/weak tests, or "None")
+
+### Manual Testing Plan
+- Server URL: http://localhost:PORT (or "Build failed")
+- Pages to visit: (list)
+- Things to check: (list)
+- curl commands: (list)
+
+### Overall: PASS/FAIL
+```
+
+## Rules
+- Do NOT modify any code — read-only review only
+- If the server fails to start, still provide the testing plan with curl commands
+- The server automatically runs acceptance gates when your process exits"""
+system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+
+[[agent]]
+name = "mergemaster"
+stage = "mergemaster"
+role = "Merges completed coder work into master, runs quality gates, archives stories, and cleans up worktrees."
+model = "opus"
+max_turns = 30
+max_budget_usd = 5.00
+prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master.
+
+Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
+
+## Your Workflow
+1. Call merge_agent_work(story_id='{{story_id}}') via the MCP tool to trigger the full merge pipeline
+2. Review the result: check success, had_conflicts, conflicts_resolved, gates_passed, and gate_output
+3. If merge succeeded and gates passed: report success to the human
+4. If conflicts were auto-resolved (conflicts_resolved=true) and gates passed: report success, noting which conflicts were resolved
+5. If conflicts could not be auto-resolved: **resolve them yourself** in the merge worktree (see below)
+6. If merge failed for any other reason: call report_merge_failure(story_id='{{story_id}}', reason='<details>') and report to the human
+7. If gates failed after merge: attempt to fix the issues yourself in the merge worktree, then re-trigger merge_agent_work. After 3 fix attempts, call report_merge_failure and stop.
+
+## Resolving Complex Conflicts Yourself
+
+When the auto-resolver fails, you have access to the merge worktree at `.story_kit/merge_workspace/`. Go in there and resolve the conflicts manually:
+
+1. Run `git diff --name-only --diff-filter=U` in the merge worktree to list conflicted files
+2. **Build context before touching code.** Run `git log --oneline master...HEAD` on the feature branch to see its commits. Then run `git log --oneline --since="$(git log -1 --format=%ci <feature-branch-base-commit>)" master` to see what landed on master since the branch was created. Read the story files in `.story_kit/work/` for any recently merged stories that touch the same files — this tells you WHY master changed and what must be preserved.
+3. Read each conflicted file and understand both sides of the conflict
+4. **Understand intent, not just syntax.** The feature branch may be behind master — master's version of shared infrastructure is almost always correct. The feature branch's contribution is the NEW functionality it adds. Your job is to integrate the new into master's structure, not pick one side.
+5. Resolve by integrating the feature's new functionality into master's code structure
+5. Stage resolved files with `git add`
+6. Run `cargo check` (and `npm run build` if frontend changed) to verify compilation
+7. If it compiles, commit and re-trigger merge_agent_work
+
+### Common conflict patterns in this project:
+
+**Story file rename/rename conflicts:** Both branches moved the story .md file to different pipeline directories. Resolution: `git rm` both sides — story files in `work/2_current/`, `work/3_qa/`, `work/4_merge/` are gitignored and don't need to be committed.
+
+**bot.rs tokio::select! conflicts:** Master has a `tokio::select!` loop in `handle_message()` that handles permission forwarding (story 275). Feature branches created before story 275 have a simpler direct `provider.chat_stream().await` call. Resolution: KEEP master's tokio::select! loop. Integrate only the feature's new logic (e.g. typing indicators, new callbacks) into the existing loop structure. Do NOT replace the loop with the old direct call.
+
+**Duplicate functions/imports:** The auto-resolver keeps both sides, producing duplicates. Resolution: keep one copy (prefer master's version), delete the duplicate.
+
+**Formatting-only conflicts:** Both sides reformatted the same code differently. Resolution: pick either side (prefer master).
+
+## Fixing Gate Failures
+
+If quality gates fail (cargo clippy, cargo test, npm run build, npm test), attempt to fix issues yourself in the merge worktree.
+
+**Fix yourself (up to 3 attempts total):**
+- Syntax errors (missing semicolons, brackets, commas)
+- Duplicate definitions from merge artifacts
+- Simple type annotation errors
+- Unused import warnings flagged by clippy
+- Mismatched braces from bad conflict resolution
+- Trivial formatting issues that block compilation or linting
+
+**Report to human without attempting a fix:**
+- Logic errors or incorrect business logic
+- Missing function implementations
+- Architectural changes required
+- Non-trivial refactoring needed
+
+**Max retry limit:** If gates still fail after 3 fix attempts, call report_merge_failure to record the failure, then stop immediately and report the full gate output to the human.
+
+## CRITICAL Rules
+- NEVER manually move story files between pipeline stages (e.g. from 4_merge/ to 5_done/)
+- NEVER call accept_story — only merge_agent_work can move stories to done after a successful merge
+- When merge fails after exhausting your fix attempts, ALWAYS call report_merge_failure
+- Report conflict resolution outcomes clearly
+- Report gate failures with full output so the human can act if needed
+- The server automatically runs acceptance gates when your process exits"""
+system_prompt = "You are the mergemaster agent. Your primary job is to merge feature branches to master. First try the merge_agent_work MCP tool. If the auto-resolver fails on complex conflicts, resolve them yourself in the merge worktree — you are an opus-class agent capable of understanding both sides of a conflict and producing correct merged code. Common patterns: keep master's tokio::select! permission loop in bot.rs, discard story file rename conflicts (gitignored), remove duplicate definitions. After resolving, verify compilation before re-triggering merge. CRITICAL: Never manually move story files or call accept_story. After 3 failed fix attempts, call report_merge_failure and stop."

.storkit/project.toml.example

@@ -0,0 +1,43 @@
+# Example project.toml — copy to .storkit/project.toml and customise.
+# This file is checked in; project.toml itself is gitignored (it may contain
+# instance-specific settings).
+
+# Project-wide default QA mode: "server", "agent", or "human".
+# Per-story `qa` front matter overrides this setting.
+default_qa = "server"
+
+# Default model for coder agents. Only agents with this model are auto-assigned.
+# Opus coders are reserved for explicit per-story `agent:` front matter requests.
+default_coder_model = "sonnet"
+
+# Maximum concurrent coder agents. Stories wait in 2_current/ when all slots are full.
+max_coders = 3
+
+# Maximum retries per story per pipeline stage before marking as blocked.
+# Set to 0 to disable retry limits.
+max_retries = 2
+
+# Base branch name for this project. Worktree creation, merges, and agent prompts
+# use this value for {{base_branch}}. When not set, falls back to auto-detection
+# (reads current HEAD branch).
+base_branch = "main"
+
+[[component]]
+name = "server"
+path = "."
+setup = ["cargo build"]
+teardown = []
+
+[[agent]]
+name = "coder-1"
+role = "Full-stack engineer"
+stage = "coder"
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = """
+You are working in a git worktree on story {{story_id}}.
+Read CLAUDE.md first, then .storkit/README.md to understand the dev process.
+Run: cd "{{worktree_path}}" && git difftool {{base_branch}}...HEAD
+Commit all your work before your process exits.
+"""

.storkit/specs/functional/SLACK_SETUP.md

@@ -0,0 +1,44 @@
+# Slack Integration Setup
+
+## Bot Configuration
+
+Slack integration is configured via `bot.toml` in the project's `.story_kit/` directory:
+
+```toml
+transport = "slack"
+display_name = "Storkit"
+slack_bot_token = "xoxb-..."
+slack_signing_secret = "..."
+slack_channel_ids = ["C01ABCDEF"]
+```
+
+## Slack App Configuration
+
+### Event Subscriptions
+
+1. In your Slack app settings, enable **Event Subscriptions**.
+2. Set the **Request URL** to: `https://<your-host>/webhook/slack`
+3. Subscribe to the `message.channels` and `message.im` bot events.
+
+### Slash Commands
+
+Slash commands provide quick access to pipeline commands without mentioning the bot.
+
+1. In your Slack app settings, go to **Slash Commands**.
+2. Create the following commands, all pointing to the same **Request URL**: `https://<your-host>/webhook/slack/command`
+
+| Command | Description |
+|---------|-------------|
+| `/storkit-status` | Show pipeline status and agent availability |
+| `/storkit-cost` | Show token spend: 24h total, top stories, and breakdown |
+| `/storkit-show` | Display the full text of a work item (e.g. `/storkit-show 42`) |
+| `/storkit-git` | Show git status: branch, changes, ahead/behind |
+| `/storkit-htop` | Show system and agent process dashboard |
+
+All slash command responses are **ephemeral** — only the user who invoked the command sees the response.
+
+### OAuth & Permissions
+
+Required bot token scopes:
+- `chat:write` — send messages
+- `commands` — handle slash commands

.storkit/specs/tech/STACK.md

@@ -9,7 +9,7 @@ This project is a standalone Rust **web server binary** that serves a Vite/React
     *   **Framework:** Poem HTTP server with WebSocket support for streaming; HTTP APIs should use Poem OpenAPI (Swagger) for non-streaming endpoints.
 *   **Frontend:** TypeScript + React
     *   **Build Tool:** Vite
-    *   **Package Manager:** pnpm (required)
+    *   **Package Manager:** npm
     *   **Styling:** CSS Modules or Tailwind (TBD - Defaulting to CSS Modules)
     *   **State Management:** React Context / Hooks
     *   **Chat UI:** Rendered Markdown with syntax highlighting.
@@ -91,8 +91,8 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 *   **Quality Gates:**
     *   `npx @biomejs/biome check src/` must show 0 errors, 0 warnings
     *   `npm run build` must succeed
-    *   `npx vitest run` must pass
+    *   `npm test` must pass
-    *   `npx playwright test` must pass
+    *   `npm run test:e2e` must pass
     *   No `any` types allowed (use proper types or `unknown`)
     *   React keys must use stable IDs, not array indices
     *   All buttons must have explicit `type` attribute
@@ -118,8 +118,8 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 
 Multiple instances can run simultaneously in different worktrees. To avoid port conflicts:
 
-- **Backend:** Set `STORYKIT_PORT` to a unique port (default is 3001). Example: `STORYKIT_PORT=3002 cargo run`
+- **Backend:** Set `STORKIT_PORT` to a unique port (default is 3001). Example: `STORKIT_PORT=3002 cargo run`
-- **Frontend:** Run `pnpm dev` from `frontend/`. It auto-selects the next unused port. It reads `STORYKIT_PORT` to know which backend to talk to, so export it before running: `export STORYKIT_PORT=3002 && cd frontend && pnpm dev`
+- **Frontend:** Run `npm run dev` from `frontend/`. It auto-selects the next unused port. It reads `STORKIT_PORT` to know which backend to talk to, so export it before running: `export STORKIT_PORT=3002 && cd frontend && npm run dev`
 
 When running in a worktree, use a port that won't conflict with the main instance (3001). Ports 3002+ are good choices.
 
@@ -127,4 +127,4 @@ When running in a worktree, use a port that won't conflict with the main instanc
 1.  **Project Scope:** The application must strictly enforce that it does not read/write outside the `project_root` selected by the user.
 2.  **Human in the Loop:**
     *   Shell commands that modify state (non-readonly) should ideally require a UI confirmation (configurable).
-    *   File writes must be confirmed or revertible.
+    *   File writes must be confirmed or revertible.

.storkit/work/1_backlog/260_refactor_upgrade_libsqlite3_sys.md

@@ -0,0 +1,24 @@
+---
+name: "Upgrade libsqlite3-sys"
+---
+
+# Refactor 260: Upgrade libsqlite3-sys
+
+## Description
+
+Upgrade the `libsqlite3-sys` dependency from `0.35.0` to `0.37.0`. The crate is used with `features = ["bundled"]` for static builds.
+
+## Version Notes
+
+- Current: `libsqlite3-sys 0.35.0` (pinned transitively by `matrix-sdk 0.16.0` → `matrix-sdk-sqlite` → `rusqlite 0.37.x`)
+- Target: `libsqlite3-sys 0.37.0`
+- Latest upstream rusqlite: `0.39.0`
+- **Blocker**: `matrix-sdk 0.16.0` pins `rusqlite 0.37.x` which pins `libsqlite3-sys 0.35.0`. A clean upgrade requires either waiting for matrix-sdk to bump their rusqlite dep, or upgrading matrix-sdk itself.
+- **Reverted 2026-03-17**: A previous coder vendored the entire rusqlite crate with a fake `0.37.99` version and patched its libsqlite3-sys dep. This was too hacky — reverted to clean `0.35.0`.
+
+## Acceptance Criteria
+
+- [ ] `libsqlite3-sys` is upgraded to `0.37.0` via a clean dependency path (no vendored forks)
+- [ ] `cargo build` succeeds
+- [ ] All tests pass
+- [ ] No `[patch.crates-io]` hacks or vendored crates

.storkit/work/1_backlog/388_story_whatsapp_webhook_hmac_signature_verification.md

@@ -0,0 +1,24 @@
+---
+name: "WhatsApp webhook HMAC signature verification"
+retry_count: 3
+blocked: true
+---
+
+# Story 388: WhatsApp webhook HMAC signature verification
+
+## User Story
+
+As a bot operator, I want incoming WhatsApp webhook requests to be cryptographically verified, so that forged requests from unauthorized sources are rejected.
+
+## Acceptance Criteria
+
+- [ ] Meta webhooks: validate X-Hub-Signature-256 HMAC-SHA256 header using the app secret before processing
+- [ ] Twilio webhooks: validate request signature using the auth token before processing
+- [ ] Requests with missing or invalid signatures are rejected with 403 Forbidden
+- [ ] Verification is fail-closed: if signature checking is configured, unsigned requests are rejected
+- [ ] Existing bot.toml config is extended with any needed secrets (e.g. Meta app_secret for HMAC verification)
+- [ ] MUST use audited crypto crates (hmac, sha2, sha1, base64) — no hand-rolled cryptographic primitives
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/408_spike_fly_io_machines_api_integration_for_multi_tenant_storkit_saas.md

@@ -0,0 +1,40 @@
+---
+name: "Fly.io Machines API integration for multi-tenant storkit SaaS"
+---
+
+# Spike 408: Fly.io Machines API integration for multi-tenant storkit SaaS
+
+## Question
+
+Can we build a working Rust integration that creates and manages per-tenant Fly.io Machines, attaches volumes, injects Claude credentials, and proxies JWT-authenticated HTTP/WebSocket traffic to the right machine?
+
+## Hypothesis
+
+A thin Rust service using `reqwest` for the Machines API and `axum` for the reverse proxy is sufficient. No heavyweight orchestration framework needed.
+
+## Prerequisites
+
+- Fly.io account with API token (set `FLY_API_TOKEN` env var)
+- Spike 407 findings reviewed
+
+## Timebox
+
+4 hours
+
+## Investigation Plan
+
+- [ ] Create a minimal Rust crate in `spikes/fly_machines/` — do not touch production code
+- [ ] Implement machine lifecycle: create, start, stop, destroy via Fly Machines REST API using `reqwest`
+- [ ] Test attaching a persistent volume to a machine and verify it persists across stop/start
+- [ ] Test secret injection — pass a dummy `credentials.json` as a Fly secret and verify it's readable inside the machine
+- [ ] Sketch the auth proxy: JWT validation → machine lookup → reverse proxy to machine's private IP; verify WebSocket proxying works
+- [ ] Measure actual cold start time for a minimal storkit container image
+- [ ] Document any API quirks, rate limits, or sharp edges discovered during testing
+
+## Findings
+
+- TBD
+
+## Recommendation
+
+- TBD

.storkit/work/1_backlog/411_story_multi_account_oauth_token_rotation_on_rate_limit.md

@@ -0,0 +1,22 @@
+---
+name: "Multi-account OAuth token rotation on rate limit"
+---
+
+# Story 411: Multi-account OAuth token rotation on rate limit
+
+## User Story
+
+As a storkit user with multiple Claude Max subscriptions, I want the system to automatically rotate to a different account when one gets rate limited, so that agents and chat don't stall out waiting for limits to reset.
+
+## Acceptance Criteria
+
+- [ ] OAuth login flow stores credentials per-account (keyed by email), not overwriting previous accounts
+- [ ] GET /oauth/status returns all stored accounts and their status (active, rate-limited, expired)
+- [ ] When the active account hits a rate limit, storkit automatically swaps to the next available account's refresh token, refreshes, and retries
+- [ ] The bot sends a notification in Matrix/WhatsApp when it swaps accounts
+- [ ] If all accounts are rate limited, the bot surfaces a clear message with the time until the earliest reset
+- [ ] A new /oauth/authorize login adds to the account pool rather than replacing the current credentials
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/412_story_recheck_bot_command_to_re_run_gates_without_restarting_agent.md

@@ -0,0 +1,24 @@
+---
+name: "Recheck bot command to re-run gates without restarting agent"
+---
+
+# Story 412: Recheck bot command to re-run gates without restarting agent
+
+## User Story
+
+As a user, I want to send `recheck <number>` to the bot so that it re-runs acceptance gates on an existing worktree without spawning a new agent, so I can unblock stories that failed due to environment issues without wasting agent turns.
+
+## Acceptance Criteria
+
+- [ ] recheck command is registered in chat/commands/mod.rs and appears in help output
+- [ ] `recheck <number>` runs run_acceptance_gates on the story's existing worktree
+- [ ] If gates pass, the story advances through the pipeline (same as if a coder completed successfully)
+- [ ] If gates fail, the error output is returned to the user (not silently retried)
+- [ ] If no worktree exists for the story, returns a clear error
+- [ ] Does not spawn a new agent or increment retry_count
+- [ ] Works from all transports (Matrix, WhatsApp, Slack)
+- [ ] Works from web UI slash commands
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/430_bug_status_command_traffic_light_dots_not_coloured_in_matrix.md

@@ -0,0 +1,27 @@
+---
+name: "Status command traffic light dots not coloured in Matrix"
+---
+
+# Bug 430: Status command traffic light dots not coloured in Matrix
+
+## Description
+
+The traffic light dots in the status command use plain Unicode characters (○ ● ◑ ✗) which render without colour in Matrix. The HTML formatted_body should use data-mx-color to colour them green/yellow/red.
+
+## How to Reproduce
+
+Send the status command to the bot in Matrix. Observe the dots are monochrome.
+
+## Actual Result
+
+Dots render as plain monochrome Unicode characters.
+
+## Expected Result
+
+Dots render in colour: green (● running), yellow (◑ throttled), red (✗ blocked), grey (○ idle). Use font tag with data-mx-color attribute for Matrix HTML formatted_body.
+
+## Acceptance Criteria
+
+- [ ] HTML formatted_body uses <font data-mx-color="#colour">dot</font> for each traffic light state
+- [ ] Green (#00cc00) for running, yellow (#ffaa00) for throttled, red (#cc0000) for blocked, grey (#888888) for idle
+- [ ] Plain text fallback remains unchanged (Unicode dots for non-HTML transports)

.storkit/work/5_done/417_refactor_split_matrix_bot_rs_into_focused_modules.md

@@ -0,0 +1,30 @@
+---
+name: "Split matrix/bot.rs into focused modules"
+---
+
+# Refactor 417: Split matrix/bot.rs into focused modules
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Refactor the monolithic server/src/chat/transport/matrix/bot.rs (1926 lines) into focused submodules.
+
+## Acceptance Criteria
+
+- [ ] history.rs contains ConversationRole, ConversationEntry, RoomConversation, PersistedHistory, load_history, save_history and their unit tests
+- [ ] context.rs contains BotContext struct
+- [ ] run.rs contains run_bot main event loop
+- [ ] messages.rs contains on_room_message, handle_message, format_user_prompt, is_permission_approval and their unit tests
+- [ ] mentions.rs contains mentions_bot, contains_word, is_reply_to_bot and their unit tests
+- [ ] verification.rs contains check_sender_verified, on_to_device_verification_request, handle_sas_verification and their unit tests
+- [ ] format.rs contains markdown_to_html, format_startup_announcement and their unit tests
+- [ ] mod.rs re-exports all public types
+- [ ] Unit tests live in their respective module files
+- [ ] No public API changes — all existing imports continue to work
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/418_refactor_split_pool_auto_assign_rs_into_submodules.md

@@ -0,0 +1,28 @@
+---
+name: "Split pool/auto_assign.rs into submodules"
+---
+
+# Refactor 418: Split pool/auto_assign.rs into submodules
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Refactor the monolithic server/src/agents/pool/auto_assign.rs (1813 lines) into focused submodules.
+
+## Acceptance Criteria
+
+- [ ] auto_assign.rs contains auto_assign_available_work and its unit tests
+- [ ] reconcile.rs contains reconcile_on_startup and its unit tests
+- [ ] watchdog.rs contains run_watchdog_once, spawn_watchdog, check_orphaned_agents and their unit tests
+- [ ] scan.rs contains scan_stage_items, is_story_assigned_for_stage, count_active_agents_for_stage, find_free_agent_for_stage, is_agent_free and their unit tests
+- [ ] story_checks.rs contains read_story_front_matter_agent, has_review_hold, is_story_blocked, has_merge_failure and their unit tests
+- [ ] mod.rs wires the submodules and re-exports all public items
+- [ ] Unit tests live in their respective module files
+- [ ] No public API changes — all existing imports continue to work
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/419_bug_matrix_bot_crashes_on_transient_network_error_instead_of_retrying.md

@@ -0,0 +1,29 @@
+---
+name: "Matrix bot crashes on transient network error instead of retrying"
+---
+
+# Bug 419: Matrix bot crashes on transient network error instead of retrying
+
+## Description
+
+The Matrix bot treats a transient sync error as fatal and stops entirely. A single failed HTTP request to the homeserver kills the bot, requiring a full server rebuild to recover.
+
+## How to Reproduce
+
+1. Run storkit with Matrix bot enabled\n2. Homeserver becomes temporarily unreachable (network blip, DNS hiccup, server restart)\n3. Bot hits sync error and crashes
+
+## Actual Result
+
+Bot logs "Fatal error: Matrix sync error: error sending request for url (...)" and stops responding. No retry, no recovery.
+
+## Expected Result
+
+Bot logs a warning, backs off with exponential delay, and retries the sync. Only crash on unrecoverable errors (invalid credentials, banned, etc).
+
+## Acceptance Criteria
+
+- [ ] Transient network errors (connection refused, timeout, DNS failure) trigger a retry with exponential backoff
+- [ ] Bot logs a warning on each failed retry attempt
+- [ ] Bot resumes normal operation once the homeserver is reachable again
+- [ ] Unrecoverable errors (401, 403) still cause a clean shutdown with a clear error message
+- [ ] Bot sends a notification after recovering from a network outage

.storkit/work/5_done/420_story_loc_for_a_specified_file_bot_command_and_web_ui_slash_command.md

@@ -0,0 +1,23 @@
+---
+name: "loc for a specified file — bot command and web UI slash command"
+---
+
+# Story 420: loc for a specified file — bot command and web UI slash command
+
+## User Story
+
+As a developer, I want to send `loc <filepath>` to the bot or use it as a slash command in the web UI to see the line count for a specific file, so I can quickly check how large a file is without leaving my workflow.
+
+## Acceptance Criteria
+
+- [ ] loc <filepath> returns the line count for the specified file
+- [ ] Relative paths are resolved against the project root
+- [ ] If the file does not exist, returns a clear error
+- [ ] Works from all transports (Matrix, WhatsApp, Slack)
+- [ ] Works as a slash command in the web UI
+- [ ] loc with no argument retains existing behavior (top files by line count)
+- [ ] Exposed as an MCP tool so agents can query file line counts programmatically
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/421_story_timer_command_for_deferred_agent_start.md

@@ -0,0 +1,24 @@
+---
+name: "Timer command for deferred agent start"
+---
+
+# Story 421: Timer command for deferred agent start
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] Bot command `timer <story_id> <HH:MM>` schedules a one-shot deferred start for the given story at the next occurrence of that time (server-local timezone)
+- [ ] Bot command `timer list` shows all pending timers with story ID and scheduled time
+- [ ] Bot command `timer cancel <story_id>` removes the pending timer for that story
+- [ ] Timers are persisted to .storkit/timers.json so they survive server restarts
+- [ ] A 30s tick loop (tokio task, same pattern as watchdog) checks for due timers and calls start_agent when triggered
+- [ ] When a timer fires, the story must already be in current — timer does not move stories between stages
+- [ ] Fired timers are removed after execution (one-shot, not recurring)
+- [ ] Multiple timers for the same time are supported and respect agent slot contention via auto-assign
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/422_story_unblock_command_to_reset_blocked_stories.md

@@ -0,0 +1,22 @@
+---
+name: "Unblock command to reset blocked stories"
+---
+
+# Story 422: Unblock command to reset blocked stories
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] Bot command `unblock <story_id>` clears blocked flag and resets retry_count to 0 on the story front matter
+- [ ] Replies with confirmation including story ID and name
+- [ ] Returns clear error if story is not found or not blocked
+- [ ] Works from all transports (Matrix, WhatsApp, Slack)
+- [ ] Exposed as an MCP tool so agents can unblock stories programmatically
+- [ ] Works as a slash command in the web UI
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/423_story_auto_schedule_timer_on_rate_limit_to_resume_after_reset.md

@@ -0,0 +1,22 @@
+---
+name: "Auto-schedule timer on rate limit to resume after reset"
+---
+
+# Story 423: Auto-schedule timer on rate limit to resume after reset
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] When a rate_limit_event with a hard block (not just allowed_warning) is received from the PTY stream, parse the reset time from rate_limit_info
+- [ ] Automatically create a timer (via TimerStore from story 421) for the blocked story at the parsed reset time
+- [ ] If a timer already exists for that story, update it to the later reset time rather than creating a duplicate
+- [ ] Log the auto-scheduled timer with story ID, agent name, and scheduled resume time
+- [ ] Notify chat transports that the story was rate-limited and will auto-resume at the scheduled time
+- [ ] When the timer fires and restarts the agent, the existing worktree and committed work are preserved
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/424_story_rate_limit_traffic_light_status_and_hard_block_alerts.md

@@ -0,0 +1,23 @@
+---
+name: "Rate limit traffic light status and hard block alerts"
+agent: coder-opus
+---
+
+# Story 424: Rate limit traffic light status and hard block alerts
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] Remove repetitive per-message throttle warnings (allowed_warning) from chat transports entirely
+- [ ] Pipeline status messages show a coloured dot next to each work item: green for running normally, yellow for throttled, red for hard blocked, white/grey for idle/no agent
+- [ ] Hard block events (429 / rate_limit_exceeded) still send an individual chat notification with a red icon, including the reset time
+- [ ] Throttle and block state tracked per-agent so the status dot updates in real time
+- [ ] Server-side logging of throttle warnings is preserved for debugging
+- [ ] Traffic light dots in status report should be small/compact, not large emoji
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/425_story_chat_notification_when_a_story_blocks_with_reason.md

@@ -0,0 +1,20 @@
+---
+name: "Chat notification when a story blocks with reason"
+---
+
+# Story 425: Chat notification when a story blocks with reason
+
+## User Story
+
+As a project owner monitoring agent progress via chat, I want to receive a notification when a story gets blocked, including the reason, so that I can decide whether to unblock it or investigate the failure.
+
+## Acceptance Criteria
+
+- [ ] When a story transitions to blocked state, send a chat notification to all configured transports
+- [ ] Notification includes the story ID, story name, and the reason for blocking (e.g. gate failure output, max retries exceeded, empty diff)
+- [ ] Notification uses a red or warning icon to distinguish from normal status messages
+- [ ] Works across Matrix, WhatsApp, and Slack transports
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/426_bug_mergemaster_pipeline_marks_story_done_without_verifying_code_landed_on_master.md

@@ -0,0 +1,77 @@
+---
+name: "Mergemaster pipeline marks story done without verifying code landed on master"
+retry_count: 1
+---
+
+# Bug 426: Mergemaster pipeline marks story done without verifying code landed on master
+
+## Description
+
+The mergemaster pipeline can mark a story as done even when the feature code never makes it to master. The cherry-pick step in merge.rs may fail or be skipped, but the pipeline still advances the story to done via the filesystem watcher. There is no post-merge verification that the code actually exists on master before marking done.
+
+## How to Reproduce
+
+Observed on stories 422 and 403. For 422: mergemaster created merge-queue branch, resolved 2 conflicts in chat/commands/mod.rs and http/mcp/mod.rs, passed quality gates, created merge-queue commit cb2ef6b (4 files, 333 insertions including unblock.rs). But the done commit on master (05db012) only moves the story file — zero code changes. There is no 'storkit: merge 422' commit on master at all. The feature branch (db3157f) still has the code but it was never cherry-picked onto master.
+
+## Manual Merge Notes
+
+When manually cherry-picking 422 onto master, two conflicts arose:
+
+1. `server/src/chat/commands/mod.rs` — both 421 (timer) and 422 (unblock) added entries to the same BotCommand registry. Resolution: keep both.
+2. `server/src/http/mcp/mod.rs` — 420 (loc_file) and 422 (unblock) both bumped the tool count assertion from 49→50. Resolution: keep loc_file assertion, bump count to 51.
+
+Additionally, the cherry-pick could not proceed at all because master was on the `merge-queue/424` branch with 3 unresolved files (notifications.rs, ws.rs, watcher.rs). A concurrent in-progress merge left the working tree dirty, which likely caused the original cherry-pick to fail silently. This suggests a race condition: the filesystem watcher commits (story file moves) can leave master in a state where the cherry-pick step in merge.rs fails.
+
+## Full Audit of Done Stories (2026-03-28)
+
+Audited all 9 stories in `5_done/` to check whether their code actually landed on master:
+
+| Story | Merge Commit | Code on Master |
+|-------|-------------|----------------|
+| 417 — Split matrix/bot.rs | `665c036` (9 files, +1973/-1926) | YES |
+| 418 — Split pool/auto_assign.rs | `d375c4b` (7 files, +1901/-1813) | YES |
+| 419 — Matrix bot network error | `1193b7a` (1 file, +121/-3) | YES |
+| 420 — loc file command | `d6f8239` (5 files, +112/-32) | YES |
+| 421 — Timer command | `cf5424f` (7 files, +836) | YES |
+| 422 — Unblock command | `6c6bc35` (4 files, +336) — manual cherry-pick | YES |
+| 423 — Auto-schedule timer on rate limit | `b44f3a3` + `8ab2e19` (6 files, +375/-8) — manual cherry-pick | YES |
+| **424 — Rate limit traffic light** | **None** | **NO — moved back to backlog for redo** |
+| 425 — Chat notification on story block | `98b5475` (5 files, +184/-15) | YES |
+| **427 — Text normalization for line breaks** | **None** | **NO — phantom done, code never landed** |
+
+**4 out of 10 stories (422, 423, 424, 427) had broken merges.** 422 and 423 were fixed via manual cherry-pick. 424 was moved back to backlog for a fresh run. 427 also hit the same bug — marked done without code on master.
+
+## Actual Result
+
+Story moved to done with no code on master. The merge-queue commit exists on a detached branch but was never applied to master. No merge commit appears in git log on master.
+
+## Expected Result
+
+Pipeline should verify that the cherry-pick produced a merge commit on master before advancing to done. If cherry-pick fails or is missing, the story should remain in merge stage with a merge_failure flag.
+
+## Suggested Fix
+
+The code path is: `merge.rs::run_squash_merge` → `pipeline/merge.rs::start_merge_agent_work` → `lifecycle.rs::move_story_to_archived`.
+
+`run_squash_merge` (merge.rs:354) cherry-picks the merge-queue commit onto `project_root` and checks `cp.status.success()`. If it returns `success: true`, `start_merge_agent_work` (pipeline/merge.rs:106) immediately calls `move_story_to_archived`, which moves the story file to `5_done/`. The watcher then commits "storkit: done".
+
+The gap: between the cherry-pick returning success and the story moving to done, nobody verifies the cherry-pick actually produced a code commit on master. Possible failure modes:
+
+1. `project_root` is not on master (e.g. checked out to a merge-queue branch from a concurrent merge)
+2. Cherry-pick exits 0 but produces an empty commit (no code diff)
+3. Cherry-pick succeeds on the wrong branch
+
+**Fix:** After the cherry-pick in `run_squash_merge` succeeds (line 384), before returning `success: true`:
+
+1. Verify `project_root` is on master: `git rev-parse --abbrev-ref HEAD` must equal the base branch
+2. Verify the HEAD commit on master contains the expected merge message (e.g. matches `storkit: merge <story_id>`) or has a non-empty diff
+3. If either check fails, abort the cherry-pick and return `success: false`
+
+This keeps the fix entirely within `run_squash_merge` — no changes needed to the pipeline advance or lifecycle code.
+
+## Acceptance Criteria
+
+- [ ] Pipeline must not move a story to done unless a merge commit containing the feature code exists on master
+- [ ] If cherry-pick fails or produces no code diff on master, the merge must be reported as failed
+- [ ] Add a post-merge verification step that checks git log on master for the expected merge commit before advancing to done
+- [ ] When verification fails, emit a merge_failure and leave the story in the merge stage for retry

.storkit/work/5_done/427_story_server_side_text_normalization_for_chat_message_line_breaks.md

@@ -0,0 +1,20 @@
+---
+name: "Server-side text normalization for chat message line breaks"
+---
+
+# Story 427: Server-side text normalization for chat message line breaks
+
+## User Story
+
+As a user reading bot messages in Matrix, I want single newlines between sentences to render correctly, so that messages don't show up with words joined together like "sentence one.Sentence two".
+
+## Acceptance Criteria
+
+- [ ] Add a text normalization step before markdown-to-HTML conversion in the Matrix transport that converts single newlines between non-empty prose lines into double newlines
+- [ ] Preserve intentional single-newline formatting in bullet lists, headings, table rows, and code fences
+- [ ] Apply the same normalization in WhatsApp and Slack transports
+- [ ] Unit tests covering prose paragraphs, bullet lists, code blocks, and mixed content
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/428_refactor_split_pool_pipeline_rs_into_submodules.md

@@ -0,0 +1,26 @@
+---
+name: "Split pool/pipeline.rs into submodules"
+---
+
+# Refactor 428: Split pool/pipeline.rs into submodules
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Refactor the monolithic server/src/agents/pool/pipeline.rs (1789 lines) into focused submodules.
+
+## Acceptance Criteria
+
+- [ ] advance.rs contains run_pipeline_advance, spawn_pipeline_advance, should_block_story and their unit tests
+- [ ] completion.rs contains run_server_owned_completion, report_completion and their unit tests
+- [ ] merge.rs contains start_merge_agent_work, run_merge_pipeline, get_merge_status, set_merge_failure_reported and their unit tests
+- [ ] mod.rs re-exports all public items and wires the submodules
+- [ ] Unit tests live in their respective module files
+- [ ] No public API changes — all existing imports continue to work
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/429_story_interactive_project_setup_wizard_for_new_storkit_projects.md

@@ -0,0 +1,27 @@
+---
+name: "Interactive project setup wizard for new storkit projects"
+agent: coder-opus
+---
+
+# Story 429: Interactive project setup wizard for new storkit projects
+
+## User Story
+
+As a developer adopting storkit on an existing project, I want a guided setup process that scaffolds the .storkit directory and has an agent generate project-specific configuration files, so that I can get up and running without manually writing specs and scripts.
+
+## Acceptance Criteria
+
+- [ ] storkit init scaffolds .storkit/ directory structure, project.toml, and .mcp.json without clobbering any existing files (especially CLAUDE.md)
+- [ ] Setup wizard tracks progress through ordered steps, resumable if interrupted
+- [ ] Step 1: scaffold .storkit/ directory structure and project.toml
+- [ ] Step 2: agent reads codebase and generates specs/00_CONTEXT.md, user confirms or requests revision
+- [ ] Step 3: agent reads tech stack and generates specs/tech/STACK.md, user confirms or requests revision
+- [ ] Step 4: agent creates script/test that runs the project's actual test suite, user runs it to verify, then confirms
+- [ ] Step 5: agent creates script/release tailored to the project's deployment, user confirms
+- [ ] Step 6: agent creates script/test_coverage if the stack supports it, user confirms
+- [ ] Each step gates on user confirmation before advancing to the next
+- [ ] Existing CLAUDE.md is preserved — storkit appends its content or leaves it untouched
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/130_bug_permission_approval_returns_wrong_format_tools_fail_after_user_approves.md

@@ -10,7 +10,7 @@ The `prompt_permission` MCP tool returns plain text ("Permission granted for '..
 
 ## How to Reproduce
 
-1. Start the story-kit server and open the web UI
+1. Start the storkit server and open the web UI
 2. Chat with the claude-code-pty model
 3. Ask it to do something that requires a tool NOT in `.claude/settings.json` allow list (e.g. `wc -l /etc/hosts`, or WebFetch to a non-allowed domain)
 4. The permission dialog appears — click Approve

.storkit/work/6_archived/139_story_retry_limit_for_mergemaster_and_pipeline_restarts.md

@@ -6,7 +6,7 @@ name: "Retry limit for mergemaster and pipeline restarts"
 
 ## User Story
 
-As a developer using story-kit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
+As a developer using storkit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
 
 ## Acceptance Criteria