fix: address review findings

- Add project_root to ActiveStepInfo in doc/mcp_interface.md
- Add mypy-required None checks in test_server.py
- Remove invalid kwargs from StartWorkflowResponse in test
- Update traceability comment to reference JOBS-REQ-001.3.10

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

Author: nhorton

doc/mcp_interface.md

@@ -289,6 +289,7 @@ interface StepInputInfo {
 interface ActiveStepInfo {
   session_id: string;              // Session ID — use this for all subsequent finished_step, abort_workflow, go_to_step calls
   step_id: string;                 // ID of the current step
+  project_root: string;            // Absolute path to the MCP server's project root (use for .deepwork/ operations)
   job_dir: string;                 // Absolute path to job directory (templates, scripts, etc.)
   step_expected_outputs: ExpectedOutput[]; // Expected outputs with type and format hints
   step_inputs: StepInputInfo[];    // Inputs provided to this step with their values
@@ -445,6 +446,7 @@ Add to your `.mcp.json`:
 
 | Version | Changes |
 |---------|---------|
+| 2.3.0 | Added `project_root` field to `ActiveStepInfo` — the absolute path to the MCP server's project root. Agents use this as the base directory for `.deepwork/` operations (e.g. creating jobs at `[project_root]/.deepwork/jobs/`). The `make_new_job.sh` script now requires `--project-root` instead of inferring the root from `git rev-parse`. |
 | 2.2.0 | `session_id` is now optional (`str | None`) on `start_workflow` only. On Claude Code (platform `"claude"`), the server raises `ToolError` if omitted. On other platforms, omitting it auto-generates a stable UUID; callers use the returned `begin_step.session_id` for all subsequent calls. `finished_step`, `abort_workflow`, and `go_to_step` continue to require `session_id`. Added `inputs` optional parameter to `start_workflow` for passing step argument values directly at workflow start. Added `issue_detected` optional field to all tool responses — present when the server detects configuration issues at startup; instructs agent to suggest repair to the user. |
 | 2.1.0 | Added `important_note` field to `StartWorkflowResponse` — instructs agents to clarify ambiguous user requests via `AskUserQuestion` when available. |
 | 2.0.0 | **Breaking**: `session_id` is now a required `string` parameter on all mutation tools (`start_workflow`, `finished_step`, `abort_workflow`, `go_to_step`). Added `agent_id` optional parameter for sub-agent scoping — sub-agents get their own isolated workflow stacks. State persistence path changed to `.deepwork/tmp/sessions/<platform>/session-<id>/state.json` (with sub-agent state in `agent_<agent_id>.json`). |

tests/unit/jobs/mcp/test_server.py

@@ -122,13 +122,15 @@ def test_issue_warning_in_instructions(self, tmp_path: Path) -> None:
         with patch("deepwork.jobs.mcp.server.detect_issues", return_value=[issue]):
             mcp = create_server(project_root=tmp_path)
 
+        assert mcp.instructions is not None
         assert "ISSUE DETECTED" in mcp.instructions
 
     def test_no_issue_warning_when_no_issues(self, tmp_path: Path) -> None:
         """When no issues exist, instructions don't contain issue warning."""
         with patch("deepwork.jobs.mcp.server.detect_issues", return_value=[]):
             mcp = create_server(project_root=tmp_path)
 
+        assert mcp.instructions is not None
         assert "ISSUE DETECTED" not in mcp.instructions
 
 
@@ -300,8 +302,6 @@ async def test_start_workflow_with_inputs_and_agent_id(self, tmp_path: Path) ->
         mcp, mock_tools = _make_server_with_mocked_tools(tmp_path)
         mock_tools.start_workflow = AsyncMock(
             return_value=StartWorkflowResponse(
-                job_name="j",
-                workflow_name="w",
                 begin_step=ActiveStepInfo(
                     session_id="s",
                     step_id="s1",
@@ -516,6 +516,7 @@ async def test_get_review_instructions_success(self, tmp_path: Path) -> None:
             mcp = create_server(project_root=tmp_path)
             result = await mcp.call_tool("get_review_instructions", {"files": ["src/foo.py"]})
 
+        assert result.structured_content is not None
         data = result.structured_content["result"]
         assert data == "Review task list"
 
@@ -537,6 +538,7 @@ async def test_get_review_instructions_error(self, tmp_path: Path) -> None:
             mcp = create_server(project_root=tmp_path)
             result = await mcp.call_tool("get_review_instructions", {})
 
+        assert result.structured_content is not None
         data = result.structured_content["result"]
         assert "Review error" in data
         assert "git not found" in data
@@ -560,6 +562,7 @@ async def test_get_configured_reviews(self, tmp_path: Path) -> None:
                 {"only_rules_matching_files": ["test.py"]},
             )
 
+        assert result.structured_content is not None
         data = result.structured_content["result"]
         assert len(data) == 1
         assert data[0]["name"] == "rule1"
@@ -580,6 +583,7 @@ async def test_mark_review_as_passed_success(self, tmp_path: Path) -> None:
             mcp = create_server(project_root=tmp_path)
             result = await mcp.call_tool("mark_review_as_passed", {"review_id": "abc123"})
 
+        assert result.structured_content is not None
         data = result.structured_content["result"]
         assert "abc123" in data
 
@@ -599,6 +603,7 @@ async def test_mark_review_as_passed_validation_error(self, tmp_path: Path) -> N
             mcp = create_server(project_root=tmp_path)
             result = await mcp.call_tool("mark_review_as_passed", {"review_id": "bad"})
 
+        assert result.structured_content is not None
         data = result.structured_content["result"]
         assert "Validation error" in data
         assert "Invalid review_id" in data

tests/unit/jobs/mcp/test_tools.py

@@ -211,7 +211,7 @@ class TestStartWorkflow:
     """Tests for start_workflow tool."""
 
     @pytest.mark.asyncio
-    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-001.3.8).
+    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-001.3.8, JOBS-REQ-001.3.10).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     async def test_creates_session_and_returns_first_step(self, tools: WorkflowTools) -> None:
         resp = await _start_main_workflow(tools)