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:

git rev-parse --abbrev-ref HEAD

Expected:

feature/claw-ws

• Step 2: Confirm no merge is in progress

Run:

git rev-parse -q --verify MERGE_HEAD

Expected: exit code 1.

• Step 3: Confirm no tracked local changes

Run:

git diff --name-only && printf '\n---STAGED---\n' && git diff --cached --name-only

Expected:

---STAGED---

• Step 4: List current untracked files

Run:

git status --short

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

• Step 5: Update origin/main

Run:

git fetch origin main

• Step 6: Show ws vs main diff surface before merge

Run:

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:

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:

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:

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:

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:

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:

git diff --check -- <path>

---

Task 3E: Confirm merge is fully resolved

Files:

• No code changes expected

• Step 1: Confirm no unmerged entries remain

Run:

git diff --name-only --diff-filter=U

Expected: no output.

• Step 2: Show final resolved file list

Run:

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:

cargo test --test task_runner_test -- --nocapture

• Step 2: Run compat runtime suite relevant to main path

Run:

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:

cargo test --test browser_ws_backend_test -- --nocapture

• Step 2: Run service websocket session suite

Run:

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:

cargo test --test agent_runtime_test production_submit_task_routes_zhihu_through_ws_backend_without_helper_bootstrap -- --nocapture

Expected:

1 passed; 0 failed

• Step 2: If additional Zhihu tests were touched by conflicts, run the smallest affected test target

Run as needed:

cargo test --test agent_runtime_test -- --nocapture

---

Task 4D: Verify config/runtime contracts

• Step 1: Run runtime profile suite

Run:

cargo test --test runtime_profile_test -- --nocapture

• Step 2: Run compat config suite

Run:

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:

cargo test --test browser_script_skill_tool_test -- --nocapture

• Step 2: If openxml files were touched

Run:

cargo test --test compat_openxml_office_tool_test -- --nocapture

---

Task 4F: Compile guard

• Step 1: Run compile-only full test build

Run:

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:

git status --short

Expected:

• no UU / AA / DD

• merged, validated, uncommitted state only

• Step 2: Show final staged summary

Run:

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:

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 旧重复实现”。