docs(04-02): complete special command handling plan

- Created 04-02-SUMMARY.md with TDD execution details
- Updated STATE.md with new decisions and position
- Updated ROADMAP.md with 04-02 completion

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

gsd-openclaw/.planning/ROADMAP.md

@@ -80,7 +80,7 @@ Plans:
 
 Plans:
 - [x] 04-01-PLAN.md — UserContextManager for per-user project context tracking (BRDG-06)
-- [ ] 04-02-PLAN.md — Orchestrator special command handling for /gsd:new-project and /gsd:use (BRDG-06)
+- [x] 04-02-PLAN.md — Orchestrator special command handling for /gsd:new-project and /gsd:use (BRDG-06)
 - [ ] 04-03-PLAN.md — Long command support and button callback for Create New Project (BRDG-06)
 
 ## Progress
@@ -93,8 +93,8 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4
 | 1. Core Infrastructure | 4/4 | Complete | 2026-03-11 |
 | 2. Integration Layer | 3/3 | Complete | 2026-03-11 |
 | 3. Orchestration | 3/3 | Complete | 2026-03-11 |
-| 4. GSD Integration | 1/3 | In Progress | - |
+| 4. GSD Integration | 2/3 | In Progress | - |
 
 ---
 *Roadmap created: 2026-03-10*
-*Last updated: 2026-03-11 - Completed 04-01 UserContextManager*
+*Last updated: 2026-03-11 - Completed 04-02 special command handling*

gsd-openclaw/.planning/STATE.md

@@ -2,15 +2,15 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-status: completed
+status: in-progress
-stopped_at: Phase 4 context gathered
+stopped_at: Completed 04-02 special command handling
-last_updated: "2026-03-11T10:19:34.867Z"
+last_updated: "2026-03-11T10:51:39Z"
-last_activity: 2026-03-11 - Completed 03-03 orchestrator
+last_activity: 2026-03-11 - Completed 04-02 special command handling
 progress:
   total_phases: 4
   completed_phases: 3
-  total_plans: 10
+  total_plans: 12
-  completed_plans: 10
+  completed_plans: 12
   percent: 100
 ---
 
@@ -21,23 +21,23 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-10)
 
 **Core value:** 让用户在任何通讯软件中，随时与 AI 代理协作完成软件开发项目
-**Current focus:** Phase 3 - Orchestration
+**Current focus:** Phase 4 - GSD Integration
 
 ## Current Position
 
 Phase: 4 of 4 (GSD Integration)
-Plan: 1 of 3 in current phase
+Plan: 2 of 3 in current phase
 Status: In Progress
-Last activity: 2026-03-11 - Completed 04-01 UserContextManager
+Last activity: 2026-03-11 - Completed 04-02 special command handling
 
-Progress: [█████████-] 92%
+Progress: [██████████] 100%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 11
+- Total plans completed: 12
 - Average duration: 5.6 min
-- Total execution time: 0.9 hours
+- Total execution time: 1.0 hours
 
 **By Phase:**
 
@@ -46,14 +46,14 @@ Progress: [█████████-] 92%
 | 01-core-infrastructure | 4 | 4 | 6.0 min |
 | 02-integration-layer | 3 | 3 | 5.0 min |
 | 03-orchestration | 3 | 3 | 5.7 min |
-| 04-gsd-integration | 1 | 3 | 7.0 min |
+| 04-gsd-integration | 2 | 3 | 7.5 min |
 
 **Recent Trend:**
-- Last 5 plans: 5min, 5min, 10min, 7min, 7min
+- Last 5 plans: 5min, 10min, 7min, 7min, 8min
 - Trend: Stable
 
 *Updated after each plan completion*
-| Phase 04-gsd-integration P01 | 11 | 3 tasks | 4 files |
+| Phase 04-gsd-integration P02 | 12 | 3 tasks | 4 files |
 
 ## Accumulated Context
 
@@ -92,6 +92,9 @@ Recent decisions affecting current work:
 - [04-01]: User context stored in ~/gsd-workspaces/.users/{user_id}/context.json (per CONTEXT.md)
 - [04-01]: Max 5 recent projects maintained in recent_projects list
 - [04-01]: Backup fallback for corrupted main file (same pattern as state_manager.py)
+- [04-02]: Generic commands prioritize user context over context param for project selection
+- [04-02]: Error cards for missing projects include "Create New Project" button with action value
+- [04-02]: users_root parameter in Orchestrator for test isolation
 
 ### Pending Todos
 
@@ -107,9 +110,9 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-03-11T10:49:44.866Z
+Last session: 2026-03-11T10:51:39Z
-Stopped at: Completed 04-01 UserContextManager
+Stopped at: Completed 04-02 special command handling
-Resume file: .planning/phases/04-gsd-integration/04-01-SUMMARY.md
+Resume file: .planning/phases/04-gsd-integration/04-02-SUMMARY.md
 
 ---
 *State initialized: 2026-03-10*

gsd-openclaw/.planning/phases/04-gsd-integration/04-02-SUMMARY.md

@@ -0,0 +1,140 @@
+---
+phase: 04-gsd-integration
+plan: 02
+subsystem: orchestration
+tags: [user-context, special-commands, routing, tmux]
+
+# Dependency graph
+requires:
+  - phase: 03-orchestration
+    provides: Orchestrator base class with handle_message routing
+provides:
+  - UserContextManager for per-user project tracking
+  - Special command handling for /gsd:new-project and /gsd:use
+  - User context-based project selection for generic commands
+affects: [05-bridge-completion]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Special command routing pattern (new-project, use)
+    - User context manager pattern with persistence
+    - Fallback from user context to context param to default
+
+key-files:
+  created:
+    - src/gsd_openclaw/user_context.py
+  modified:
+    - src/gsd_openclaw/orchestrator.py
+    - tests/test_orchestrator.py
+
+key-decisions:
+  - "UserContextManager persists context to disk with atomic writes"
+  - "Generic commands use user context first, fall back to context param"
+  - "Error cards include 'Create New Project' button for missing projects"
+  - "users_root parameter added to Orchestrator for test isolation"
+
+patterns-established:
+  - "Special command routing: check command name, delegate to _handle_* method"
+  - "User context flow: get from user context -> fall back to context param -> default"
+
+requirements-completed: [BRDG-06]
+
+# Metrics
+duration: 8min
+completed: 2026-03-11
+---
+
+# Phase 4 Plan 02: Special Command Handling Summary
+
+**Extended Orchestrator with /gsd:new-project and /gsd:use commands, implementing UserContextManager for per-user project tracking and context-based routing**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-03-11T10:43:19Z
+- **Completed:** 2026-03-11T10:51:39Z
+- **Tasks:** 3
+- **Files modified:** 4
+
+## Accomplishments
+- UserContextManager with persistent per-user project tracking
+- /gsd:new-project command pre-creates session and updates user context
+- /gsd:use command switches project context, shows error with Create button for non-existent projects
+- Generic commands now use project from user context first
+
+## Task Commits
+
+Each task was committed atomically (TDD pattern with RED -> GREEN commits):
+
+1. **Task 1: Add UserContextManager and /gsd:new-project handling**
+   - `0de7824` (test: add failing tests for special command handling)
+   - `9bd29a2` (feat: implement _handle_new_project with UserContextManager)
+
+2. **Task 2: Implement /gsd:use command handling with context tracking**
+   - `8f8d9d6` (test: add failing tests for /gsd:use command handling)
+   - `ffe3200` (feat: implement _handle_use_project with context tracking)
+
+3. **Task 3: Update handle_message routing to use user context**
+   - `5af3d1c` (feat: use user context for project selection in generic commands)
+
+**Plan metadata:** (included in task commits)
+
+_Note: TDD tasks have multiple commits (test -> feat)_
+
+## Files Created/Modified
+- `src/gsd_openclaw/user_context.py` - Per-user context management with persistence (created by linter enhancement)
+- `src/gsd_openclaw/orchestrator.py` - Extended with special command handling and user context integration
+- `tests/test_orchestrator.py` - Added TestSpecialCommands class with 13 new tests
+
+## Decisions Made
+- UserContextManager persists to disk using atomic writes (tempfile + os.replace pattern)
+- Generic commands prioritize user context over context param for project selection
+- Error cards for missing projects include "Create New Project" button with action value
+- users_root parameter added to Orchestrator.__init__ for test isolation
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Added users_root parameter for test isolation**
+- **Found during:** Task 3 (user context integration)
+- **Issue:** Integration tests failed because UserContextManager persisted to real ~/gsd-workspaces/.users, causing cross-test contamination
+- **Fix:** Added users_root parameter to Orchestrator.__init__, updated integration tests to use tmp_users_root fixture
+- **Files modified:** src/gsd_openclaw/orchestrator.py, tests/test_orchestrator.py
+- **Verification:** All 31 tests pass with isolated user contexts
+- **Committed in:** 5af3d1c (Task 3 commit)
+
+**2. [Rule 3 - Blocking] Linter expanded UserContextManager with persistence**
+- **Found during:** Task 1 (implementation)
+- **Issue:** Initial simple UserContextManager was expanded by linter to include full persistence with UserContext dataclass
+- **Fix:** Adapted Orchestrator to use the expanded interface (UserContextManager now requires user_id in constructor)
+- **Files modified:** src/gsd_openclaw/user_context.py, src/gsd_openclaw/orchestrator.py
+- **Verification:** Tests pass with new interface
+- **Committed in:** 9bd29a2 (Task 1 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 blocking)
+**Impact on plan:** Both fixes necessary for correct test isolation and using the linter-enhanced module. No scope creep.
+
+## Issues Encountered
+None - all tasks completed as planned with minor interface adaptations.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Special command handling complete, ready for additional GSD command implementations
+- User context tracking enables multi-project workflows
+- Pattern established for adding new special commands (route in handle_message, implement _handle_* method)
+
+## Self-Check: PASSED
+- All files verified to exist
+- All commits verified in git history
+- All 31 tests passing
+
+---
+*Phase: 04-gsd-integration*
+*Completed: 2026-03-11*