Story 49: Deterministic Bug Lifecycle Management

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/http/mcp.rs

@@ -3,9 +3,10 @@ use crate::config::ProjectConfig;
 use crate::http::context::AppContext;
 use crate::http::settings::get_editor_command_from_store;
 use crate::http::workflow::{
-    check_criterion_in_file, create_story_file, load_upcoming_stories, set_test_plan_in_file,
-    validate_story_dirs,
+    check_criterion_in_file, create_bug_file, create_story_file, list_bug_files,
+    load_upcoming_stories, set_test_plan_in_file, validate_story_dirs,
 };
+use crate::agents::close_bug_to_archive;
 use crate::worktree;
 use crate::io::story_metadata::{parse_front_matter, parse_unchecked_todos};
 use crate::workflow::{evaluate_acceptance_with_coverage, TestCaseResult, TestStatus};
@@ -653,6 +654,63 @@ fn handle_tools_list(id: Option<Value>) -> JsonRpcResponse {
                         },
                         "required": ["story_id", "status"]
                     }
+                },
+                {
+                    "name": "create_bug",
+                    "description": "Create a bug file in .story_kit/bugs/ with a deterministic filename and auto-commit to master. Returns the bug_id.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "description": "Short human-readable bug name"
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Description of the bug"
+                            },
+                            "steps_to_reproduce": {
+                                "type": "string",
+                                "description": "Steps to reproduce the bug"
+                            },
+                            "actual_result": {
+                                "type": "string",
+                                "description": "What actually happens"
+                            },
+                            "expected_result": {
+                                "type": "string",
+                                "description": "What should happen"
+                            },
+                            "acceptance_criteria": {
+                                "type": "array",
+                                "items": { "type": "string" },
+                                "description": "Optional list of acceptance criteria for the fix"
+                            }
+                        },
+                        "required": ["name", "description", "steps_to_reproduce", "actual_result", "expected_result"]
+                    }
+                },
+                {
+                    "name": "list_bugs",
+                    "description": "List all open bugs (files in .story_kit/bugs/ excluding archive/).",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {}
+                    }
+                },
+                {
+                    "name": "close_bug",
+                    "description": "Move a bug from .story_kit/bugs/ (or current/) to .story_kit/bugs/archive/ and auto-commit to master.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "bug_id": {
+                                "type": "string",
+                                "description": "Bug identifier (e.g. 'bug-3-login_crash')"
+                            }
+                        },
+                        "required": ["bug_id"]
+                    }
                 }
             ]
         }),
@@ -701,6 +759,10 @@ async fn handle_tools_call(
         // Story mutation tools (auto-commit to master)
         "check_criterion" => tool_check_criterion(&args, ctx),
         "set_test_plan" => tool_set_test_plan(&args, ctx),
+        // Bug lifecycle tools
+        "create_bug" => tool_create_bug(&args, ctx),
+        "list_bugs" => tool_list_bugs(ctx),
+        "close_bug" => tool_close_bug(&args, ctx),
         _ => Err(format!("Unknown tool: {tool_name}")),
     };
 
@@ -1148,6 +1210,71 @@ fn tool_set_test_plan(args: &Value, ctx: &AppContext) -> Result<String, String>
     ))
 }
 
+// ── Bug lifecycle tool implementations ───────────────────────────
+
+fn tool_create_bug(args: &Value, ctx: &AppContext) -> Result<String, String> {
+    let name = args
+        .get("name")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: name")?;
+    let description = args
+        .get("description")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: description")?;
+    let steps_to_reproduce = args
+        .get("steps_to_reproduce")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: steps_to_reproduce")?;
+    let actual_result = args
+        .get("actual_result")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: actual_result")?;
+    let expected_result = args
+        .get("expected_result")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: expected_result")?;
+    let acceptance_criteria: Option<Vec<String>> = args
+        .get("acceptance_criteria")
+        .and_then(|v| serde_json::from_value(v.clone()).ok());
+
+    let root = ctx.state.get_project_root()?;
+    let bug_id = create_bug_file(
+        &root,
+        name,
+        description,
+        steps_to_reproduce,
+        actual_result,
+        expected_result,
+        acceptance_criteria.as_deref(),
+    )?;
+
+    Ok(format!("Created bug: {bug_id}"))
+}
+
+fn tool_list_bugs(ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let bugs = list_bug_files(&root)?;
+    serde_json::to_string_pretty(&json!(bugs
+        .iter()
+        .map(|(id, name)| json!({ "bug_id": id, "name": name }))
+        .collect::<Vec<_>>()))
+    .map_err(|e| format!("Serialization error: {e}"))
+}
+
+fn tool_close_bug(args: &Value, ctx: &AppContext) -> Result<String, String> {
+    let bug_id = args
+        .get("bug_id")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: bug_id")?;
+
+    let root = ctx.agents.get_project_root(&ctx.state)?;
+    close_bug_to_archive(&root, bug_id)?;
+
+    Ok(format!(
+        "Bug '{bug_id}' closed, moved to bugs/archive/, and committed to master."
+    ))
+}
+
 /// Run `git log <base>..HEAD --oneline` in the worktree and return the commit
 /// summaries, or `None` if git is unavailable or there are no new commits.
 async fn get_worktree_commits(worktree_path: &str, base_branch: &str) -> Option<Vec<String>> {
@@ -1302,7 +1429,10 @@ mod tests {
         assert!(names.contains(&"accept_story"));
         assert!(names.contains(&"check_criterion"));
         assert!(names.contains(&"set_test_plan"));
-        assert_eq!(tools.len(), 21);
+        assert!(names.contains(&"create_bug"));
+        assert!(names.contains(&"list_bugs"));
+        assert!(names.contains(&"close_bug"));
+        assert_eq!(tools.len(), 24);
     }
 
     #[test]
@@ -1699,4 +1829,196 @@ mod tests {
         let req_names: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();
         assert!(req_names.contains(&"worktree_path"));
     }
+
+    // ── Bug lifecycle tool tests ──────────────────────────────────
+
+    fn setup_git_repo_in(dir: &std::path::Path) {
+        std::process::Command::new("git")
+            .args(["init"])
+            .current_dir(dir)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.email", "test@test.com"])
+            .current_dir(dir)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.name", "Test"])
+            .current_dir(dir)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["commit", "--allow-empty", "-m", "init"])
+            .current_dir(dir)
+            .output()
+            .unwrap();
+    }
+
+    #[test]
+    fn create_bug_in_tools_list() {
+        let resp = handle_tools_list(Some(json!(1)));
+        let tools = resp.result.unwrap()["tools"].as_array().unwrap().clone();
+        let tool = tools.iter().find(|t| t["name"] == "create_bug");
+        assert!(tool.is_some(), "create_bug missing from tools list");
+        let t = tool.unwrap();
+        assert!(t["description"].is_string());
+        let required = t["inputSchema"]["required"].as_array().unwrap();
+        let req_names: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();
+        assert!(req_names.contains(&"name"));
+        assert!(req_names.contains(&"description"));
+        assert!(req_names.contains(&"steps_to_reproduce"));
+        assert!(req_names.contains(&"actual_result"));
+        assert!(req_names.contains(&"expected_result"));
+    }
+
+    #[test]
+    fn list_bugs_in_tools_list() {
+        let resp = handle_tools_list(Some(json!(1)));
+        let tools = resp.result.unwrap()["tools"].as_array().unwrap().clone();
+        let tool = tools.iter().find(|t| t["name"] == "list_bugs");
+        assert!(tool.is_some(), "list_bugs missing from tools list");
+    }
+
+    #[test]
+    fn close_bug_in_tools_list() {
+        let resp = handle_tools_list(Some(json!(1)));
+        let tools = resp.result.unwrap()["tools"].as_array().unwrap().clone();
+        let tool = tools.iter().find(|t| t["name"] == "close_bug");
+        assert!(tool.is_some(), "close_bug missing from tools list");
+        let t = tool.unwrap();
+        let required = t["inputSchema"]["required"].as_array().unwrap();
+        let req_names: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();
+        assert!(req_names.contains(&"bug_id"));
+    }
+
+    #[test]
+    fn tool_create_bug_missing_name() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let result = tool_create_bug(
+            &json!({
+                "description": "d",
+                "steps_to_reproduce": "s",
+                "actual_result": "a",
+                "expected_result": "e"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("name"));
+    }
+
+    #[test]
+    fn tool_create_bug_missing_description() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let result = tool_create_bug(
+            &json!({
+                "name": "Bug",
+                "steps_to_reproduce": "s",
+                "actual_result": "a",
+                "expected_result": "e"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("description"));
+    }
+
+    #[test]
+    fn tool_create_bug_creates_file_and_commits() {
+        let tmp = tempfile::tempdir().unwrap();
+        setup_git_repo_in(tmp.path());
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_create_bug(
+            &json!({
+                "name": "Login Crash",
+                "description": "The app crashes on login.",
+                "steps_to_reproduce": "1. Open app\n2. Click login",
+                "actual_result": "500 error",
+                "expected_result": "Successful login"
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        assert!(result.contains("bug-1-login_crash"));
+        let bug_file = tmp
+            .path()
+            .join(".story_kit/bugs/bug-1-login_crash.md");
+        assert!(bug_file.exists());
+    }
+
+    #[test]
+    fn tool_list_bugs_empty() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let result = tool_list_bugs(&ctx).unwrap();
+        let parsed: Vec<Value> = serde_json::from_str(&result).unwrap();
+        assert!(parsed.is_empty());
+    }
+
+    #[test]
+    fn tool_list_bugs_returns_open_bugs() {
+        let tmp = tempfile::tempdir().unwrap();
+        let bugs_dir = tmp.path().join(".story_kit/bugs");
+        std::fs::create_dir_all(&bugs_dir).unwrap();
+        std::fs::write(
+            bugs_dir.join("bug-1-crash.md"),
+            "# Bug 1: App Crash\n",
+        )
+        .unwrap();
+        std::fs::write(
+            bugs_dir.join("bug-2-typo.md"),
+            "# Bug 2: Typo in Header\n",
+        )
+        .unwrap();
+
+        let ctx = test_ctx(tmp.path());
+        let result = tool_list_bugs(&ctx).unwrap();
+        let parsed: Vec<Value> = serde_json::from_str(&result).unwrap();
+        assert_eq!(parsed.len(), 2);
+        assert_eq!(parsed[0]["bug_id"], "bug-1-crash");
+        assert_eq!(parsed[0]["name"], "App Crash");
+        assert_eq!(parsed[1]["bug_id"], "bug-2-typo");
+        assert_eq!(parsed[1]["name"], "Typo in Header");
+    }
+
+    #[test]
+    fn tool_close_bug_missing_bug_id() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let result = tool_close_bug(&json!({}), &ctx);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("bug_id"));
+    }
+
+    #[test]
+    fn tool_close_bug_moves_to_archive() {
+        let tmp = tempfile::tempdir().unwrap();
+        setup_git_repo_in(tmp.path());
+        let bugs_dir = tmp.path().join(".story_kit/bugs");
+        std::fs::create_dir_all(&bugs_dir).unwrap();
+        let bug_file = bugs_dir.join("bug-1-crash.md");
+        std::fs::write(&bug_file, "# Bug 1: Crash\n").unwrap();
+        // Stage the file so it's tracked
+        std::process::Command::new("git")
+            .args(["add", "."])
+            .current_dir(tmp.path())
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["commit", "-m", "add bug"])
+            .current_dir(tmp.path())
+            .output()
+            .unwrap();
+
+        let ctx = test_ctx(tmp.path());
+        let result = tool_close_bug(&json!({"bug_id": "bug-1-crash"}), &ctx).unwrap();
+        assert!(result.contains("bug-1-crash"));
+        assert!(!bug_file.exists());
+        assert!(bugs_dir.join("archive/bug-1-crash.md").exists());
+    }
 }