claw/docs/superpowers/plans/2026-04-11-main-into-ws-merge-v2-plan.md

# Main → WS Merge v2 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:** 把最新 `origin/main` 合并到 `feature/claw-ws`，让 `ws` 分支最终同时保留 **pipe + ws** 两套通信能力、保留 Zhihu 行为，并用 `main` 上正式的 fault-details 实现替换 `ws` 上已 cleanup 删除的旧重复实现。

**Architecture:** 这次合并不是“把 cleanup 永久保持成没有 fault-details”，而是“先删除 ws 上旧重复实现，再吸收 main 上正式实现”。冲突裁决优先级是：**先保 pipe、再保 ws、再保 Zhihu、同时拒绝 ws 上旧重复 scene/fault-details 实现回流**。整个过程使用 `git merge --no-commit --no-ff origin/main`，冲突解决后只做聚焦验证，停在未提交状态。

**Tech Stack:** Git, Rust 2021, Cargo test, sgClaw pipe transport, ws transport, compat/runtime/orchestration stack, Zhihu direct workflow tests.

---

## Preconditions

- 当前分支必须是 `feature/claw-ws`
- `2026-04-09-ws-branch-scene-cleanup-plan.md` 已完成
- 当前不在 merge 状态
- 当前没有 tracked 未提交改动
- 本次**不创建 worktree**，按当前仓库执行
- 本次结束点是：**已合并、已验证、未提交**

---

## Final Merge Principles

### 1) `main` 是 pipe 主线
合并后不能把 `main` 上现有的 pipe 管道通信破坏掉。

### 2) `ws` 分支最终要同时保留 pipe + ws
合并后不能让 `ws` 分支丢掉 websocket 路径，也不能只剩 pipe。

### 3) 两边都有 Zhihu
合并后不能把现有 Zhihu 行为合坏，尤其是 ws→Zhihu 保留路径。

### 4) fault-details 以 `main` 正式实现为准
- `ws` 上那套旧重复实现：**不能回流**
- `main` 上正式实现：**应被合进来**
- 最终结果不是“没有 fault-details”，而是“没有 ws 那套旧 fault-details，只保留 main 正式版本”

### 5) 不回流旧 scene plumbing
以下旧面不能作为最终结果保留：
- ws 自己那套旧 scene registry / old scene plumbing
- ws cleanup 已删掉的旧重复 route/contract
- 仅为旧 `skill_staging` 场景装配服务的残留逻辑

---

## File Map

### A. 合并时重点观察的共享/高风险文件
- `Cargo.toml`
- `Cargo.lock`
- `src/agent/mod.rs`
- `src/agent/task_runner.rs`
- `src/config/settings.rs`
- `src/compat/config_adapter.rs`
- `src/compat/runtime.rs`
- `src/compat/orchestration.rs`
- `src/compat/workflow_executor.rs`
- `src/compat/browser_script_skill_tool.rs`
- `src/compat/direct_skill_runtime.rs`
- `src/compat/openxml_office_tool.rs`

### B. pipe / ws / Zhihu 保护面
- `src/compat/runtime.rs`
- `src/compat/orchestration.rs`
- `src/compat/workflow_executor.rs`
- `src/agent/task_runner.rs`
- `tests/agent_runtime_test.rs`
- `tests/browser_ws_backend_test.rs`
- `tests/service_ws_session_test.rs`
- `tests/task_runner_test.rs`

### C. cleanup 后仍需防止旧实现回流的文件
- `src/runtime/mod.rs`
- `src/runtime/engine.rs`
- `src/config/settings.rs`
- `src/compat/config_adapter.rs`
- `tests/compat_runtime_test.rs`
- `tests/runtime_profile_test.rs`
- `tests/compat_config_test.rs`

### D. 可能需要随 main 正式 fault-details 一起更新的测试面
- `tests/compat_runtime_test.rs`
- `tests/compat_config_test.rs`
- `tests/browser_script_skill_tool_test.rs`
- `tests/compat_openxml_office_tool_test.rs`

---

## Conflict Resolution Rule Table

| 类别 | 最终保留原则 |
|---|---|
| pipe 主路径 | **优先保留可工作的 main 版本**，不能被 ws 改坏 |
| ws 路径 | **必须继续保留 ws 能力**，不能因吸收 main 而丢失 |
| Zhihu | 两边相关能力都不能合坏，至少保住现有 keep-path |
| fault-details | **保留 main 正式实现**，不保留 ws 旧重复实现 |
| old scene/95598 cleanup 残留 | 不允许以 ws 旧重复实现形式回流 |
| `skillsDir` / config | 以最终产品需要为准；若 main 正式实现不要求旧 array-style/scene expansion，则不回流 |
| 临时 merge 修补 | 一律不保留 |

---

### Task 1: Confirm Merge Preconditions And Diff Surface

**Files:**
- No code changes expected
- Observe repo state and branch diff only

- [ ] **Step 1: Confirm current branch**

Run:
```bash
git rev-parse --abbrev-ref HEAD
```

Expected:
```text
feature/claw-ws
```

- [ ] **Step 2: Confirm no merge is in progress**

Run:
```bash
git rev-parse -q --verify MERGE_HEAD
```

Expected: exit code `1`.

- [ ] **Step 3: Confirm no tracked local changes**

Run:
```bash
git diff --name-only && printf '\n---STAGED---\n' && git diff --cached --name-only
```

Expected:
```text

---STAGED---
```

- [ ] **Step 4: List current untracked files**

Run:
```bash
git status --short
```

Expected: only known local untracked items, or a clearly understood list.

- [ ] **Step 5: Update `origin/main`**

Run:
```bash
git fetch origin main
```

- [ ] **Step 6: Show ws vs main diff surface before merge**

Run:
```bash
git diff --name-status HEAD...origin/main
```

Expected: clear file list to compare likely merge surface.

- [ ] **Step 7: Stop if preconditions fail**

Stop if:
- branch is wrong
- merge is in progress
- tracked changes exist
- untracked file collision with `origin/main` is found and unresolved

---

### Task 2: Start The Merge Without Committing

**Files:**
- Merge index / working tree only

- [ ] **Step 1: Start no-commit merge**

Run:
```bash
git merge --no-commit --no-ff origin/main
```

Expected:
- either auto-merge pauses before commit
- or Git reports conflicts

- [ ] **Step 2: Capture merge surface immediately**

Run:
```bash
git status --short
```

- [ ] **Step 3: Separate results into three buckets**
Create a working list of conflicted files under:
1. pipe-critical
2. ws/Zhihu-critical
3. shared infra / tests

- [ ] **Step 4: If no conflicts, proceed directly to Task 4 verification**

- [ ] **Step 5: If conflicts exist, proceed to Task 3**

---

### Task 3: Resolve Conflicts By System Role, Not By Branch Bias

**Files:**
- Only files reported by Git as conflicted

#### Global conflict policy
For every conflicted hunk, answer these four questions in order:

1. Does this hunk affect **pipe** correctness?
2. Does this hunk affect **ws** correctness?
3. Does this hunk affect **Zhihu** correctness?
4. Is this hunk part of **ws old duplicate fault-details/scene logic** or **main official implementation**?

Then apply the rule:
- **pipe cannot break**
- **ws cannot break**
- **Zhihu cannot break**
- **ws old duplicate fault-details must stay deleted**
- **main official fault-details should come in**

---

#### Task 3A: Resolve pipe-critical shared runtime files

**Files:**
- `src/compat/runtime.rs`
- `src/agent/task_runner.rs`
- `src/agent/mod.rs`
- `src/config/settings.rs`
- `src/compat/config_adapter.rs`

- [ ] **Step 1: For each conflict, keep the side that preserves main’s pipe behavior**

- [ ] **Step 2: Reject ws-only duplicate business logic that main already owns**

- [ ] **Step 3: Keep ws support if the file also serves ws path**
This is additive preservation, not “main wins everything”.

- [ ] **Step 4: Verify each resolved file has no conflict markers**

Run per file:
```bash
git diff --check -- <path>
```

---

#### Task 3B: Resolve ws / Zhihu-critical routing files

**Files:**
- `src/compat/workflow_executor.rs`
- `src/compat/orchestration.rs`

- [ ] **Step 1: Bring in main’s official fault-details path if it lives here**

- [ ] **Step 2: Do not reintroduce ws’s old duplicate fault-details path**

- [ ] **Step 3: Preserve ws submit/browser websocket path**

- [ ] **Step 4: Preserve Zhihu routing path**

- [ ] **Step 5: Verify each resolved file has no conflict markers**

Run per file:
```bash
git diff --check -- <path>
```

---

#### Task 3C: Resolve shared infra files minimally

**Files:**
- `Cargo.toml`
- `Cargo.lock`
- `src/compat/browser_script_skill_tool.rs`
- `src/compat/direct_skill_runtime.rs`
- `src/compat/openxml_office_tool.rs`

- [ ] **Step 1: Keep only the dependency/code shape needed by the merged result**

- [ ] **Step 2: Do not keep lines from prior failed merge attempts**

- [ ] **Step 3: Accept main fixes unless they break pipe/ws/Zhihu behavior**

- [ ] **Step 4: Verify each resolved file has no conflict markers**

Run per file:
```bash
git diff --check -- <path>
```

---

#### Task 3D: Resolve tests to reflect final intended product

**Files:**
- `tests/compat_runtime_test.rs`
- `tests/runtime_profile_test.rs`
- `tests/compat_config_test.rs`
- `tests/agent_runtime_test.rs`
- `tests/browser_script_skill_tool_test.rs`
- `tests/compat_openxml_office_tool_test.rs`

- [ ] **Step 1: Keep tests proving pipe path still works**

- [ ] **Step 2: Keep tests proving ws path still works**

- [ ] **Step 3: Keep Zhihu keep-path regression**

- [ ] **Step 4: Replace cleanup-only “fault-details absent” assertions if final intended state is now “fault-details present via main official implementation”**

- [ ] **Step 5: Do not keep assertions that only prove ws’s old duplicate implementation is absent if they now contradict the intended merged product**

- [ ] **Step 6: Verify each resolved test file has no conflict markers**

Run per file:
```bash
git diff --check -- <path>
```

---

#### Task 3E: Confirm merge is fully resolved

**Files:**
- No code changes expected

- [ ] **Step 1: Confirm no unmerged entries remain**

Run:
```bash
git diff --name-only --diff-filter=U
```

Expected: no output.

- [ ] **Step 2: Show final resolved file list**

Run:
```bash
git diff --cached --name-only
```

---

### Task 4: Verify Final Product Behavior, Not Cleanup Intermediate State

**Files:**
- Test: `tests/agent_runtime_test.rs`
- Test: `tests/browser_ws_backend_test.rs`
- Test: `tests/service_ws_session_test.rs`
- Test: `tests/task_runner_test.rs`
- Test: `tests/compat_runtime_test.rs`
- Test: `tests/runtime_profile_test.rs`
- Test: `tests/compat_config_test.rs`
- Conditional: `tests/browser_script_skill_tool_test.rs`
- Conditional: `tests/compat_openxml_office_tool_test.rs`

#### Verification goals
This task must prove all four:

1. **pipe path still works**
2. **ws path still works**
3. **Zhihu still works**
4. **final fault-details implementation is the main version, not ws’s old duplicate**

---

#### Task 4A: Verify pipe-related behavior

- [ ] **Step 1: Run task runner coverage**

Run:
```bash
cargo test --test task_runner_test -- --nocapture
```

- [ ] **Step 2: Run compat runtime suite relevant to main path**

Run:
```bash
cargo test --test compat_runtime_test -- --nocapture
```

- [ ] **Step 3: If pipe-specific tests fail, stop and fix merge resolution before continuing**

---

#### Task 4B: Verify ws-related behavior

- [ ] **Step 1: Run browser websocket backend suite**

Run:
```bash
cargo test --test browser_ws_backend_test -- --nocapture
```

- [ ] **Step 2: Run service websocket session suite**

Run:
```bash
cargo test --test service_ws_session_test -- --nocapture
```

- [ ] **Step 3: If ws-specific tests fail, stop and fix merge resolution before continuing**

---

#### Task 4C: Verify Zhihu behavior

- [ ] **Step 1: Re-run ws→Zhihu keep-path regression**

Run:
```bash
cargo test --test agent_runtime_test production_submit_task_routes_zhihu_through_ws_backend_without_helper_bootstrap -- --nocapture
```

Expected:
```text
1 passed; 0 failed
```

- [ ] **Step 2: If additional Zhihu tests were touched by conflicts, run the smallest affected test target**

Run as needed:
```bash
cargo test --test agent_runtime_test -- --nocapture
```

---

#### Task 4D: Verify config/runtime contracts

- [ ] **Step 1: Run runtime profile suite**

Run:
```bash
cargo test --test runtime_profile_test -- --nocapture
```

- [ ] **Step 2: Run compat config suite**

Run:
```bash
cargo test --test compat_config_test -- --nocapture
```

- [ ] **Step 3: Ensure contracts now reflect final merged product, not the cleanup-only intermediate**

---

#### Task 4E: Verify shared infra if touched

- [ ] **Step 1: If browser-script tool files were touched**

Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture
```

- [ ] **Step 2: If openxml files were touched**

Run:
```bash
cargo test --test compat_openxml_office_tool_test -- --nocapture
```

---

#### Task 4F: Compile guard

- [ ] **Step 1: Run compile-only full test build**

Run:
```bash
cargo test --no-run
```

Expected: exit code `0`.

---

### Task 5: Confirm The Merge Outcome Matches The Principle

**Files:**
- No code changes expected

- [ ] **Step 1: Show final status**

Run:
```bash
git status --short
```

Expected:
- no `UU` / `AA` / `DD`
- merged, validated, uncommitted state only

- [ ] **Step 2: Show final staged summary**

Run:
```bash
git diff --cached --stat
```

- [ ] **Step 3: Report the four required facts with command-backed evidence**
Only if verified:
1. pipe 没坏
2. ws 没坏
3. Zhihu 没坏
4. 最终 fault-details 来自 main 正式实现，而不是 ws 旧重复实现

- [ ] **Step 4: Stop here**
Do **not** run:
```bash
git commit
git push
```

---

## Stop Conditions

出现以下任一情况立即停止，不擅自扩展处理：

- `origin/main` 的正式 fault-details 实现依赖 cleanup 已删掉的契约，而这已经超出简单 merge 范围
- pipe 与 ws 同时依赖同一段共享代码，但两边要求已结构性冲突
- Zhihu keep-path 失败
- `cargo test --no-run` 失败且问题超出本次 merge surface
- 需要重新设计 pipe/ws 共存方式，而不是单纯合并

---

## One-line Execution Rule

**这次 merge 的最终标准不是“继续保持 ws 没有 fault-details”，而是“保住 pipe、保住 ws、保住 Zhihu，并让 main 的正式 fault-details 替换 ws 旧重复实现”。**