@zhushanwen/pi-goal 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -22,9 +22,9 @@
     "index.ts"
   ],
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
     "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "@mariozechner/pi-coding-agent": "*",
     "@sinclair/typebox": "*"
   },
   "peerDependenciesMeta": {
@@ -36,6 +36,10 @@
     }
   },
   "scripts": {
-    "typecheck": "npx tsc --noEmit"
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
   }
 }

package/src/__tests__/deserialize-state.test.ts

@@ -0,0 +1,109 @@
+/**
+ * P1 测试：deserializeState — 旧格式向后兼容
+ */
+import { describe, expect, it } from "vitest";
+
+import { deserializeState } from "../state";
+
+describe("deserializeState — 向后兼容", () => {
+	it("旧数据无 verification 字段 → verification 为 undefined", () => {
+		const data = {
+			goalId: "g1",
+			objective: "test",
+			status: "active",
+			tasks: [{
+				id: 1,
+				description: "task 1",
+				status: "completed",
+				lastUpdatedTurn: 0,
+			}],
+			stallCount: 0,
+			tokensUsed: 0,
+			timeStartedAt: 1000,
+			timeUsedSeconds: 0,
+			budget: { maxStallTurns: 5, maxTurns: 50 },
+		};
+		const state = deserializeState(data);
+		expect(state.tasks[0]!.verification).toBeUndefined();
+	});
+
+	it("旧数据有 turnCount 字段 → 被忽略（不报错）", () => {
+		const data = {
+			goalId: "g1",
+			objective: "test",
+			status: "active",
+			tasks: [],
+			stallCount: 0,
+			tokensUsed: 0,
+			timeStartedAt: 1000,
+			timeUsedSeconds: 0,
+			budget: { maxStallTurns: 5, maxTurns: 50 },
+			turnCount: 42,
+		};
+		const state = deserializeState(data);
+		expect(state.currentTurnIndex).toBe(0);
+		// turnCount 不存在于 GoalRuntimeState 接口
+		expect("turnCount" in state).toBe(false);
+	});
+
+	it("新数据有 verification 字段 → 正确还原", () => {
+		const data = {
+			goalId: "g1",
+			objective: "test",
+			status: "active",
+			tasks: [{
+				id: 1,
+				description: "task 1",
+				status: "completed",
+				lastUpdatedTurn: 5,
+				verification: { method: "pnpm test", expected: "all pass", actual: "passed" },
+			}],
+			stallCount: 0,
+			tokensUsed: 0,
+			timeStartedAt: 1000,
+			timeUsedSeconds: 0,
+			budget: { maxStallTurns: 5, maxTurns: 50 },
+		};
+		const state = deserializeState(data);
+		expect(state.tasks[0]!.verification).toEqual({
+			method: "pnpm test",
+			expected: "all pass",
+			actual: "passed",
+		});
+	});
+
+	it("旧数据 verified 状态的 task → 正常加载", () => {
+		const data = {
+			goalId: "g1",
+			objective: "test",
+			status: "active",
+			tasks: [{
+				id: 1,
+				description: "task 1",
+				status: "verified",
+				lastUpdatedTurn: 3,
+			}],
+			stallCount: 0,
+			tokensUsed: 0,
+			timeStartedAt: 1000,
+			timeUsedSeconds: 0,
+			budget: { maxStallTurns: 5, maxTurns: 50 },
+		};
+		const state = deserializeState(data);
+		expect(state.tasks[0]!.status).toBe("verified");
+	});
+
+	it("缺少字段时给默认值", () => {
+		const data = {
+			goalId: "g1",
+			objective: "test",
+			status: "active",
+			tasks: [],
+		};
+		const state = deserializeState(data);
+		expect(state.stallCount).toBe(0);
+		expect(state.tokensUsed).toBe(0);
+		expect(state.budget.maxTurns).toBe(50);
+		expect(state.budget.maxStallTurns).toBe(5);
+	});
+});

package/src/__tests__/is-task-done.test.ts

@@ -0,0 +1,43 @@
+/**
+ * P0 测试：isTaskDone — 业务语义的"完成"判定
+ */
+import { describe, expect, it } from "vitest";
+
+import { type GoalTask, isTaskDone } from "../state";
+
+const makeTask = (overrides: Partial<GoalTask> = {}): GoalTask => ({
+	id: 1,
+	description: "test task",
+	status: "pending",
+	lastUpdatedTurn: 0,
+	...overrides,
+});
+
+describe("isTaskDone", () => {
+	it("verified task → done", () => {
+		expect(isTaskDone(makeTask({ status: "verified" }))).toBe(true);
+	});
+
+	it("cancelled task → done", () => {
+		expect(isTaskDone(makeTask({ status: "cancelled" }))).toBe(true);
+	});
+
+	it("completed without verification → done", () => {
+		expect(isTaskDone(makeTask({ status: "completed" }))).toBe(true);
+	});
+
+	it("completed with verification awaiting → NOT done", () => {
+		expect(isTaskDone(makeTask({
+			status: "completed",
+			verification: { method: "pnpm test", expected: "all pass" },
+		}))).toBe(false);
+	});
+
+	it("pending → NOT done", () => {
+		expect(isTaskDone(makeTask({ status: "pending" }))).toBe(false);
+	});
+
+	it("in_progress → NOT done", () => {
+		expect(isTaskDone(makeTask({ status: "in_progress" }))).toBe(false);
+	});
+});

package/src/__tests__/stubs/pi-sdk.ts

@@ -0,0 +1,11 @@
+/**
+ * Pi SDK stub for vitest — 提供运行时 mock，避免 import 真实的 Pi 包
+ */
+
+// StringEnum: 返回 values 的 union type 的 runtime 值（简化为第一个元素）
+export function StringEnum<T extends readonly string[]>(values: T, _options?: Record<string, unknown>): T[number] {
+	return values[0] as T[number];
+}
+
+// Pi SDK types used in import chains — re-export as empty
+export {};

package/src/__tests__/stubs/typebox.ts

@@ -0,0 +1,14 @@
+/**
+ * typebox stub for vitest — 只需要 Type.Object/String/Array/Number/Optional/StringEnum 等
+ * 被 tool-handler.ts import 链拉入，测试中不实际调用 schema 验证
+ */
+export const Type = {
+	Object: (_schema: unknown) => ({}),
+	String: (_opts?: unknown) => ({}),
+	Number: (_opts?: unknown) => ({}),
+	Array: (_item: unknown, _opts?: unknown) => ([]),
+	Optional: (_item: unknown) => ({}),
+	Boolean: (_opts?: unknown) => ({}),
+};
+
+export type Static<_T> = Record<string, unknown>;

package/src/__tests__/validate-update-tasks.test.ts

@@ -0,0 +1,172 @@
+/**
+ * P0 测试：validateUpdateTasks — 状态转换验证
+ */
+import { describe, expect, it } from "vitest";
+
+import { validateUpdateTasks } from "../action-handlers";
+import { type GoalRuntimeState, type GoalTask } from "../state";
+
+const makeState = (tasks: GoalTask[]): GoalRuntimeState => ({
+	goalId: "test",
+	objective: "test",
+	status: "active",
+	tasks,
+	stallCount: 0,
+	tokensUsed: 0,
+	timeStartedAt: Date.now(),
+	timeUsedSeconds: 0,
+	budget: { maxStallTurns: 5, maxTurns: 50 },
+	lastProgressTurn: 0,
+	budgetLimitSteeringSent: false,
+	objectiveUpdatedAt: Date.now(),
+	lastBlockerReason: null,
+	budgetWarning70Sent: false,
+	budgetWarning90Sent: false,
+	lastTurnTokensUsed: 0,
+	currentTurnIndex: 1,
+});
+
+const makeTask = (overrides: Partial<GoalTask> = {}): GoalTask => ({
+	id: 1,
+	description: "test task",
+	status: "pending",
+	lastUpdatedTurn: 0,
+	...overrides,
+});
+
+describe("validateUpdateTasks — 合法转换", () => {
+	it("pending → in_progress ✓", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "in_progress" }]);
+		expect(err).toBeNull();
+	});
+
+	it("pending → cancelled ✓", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "cancelled" }]);
+		expect(err).toBeNull();
+	});
+
+	it("in_progress → completed (有 evidence) ✓", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "completed", evidence: "done" }]);
+		expect(err).toBeNull();
+	});
+
+	it("in_progress → cancelled ✓", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "cancelled" }]);
+		expect(err).toBeNull();
+	});
+
+	it("completed(有 verification) → verified (有 actual) ✓", () => {
+		const state = makeState([makeTask({
+			id: 1,
+			status: "completed",
+			verification: { method: "pnpm test", expected: "pass" },
+		})]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "verified", actual: "all pass" }]);
+		expect(err).toBeNull();
+	});
+});
+
+describe("validateUpdateTasks — 非法转换", () => {
+	it("pending → completed (应先走 in_progress)", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "completed", evidence: "done" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("pending → verified (不能跳过)", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "verified", actual: "ok" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("in_progress → verified (不能跳过 completed)", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "verified", actual: "ok" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("in_progress → pending (不能回退)", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "pending" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("completed(无 verification) → 任何状态 (终态不可变)", () => {
+		const state = makeState([makeTask({ id: 1, status: "completed" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "in_progress" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("completed(有 verification) → 非 verified 状态", () => {
+		const state = makeState([makeTask({
+			id: 1,
+			status: "completed",
+			verification: { method: "pnpm test", expected: "pass" },
+		})]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "cancelled" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("verified → 任何状态 (终态不可变)", () => {
+		const state = makeState([makeTask({ id: 1, status: "verified" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "in_progress" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("cancelled → 任何状态 (终态不可变)", () => {
+		const state = makeState([makeTask({ id: 1, status: "cancelled" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "in_progress" }]);
+		expect(err).not.toBeNull();
+	});
+});
+
+describe("validateUpdateTasks — 必填检查", () => {
+	it("completed 缺 evidence → 错误", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "completed" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("completed evidence 为空字符串 → 错误", () => {
+		const state = makeState([makeTask({ id: 1, status: "in_progress" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "completed", evidence: "  " }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("verified 缺 actual → 错误", () => {
+		const state = makeState([makeTask({
+			id: 1,
+			status: "completed",
+			verification: { method: "pnpm test", expected: "pass" },
+		})]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "verified" }]);
+		expect(err).not.toBeNull();
+	});
+
+	it("verified 但 task 无 verification 配置 → 错误", () => {
+		const state = makeState([makeTask({ id: 1, status: "completed" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 1, status: "verified", actual: "ok" }]);
+		expect(err).not.toBeNull();
+	});
+});
+
+describe("validateUpdateTasks — 其他检查", () => {
+	it("重复 taskId → 错误", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [
+			{ taskId: 1, status: "in_progress" },
+			{ taskId: 1, status: "cancelled" },
+		]);
+		expect(err).not.toBeNull();
+	});
+
+	it("不存在的 taskId → 错误", () => {
+		const state = makeState([makeTask({ id: 1, status: "pending" })]);
+		const err = validateUpdateTasks(state, [{ taskId: 99, status: "in_progress" }]);
+		expect(err).not.toBeNull();
+	});
+});

package/src/action-handlers.ts

@@ -10,16 +10,19 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { Static } from "typebox";
 
-import { SECONDS_PER_MINUTE } from "./constants";
+import { ELLIPSIS_LENGTH, SECONDS_PER_MINUTE, TASK_DESC_MAX_LENGTH } from "./constants";
 import {
 	getCompletedCount,
 	getElapsedTimeSeconds,
 	getIncompleteTasks,
+	getNextTaskId,
 	type GoalRuntimeState,
 	type GoalTask,
 	isTerminalStatus,
 	isTerminalTaskStatus,
+	isTaskDone,
 	type Subtask,
+	type TaskVerification,
 	transitionStatus,
 } from "./state";
 import { formatTaskList } from "./templates";
@@ -31,6 +34,7 @@ import {
 	type GoalSession,
 	makeGoalResult,
 	persistGoalState,
+	sendGoalContextMessage,
 	writeGoalHistoryEntry,
 } from "./tool-handler";
 
@@ -60,15 +64,17 @@ export const handleCreateTasks: ActionHandler = ({ state, params, pi, session, c
 			`Already has ${state.tasks.length} tasks (${existingIncomplete.length} incomplete). Use add_tasks to append, or /goal update to re-plan.`,
 		);
 	}
+	const verifications = params.verifications;
 	state.tasks = params.tasks.map((desc: string, i: number) => ({
 		id: i + 1,
 		description: normalizeDescription(desc),
 		status: "pending" as const,
+		verification: verifications?.[i] as TaskVerification | undefined,
 		lastUpdatedTurn: state.currentTurnIndex,
 	}));
 	persistGoalState(pi, session, ctx);
 	return makeGoalResult(session,
-		`Created ${state.tasks.length} tasks:\n${state.tasks.map((t) => `  #${t.id}: ${t.description}`).join("\n")}`,
+		`Created ${state.tasks.length} tasks:\n${state.tasks.map((t) => `  #${t.id}: ${t.description}${t.verification ? ` [验证: ${t.verification.method}]` : ""}`).join("\n")}`,
 	);
 };
 
@@ -78,19 +84,19 @@ export const handleAddTasks: ActionHandler = ({ state, params, pi, session, ctx
 	if (!params.tasks || params.tasks.length === 0) {
 		return errorResult("add_tasks requires a non-empty tasks array");
 	}
-	const startId = state.tasks.length > 0
-		? Math.max(...state.tasks.map((t) => t.id)) + 1
-		: 1;
+	const startId = getNextTaskId(state.tasks);
+	const verifications = params.verifications;
 	const newTasks: GoalTask[] = params.tasks.map((desc: string, i: number) => ({
 		id: startId + i,
 		description: normalizeDescription(desc),
 		status: "pending" as const,
+		verification: verifications?.[i] as TaskVerification | undefined,
 		lastUpdatedTurn: state.currentTurnIndex,
 	}));
 	state.tasks.push(...newTasks);
 	persistGoalState(pi, session, ctx);
 	return makeGoalResult(session,
-		`Appended ${newTasks.length} tasks:\n${newTasks.map((t) => `  #${t.id}: ${t.description}`).join("\n")}`,
+		`Appended ${newTasks.length} tasks:\n${newTasks.map((t) => `  #${t.id}: ${t.description}${t.verification ? ` [验证: ${t.verification.method}]` : ""}`).join("\n")}`,
 	);
 };
 
@@ -102,7 +108,10 @@ export const handleUpdateTasks: ActionHandler = ({ state, params, pi, session, c
 	}
 	const validationErr = validateUpdateTasks(state, params.updates);
 	if (validationErr) return validationErr;
+
 	const results: string[] = [];
+	const tasksNeedingVerification: GoalTask[] = [];
+
 	for (const u of params.updates) {
 		const task = state.tasks.find((t) => t.id === u.taskId)!;
 		const prev = task.status;
@@ -111,17 +120,41 @@ export const handleUpdateTasks: ActionHandler = ({ state, params, pi, session, c
 			task.status = "completed";
 			task.evidence = u.evidence;
 			results.push(`#${task.id}: ${prev} → completed (${u.evidence})`);
+			if (task.verification) {
+				tasksNeedingVerification.push(task);
+			}
+		} else if (u.status === "verified") {
+			task.status = "verified";
+			task.verification!.actual = u.actual;
+			results.push(`#${task.id}: ${prev} → verified (actual: ${u.actual})`);
 		} else {
 			task.status = u.status;
 			results.push(`#${task.id}: ${prev} → ${u.status}`);
 		}
 	}
+
 	persistGoalState(pi, session, ctx);
-	return makeGoalResult(session, `Updated ${results.length} tasks:\n${results.join("\n")}`);
+	if (tasksNeedingVerification.length > 0) {
+		injectVerificationSteering(pi, tasksNeedingVerification);
+	}
+	return makeGoalResult(session, `Updated ${results.length} task actions:\n${results.join("\n")}`);
 };
 
+/** 注入 steering 提示 AI 对已完成的 task 执行验证命令。 */
+function injectVerificationSteering(pi: ExtensionAPI, tasks: GoalTask[]): void {
+	const lines = tasks.map((t) =>
+		`Task #${t.id} requires verification. Run: ${t.verification!.method} (expected: ${t.verification!.expected})\n` +
+		`Then call update_tasks with taskId=${t.id}, status="verified", actual=<result>.`
+	).join("\n\n");
+	sendGoalContextMessage(
+		pi,
+		`[GOAL Verification] Task(s) completed with verification pending:\n${lines}`,
+		"steer",
+	);
+}
+
 /** 验证 update_tasks 的所有更新项；返回首个错误或 null。 */
-function validateUpdateTasks(state: GoalRuntimeState, updates: NonNullable<Static<typeof GoalManagerParams>["updates"]>) {
+export function validateUpdateTasks(state: GoalRuntimeState, updates: NonNullable<Static<typeof GoalManagerParams>["updates"]>) {
 	const taskIds = updates.map((u: { taskId: number }) => u.taskId);
 	const duplicateIds = taskIds.filter((id: number, i: number) => taskIds.indexOf(id) !== i);
 	if (duplicateIds.length > 0) {
@@ -130,12 +163,44 @@ function validateUpdateTasks(state: GoalRuntimeState, updates: NonNullable<Stati
 	for (const u of updates) {
 		const task = state.tasks.find((t) => t.id === u.taskId);
 		if (!task) return errorResult(`Task #${u.taskId} not found`);
-		if (isTerminalTaskStatus(task.status)) {
-			return errorResult(`Task #${task.id} already in terminal state (${task.status}), cannot be changed`);
+
+		// 终态检查
+		if (task.status === "verified" || task.status === "cancelled") {
+			return errorResult(`Task #${task.id} in terminal state (${task.status}), cannot be changed`);
 		}
+		// completed 无 verification：不可变更
+		if (task.status === "completed" && !task.verification) {
+			return errorResult(`Task #${task.id} already completed, cannot be changed`);
+		}
+		// completed 有 verification：只允许 verified
+		if (task.status === "completed" && task.verification && u.status !== "verified") {
+			return errorResult(`Task #${task.id} completed but requires verification. Call update_tasks with status=verified.`);
+		}
+
+		// 合法转换检查
+		const validNext: Record<string, Set<string>> = {
+			pending: new Set(["in_progress", "cancelled"]),
+			in_progress: new Set(["completed", "cancelled"]),
+			completed: new Set(["verified"]),
+		};
+		const allowed = validNext[task.status];
+		if (!allowed || !allowed.has(u.status)) {
+			const hints: Record<string, string> = { pending: "allowed: in_progress or cancelled", in_progress: "allowed: completed or cancelled", completed: "allowed: verified (only if task has verification config)" };
+			return errorResult(`Task #${task.id}: invalid transition ${task.status} → ${u.status}. From ${task.status}, ${hints[task.status] ?? "no transitions allowed"}`);
+		}
+
+		// completed 必须有 evidence
 		if (u.status === "completed" && (!u.evidence || u.evidence.trim() === "")) {
 			return errorResult(`Task #${task.id}: completed requires evidence`);
 		}
+		// verified 必须有 actual
+		if (u.status === "verified" && (!u.actual || u.actual.trim() === "")) {
+			return errorResult(`Task #${task.id}: verified requires actual verification result`);
+		}
+		// verified 要求 task 有 verification 配置
+		if (u.status === "verified" && !task.verification) {
+			return errorResult(`Task #${task.id}: cannot verify a task without verification config`);
+		}
 	}
 	return null;
 }
@@ -155,14 +220,20 @@ export const handleCompleteGoal: ActionHandler = ({ state, params, pi, session,
 	if (state.tasks.length === 0) {
 		return errorResult("Create a task list with create_tasks before completing the goal.");
 	}
-	const incomplete = getIncompleteTasks(state.tasks);
-	if (incomplete.length > 0) {
+	// 检查所有 task 都已完成（含 verified、cancelled、无 verification 的 completed）
+	const notDone = state.tasks.filter((t) => !isTaskDone(t));
+	if (notDone.length > 0) {
+		const hint = notDone.some((t) => t.status === "completed" && t.verification)
+			? " Some completed tasks still require verification (status=verified)."
+			: "";
 		return errorResult(
-			`${incomplete.length} tasks still incomplete: ${incomplete.map((t) => `#${t.id}`).join(", ")}. Complete them first or explain why they don't need completion.`,
+			`${notDone.length} tasks not done: ${notDone.map((t) => `#${t.id}`).join(", ")}.${hint} Complete them first.`,
 		);
 	}
-	if (getCompletedCount(state.tasks) === 0) {
-		return errorResult("At least one task must be completed. All-cancelled does not count.");
+	// 至少一个 task 必须是 completed 或 verified（不能全 cancelled）
+	const completedOrVerified = state.tasks.filter((t) => t.status === "completed" || t.status === "verified");
+	if (completedOrVerified.length === 0) {
+		return errorResult("At least one task must be completed or verified. All-cancelled does not count.");
 	}
 	state.status = transitionStatus(state.status, "complete");
 	state.completedAtTurnIndex = state.currentTurnIndex;
@@ -237,8 +308,10 @@ export const handleAddSubtasks: ActionHandler = ({ state, params, pi, session, c
 	}
 	const parentTask = state.tasks.find((t) => t.id === params.taskId);
 	if (!parentTask) return errorResult(`Task #${params.taskId} not found`);
-	if (isTerminalTaskStatus(parentTask.status)) {
-		return errorResult(`Task #${parentTask.id} already in terminal state (${parentTask.status}), cannot add subtask`);
+	// isTerminalTaskStatus 不含 completed（completed 有 verification 时需转为 verified）
+	// 这里的 || completed 是有意的业务决策：completed 任务不允许加 subtask
+	if (isTerminalTaskStatus(parentTask.status) || parentTask.status === "completed") {
+		return errorResult(`Task #${parentTask.id} in terminal state (${parentTask.status}), cannot add subtask`);
 	}
 	const subtasks = parentTask.subtasks ?? [];
 	const startId = subtasks.length > 0 ? Math.max(...subtasks.map((s) => s.id)) + 1 : 1;
@@ -316,10 +389,8 @@ export const handleDeleteSubtasks: ActionHandler = ({ state, params, pi, session
 /** 将 AI 传入的 task description 标准化：去换行、截断 */
 function normalizeDescription(desc: string): string {
 	const singleLine = desc.replace(/\r?\n/g, " ").replace(/\s+/g, " ").trim();
-	const ELLIPSIS_LENGTH = 3;
-	const MAX_TASK_DESC_LENGTH = 80;
-	if (singleLine.length > MAX_TASK_DESC_LENGTH) {
-		return singleLine.slice(0, MAX_TASK_DESC_LENGTH - ELLIPSIS_LENGTH) + "...";
+	if (singleLine.length > TASK_DESC_MAX_LENGTH) {
+		return singleLine.slice(0, TASK_DESC_MAX_LENGTH - ELLIPSIS_LENGTH) + "...";
 	}
 	return singleLine;
 }