@zhushanwen/pi-cw-tool 0.3.1 → 0.4.1

package/agents/planning-agent.md

@@ -106,7 +106,7 @@ worktree: false
 agent: wave-agent
 task: 你是 <子 waveId> 的 wave 层主。unitId=<子 waveId>。按 wave-agent 流程执行。
 worktree: true
-fork: true
+fork: false
 ```
 
 ## 续 turn 指导（被 steer 唤醒）

package/agents/wave-agent.md

@@ -30,7 +30,7 @@ tools: cw_wave, subagent
 
 ## 生命周期（v4 §6）
 
-你被父（slice/feature 层主）用 subagent 工具带 `worktree: true` + `fork: true` 后台派出（worktree:true 强制要求 fork:true，缺 fork 派发即失败），在专属 worktree 工作。
+你被父（slice/feature 层主）用 subagent 工具带 `worktree: true` 后台派出，在专属 worktree 工作。
 
 ### turn 1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-cw-tool",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Pi extension wrapping the `cw` CLI as role-restricted tools (cw_planning / cw_wave / cw_dev / cw_review) with per-tool action whitelists — hard-guarantees no self-review by layer-owner agents.",
   "type": "module",
   "main": "index.ts",

package/skills/pi-cw/SKILL.md

@@ -5,16 +5,16 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
 
 # pi-cw
 
-主 agent 发起递归编排:用 cw 建一棵 epic->feature->slice->wave 的任务树,派第一个 planning-agent 自递归展开整棵树,主 agent 空闲等 steer 唤醒,全树完成后报告用户。
+主 agent 发起递归编排:用 cw 建一棵 <顶层>->...->wave 的任务树(<顶层> 通常 epic,也可 feature/slice),派第一个 planning-agent 自递归展开整棵树,主 agent 空闲等 steer 唤醒,全树完成后报告用户。
 
-> **编排机制**:子 agent 完成时 pi 自动 steer 唤醒父 agent(事件驱动,无轮询)。主 agent 只派第一个 epic planning-agent,**不自己 descend 到子层**。设计依据见 `design-v4.md`（同目录）。
+> **编排机制**:子 agent 完成时 pi 自动 steer 唤醒父 agent(事件驱动,无轮询)。主 agent 只派第一个(根层) planning-agent,**不自己 descend 到子层**。设计依据见 `design-v4.md`（同目录）。
 
 ## 何时用
 
-满足任一:
-- 任务需要 epic/feature/slice/wave 多层拆解(单层 wave 装不下)
-- 多个 wave 可并行,各自 worktree 隔离开发
-- 单 agent 从头做到尾会撑爆上下文(设计 + 实现 + 审查 + 合并全栈)
+核心判据:**任务需要多 subagent 并行推进 + 上下文隔离**(不是树深——一棵 epic 树也能单 agent 线性走,见 cw-cli)。满足以下场景之一才用 pi-cw:
+- 多个 wave 要 worktree 隔离并行开发
+- 多个 slice/feature 子树要并行展开
+- 单 agent 线性走完整棵树会撑爆上下文(设计 + 实现 + 审查 + 合并全栈),需按层隔离上下文
 
 > 单 agent 模式或小任务（改 typo / 单文件 / 明确小 bug）走 `cw-cli` skill,不必建树。
 
@@ -22,6 +22,7 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
 
 - 单文件小改、明确的小 bug:直接 edit,或派单个 worker subagent;或走 `cw-cli` skill 单 agent 模式
 - 线性任务、无需多 agent 并行:走 cw 单层 wave 即可,不必建树
+- 能单 agent 线性走完的任务(哪怕要建 epic 树):走 `cw-cli` skill 单 agent 模式,不必上递归编排
 - 纯分析 / 调研 / 设计文档:不写代码不该进 cw 编排
 
 ## 前置：cw-tool
@@ -40,26 +41,28 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
 ### 1. 建树根
 
 ```bash
-cw create epic --slug <kebab-slug> --objective "<一句话目标,含可验收的完成标准>"
+cw create <顶层> --slug <kebab-slug> --objective "<一句话目标,含可验收的完成标准>"
 ```
 
-拿到 epic 的 unitId(下文记作 `<epicId>`)。
+`<顶层>` 通常 epic,但 feature/slice 也能做根——选能覆盖全貌的最小层(选层标准复用 cw-cli skill 的「规模 × 性质」表)。递归编排的额外门槛:**顶层必须会拆出 ≥2 个可并行的下层 unit**;只拆 1 个(无并行价值)或整棵树线性串行即可,走 cw-cli 单 agent 模式更省。
+
+拿到根 unit 的 unitId(下文记作 `<根Id>`)。
 
 ### 2. 派第一个 planning-agent
 
 用 `subagent` 工具**后台**派发(`planning-agent` 是 cw-tool 内置的 agent 模板):
 
 ```
-subagent(action="start", agent="planning-agent", slug="<epic-slug>-planning", fork=true,
-  task="<背景>这是 cw epic <epicId> 的层主 agent,目标:<原 objective>。这是递归编排,你会自递归派 feature/slice/wave 层 planning-agent。<目标>先调 cw handoff --unitId <epicId> 拿上下文与 guidance,按 guidance 的派发指导自递归展开并合并子树。<验收>cw status --unitId <epicId> 显示该 epic 子树全部 closed。")
+subagent(action="start", agent="planning-agent", slug="<根-slug>-planning", fork=false,
+  task="<背景>这是 cw <根层> <根Id> 的层主 agent,目标:<原 objective>。这是递归编排,你会自递归派下层 planning-agent(<根层> 是 epic 派 feature,是 feature 派 slice,是 slice 派 wave)。<目标>先调 cw handoff --unitId <根Id> 拿上下文与 guidance,按 guidance 的派发指导自递归展开并合并子树。<验收>cw status --unitId <根Id> 显示该 <根层> 子树全部 closed。")
 # 不传 model 参数——默认继承主 agent 模型,递归传给所有下层(见「模型派发」)。
 # 用户特别指定时才传 model="provider/modelId",单个 subagent 生效或作为全树根模型。
 ```
 
 task 三要素:
-- **背景**:epic 的 `<epicId>`、目标、说明这是递归编排(planning-agent 会自递归派下层)
-- **目标**:入口是 `cw handoff --unitId <epicId>`;自递归的每一步按 cw guidance 的派发指导执行
-- **验收**:`cw status --unitId <epicId>` 子树全 `closed`(可查的检查点,禁止"完成""实现该功能"这类不可证伪描述)
+- **背景**:`<根层>` 的 `<根Id>`、目标、说明这是递归编排(planning-agent 会自递归派下层)
+- **目标**:入口是 `cw handoff --unitId <根Id>`;自递归的每一步按 cw guidance 的派发指导执行
+- **验收**:`cw status --unitId <根Id>` 子树全 `closed`(可查的检查点,禁止"完成""实现该功能"这类不可证伪描述)
 
 派发后主 agent 结束当前 turn,进空闲态(session 保活)。
 
@@ -71,7 +74,7 @@ planning-agent 自递归展开(epic->feature->slice->wave),每层 design -> 审
 
 ```bash
 cw status                     # 全局
-cw frontier --root <epicId>   # 看 epic 子树 frontier
+cw frontier --root <根Id>   # 看根子树 frontier
 ```
 
 - 子树全 `closed` -> 进入第 5 步汇报用户
@@ -86,7 +89,7 @@ cw frontier --root <epicId>   # 看 epic 子树 frontier
 
 - **只派第一个 planning-agent**:主 agent 不自己 descend 到 feature / slice / wave 层。下层派发是 planning-agent 的职责(它调 cw execute 自动建子 unit,并按 guidance 派子 planning-agent / wave-agent)。
 - **靠 cw 查进度,不信自报**:agent 汇报"我做完了"不等于 cw 状态 closed。以 `cw status` / `cw frontier` 为唯一真相。
-- **worktree 隔离**:wave 层用 `worktree: true, fork: true` 派出(`worktree: true` 强制要求同时 `fork: true`,否则 subagent 工具运行时 throw「worktree:true requires fork:true」,派发即失败;各 wave 独立工作目录,并行不冲突);主 agent 派的 epic planning-agent 不需 worktree(它只编排不写码)。worktree 的合并与清理由 slice 层 planning-agent 派 chain workflow(merge-agent)处理,细节见 planning-agent 模板。
+- **worktree 隔离**:wave 层用 `worktree: true` 派出(各 wave 独立工作目录,并行不冲突;worktree 与 fork 正交,fork 默认 false);主 agent 派的根层 planning-agent 不需 worktree(它只编排不写码)。worktree 的合并与清理由 slice 层 planning-agent 派 chain workflow(merge-agent)处理,细节见 planning-agent 模板。
 - **失败恢复靠 L0-L3**:cw gate fail / 审查 must-fix / 方案缺陷 / 父层拆错,各有恢复路径(L0 就地改重审 / L1 cw replan / L2 父 replan 级联 / L3 上报人),定义在 planning-agent 模板与 cw guidance,本 skill 不重复。
 
 ## 模型派发

package/src/__tests__/cw-tool.test.ts

@@ -57,6 +57,11 @@ function fakeSpawner(responses: CwSpawnResult[]): { spawner: CwSpawner; calls: C
 	const calls: CapturedCall[] = [];
 	let i = 0;
 	const spawner: CwSpawner = vi.fn(async (args, input, cwd, _signal): Promise<CwSpawnResult> => {
+		// 门控 probe（['--version']）是内部细节：返回低版本（不支持归一化）让 write action
+		// 走兜底路径，且不入 calls（测试断言的是 action 调用，probe 透明）。
+		if (args[0] === "--version") {
+			return { stdout: "cw 1.0.0", stderr: "", exitCode: 0 };
+		}
 		calls.push({ args, input, cwd });
 		const r = responses[i] ?? { stdout: "", stderr: "", exitCode: 0 };
 		i += 1;

package/src/__tests__/detect-repo-workspace.test.ts

@@ -1,25 +1,20 @@
 /**
- * detectRepoWorkspace 真实 git 测试 + executeCwAction 集成（真实 cwd）。
+ * detectRepoWorkspace 真实 git 探测测试 + buildCwArgs 纯函数构造测试。
  *
- * 与 cw-tool.test.ts 分开：该文件 mock 了 node:child_process（spawnSync 被替换），
- * 而本文件需要真实 git 探测，故不 mock，直接对临时 git repo 验证。
+ * executeCwAction 的 workspace 门控行为测试已移到 workspace-gate.test.ts
+ * （门控后 spawner 被调两次：probe `cw --version` + action，calls[0] 语义变化，
+ * 集成测试在那里用区分 probe/action 的 gateSpawner 覆盖）。本文件只测两个纯函数。
  *
- * 测试框架：vitest（从 vitest 导入 describe/it/expect/vi）。
+ * 测试框架：vitest（从 vitest 导入 describe/it/expect）。
  */
 import { execSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
-import {
-	buildCwArgs,
-	detectRepoWorkspace,
-	executeCwAction,
-} from "../cw-runner.ts";
-import { type CwSpawner } from "../cw-spawn.ts";
-import { DEV_ALLOWED } from "../index.ts";
+import { buildCwArgs, detectRepoWorkspace } from "../cw-runner.ts";
 
 // ── 临时目录管理 ────────────────────────────────────────────────
 
@@ -98,70 +93,6 @@ describe("detectRepoWorkspace（真实 git）", () => {
 	});
 });
 
-// ── executeCwAction 集成（真实 cwd，fake spawner 记录 args）─────
-
-describe("executeCwAction 集成（真实 git cwd）", () => {
-	/** 记录 args 的 fake spawner（不真调 cw）。 */
-	function recordingSpawner(): { spawner: CwSpawner; calls: Array<{ args: string[] }> } {
-		const calls: Array<{ args: string[] }> = [];
-		const spawner: CwSpawner = vi.fn(async (args: string[]) => {
-			calls.push({ args });
-			return { stdout: "{}", stderr: "", exitCode: 0 };
-		}) as unknown as CwSpawner;
-		return { spawner, calls };
-	}
-
-	it("cwd 在 git repo 内 → write action args 含 --workspace <repo 根>", async () => {
-		const base = makeTempDir("cw-int-");
-		const repo = createGitRepo(base, "repo");
-		const { spawner, calls } = recordingSpawner();
-		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
-		expect(calls[0].args).toContain("--workspace");
-		expect(calls[0].args[calls[0].args.indexOf("--workspace") + 1]).toBe(repo);
-	});
-
-	it("cwd 在 linked worktree 内 → write action --workspace 指向 repo 主目录", async () => {
-		const base = makeTempDir("cw-int-");
-		const repo = createGitRepo(base, "repo");
-		const wtDir = path.join(base, "wt1");
-		execSync(`git worktree add -q ${wtDir}`, { cwd: repo });
-		const { spawner, calls } = recordingSpawner();
-		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, wtDir);
-		expect(calls[0].args).toContain("--workspace");
-		expect(calls[0].args[calls[0].args.indexOf("--workspace") + 1]).toBe(repo);
-	});
-
-	it("read-only action（status）即使在 git repo 内也不附加 --workspace（S-3）", async () => {
-		const base = makeTempDir("cw-int-");
-		const repo = createGitRepo(base, "repo");
-		const { spawner, calls } = recordingSpawner();
-		await executeCwAction("status", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
-		expect(calls[0].args).not.toContain("--workspace");
-	});
-
-	it("cwd 为非 git 目录 → write action 不含 --workspace", async () => {
-		const plain = makeTempDir("cw-int-plain-");
-		const { spawner, calls } = recordingSpawner();
-		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, plain);
-		expect(calls[0].args).not.toContain("--workspace");
-	});
-
-	it("cwd 不存在 → write action 不含 --workspace（探测失败不抛）", async () => {
-		const base = makeTempDir("cw-int-");
-		const { spawner, calls } = recordingSpawner();
-		await executeCwAction(
-			"execute",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			path.join(base, "missing"),
-		);
-		expect(calls[0].args).not.toContain("--workspace");
-	});
-});
-
 // ── buildCwArgs 纯函数（workspace 参数）─────────────────────────
 
 describe("buildCwArgs（workspace 参数）", () => {

package/src/__tests__/workspace-gate.test.ts

@@ -0,0 +1,233 @@
+/**
+ * workspace 门控测试：probeCwCliNormalization 纯函数 + executeCwAction 门控决策。
+ *
+ * 门控语义（差异文档 §3 §4 + ADR-0045 Superseded）：cw-cli 支持 store 内部归一化
+ * （probe 版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION）→ write action 不传 --workspace（纯封装）；
+ * 不支持 → 兜底 ADR-0045 的 detectRepoWorkspace + --workspace。只读 action 始终不传（S-3）。
+ *
+ * detectRepoWorkspace 探测纯函数 + buildCwArgs 构造的测试在 detect-repo-workspace.test.ts，
+ * 本文件只测门控决策（probe 三态 × action 两类 × git 环境）。
+ *
+ * 测试框架：vitest（从 vitest 导入 describe/it/expect/vi）。
+ */
+import { execSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { _resetCapabilityCacheForTest, executeCwAction, probeCwCliNormalization } from "../cw-runner.ts";
+import { type CwSpawner, type CwSpawnResult } from "../cw-spawn.ts";
+import { DEV_ALLOWED } from "../index.ts";
+
+// ── 临时目录管理（同 detect-repo-workspace.test.ts 风格）─────────
+
+const tmpDirs: string[] = [];
+
+function makeTempDir(prefix: string): string {
+	const dir = mkdtempSync(path.join(tmpdir(), prefix));
+	tmpDirs.push(dir);
+	return dir;
+}
+
+/** 建含一次空 commit 的 git repo，返回 realpath 规范化的 repo 根（macOS /tmp→/private/tmp 对齐）。 */
+function createGitRepo(parentDir: string, name: string): string {
+	const repo = path.join(parentDir, name);
+	mkdirSync(repo);
+	execSync("git init -q", { cwd: repo });
+	execSync("git -c user.name=test -c user.email=test@test.local commit -q --allow-empty -m init", {
+		cwd: repo,
+	});
+	return realpathSync(repo);
+}
+
+afterEach(() => {
+	for (const dir of tmpDirs.splice(0)) {
+		rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+// capability 缓存是进程内全局单值（S-1），测试间必须重置避免串台。
+beforeEach(() => {
+	_resetCapabilityCacheForTest();
+});
+
+// ── mock spawner：对 ['--version'] 可控，对 action 默认成功 ───────
+
+interface GateSpawnerOpts {
+	/** cw --version 的 stdout（如 "cw 1.6.1"）。 */
+	versionStdout?: string;
+	/** cw --version 的 exitCode（默认 0）。 */
+	versionExitCode?: number;
+	/** cw --version spawn 抛异常（模拟 cw 不在 PATH）。 */
+	versionThrow?: boolean;
+}
+
+/**
+ * 记录所有调用的 fake spawner：对 `['--version']`（probe）返回可控结果，
+ * 对其他（action）返回默认成功 `{ stdout: "{}", exitCode: 0 }`。
+ */
+function gateSpawner(opts: GateSpawnerOpts = {}): {
+	spawner: CwSpawner;
+	calls: Array<{ args: string[] }>;
+} {
+	const calls: Array<{ args: string[] }> = [];
+	// contextual typing：变量类型 CwSpawner 提供 4 参数完整签名，回调签名漂移会编译失败（消除假绿，S-5）。
+	const spawner: CwSpawner = vi.fn(async (args, _input, _cwd, _signal): Promise<CwSpawnResult> => {
+		calls.push({ args });
+		if (args[0] === "--version") {
+			if (opts.versionThrow) throw new Error("cw not in PATH (spawn error)");
+			return {
+				stdout: opts.versionStdout ?? "",
+				stderr: "",
+				exitCode: opts.versionExitCode ?? 0,
+			};
+		}
+		return { stdout: "{}", stderr: "", exitCode: 0 };
+	});
+	return { spawner, calls };
+}
+
+/** 从 calls 中取 action 调用（非 `['--version']` 的最后一个）。 */
+function actionCall(calls: Array<{ args: string[] }>): { args: string[] } {
+	const action = calls.filter((c) => c.args[0] !== "--version").pop();
+	if (!action) throw new Error("无 action 调用（只有 probe 或未触发）");
+	return action;
+}
+
+// ── probeCwCliNormalization 纯函数 ──────────────────────────────
+
+describe("probeCwCliNormalization", () => {
+	it("版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION → supported:true", async () => {
+		const cwd = makeTempDir("probe-supported-");
+		const { spawner } = gateSpawner({ versionStdout: "cw 99.9.9" });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(true);
+		expect(cap.version).toBe("99.9.9");
+	});
+
+	it("版本 === MIN（等号边界）→ supported:true（门控用 >=，锁定等号语义，S-7）", async () => {
+		const cwd = makeTempDir("probe-eq-");
+		const { spawner } = gateSpawner({ versionStdout: "cw 99.0.0" });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(true);
+		expect(cap.version).toBe("99.0.0");
+	});
+
+	it("版本 < MIN → supported:false（当前 placeholder 99.0.0，真实 cw 1.6.1 不支持）", async () => {
+		const cwd = makeTempDir("probe-unsupported-");
+		const { spawner } = gateSpawner({ versionStdout: "cw 1.6.1" });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(false);
+		expect(cap.version).toBe("1.6.1");
+	});
+
+	it("cw --version exitCode 非 0 → supported:false（fail-safe）", async () => {
+		const cwd = makeTempDir("probe-exit-");
+		const { spawner } = gateSpawner({ versionExitCode: 127 });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(false);
+		expect(cap.version).toBeUndefined();
+	});
+
+	it("stdout 无版本号 → supported:false（parse 失败 fail-safe）", async () => {
+		const cwd = makeTempDir("probe-parse-");
+		const { spawner } = gateSpawner({ versionStdout: "garbage no version here" });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(false);
+		expect(cap.version).toBeUndefined();
+	});
+
+	it("spawn 抛异常（cw 不在 PATH）→ supported:false（fail-safe）", async () => {
+		const cwd = makeTempDir("probe-throw-");
+		const { spawner } = gateSpawner({ versionThrow: true });
+		const cap = await probeCwCliNormalization(spawner, cwd);
+		expect(cap.supported).toBe(false);
+	});
+
+	it("probe 5s 超时 → supported:false（fail-safe，防御 cw --version 卡死，S-6）", async () => {
+		vi.useFakeTimers();
+		try {
+			const cwd = makeTempDir("probe-timeout-");
+			// spawner 模拟 cw --version 卡死：永不 resolve，signal abort 时 reject（走 probe catch 路径）。
+			const spawner: CwSpawner = vi.fn((_args, _input, _cwd, signal): Promise<CwSpawnResult> =>
+				new Promise<CwSpawnResult>((_resolve, reject) => {
+					signal?.addEventListener("abort", () => reject(new Error("aborted by timeout")), {
+						once: true,
+					});
+				}),
+			);
+			const probePromise = probeCwCliNormalization(spawner, cwd);
+			await vi.advanceTimersByTimeAsync(5001);
+			const cap = await probePromise;
+			expect(cap.supported).toBe(false);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("memoize：同 cwd 第二次不调 spawner（进程内缓存）", async () => {
+		const cwd = makeTempDir("probe-memo-");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 99.9.9" });
+		await probeCwCliNormalization(spawner, cwd);
+		await probeCwCliNormalization(spawner, cwd);
+		expect(calls.length).toBe(1);
+	});
+
+	it("memoize：全局单值缓存，不同 cwd 也命中（cw 版本 cwd 无关，S-1）", async () => {
+		const cwdA = makeTempDir("probe-memo-a-");
+		const cwdB = makeTempDir("probe-memo-b-");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 99.9.9" });
+		await probeCwCliNormalization(spawner, cwdA);
+		await probeCwCliNormalization(spawner, cwdB);
+		expect(calls.length).toBe(1);
+	});
+});
+
+// ── executeCwAction workspace 门控（TC1-5）──────────────────────
+
+describe("executeCwAction workspace 门控", () => {
+	it("TC1: probe 支持 → write action 不传 --workspace（纯封装）", async () => {
+		const base = makeTempDir("gate-tc1-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 99.9.9" });
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		expect(actionCall(calls).args).not.toContain("--workspace");
+	});
+
+	it("TC2: probe 不支持 → write action 兜底传 --workspace（ADR-0045 行为）", async () => {
+		const base = makeTempDir("gate-tc2-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 1.6.1" });
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		const args = actionCall(calls).args;
+		expect(args).toContain("--workspace");
+		expect(args[args.indexOf("--workspace") + 1]).toBe(repo);
+	});
+
+	it("TC3: probe 失败（spawn error）→ fail-safe 兜底传 --workspace", async () => {
+		const base = makeTempDir("gate-tc3-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = gateSpawner({ versionThrow: true });
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		expect(actionCall(calls).args).toContain("--workspace");
+	});
+
+	it("TC4: 只读 action（status）始终不传 --workspace（不 probe）", async () => {
+		const base = makeTempDir("gate-tc4-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 99.9.9" });
+		await executeCwAction("status", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		// 只读不 probe：仅 1 次调用（action），且不含 --workspace
+		expect(calls.length).toBe(1);
+		expect(calls[0].args).not.toContain("--workspace");
+	});
+
+	it("TC5: 非 git 目录 + probe 不支持 → detectRepoWorkspace undefined → 不传", async () => {
+		const plain = makeTempDir("gate-tc5-plain-");
+		const { spawner, calls } = gateSpawner({ versionStdout: "cw 1.6.1" });
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, plain);
+		expect(actionCall(calls).args).not.toContain("--workspace");
+	});
+});

package/src/cw-runner.ts

@@ -109,6 +109,122 @@ export function detectRepoWorkspace(cwd: string): string | undefined {
 	}
 }
 
+/**
+ * cw-cli 支持 store 内部归一化的最低版本（门控阈值）。
+ *
+ * cw-tool 与 cw-cli 是两个独立 npm 包（cw-tool 经 PATH 裸调 cw、零依赖声明），
+ * 两包独立升级。cw-tool 退回纯封装前需探测 cw-cli 是否已落地 store 归一化
+ * （coding-workflow S1：getCwJsonPath 用 git-common-dir），支持则不传 --workspace
+ * （纯封装），不支持则兜底 ADR-0045 的 detectRepoWorkspace + --workspace。
+ *
+ * TODO(S1): 当前 placeholder "99.0.0" 使门控永远判定为「不支持」→ 永远走兜底
+ * （=现状 dirname 行为，不引入回归）。cw-cli S1 落地并发布后，改为实际版本号
+ * （如 "1.7.0"），门控自动激活。详见 docs/architecture/cw-store-workspace-decoupling.md §3 §4。
+ */
+const MIN_CW_CLI_VERSION_FOR_NORMALIZATION = "99.0.0";
+
+/** probe 超时（ms）：cw --version 卡死时 fail-safe 为「不支持」。 */
+const CW_VERSION_PROBE_TIMEOUT_MS = 5000;
+
+/** 版本 parse 失败时 reason 截断长度（避免 stdout 过长污染日志）。 */
+const VERSION_REASON_MAX_LEN = 60;
+
+/** cw-cli 能力探测结果。 */
+export interface CwCliCapability {
+	/** true = cw-cli 支持 store 内部归一化（cw-tool 应纯封装，不传 --workspace）。 */
+	supported: boolean;
+	/** parse 到的 cw 版本号（如 "1.6.1"），parse 失败 = undefined。 */
+	version: string | undefined;
+	/** 不支持/失败的简要原因（日志/调试用）。 */
+	reason?: string;
+}
+
+/**
+ * 进程内 memoize 缓存：全局单值（cw --version 输出与 cwd 无关，cw-cli 安装版本在进程
+ * 生命周期内不变，按 cwd 做 key 多余）。首次探测后整个进程复用；测试用
+ * {@link _resetCapabilityCacheForTest} 在 beforeEach 隔离。
+ */
+let cachedCapability: CwCliCapability | undefined;
+
+/** 测试用：重置 capability 缓存（全局单值，测试 beforeEach 隔离避免串台）。 */
+export function _resetCapabilityCacheForTest(): void {
+	cachedCapability = undefined;
+}
+
+/** 从 cw --version stdout 提取版本号（如 "cw 1.6.1" → [1,6,1]）。失败返回 undefined。 */
+function parseCwVersion(stdout: string): number[] | undefined {
+	const match = stdout.match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!match) return undefined;
+	return [Number.parseInt(match[1], 10), Number.parseInt(match[2], 10), Number.parseInt(match[3], 10)];
+}
+
+/** semver 三段比较：a < b → -1，a === b → 0，a > b → 1。 */
+function compareSemver(a: number[], b: number[]): number {
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+	}
+	return 0;
+}
+
+/**
+ * 探测 cw-cli 是否支持 store 内部归一化（门控）。
+ *
+ * 用 spawner 跑 `cw --version`，parse 版本号与 {@link MIN_CW_CLI_VERSION_FOR_NORMALIZATION}
+ * 比较。失败（spawn 失败/parse 不到/超时）→ supported:false（fail-safe，兜底 ADR-0045 行为）。
+ * 进程内 memoize（全局单值，cw 版本 cwd 无关）：首次探测后缓存，消除重复 spawn。
+ *
+ * @param parentSignal 调用方 SDK abort signal，与内部 5s 超时合并转发给 spawner（S-4）：
+ *   任一 abort 即 abort，让卡死的 `cw --version` 尽快收尾。
+ */
+export async function probeCwCliNormalization(
+	spawner: CwSpawner,
+	cwd: string,
+	parentSignal?: AbortSignal,
+): Promise<CwCliCapability> {
+	if (cachedCapability) return cachedCapability;
+
+	const minVersion = parseCwVersion(MIN_CW_CLI_VERSION_FOR_NORMALIZATION);
+	if (!minVersion) {
+		// placeholder 本身非法（不应发生）——保守不支持
+		const fallback: CwCliCapability = { supported: false, version: undefined, reason: "MIN_CW_CLI_VERSION_FOR_NORMALIZATION 非法" };
+		cachedCapability = fallback;
+		return fallback;
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), CW_VERSION_PROBE_TIMEOUT_MS);
+	// 合并调用方 SDK signal：任一 abort（5s 超时 fail-safe 或调用方主动 abort）即 abort（S-4）。
+	const onParentAbort = (): void => controller.abort();
+	if (parentSignal) {
+		if (parentSignal.aborted) controller.abort();
+		else parentSignal.addEventListener("abort", onParentAbort, { once: true });
+	}
+	let result: CwCliCapability;
+	try {
+		const spawnResult = await spawner(["--version"], undefined, cwd, controller.signal);
+		if (spawnResult.exitCode !== 0) {
+			result = { supported: false, version: undefined, reason: `cw --version exit ${spawnResult.exitCode ?? "null"}` };
+		} else {
+			const v = parseCwVersion(spawnResult.stdout);
+			if (!v) {
+				result = { supported: false, version: undefined, reason: `version parse fail: ${spawnResult.stdout.trim().slice(0, VERSION_REASON_MAX_LEN)}` };
+			} else {
+				const supported = compareSemver(v, minVersion) >= 0;
+				result = { supported, version: v.join("."), reason: supported ? undefined : `version ${v.join(".")} < ${MIN_CW_CLI_VERSION_FOR_NORMALIZATION}` };
+			}
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		result = { supported: false, version: undefined, reason: `probe failed: ${msg}` };
+	} finally {
+		clearTimeout(timer);
+		if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
+	}
+
+	cachedCapability = result;
+	return result;
+}
+
 /** input / inputFile 互斥校验。 */
 export function rejectConflictingInput(opts: CwToolOptions): string | undefined {
 	if (opts.input !== undefined && opts.inputFile !== undefined) {
@@ -220,9 +336,17 @@ export async function executeCwAction(
 	const unitIdErr = rejectMissingUnitId(action, unitId);
 	if (unitIdErr) return { ok: false, ...base, error: unitIdErr };
 
-	// repo 级 workspace（ADR-0045）：仅写 action 附加（S-3：只读 action 保守不加，避免 cw 子命令
-	// 拒收未知选项导致 readonly 查询失败）；cwd 在 git repo 内才探测，探测失败静默跳过。
-	const workspace = isReadonlyAction(action) ? undefined : detectRepoWorkspace(cwd);
+	// workspace 门控（差异文档 §3 §4 + ADR-0045 Superseded）：cw-cli 支持 store 内部归一化
+	// （probe 版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION）→ 纯封装不传 --workspace；
+	// 不支持 → 兜底 ADR-0045 的 detectRepoWorkspace + --workspace（保持向后兼容）。
+	// 只读 action 始终不传（S-3：保守避免 cw 子命令拒收未知选项导致 readonly 查询失败）。
+	let workspace: string | undefined;
+	if (isReadonlyAction(action)) {
+		workspace = undefined;
+	} else {
+		const capability = await probeCwCliNormalization(spawner, cwd, signal);
+		workspace = capability.supported ? undefined : detectRepoWorkspace(cwd);
+	}
 	const args = buildCwArgs(action, unitId, opts, workspace);
 	const stdinPayload = opts.input !== undefined ? opts.input : undefined;