@zhushanwen/pi-goal 0.9.4 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.9.4",
+  "version": "0.11.0",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",
@@ -29,10 +29,10 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.5"
+    "@zhushanwen/pi-pending-notifications": "0.5.0"
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.6.0"
+    "@xyz-agent/extension-protocol": "0.7.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/src/__tests__/command-adapter.test.ts

@@ -18,6 +18,7 @@ import {
 	OBJECTIVE_DISPLAY_LIMIT,
 	OBJECTIVE_TRUNCATE_KEEP,
 } from "../constants";
+import { parseGoalArgs } from "../commands";
 import { createGoalState } from "../engine/goal";
 import type { GoalRuntimeState } from "../engine/types";
 import type { GoalHistoryEntry, SessionEntryLike } from "../ports";
@@ -139,6 +140,19 @@ describe("handleGoalCommand — status", () => {
 		expect(text).toContain("test objective");
 		expect(text).toContain("Status: active");
 	});
+
+	it("U23: successCriteria 逐条编号多行显示（不再 join(\"; \") 内联）", async () => {
+		const h = makeHarness();
+		const session = createGoalSession();
+		session.state = makeActiveState({ successCriteria: ["s1", "s2"] });
+		await handleGoalCommand(h.pi, session, "status", h.ctx);
+		const text = notifyText(h).join("\n");
+		expect(text).toContain("Success criteria:");
+		expect(text).toContain("1. s1");
+		expect(text).toContain("2. s2");
+		// 旧形态（分号拼接内联一行）不再出现
+		expect(text).not.toContain("s1; s2");
+	});
 });
 
 // ── /goal pause（FR-3 用户暂停 active→paused）──
@@ -291,12 +305,72 @@ describe("handleGoalCommand — update (FR-8.4 G-002)", () => {
 		const session = createGoalSession();
 		session.state = makeActiveState({
 			objective: "old objective",
-			successCriteria: "old criteria",
+			successCriteria: ["old criteria"],
 		});
 		await handleGoalCommand(h.pi, session, "update new obj --criteria new criteria text", h.ctx);
 
 		expect(session.state!.objective).toBe("new obj");
-		expect(session.state!.successCriteria).toBe("new criteria text");
+		// /goal update --criteria 按分号拆分为 string[]
+		expect(session.state!.successCriteria).toEqual(["new criteria text"]);
+	});
+
+	it("U22: --criteria 多条（分号分隔）→ 数组直赋值替换", async () => {
+		const h = makeHarness();
+		const session = createGoalSession();
+		session.state = makeActiveState({
+			objective: "old objective",
+			successCriteria: ["old criteria"],
+		});
+		await handleGoalCommand(h.pi, session, "update new obj --criteria new a; new b", h.ctx);
+
+		expect(session.state!.successCriteria).toEqual(["new a", "new b"]);
+	});
+
+	it("U22 决策④: --criteria 拆分后全空（;;）→ 保留旧值（不写入 [\";;\"] 等非法数组）", async () => {
+		const h = makeHarness();
+		const session = createGoalSession();
+		session.state = makeActiveState({
+			objective: "old objective",
+			successCriteria: ["old criteria"],
+		});
+		await handleGoalCommand(h.pi, session, "update new obj --criteria ;;", h.ctx);
+
+		expect(session.state!.objective).toBe("new obj");
+		expect(session.state!.successCriteria).toEqual(["old criteria"]);
+	});
+
+	it("U22 决策④: --criteria 值拆分后全空（空格分号）→ 保留旧值", async () => {
+		const h = makeHarness();
+		const session = createGoalSession();
+		session.state = makeActiveState({
+			objective: "old objective",
+			successCriteria: ["old criteria"],
+		});
+		// 注：纯尾随空白（`--criteria  `）在 parse 层被 trim 后 flag 不匹配、
+		// 并入 objective（既有语义）；此处用「分隔符后仅空白+分号」构造拆分后全空
+		await handleGoalCommand(h.pi, session, "update new obj --criteria  ;", h.ctx);
+
+		expect(session.state!.objective).toBe("new obj");
+		expect(session.state!.successCriteria).toEqual(["old criteria"]);
+	});
+
+	it("U22: 条目含换行 → throw 带 Correct: 正例，且 state 重塑字段不动（校验前置）", async () => {
+		const h = makeHarness();
+		const session = createGoalSession();
+		session.state = makeActiveState({
+			objective: "old objective",
+			slug: "old-slug",
+			successCriteria: ["old criteria"],
+		});
+		// 单段内含换行（无分号）→ parse 拆为一条含 \n 的条目，handleUpdate 校验拒绝
+		await expect(
+			handleGoalCommand(h.pi, session, "update new obj --criteria line1\nline2", h.ctx),
+		).rejects.toThrow(/single-line[\s\S]*Correct:/);
+
+		expect(session.state!.objective).toBe("old objective");
+		expect(session.state!.slug).toBe("old-slug");
+		expect(session.state!.successCriteria).toEqual(["old criteria"]);
+		expect(h.states).toHaveLength(0); // 未 persist
 	});
 
 	it("不带 --criteria → 保留旧 successCriteria（不静默丢失验证标准）", async () => {
@@ -304,12 +378,12 @@ describe("handleGoalCommand — update (FR-8.4 G-002)", () => {
 		const session = createGoalSession();
 		session.state = makeActiveState({
 			objective: "old objective",
-			successCriteria: "old criteria",
+			successCriteria: ["old criteria"],
 		});
 		await handleGoalCommand(h.pi, session, "update new obj", h.ctx);
 
 		expect(session.state!.objective).toBe("new obj");
-		expect(session.state!.successCriteria).toBe("old criteria");
+		expect(session.state!.successCriteria).toEqual(["old criteria"]);
 	});
 
 	it("active 状态重塑 → 注入 objectiveUpdated steering", async () => {
@@ -322,6 +396,32 @@ describe("handleGoalCommand — update (FR-8.4 G-002)", () => {
 	});
 });
 
+// ── parseGoalArgs — --criteria 分号拆分（U20/U21）──
+
+describe("parseGoalArgs — --criteria 分号拆分（U20/U21）", () => {
+	it("U20: 分号多段 → 逐段 trim + 去空段（\"a; b; c\" → [\"a\",\"b\",\"c\"]）", () => {
+		const parsed = parseGoalArgs("update new obj --criteria a; b; c");
+		expect(parsed.action).toBe("update");
+		expect(parsed.objective).toBe("new obj");
+		expect(parsed.criteria).toEqual(["a", "b", "c"]);
+	});
+
+	it("U20: 单段 → 单元素数组（\"single\" → [\"single\"]）", () => {
+		const parsed = parseGoalArgs("update new obj --criteria single");
+		expect(parsed.criteria).toEqual(["single"]);
+	});
+
+	it("U21: 连续分号 → 空段被过滤（\"a;;b\" → [\"a\",\"b\"]）", () => {
+		const parsed = parseGoalArgs("update new obj --criteria a;;b");
+		expect(parsed.criteria).toEqual(["a", "b"]);
+	});
+
+	it("U21 决策④: 拆分后全空（\";;\"）→ criteria undefined（不产出空数组）", () => {
+		const parsed = parseGoalArgs("update new obj --criteria ;;");
+		expect(parsed.criteria).toBeUndefined();
+	});
+});
+
 // ── /goal set（提示词触发器：sendUserMessage 让 AI 调 goal_control create）──
 
 describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终态)", () => {

package/src/__tests__/criteria-array-adapter.test.ts

@@ -0,0 +1,213 @@
+/**
+ * goal_control adapter — successCriteria string[] handler 测试
+ *
+ * W1：handleCreate 接收 string[] 类型的 successCriteria，验证：
+ * - 数组存入 state
+ * - 空数组/空串项 → throw
+ * - 完整字段后 state.successCriteria 为 string[]
+ */
+import { describe, expect, it } from "vitest";
+import { Value } from "typebox/value";
+
+import { GoalControlParams, handleCreate, type GoalControlParamsT } from "../adapters/goal-control-adapter";
+import type { GoalRuntimeState } from "../engine/types";
+import type { UiPort } from "../ports";
+import type { ServicePorts } from "../service";
+import { createGoalSession } from "../session";
+
+function makeFakePorts(): ServicePorts & {
+	states: GoalRuntimeState[];
+	history: unknown[];
+	notifications: Array<{ text: string; level: string }>;
+} {
+	const states: GoalRuntimeState[] = [];
+	const history: unknown[] = [];
+	const notifications: Array<{ text: string; level: string }> = [];
+	return {
+		states,
+		history,
+		notifications,
+		persistence: {
+			appendState: (s) => { states.push(s); },
+			appendHistory: (e) => { history.push(e); },
+		},
+		ui: {
+			setWidget: () => {},
+			setStatus: () => {},
+			notify: (text, level) => { notifications.push({ text, level }); },
+			hasUI: true,
+			isGui: false,
+			setGuiWidget: () => {},
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		} as UiPort,
+		messaging: {
+			sendContextMessage: () => {},
+			sendUserMessage: () => {},
+		},
+		session: {
+			getEntries: () => [],
+			getContextUsage: () => null,
+			signal: undefined,
+		},
+	};
+}
+
+describe("handleCreate — successCriteria string[]", () => {
+	it("successCriteria string[] → state.successCriteria 为 string[]", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		const details = handleCreate(
+			{
+				action: "create",
+				slug: "test-goal",
+				objective: "do something",
+				successCriteria: ["criterion 1", "criterion 2", "criterion 3"],
+			},
+			session,
+			ports,
+		);
+
+		expect(details.action).toBe("create");
+		expect(details.status).toBe("active");
+		expect(session.state!.successCriteria).toEqual(["criterion 1", "criterion 2", "criterion 3"]);
+	});
+
+	it("successCriteria 空数组 → throw", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		expect(() =>
+			handleCreate(
+				{
+					action: "create",
+					objective: "do something",
+					successCriteria: [],
+				},
+				session,
+				ports,
+			),
+		).toThrow(/successCriteria/);
+	});
+
+	it("successCriteria 含空串项 → throw（U6：文案含 Correct: 恢复正例）", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		expect(() =>
+			handleCreate(
+				{
+					action: "create",
+					objective: "do something",
+					successCriteria: ["valid", "  ", "also valid"],
+				},
+				session,
+				ports,
+			),
+		).toThrow(/successCriteria[\s\S]*Correct:/);
+	});
+
+	it.each([
+		["LF", ["line1\nline2"]],
+		["CRLF", ["a\r\nb"]],
+		["孤立 CR", ["a\rb"]],
+	])("U7: 条目含换行（%s）→ throw 且文案含「单行」提示与 Correct: 正例", (_label, criteria) => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		expect(() =>
+			handleCreate(
+				{
+					action: "create",
+					objective: "do something",
+					successCriteria: criteria,
+				},
+				session,
+				ports,
+			),
+		).toThrow(/successCriteria[\s\S]*single-line[\s\S]*Correct:/);
+	});
+
+	it("U28②: 非 string 元素（绕过 schema 直调 handler）→ 业务 throw 含 Correct:，不产生 TypeError", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		// 直调 handler 绕过 schema 校验（测试/异常路径可能传入脏元素），断言运行时 typeof 防御
+		const dirtyParams = {
+			action: "create",
+			objective: "do something",
+			successCriteria: [1, null, true],
+		} as unknown as GoalControlParamsT;
+
+		expect(() => handleCreate(dirtyParams, session, ports)).toThrow(/successCriteria[\s\S]*Correct:/);
+		expect(() => handleCreate(dirtyParams, session, ports)).not.toThrow(TypeError);
+	});
+
+	it("U5b: 恰 1 条与恰 8 条（含 emoji/中文）→ schema 与 handleCreate 双层均不 throw，state 长度 1/8", () => {
+		// 恰 8 条，含 emoji/中文（pattern ^[^\r\n]+$ 不误杀多字节字符）
+		const eight = [
+			"通过测试✅",
+			"条件二：构建成功",
+			"tsc --noEmit clean",
+			"文件 X 存在且含内容 Y",
+			"docs updated 📄",
+			"review done",
+			"no regressions",
+			"ship it 🚀",
+		];
+
+		// schema 层：minItems:1 / maxItems:8 边界正值
+		expect(
+			Value.Check(GoalControlParams, {
+				action: "create",
+				objective: "do something",
+				successCriteria: ["single"],
+			}),
+		).toBe(true);
+		expect(
+			Value.Check(GoalControlParams, {
+				action: "create",
+				objective: "do something",
+				successCriteria: eight,
+			}),
+		).toBe(true);
+
+		// handleCreate 直调层：均不 throw，state 数组长度 1/8
+		const session1 = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", objective: "do something", successCriteria: ["single"] },
+				session1,
+				makeFakePorts(),
+			),
+		).not.toThrow();
+		expect(session1.state!.successCriteria).toHaveLength(1);
+
+		const session8 = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", objective: "do something", successCriteria: eight },
+				session8,
+				makeFakePorts(),
+			),
+		).not.toThrow();
+		expect(session8.state!.successCriteria).toHaveLength(8);
+	});
+
+	it("successCriteria undefined → throw", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		expect(() =>
+			handleCreate(
+				{
+					action: "create",
+					objective: "do something",
+				},
+				session,
+				ports,
+			),
+		).toThrow(/successCriteria.*required/);
+	});
+});

package/src/__tests__/criteria-array-migration.test.ts

@@ -0,0 +1,146 @@
+/**
+ * successCriteria 结构化迁移测试 — string → string[]
+ *
+ * W1：successCriteria 从单条自由文本 string 结构化为条件数组 string[]
+ *（1~8 条、每条单行短条件）。旧持久化数据兼容迁移：按行拆分（/\r\n|\r|\n/）、
+ * 逐条 trim、去空行，空态归一 undefined，脏数据防御性丢弃（plan 决策①②③⑤）。
+ */
+import { describe, expect, it } from "vitest";
+
+import { deserializeState, makeHistoryEntry, serializeState } from "../persistence";
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+
+// ── 旧数据 fixture 工厂 ───────────────────────────────
+
+/** 构造含指定 successCriteria 的旧持久化数据（其余必填字段齐全）。 */
+function makeLegacyData(successCriteria: unknown): Record<string, unknown> {
+	return {
+		goalId: "g1",
+		objective: "test",
+		status: "active",
+		successCriteria,
+		tokensUsed: 0,
+		timeStartedAt: 1000,
+		timeUsedSeconds: 0,
+		budget: {},
+		lastProgressTurn: 0,
+		budgetLimitSteeringSent: false,
+		objectiveUpdatedAt: 1000,
+		lastBlockerReason: null,
+		tokenWarning70Sent: false,
+		tokenWarning90Sent: false,
+		lastTurnTokensUsed: 0,
+		currentTurnIndex: 0,
+	};
+}
+
+// ── 类型断言辅助 ─────────────────────────────────────
+
+describe("GoalRuntimeState.successCriteria — string[] 类型", () => {
+	it("createGoalState 返回 string[] 类型的 successCriteria", () => {
+		const state = createGoalState("obj", undefined, undefined, ["criterion 1", "criterion 2"]);
+		expect(Array.isArray(state.successCriteria)).toBe(true);
+		expect(state.successCriteria).toEqual(["criterion 1", "criterion 2"]);
+	});
+
+	it("createGoalState 无 successCriteria → undefined", () => {
+		const state = createGoalState("obj");
+		expect(state.successCriteria).toBeUndefined();
+	});
+});
+
+// ── 持久化 round-trip（新格式 string[]）───────────────
+
+describe("serializeState / deserializeState — string[] round-trip", () => {
+	it("successCriteria string[] 正确 round-trip", () => {
+		const state = createGoalState("obj", undefined, "slug", ["a", "b", "c"]);
+		const serialized = serializeState(state);
+		const deserialized = deserializeState(serialized as unknown as Record<string, unknown>);
+		expect(deserialized.successCriteria).toEqual(["a", "b", "c"]);
+	});
+
+	it("successCriteria undefined 正确 round-trip", () => {
+		const state = createGoalState("obj");
+		const serialized = serializeState(state);
+		const deserialized = deserializeState(serialized as unknown as Record<string, unknown>);
+		expect(deserialized.successCriteria).toBeUndefined();
+	});
+
+	it("makeHistoryEntry 数组 round-trip 深相等（U15b：history 数据数组形态不丢）", () => {
+		const state = createGoalState("obj", undefined, "slug", ["a", "b"]);
+		const entry = makeHistoryEntry(state);
+		// history entry 经 JSON 序列化（appendHistory 落盘）→ 反序列化后仍为同形态数组
+		const restored = JSON.parse(JSON.stringify(entry)) as { successCriteria?: string[] };
+		expect(restored.successCriteria).toEqual(["a", "b"]);
+	});
+});
+
+// ── 旧持久化数据迁移（string → string[]，按行拆分）────
+
+describe("deserializeState — 旧数据迁移 string → string[]（按行拆分）", () => {
+	it("U10: 单行 string → 单元素数组", () => {
+		const state = deserializeState(makeLegacyData("tests pass"));
+		expect(state.successCriteria).toEqual(["tests pass"]);
+	});
+
+	it("U11: 多行 string（含空白与空行）→ 逐条 trim、去空行", () => {
+		const state = deserializeState(makeLegacyData("a\n b \n\nc"));
+		expect(state.successCriteria).toEqual(["a", "b", "c"]);
+	});
+
+	it("U11b: CRLF 与混合换行均正确拆分（无 \\r 残留）", () => {
+		expect(deserializeState(makeLegacyData("cond-1\r\ncond-2\r\ncond-3")).successCriteria).toEqual([
+			"cond-1",
+			"cond-2",
+			"cond-3",
+		]);
+		expect(deserializeState(makeLegacyData("a\nb\r\nc\rd")).successCriteria).toEqual(["a", "b", "c", "d"]);
+	});
+
+	it("U11c: 纯分隔符（\\r\\n / \\r / \\n）→ undefined（空态归一）", () => {
+		expect(deserializeState(makeLegacyData("\r\n")).successCriteria).toBeUndefined();
+		expect(deserializeState(makeLegacyData("\r")).successCriteria).toBeUndefined();
+		expect(deserializeState(makeLegacyData("\n")).successCriteria).toBeUndefined();
+	});
+
+	it("U12: 新格式 string[] → 原样保留（不二次拆分、不 trim）", () => {
+		const state = deserializeState(makeLegacyData(["item a", "item b"]));
+		expect(state.successCriteria).toEqual(["item a", "item b"]);
+	});
+
+	it("U12: 缺 successCriteria 字段 → undefined", () => {
+		const data = makeLegacyData(undefined);
+		delete data.successCriteria;
+		expect(deserializeState(data).successCriteria).toBeUndefined();
+	});
+
+	it("U13: 旧 string 拆分后 10 条 → 全部保留不截断（迁移不丢数据）", () => {
+		const tenLines = Array.from({ length: 10 }, (_, i) => `cond ${i + 1}`).join("\n");
+		const state = deserializeState(makeLegacyData(tenLines));
+		expect(state.successCriteria).toHaveLength(10);
+		expect(state.successCriteria).toEqual(Array.from({ length: 10 }, (_, i) => `cond ${i + 1}`));
+	});
+
+	it("U14: 全空白 string（含空串）→ undefined（空态归一）", () => {
+		expect(deserializeState(makeLegacyData(" \n ")).successCriteria).toBeUndefined();
+		expect(deserializeState(makeLegacyData("   ")).successCriteria).toBeUndefined();
+		expect(deserializeState(makeLegacyData("")).successCriteria).toBeUndefined();
+	});
+
+	it("U14b: 脏数据类型 → 防御性丢弃为 undefined（不 throw）", () => {
+		for (const dirty of [42, null, true, ["a", ["b", "c"]], ["a", null]]) {
+			const state = deserializeState(makeLegacyData(dirty));
+			expect(state.successCriteria).toBeUndefined();
+		}
+	});
+});
+
+// ── makeHistoryEntry 类型链 ──────────────────────────
+
+describe("makeHistoryEntry — 数组形态透传", () => {
+	it("state.successCriteria 数组透传到 entry（类型链不变形）", () => {
+		const state = createGoalState("obj", undefined, "slug", ["x", "y"]) as GoalRuntimeState;
+		expect(makeHistoryEntry(state).successCriteria).toEqual(["x", "y"]);
+	});
+});

package/src/__tests__/criteria-array-prompt-guidance.test.ts

@@ -0,0 +1,145 @@
+/**
+ * goal_control prompt guidance — successCriteria 三层引导文本独立 prompt-lock
+ *
+ * W1（plan U24）：粒度约束分布在三层，每层独立锁死，删掉任一层约束本文件对应 describe 必红：
+ * 1. 参数层：GoalControlParams.successCriteria 的 schema description（导出对象直读）
+ * 2. 工具层：registerGoalControlTool 工具 description 的 create 段（源码文本切片）
+ * 3. guidelines 层：promptGuidelines 的 create 条目（源码文本按赋值块切片）
+ *
+ * 为什么源码文本断言：description / promptGuidelines 内联在 registerGoalControlTool、
+ * 未导出常量；按变量边界切片（marker 定位 + 范围内断言），禁止跨块 [\s\S]*? 全文穿越——
+ * 否则删掉某层约束后其余层文本仍能命中，测试假绿（review 发现的历史缺陷）。
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { GoalControlParams } from "../adapters/goal-control-adapter";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ADAPTER_SRC = readFileSync(
+	join(__dirname, "../adapters/goal-control-adapter.ts"),
+	"utf-8",
+);
+
+/** 按 marker 切片（含 start，不含 end）。marker 缺失时抛可定位错误，防切片静默错位。 */
+function sliceBetween(src: string, startMarker: string, endMarker: string): string {
+	const start = src.indexOf(startMarker);
+	if (start === -1) {
+		throw new Error(`start marker not found in goal-control-adapter.ts: ${startMarker}`);
+	}
+	const end = src.indexOf(endMarker, start + startMarker.length);
+	if (end === -1) {
+		throw new Error(`end marker "${endMarker}" not found after "${startMarker}" in goal-control-adapter.ts`);
+	}
+	return src.slice(start, end);
+}
+
+// ── 第 1 层切片：参数 schema（从模块导出直读，非文本匹配）──────
+
+const successCriteriaSchema = GoalControlParams.properties.successCriteria;
+const PARAM_DESCRIPTION =
+	typeof successCriteriaSchema.description === "string" ? successCriteriaSchema.description : "";
+
+// ── 第 2 层切片：工具 description 模板字面量（"description: `" 到闭合反引号）──
+
+const TOOL_DESCRIPTION = sliceBetween(ADAPTER_SRC, "description: `", "`");
+// create 段：从 "- create：" 行首到 "- complete：" 行首（同在 description 块内）
+const TOOL_DESCRIPTION_CREATE_SEGMENT = sliceBetween(TOOL_DESCRIPTION, "- create：", "- complete：");
+
+// ── 第 3 层切片：promptGuidelines 赋值块 ─────────────────────
+// 闭合 "]" 不能用 indexOf 找——块内 guideline 文本自身含 "string[]" 的 "]"，
+// 故按行扫描 trim() === "]," 的行作块尾（缩进无关）。
+
+function extractPromptGuidelinesBlock(src: string): string {
+	const startMarker = "promptGuidelines: [";
+	const start = src.indexOf(startMarker);
+	if (start === -1) {
+		throw new Error(`start marker not found in goal-control-adapter.ts: ${startMarker}`);
+	}
+	const blockLines: string[] = [];
+	for (const line of src.slice(start).split("\n")) {
+		blockLines.push(line);
+		if (line.trim() === "],") return blockLines.join("\n");
+	}
+	throw new Error('promptGuidelines block closing "]," line not found in goal-control-adapter.ts');
+}
+
+const PROMPT_GUIDELINES_BLOCK = extractPromptGuidelinesBlock(ADAPTER_SRC);
+// create 条目：块内以 `"create:` 开头的单行 guideline（源码中每条 guideline 独占一行）
+const CREATE_GUIDELINE_LINE = PROMPT_GUIDELINES_BLOCK.split("\n").find((line) =>
+	line.trim().startsWith('"create:'),
+);
+if (CREATE_GUIDELINE_LINE === undefined) {
+	throw new Error('create guideline line not found in promptGuidelines block of goal-control-adapter.ts');
+}
+
+// ── 第 1 层：successCriteria 参数 schema description ─────────
+
+describe("第 1 层：successCriteria 参数 schema description（粒度约束）", () => {
+	it("schema 结构为 string[]（type: array + items type: string）", () => {
+		expect(successCriteriaSchema.type).toBe("array");
+		expect(successCriteriaSchema.items.type).toBe("string");
+	});
+
+	it("description 含条数区间语义（1~8 条，与 minItems/maxItems 对齐）", () => {
+		expect(PARAM_DESCRIPTION).toMatch(/1~8\s*条/);
+	});
+
+	it("description 含每条单行短条件语义", () => {
+		expect(PARAM_DESCRIPTION).toContain("单行");
+	});
+
+	it("description 含数组语义（完成条件数组）", () => {
+		expect(PARAM_DESCRIPTION).toContain("完成条件数组");
+	});
+
+	it("description 含高层终态条件语义（非愿景、非细粒度清单）", () => {
+		expect(PARAM_DESCRIPTION).toContain("高层终态条件");
+		expect(PARAM_DESCRIPTION).toContain("不是愿景");
+	});
+
+	it("description 含只引用不复制 + 禁止倾倒完整规格语义", () => {
+		expect(PARAM_DESCRIPTION).toContain("细粒度检查清单放 todo/plan");
+		expect(PARAM_DESCRIPTION).toContain("只引用不复制");
+		expect(PARAM_DESCRIPTION).toContain("禁止倾倒完整规格");
+	});
+});
+
+// ── 第 2 层：工具 description create 段 ─────────────────────
+
+describe("第 2 层：工具 description create 段（粒度约束）", () => {
+	it("create 段含 successCriteria 条数约束（3~8 条高层终态条件）", () => {
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toContain("successCriteria");
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toMatch(/3~8\s*条/);
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toContain("高层终态条件");
+	});
+
+	it("create 段含细粒度清单只引用不复制语义", () => {
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toContain("细粒度检查清单放 todo/plan");
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toContain("只引用不复制");
+	});
+
+	it("create 段含禁止倾倒完整规格语义", () => {
+		expect(TOOL_DESCRIPTION_CREATE_SEGMENT).toContain("禁止倾倒完整规格");
+	});
+});
+
+// ── 第 3 层：promptGuidelines create 条目 ────────────────────
+
+describe("第 3 层：promptGuidelines create 条目（粒度约束）", () => {
+	it("create 条目含 3~8 条高层终态条件 + string[] 语义", () => {
+		expect(CREATE_GUIDELINE_LINE).toMatch(/3~8 high-level terminal conditions as string\[\]/);
+	});
+
+	it("create 条目含细粒度清单只引用不复制语义（reference, do not copy）", () => {
+		expect(CREATE_GUIDELINE_LINE).toContain("Fine-grained checklists belong in todo/plan");
+		expect(CREATE_GUIDELINE_LINE).toContain("reference them, do not copy");
+	});
+
+	it("create 条目含禁止倾倒完整规格语义（Do NOT dump full specs）", () => {
+		expect(CREATE_GUIDELINE_LINE).toContain("Do NOT dump full specs into successCriteria");
+	});
+});