feat(mcp): Phase 3 — gui_set_spec_status (the only write tool) (#55)

* feat(mcp): Phase 3 — gui_set_spec_status (the only write tool)

Wraps the existing PUT /api/cowork/specs/{feature}/{phase}/status
route as an MCP tool. Same validation (slug regex, phase enum,
_VALID_STATUSES), same atomic write via attune_gui._fs.atomic_write.

Behavior mirrors the FastAPI route:
  - if a `**Status**:` line already exists, substitute via _STATUS_RE
  - otherwise insert a fresh line near the top, after the title

This is the only write tool in the MCP surface — additive to the five
read-mostly tools from Phase 2. The spec called it out as "optional /
gated" and Patrick approved shipping it as part of the post-Phase-2
plan.

Tests (test_mcp_tools.py, +6):
  - happy path: status flip persists to disk + gui_get_spec_status
    reflects the new value
  - invalid status (not in _VALID_STATUSES)
  - invalid phase
  - invalid feature slug (path-traversal attempt)
  - unknown feature
  - missing phase file (e.g. setting tasks.md status on a spec that
    has only requirements/design)

Also updated test_mcp_server.py's tool-registry assertion to expect
six tools, renaming the test from _phase2_ to _full_.

Marks 3.1 done in tasks.md. CHANGELOG entry under Unreleased.

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

* docs(living-docs): regenerate sidecar templates for Phase 3 changes

Auto-regen triggered by the new gui_set_spec_status code in
sidecar/attune_gui/mcp/tools.py. source_hash drift only.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

.help/templates/sidecar/concept.md

@@ -1,8 +1,8 @@
 ---
 feature: sidecar
 depth: concept
-generated_at: 2026-05-23T15:00:21.678404+00:00
-source_hash: 8bd8cc535fccde713e960fad2b1ad134f8610ef75f44845a840dfbd2e438853e
+generated_at: 2026-05-23T15:23:17.077441+00:00
+source_hash: 82f32c163679d9108687682ce676ff1f4f1242f118d1e8295e480bcbcb749660
 status: generated
 ---
 

.help/templates/sidecar/reference.md

@@ -1,8 +1,8 @@
 ---
 feature: sidecar
 depth: reference
-generated_at: 2026-05-23T15:00:21.690599+00:00
-source_hash: 8bd8cc535fccde713e960fad2b1ad134f8610ef75f44845a840dfbd2e438853e
+generated_at: 2026-05-23T15:23:17.087987+00:00
+source_hash: 82f32c163679d9108687682ce676ff1f4f1242f118d1e8295e480bcbcb749660
 status: generated
 ---
 
@@ -128,6 +128,7 @@ status: generated
 | `gui_get_spec_status()` | — | `sidecar/attune_gui/mcp/tools.py` |
 | `gui_list_living_docs()` | — | `sidecar/attune_gui/mcp/tools.py` |
 | `gui_get_living_doc()` | — | `sidecar/attune_gui/mcp/tools.py` |
+| `gui_set_spec_status()` | — | `sidecar/attune_gui/mcp/tools.py` |
 | `get_dispatch()` | Tool-name → async handler. Imported by :mod:`.server`. | `sidecar/attune_gui/mcp/tools.py` |
 | `list_features()` | Return the feature names from ``<help_dir>/features.yaml``. | `sidecar/attune_gui/routes/choices.py` |
 | `read_file()` | Return raw file contents (UTF-8) plus the `manual` frontmatter flag for `.md` files. | `sidecar/attune_gui/routes/cowork_files.py` |
@@ -523,7 +524,7 @@ status: generated
 | `test_config_command_set_unknown_key_returns_2()` | — | `sidecar/tests/test_main.py` |
 | `test_config_command_unset_unknown_key_returns_2()` | — | `sidecar/tests/test_main.py` |
 | `test_config_command_unknown_action_returns_2()` | — | `sidecar/tests/test_main.py` |
-| `test_app_initializes_with_phase2_tool_registry()` | — | `sidecar/tests/test_mcp_server.py` |
+| `test_app_initializes_with_full_tool_registry()` | — | `sidecar/tests/test_mcp_server.py` |
 | `test_unknown_tool_returns_error_envelope()` | — | `sidecar/tests/test_mcp_server.py` |
 | `test_server_name_is_attune_gui()` | — | `sidecar/tests/test_mcp_server.py` |
 | `test_main_entry_point_is_callable()` | — | `sidecar/tests/test_mcp_server.py` |
@@ -538,6 +539,12 @@ status: generated
 | `test_get_spec_status_returns_most_advanced()` | — | `sidecar/tests/test_mcp_tools.py` |
 | `test_get_spec_status_explicit_phase()` | — | `sidecar/tests/test_mcp_tools.py` |
 | `test_get_spec_status_rejects_invalid_phase()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_persists_to_disk()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_rejects_invalid_status()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_rejects_invalid_phase()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_rejects_invalid_feature()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_unknown_feature()` | — | `sidecar/tests/test_mcp_tools.py` |
+| `test_set_spec_status_missing_phase_file()` | — | `sidecar/tests/test_mcp_tools.py` |
 | `test_list_living_docs_returns_docs()` | — | `sidecar/tests/test_mcp_tools.py` |
 | `test_get_living_doc_reads_file_content()` | — | `sidecar/tests/test_mcp_tools.py` |
 | `test_get_living_doc_rejects_malformed_id()` | — | `sidecar/tests/test_mcp_tools.py` |

.help/templates/sidecar/task.md

@@ -1,8 +1,8 @@
 ---
 feature: sidecar
 depth: task
-generated_at: 2026-05-23T15:00:21.685731+00:00
-source_hash: 8bd8cc535fccde713e960fad2b1ad134f8610ef75f44845a840dfbd2e438853e
+generated_at: 2026-05-23T15:23:17.083621+00:00
+source_hash: 82f32c163679d9108687682ce676ff1f4f1242f118d1e8295e480bcbcb749660
 status: generated
 ---
 

CHANGELOG.md

@@ -13,6 +13,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   and a cross-link to attune-ai's complementary `ops-specs-features`
   spec. Completes the [mcp-server-scope](docs/specs/mcp-server-scope/)
   spec's Phase 5.
+- **MCP server — Phase 3 write tool.** New `gui_set_spec_status`
+  tool wraps the existing
+  `PUT /api/cowork/specs/{feature}/{phase}/status` route as MCP.
+  Same validation (slug regex, phase enum, `_VALID_STATUSES`),
+  same atomic write via `attune_gui._fs.atomic_write`. The only
+  write tool in the MCP surface — additive to the five read-mostly
+  tools from Phase 2. Six new tests in `test_mcp_tools.py` cover
+  the happy path (persistence + readback parity with
+  `gui_get_spec_status`) plus invalid status, invalid phase,
+  invalid feature slug, unknown feature, and missing phase file.
+  Closes Phase 3 of
+  [mcp-server-scope](docs/specs/mcp-server-scope/).
 - **MCP server — Phase 2 tools.** Five read-mostly tools wired
   on top of the Phase 1 scaffold, each returning a
   JSON-serializable envelope with `{"success": bool, ...}`:

docs/specs/mcp-server-scope/tasks.md

@@ -37,10 +37,12 @@ Each tool:
 
 ## Phase 3 — Optional write tool
 
-- [ ] **3.1** `gui_set_spec_status` — wrap the existing
-      PUT route. Same body shape:
-      `{"status": "<valid-value>"}`. Same validation. Honor
-      any read-only flag on the server.
+- [x] **3.1** `gui_set_spec_status` — wrap the existing
+      PUT route. Same validation (slug regex, phase enum,
+      `_VALID_STATUSES`). Atomic write via `attune_gui._fs.atomic_write`.
+      Inserts a `**Status**:` line if missing, otherwise substitutes
+      via `_STATUS_RE`. The only write tool — additive to the
+      five read-mostly tools.
 
 ## Phase 4 — Integration test
 

sidecar/attune_gui/mcp/tools.py

@@ -142,6 +142,39 @@
             "additionalProperties": False,
         },
     },
+    "gui_set_spec_status": {
+        "description": (
+            "Rewrite the `**Status**:` line in a spec's phase file. The only "
+            "write tool — use sparingly. Mirrors the validation of the existing "
+            "PUT /api/cowork/specs/{feature}/{phase}/status route."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "feature": {"type": "string"},
+                "phase": {
+                    "type": "string",
+                    "enum": list(_PHASE_NAMES),
+                },
+                "status": {
+                    "type": "string",
+                    "description": (
+                        "One of: draft, in-review, approved, complete, " "completed, done."
+                    ),
+                },
+                "root": {
+                    "type": "string",
+                    "description": (
+                        "Optional absolute path of the specs root to "
+                        "disambiguate when the same slug exists in multiple "
+                        "roots. If omitted, the first match wins."
+                    ),
+                },
+            },
+            "required": ["feature", "phase", "status"],
+            "additionalProperties": False,
+        },
+    },
 }
 
 
@@ -355,6 +388,68 @@ async def gui_get_living_doc(args: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+async def gui_set_spec_status(args: dict[str, Any]) -> dict[str, Any]:
+    # Lazy imports keep the writes-only deps (atomic_write, _VALID_STATUSES, the
+    # status regexes) out of module-import time. Matches the gui_get_living_doc
+    # workspace pattern above.
+    from attune_gui._fs import atomic_write  # noqa: PLC0415
+    from attune_gui.routes.cowork_specs import (  # noqa: PLC0415
+        _STATUS_RE,
+        _STATUS_VALUE_RE,
+        _VALID_STATUSES,
+    )
+
+    feature = args.get("feature", "")
+    if (msg := _validate_slug(feature)) is not None:
+        return _err(msg)
+    phase = args.get("phase", "")
+    if phase not in _PHASE_FILE_BY_NAME:
+        return _err(f"Invalid phase: {phase!r} (valid: {', '.join(_PHASE_NAMES)})")
+    status = args.get("status", "")
+    if not isinstance(status, str) or status not in _VALID_STATUSES:
+        return _err(f"Invalid status: {status!r} (valid: {', '.join(_VALID_STATUSES)})")
+    root = args.get("root")
+
+    found = _resolve_feature_dir(feature, root)
+    if isinstance(found, dict):
+        return found
+    feat_dir, project = found
+
+    target = feat_dir / _PHASE_FILE_BY_NAME[phase]
+    if not target.is_file():
+        return _err(f"Phase file does not exist: {target.name}")
+
+    try:
+        original = target.read_text(encoding="utf-8")
+    except OSError as exc:
+        return _err(f"Read failed: {exc}")
+
+    # Mirrors the PUT route's logic: substitute if a Status line exists,
+    # insert near the top otherwise.
+    if not _STATUS_VALUE_RE.search(original):
+        lines = original.splitlines()
+        insert_at = 1 if lines and lines[0].startswith("# ") else 0
+        lines.insert(insert_at, f"\n**Status**: {status}\n")
+        new_text = "\n".join(lines) + ("\n" if not original.endswith("\n") else "")
+    else:
+        new_text = _STATUS_RE.sub(f"**Status**: {status}", original, count=1)
+
+    try:
+        atomic_write(target, new_text)
+    except OSError as exc:
+        return _err(f"Write failed: {exc}")
+
+    return {
+        "success": True,
+        "feature": feature,
+        "project": project,
+        "phase": phase,
+        "file": target.name,
+        "status": status,
+        "path": str(target),
+    }
+
+
 # ---------------------------------------------------------------------------
 # Public dispatch table
 # ---------------------------------------------------------------------------
@@ -368,4 +463,5 @@ def get_dispatch() -> dict[str, Any]:
         "gui_get_spec_status": gui_get_spec_status,
         "gui_list_living_docs": gui_list_living_docs,
         "gui_get_living_doc": gui_get_living_doc,
+        "gui_set_spec_status": gui_set_spec_status,
     }

sidecar/tests/test_mcp_server.py

@@ -9,7 +9,7 @@
 import pytest
 
 
-def test_app_initializes_with_phase2_tool_registry() -> None:
+def test_app_initializes_with_full_tool_registry() -> None:
     from attune_gui.mcp.server import create_server
 
     app = create_server()
@@ -19,6 +19,7 @@ def test_app_initializes_with_phase2_tool_registry() -> None:
         "gui_get_spec_status",
         "gui_list_living_docs",
         "gui_get_living_doc",
+        "gui_set_spec_status",
     }
 
 

sidecar/tests/test_mcp_tools.py

@@ -143,6 +143,83 @@ async def test_get_spec_status_rejects_invalid_phase(app, specs_root) -> None:
     assert "Invalid phase" in result["error"]
 
 
+# ---------------------------------------------------------------------------
+# gui_set_spec_status (the only write tool)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_persists_to_disk(app, specs_root) -> None:
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "alpha", "phase": "requirements", "status": "complete"},
+    )
+    assert result["success"] is True
+    assert result["status"] == "complete"
+    # Verify the file actually changed.
+    content = (specs_root / "alpha" / "requirements.md").read_text(encoding="utf-8")
+    assert "**Status**: complete" in content
+    # And that gui_get_spec_status now reports the new value.
+    follow = await app.call_tool(
+        "gui_get_spec_status", {"feature": "alpha", "phase": "requirements"}
+    )
+    assert follow["status"] == "complete"
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_rejects_invalid_status(app, specs_root) -> None:
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "alpha", "phase": "requirements", "status": "shipped-it"},
+    )
+    assert result["success"] is False
+    assert "Invalid status" in result["error"]
+    # File must not have been touched.
+    content = (specs_root / "alpha" / "requirements.md").read_text(encoding="utf-8")
+    assert "**Status**: approved" in content
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_rejects_invalid_phase(app, specs_root) -> None:
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "alpha", "phase": "summary", "status": "complete"},
+    )
+    assert result["success"] is False
+    assert "Invalid phase" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_rejects_invalid_feature(app, specs_root) -> None:
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "../etc", "phase": "requirements", "status": "approved"},
+    )
+    assert result["success"] is False
+    assert "Invalid feature" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_unknown_feature(app, specs_root) -> None:
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "ghost", "phase": "requirements", "status": "approved"},
+    )
+    assert result["success"] is False
+    assert "'ghost' not found" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_set_spec_status_missing_phase_file(app, specs_root) -> None:
+    # design.md is present on alpha (from the fixture); tasks.md is not.
+    result = await app.call_tool(
+        "gui_set_spec_status",
+        {"feature": "alpha", "phase": "tasks", "status": "complete"},
+    )
+    assert result["success"] is False
+    assert "Phase file does not exist" in result["error"]
+
+
 # ---------------------------------------------------------------------------
 # gui_list_living_docs / gui_get_living_doc
 # ---------------------------------------------------------------------------