# 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