PMFlow/docs/superpowers/plans/2026-04-05-mounted-planmode-context-upgrade.md

Mounted Plan Mode Context Upgrade Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Upgrade PMFlow's mounted runtime so requirement planning uses explicit topic and plan-state transitions instead of sender-level implicit continuation.

Architecture: Keep MountedTopicWorkspace as the topic container and extend mounted runtime with explicit plan session semantics. Route classification remains in the semantic planner, but topic reuse, topic switching, and plan progression move into deterministic runtime state transitions.

Tech Stack: FastAPI, SQLAlchemy 2.0, Alembic, pytest

---

Task 1: Lock The Runtime Contract

Files:

• Modify: backend/app/models/mounted_ai_runtime.py

• Modify: backend/app/services/mounted_ai_runtime_write_service.py

• Create: backend/alembic/versions/20260405_add_plan_state_to_mounted_runtime.py

• Test: backend/tests/test_mounted_ai_runtime_write_service.py

• Step 1: Write the failing tests

Add tests that prove:

• mounted topics can store explicit plan_status

• draft_ready and awaiting_execute_confirm state transitions are persisted

• switching to a new topic from the same chat/sender does not silently reuse the previous plan topic

• Step 2: Run tests to verify they fail

Run: pytest backend/tests/test_mounted_ai_runtime_write_service.py -q Expected: FAIL because the new runtime contract is not implemented yet.

• Step 3: Implement the minimal runtime changes

Add mounted runtime fields for explicit plan state and topic lifecycle, plus helper methods to update them deterministically.

• Step 4: Run tests to verify they pass

Run: pytest backend/tests/test_mounted_ai_runtime_write_service.py -q Expected: PASS

Task 2: Make Topic Switching Deterministic

Files:

• Modify: backend/app/services/ai_pmo/workflow_semantic_planner/service.py

• Modify: backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py

• Modify: backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_entry.py

• Test: backend/tests/test_workflow_semantic_planner.py

• Test: backend/tests/test_ai_pmo_ingress_mainline.py

• Step 1: Write the failing tests

Add tests that prove:

• messages like “这是另一个需求 / 换个需求 / 不是这个需求” are classified as explicit new-topic signals

• requirement plan continuation only reuses the current topic when the message is a real continuation

• active plan workspaces no longer force reuse when the user explicitly starts a new demand in the same chat

• Step 2: Run tests to verify they fail

Run: pytest backend/tests/test_workflow_semantic_planner.py backend/tests/test_ai_pmo_ingress_mainline.py -q Expected: FAIL because explicit topic switching is not supported yet.

• Step 3: Implement the minimal planner and routing changes

Add explicit new-topic detection and use it to bypass old workspace reuse. Keep existing draft-confirm flows intact.

• Step 4: Run tests to verify they pass

Run: pytest backend/tests/test_workflow_semantic_planner.py backend/tests/test_ai_pmo_ingress_mainline.py -q Expected: PASS

Task 3: Align Requirement Planning With Explicit Plan States

Files:

• Modify: backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py

• Test: backend/tests/test_ai_pmo_ingress_mainline.py

• Step 1: Write the failing tests

Add tests for:

• collecting -> options_ready -> draft_ready transitions

• draft emission marks the topic as awaiting execution confirmation

• suspend/new-topic actions leave the old topic resumable instead of overwriting it

• Step 2: Run tests to verify they fail

Run: pytest backend/tests/test_ai_pmo_ingress_mainline.py -q Expected: FAIL until plan-state transitions are explicit.

• Step 3: Implement the minimal state machine changes

Update requirement planning flow to persist explicit plan state and pending actions on the mounted topic and draft workspace.

• Step 4: Run tests to verify they pass

Run: pytest backend/tests/test_ai_pmo_ingress_mainline.py -q Expected: PASS

Task 4: Sync Docs And Verify

Files:

• Modify: CLAUDE.md

• Step 1: Update docs

Record the new mounted runtime plan-state behavior, migration file, and any changed structural references.

• Step 2: Run focused backend verification

Run: pytest backend/tests/test_mounted_ai_runtime_write_service.py backend/tests/test_workflow_semantic_planner.py backend/tests/test_ai_pmo_ingress_mainline.py -q Expected: PASS

• Step 3: Run Python compile verification

Run: python -m py_compile backend/app/models/mounted_ai_runtime.py backend/app/services/mounted_ai_runtime_write_service.py backend/app/services/ai_pmo/workflow_semantic_planner/service.py backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_entry.py Expected: exit 0