docs

docs/current_roadmap.md

@@ -43,6 +43,10 @@ implementation state.
    - `wf_api` imports no `wf_mcp` modules. The current adapter,
      `WfMcpWorkflowApiBackend`, still wraps the existing MCP service stack while
      later slices extract protocol-neutral logic behind that seam.
+   - Protocol-neutral helpers now live in `wf_api`: refs/constants, wrapper
+     hints, next actions, raw workflow plans, runtime dependencies, saved
+     subgraph preparation, and durable run lifecycle helpers. Old
+     `wf_mcp.workflow_surface` helper paths remain compatibility shims.
 
 ## Runtime and Platform Roadmap
 
@@ -108,9 +112,9 @@ implementation state.
   inventory and deployment metadata instead of reverse-engineering MCP tools.
 - **Workflow API extraction**: continue the staged extraction in
   [wf_api extraction roadmap](./superpowers/plans/2026-06-01-wf-api-extraction-roadmap.md).
-  The next useful slice is naming/documentation cleanup around
-  `WorkflowSurfaceHandlers` versus `wf_api.WorkflowApi`, before moving helper
-  modules or splitting the large operation implementation.
+  The next useful slice is splitting the large `WorkflowSurfaceHandlers`
+  implementation by domain behind `wf_api`, while leaving MCP tool schemas and
+  tool registration in `wf_mcp`.
 
 Frame stress points remaining for native subgraphs and future fork/gather:
 

docs/superpowers/plans/2026-06-01-wf-api-extraction-roadmap.md

@@ -13,6 +13,12 @@ Both CLI and MCP workflow tools now call `WorkflowApi`; `wf_api` imports no
 operation implementation and still depends on `WfMcpService`, but it is now
 MCP-owned backend plumbing rather than the public application API.
 
+Slice 3 moved the protocol-neutral workflow helpers into `wf_api`: constants,
+capability refs, wrapper hints, next actions, raw workflow plan model, runtime
+dependency resolution, saved subgraph preparation, and durable run lifecycle
+helpers. The old `wf_mcp.workflow_surface.*` module paths remain compatibility
+shims for those helpers.
+
 **Current Constraint:** `WorkflowSurfaceHandlers` is large and still carries
 most workflow-surface logic. Slice 1 fixed dependency direction only; later
 slices can split and rename once the boundary is correct.
@@ -171,19 +177,23 @@ MCP tools and CLI commands are adapters over wf_api.
 
 Move helper modules that are not MCP-specific out of `wf_mcp.workflow_surface`.
 
-### Candidate Moves
+### Completed Moves
 
 ```text
-wf_mcp.workflow_surface.models                -> wf_api.models
-wf_mcp.workflow_surface.next_actions          -> wf_api.next_actions
-wf_mcp.workflow_surface.wrapper_hints         -> wf_api.wrapper_hints
+wf_mcp.workflow_surface.constants             -> wf_api.constants
 wf_mcp.workflow_surface.refs                  -> wf_api.refs
-wf_mcp.workflow_surface.run_lifecycle         -> wf_api.run_lifecycle
+wf_mcp.workflow_surface.wrapper_hints         -> wf_api.wrapper_hints
+wf_mcp.workflow_surface.next_actions          -> wf_api.next_actions
+wf_mcp.models.RawWorkflowPlan                 -> wf_api.models.RawWorkflowPlan
 wf_mcp.workflow_surface.runtime_dependencies  -> wf_api.runtime_dependencies
 wf_mcp.workflow_surface.saved_subgraphs       -> wf_api.saved_subgraphs
-wf_mcp.workflow_surface.constants             -> wf_api.constants
+wf_mcp.workflow_surface.run_lifecycle         -> wf_api.run_lifecycle
 ```
 
+The full `wf_mcp.workflow_surface.models` module did not move. It still holds
+MCP tool request/response schemas such as `TraceRange` and workflow tool result
+models. Move or split those only when the MCP schema boundary is clearer.
+
 ### If/Then
 
 - If a module imports MCP connection/adapters/auth, do not move it in this slice.
@@ -192,9 +202,11 @@ wf_mcp.workflow_surface.constants             -> wf_api.constants
 
 ### Success Criteria
 
-- `wf_api` owns workflow API helper models.
-- `wf_mcp.workflow_surface` keeps only MCP adapter/shim code.
-- Tests still pass with import-only or near-import-only changes.
+- `wf_api` owns protocol-neutral workflow API helpers. **Done.**
+- `wf_mcp.workflow_surface` keeps MCP adapter/schema code plus compatibility
+  shims. **Mostly done.**
+- Tests still pass with import-only or near-import-only changes. **Done at
+  implementation time.**
 
 ## Slice 4: Split The Big API By Domain
 

docs/wf_mcp_architecture.md

@@ -57,8 +57,19 @@ inside the MCP backend adapter or compatibility tests.
 
 This is a dependency-direction cleanup, not a full domain split. Most API
 methods still mirror the old workflow-surface payloads and return
-`dict[str, Any]`. Stronger domain models and helper-module moves belong in later
-`wf_api` extraction slices.
+`dict[str, Any]`.
+
+Protocol-neutral workflow helpers have moved to `wf_api`: constants, capability
+refs, wrapper hints, next actions, raw workflow plans, runtime dependency
+resolution, saved subgraph preparation, and durable run lifecycle helpers. The
+old `wf_mcp.workflow_surface.*` helper modules are compatibility shims. MCP
+tool schemas and registration still live in `wf_mcp.workflow_surface.models` and
+`wf_mcp.workflow_surface.tools`.
+
+The remaining extraction work is the large operation implementation:
+`WorkflowSurfaceHandlers` still owns most capability, draft, artifact,
+deployment, and run methods. Split that implementation by domain only after the
+current helper shims are stable.
 
 ## Broker Catalogs