patchwarden 1.5.0 → 1.6.1

package/dist/goal/goalStore.js

@@ -12,16 +12,29 @@
  * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
  * 默认从 getConfig().workspaceRoot 读取。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, } from "node:fs";
 import { join } from "node:path";
 import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
+import { guardPath, guardWorkspacePath } from "../security/pathGuard.js";
 import { PatchWardenError } from "../errors.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { mutateLockedJsonFileSync, readJsonObjectFileSync, withFileLock, withFileLockSync, } from "../utils/lockedJsonFile.js";
 import { createInitialGoalStatus, } from "./goalStatus.js";
 // ── 辅助：解析 workspaceRoot ──────────────────────────────────────
 function resolveWorkspaceRoot(workspaceRoot) {
     return workspaceRoot ?? getConfig().workspaceRoot;
 }
+const GOALS_PREFIX = join(".patchwarden", "goals");
+const GOAL_ID_MAX_LENGTH = 128;
+const GOAL_ID_PATTERN = /^goal_[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Validate the storage key before it can participate in path construction. */
+export function assertValidGoalId(goalId) {
+    if (goalId.length > GOAL_ID_MAX_LENGTH ||
+        !GOAL_ID_PATTERN.test(goalId)) {
+        throw new PatchWardenError("invalid_goal_id", `Invalid goal id. Expected "goal_" followed by at most ${GOAL_ID_MAX_LENGTH - 5} ASCII letters, digits, underscores, or hyphens.`, "Use the goal_id returned by create_goal or list_goals.", true, { goal_id_length: goalId.length });
+    }
+}
 // ── Goal ID 生成 ──────────────────────────────────────────────────
 /**
  * 从 title 生成 slug：小写、非字母数字字符替换为 `_`、合并连续 `_`、去除首尾 `_`、截断到 30 字符。
@@ -64,13 +77,16 @@ export function generateGoalId(title, existingIds) {
  * 不自动创建目录。
  */
 export function getGoalsDir(workspaceRoot) {
-    return join(resolveWorkspaceRoot(workspaceRoot), ".patchwarden", "goals");
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(wsRoot, GOALS_PREFIX), wsRoot, GOALS_PREFIX);
 }
 /**
  * 返回 `{getGoalsDir()}/{goalId}` 路径。
  */
 export function getGoalDir(goalId, workspaceRoot) {
-    return join(getGoalsDir(workspaceRoot), goalId);
+    assertValidGoalId(goalId);
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(getGoalsDir(wsRoot), goalId), wsRoot, GOALS_PREFIX);
 }
 // ── CRUD ──────────────────────────────────────────────────────────
 /**
@@ -82,11 +98,21 @@ export function getGoalDir(goalId, workspaceRoot) {
  * 返回 { goal_id, goal_dir }。
  */
 export function createGoal(repoPath, title, description, workspaceRoot) {
+    const safeTitle = redactSensitiveContent(title)
+        .content
+        .replace(/[\r\n\t]+/g, " ")
+        .trim()
+        .slice(0, 500) || "Untitled goal";
+    const safeDescription = redactSensitiveContent(description).content;
+    if (Buffer.byteLength(safeDescription, "utf-8") > 1024 * 1024) {
+        throw new PatchWardenError("goal_description_too_large", "Goal description exceeds the 1 MiB limit.", "Split the work into smaller Goal Sessions.");
+    }
     const wsRoot = resolveWorkspaceRoot(workspaceRoot);
     const guardedRepo = guardWorkspacePath(repoPath, wsRoot);
     const goalsDir = getGoalsDir(workspaceRoot);
-    const existingIds = [];
-    if (existsSync(goalsDir)) {
+    mkdirSync(goalsDir, { recursive: true });
+    return withFileLockSync(join(goalsDir, "goal-creation"), () => {
+        const existingIds = [];
         for (const entry of readdirSync(goalsDir)) {
             const entryPath = join(goalsDir, entry);
             try {
@@ -95,35 +121,32 @@ export function createGoal(repoPath, title, description, workspaceRoot) {
                 }
             }
             catch {
-                // 跳过无法 stat 的条目
+                // Skip entries that cannot be inspected.
             }
         }
-    }
-    const goalId = generateGoalId(title, existingIds);
-    const goalDir = join(goalsDir, goalId);
-    // 创建目录结构
-    mkdirSync(join(goalDir, "tasks"), { recursive: true });
-    mkdirSync(join(goalDir, "artifacts"), { recursive: true });
-    // 写入 GOAL.md
-    const now = new Date().toISOString();
-    const goalMd = [
-        `# ${title}`,
-        "",
-        description,
-        "",
-        `- Created: ${now}`,
-        `- Repo: ${guardedRepo}`,
-        "- Status: active",
-        "",
-    ].join("\n");
-    writeFileSync(join(goalDir, "GOAL.md"), goalMd, "utf-8");
-    // 写入 GOALS.md
-    const goalsMd = `# Subgoals: ${title}\n\n_No subgoals yet._\n`;
-    writeFileSync(join(goalDir, "GOALS.md"), goalsMd, "utf-8");
-    // 写入 goal_status.json
-    const status = createInitialGoalStatus(goalId, title, guardedRepo);
-    writeFileSync(join(goalDir, "goal_status.json"), JSON.stringify(status, null, 2) + "\n", "utf-8");
-    return { goal_id: goalId, goal_dir: goalDir };
+        const goalId = generateGoalId(safeTitle, existingIds);
+        const goalDir = getGoalDir(goalId, wsRoot);
+        mkdirSync(goalDir);
+        mkdirSync(join(goalDir, "tasks"));
+        mkdirSync(join(goalDir, "artifacts"));
+        const now = new Date().toISOString();
+        const goalMd = [
+            `# ${safeTitle}`,
+            "",
+            safeDescription,
+            "",
+            `- Created: ${now}`,
+            `- Repo: ${guardedRepo}`,
+            "- Status: active",
+            "",
+        ].join("\n");
+        atomicWriteFileSync(join(goalDir, "GOAL.md"), goalMd);
+        const goalsMd = `# Subgoals: ${safeTitle}\n\n_No subgoals yet._\n`;
+        atomicWriteFileSync(join(goalDir, "GOALS.md"), goalsMd);
+        const status = createInitialGoalStatus(goalId, safeTitle, guardedRepo);
+        atomicWriteJsonFileSync(join(goalDir, "goal_status.json"), status);
+        return { goal_id: goalId, goal_dir: goalDir };
+    }, goalBusyOptions("creation"));
 }
 /**
  * 列出所有 goal 的摘要信息，按 updated_at 降序排列。
@@ -136,8 +159,8 @@ export function listGoals(workspaceRoot) {
     }
     const results = [];
     for (const entry of readdirSync(goalsDir)) {
-        const entryPath = join(goalsDir, entry);
         try {
+            const entryPath = getGoalDir(entry, workspaceRoot);
             if (!statSync(entryPath).isDirectory()) {
                 continue;
             }
@@ -172,7 +195,8 @@ export function readGoal(goalId, workspaceRoot) {
     let goalDescription = "";
     const goalMdPath = join(goalDir, "GOAL.md");
     if (existsSync(goalMdPath)) {
-        goalDescription = readFileSync(goalMdPath, "utf-8");
+        const safeGoalMdPath = guardPath(goalMdPath, resolveWorkspaceRoot(workspaceRoot), GOALS_PREFIX);
+        goalDescription = readFileSync(safeGoalMdPath, "utf-8");
     }
     return {
         goal_id: status.goal_id,
@@ -186,26 +210,109 @@ export function readGoal(goalId, workspaceRoot) {
     };
 }
 /**
- * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
- * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ * Replace goal_status.json under the shared cross-process mutation lock.
  */
 export function writeGoalStatus(goalId, status, workspaceRoot) {
     const goalDir = getGoalDir(goalId, workspaceRoot);
-    const finalPath = join(goalDir, "goal_status.json");
-    const tmpPath = join(goalDir, "goal_status.json.tmp");
-    writeFileSync(tmpPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
-    renameSync(tmpPath, finalPath);
+    if (!existsSync(goalDir)) {
+        throw new PatchWardenError("goal_not_found", `Goal directory not found: "${goalDir}"`, "Ensure the goal has been created before writing its status.", true, { goal_id: goalId, goal_dir: goalDir });
+    }
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    if (!existsSync(statusPath)) {
+        withFileLockSync(statusPath, () => {
+            atomicWriteJsonFileSync(statusPath, normalizeGoalLifecycle(validateGoalStatus(goalId, status, workspaceRoot)));
+        }, goalBusyOptions(goalId));
+        return;
+    }
+    mutateGoalStatus(goalId, () => ({ next: status, result: undefined }), workspaceRoot);
 }
 /**
  * 读取 goal_status.json 并 JSON.parse。
  * 如果文件不存在，抛出 PatchWardenError("goal_not_found")。
  */
 export function readGoalStatus(goalId, workspaceRoot) {
-    const goalDir = getGoalDir(goalId, workspaceRoot);
-    const statusPath = join(goalDir, "goal_status.json");
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
     if (!existsSync(statusPath)) {
         throw new PatchWardenError("goal_not_found", `goal_status.json not found for goal "${goalId}" at "${statusPath}"`, "Ensure the goal has been created via createGoal before reading its status.", true, { goal_id: goalId, status_path: statusPath });
     }
-    const raw = readFileSync(statusPath, "utf-8");
-    return JSON.parse(raw);
+    let parsed;
+    try {
+        parsed = readJsonObjectFileSync(statusPath);
+    }
+    catch {
+        throw invalidGoalStatus(goalId, "goal_status.json is not valid JSON");
+    }
+    return validateGoalStatus(goalId, parsed, workspaceRoot);
+}
+export function mutateGoalStatus(goalId, mutation, workspaceRoot) {
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    ensureGoalStatusExists(goalId, statusPath);
+    return mutateLockedJsonFileSync(statusPath, (raw) => {
+        const current = validateGoalStatus(goalId, raw, workspaceRoot);
+        const outcome = mutation(current);
+        if (!outcome.next)
+            return outcome;
+        return {
+            next: normalizeGoalLifecycle(validateGoalStatus(goalId, outcome.next, workspaceRoot)),
+            result: outcome.result,
+        };
+    }, goalBusyOptions(goalId));
+}
+export async function mutateGoalStatusAsync(goalId, mutation, workspaceRoot) {
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    ensureGoalStatusExists(goalId, statusPath);
+    return withFileLock(statusPath, async () => {
+        const current = validateGoalStatus(goalId, readJsonObjectFileSync(statusPath), workspaceRoot);
+        const outcome = await mutation(current);
+        if (outcome.next) {
+            atomicWriteJsonFileSync(statusPath, normalizeGoalLifecycle(validateGoalStatus(goalId, outcome.next, workspaceRoot)));
+        }
+        return outcome.result;
+    }, goalBusyOptions(goalId));
+}
+function getGoalStatusPath(goalId, workspaceRoot) {
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(getGoalDir(goalId, wsRoot), "goal_status.json"), wsRoot, GOALS_PREFIX);
+}
+function ensureGoalStatusExists(goalId, statusPath) {
+    if (!existsSync(statusPath)) {
+        throw new PatchWardenError("goal_not_found", `goal_status.json not found for goal "${goalId}" at "${statusPath}"`, "Ensure the goal has been created via createGoal before updating it.", true, { goal_id: goalId, status_path: statusPath });
+    }
+}
+function validateGoalStatus(goalId, value, workspaceRoot) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidGoalStatus(goalId, "expected a JSON object");
+    }
+    const candidate = value;
+    if (candidate.goal_id !== goalId) {
+        throw invalidGoalStatus(goalId, "goal_id does not match its directory");
+    }
+    if (typeof candidate.title !== "string" || typeof candidate.repo_path !== "string") {
+        throw invalidGoalStatus(goalId, "title or repo_path is missing");
+    }
+    if (candidate.status !== "active" && candidate.status !== "completed" && candidate.status !== "abandoned") {
+        throw invalidGoalStatus(goalId, "status is invalid");
+    }
+    if (!Array.isArray(candidate.subgoals)) {
+        throw invalidGoalStatus(goalId, "subgoals must be an array");
+    }
+    guardWorkspacePath(candidate.repo_path, resolveWorkspaceRoot(workspaceRoot));
+    return candidate;
+}
+function normalizeGoalLifecycle(status) {
+    if (status.status === "active" &&
+        status.subgoals.length > 0 &&
+        status.subgoals.every((subgoal) => subgoal.status === "accepted")) {
+        return { ...status, status: "completed", updated_at: new Date().toISOString() };
+    }
+    return status;
+}
+function invalidGoalStatus(goalId, detail) {
+    return new PatchWardenError("invalid_goal_status", `Invalid goal status for "${goalId}": ${detail}.`, "Recreate the Goal Session or restore a valid goal_status.json artifact.", true, { goal_id: goalId });
+}
+function goalBusyOptions(goalId) {
+    return {
+        waitMs: 0,
+        busyError: () => new PatchWardenError("goal_busy", `Goal "${goalId}" is currently being updated.`, "Retry after the active Goal operation finishes.", true, { goal_id: goalId }),
+    };
 }

package/dist/goal/handoffExport.js

@@ -7,9 +7,10 @@
  * 以避免与 goalStore 形成循环依赖。
  */
 import { suggestNextSubgoal } from "./goalGraph.js";
-import { getConfig } from "../config.js";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { getGoalDir } from "./goalStore.js";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "../utils/atomicFile.js";
 // ── Markdown 生成 ────────────────────────────────────────────────
 /**
  * 生成 Goal Session 交接文档（Markdown 字符串）。
@@ -170,11 +171,10 @@ export function generateHandoff(goalId, goalStatus, recentDiff, recentTestResult
  */
 export function exportHandoff(goalId, goalStatus, workspaceRoot) {
     const content = generateHandoff(goalId, goalStatus);
-    const root = workspaceRoot ?? getConfig().workspaceRoot;
-    const goalDir = resolve(root, ".patchwarden", "goals", goalId);
+    const goalDir = getGoalDir(goalId, workspaceRoot);
     mkdirSync(goalDir, { recursive: true });
     const handoffPath = join(goalDir, "handoff.md");
-    writeFileSync(handoffPath, content, "utf-8");
+    atomicWriteFileSync(handoffPath, content);
     const preview = content.length > 500 ? content.slice(0, 500) + "..." : content;
     return {
         handoff_path: handoffPath,

package/dist/goal/specKitImport.d.ts

@@ -0,0 +1,63 @@
+/**
+ * v0.8.0: Spec Kit tasks 导入 — 将 Spec Kit 的 spec/tasks 结构转换为 Goal Session 子目标。
+ *
+ * - 解析 Spec Kit JSON（parseSpecKitJson）
+ * - 幂等导入：按 external_ref 去重，重复导入不产生重复 subgoal
+ * - 依赖解析：将 task.depends_on（external_ref 引用）解析为本地 subgoal id
+ * - 验收标准映射：input.acceptance → GoalStatus.acceptance_criteria
+ *
+ * 不引入第三方依赖，仅用 Node.js 内置模块。
+ */
+export interface SpecKitTask {
+    id: string;
+    desc: string;
+    files?: string[];
+    /** 引用其他 task 的 id（external_ref） */
+    depends_on?: string[];
+}
+export interface SpecKitInput {
+    spec: string;
+    tasks: SpecKitTask[];
+    acceptance?: string[];
+}
+export interface SpecKitImportResult {
+    goal_id: string;
+    spec_name: string;
+    created_count: number;
+    existing_count: number;
+    subgoal_ids: string[];
+}
+/**
+ * 解析 Spec Kit JSON 文本并验证结构。
+ *
+ * 必须包含：
+ * - spec: 非空字符串
+ * - tasks: 数组，每个元素含 id（字符串）和 desc（字符串）
+ *
+ * 可选：
+ * - acceptance: 字符串数组
+ *
+ * 解析失败或结构不合法时抛出 PatchWardenError("invalid_spec_kit_json" | "invalid_spec_kit_input")。
+ */
+export declare function parseSpecKitJson(jsonText: string): SpecKitInput;
+/**
+ * 将 Spec Kit tasks 导入到指定 Goal Session，创建对应的 subgoal。
+ *
+ * 行为：
+ * - 验证 input（spec 非空、tasks 为数组）
+ * - 幂等去重：按 external_ref（task.id）匹配现有 subgoal，已存在则跳过
+ * - 依赖解析：将 task.depends_on（external_ref）解析为本地 subgoal id
+ *   - 先创建无依赖的 subgoal，再处理有依赖的，支持多级依赖
+ *   - 依赖的 task 在同一批次中：用刚创建的 subgoal_id
+ *   - 依赖的 task 不存在：忽略该依赖并记录 warning（console.warn）
+ * - 验收标准：input.acceptance 非空时写入 GoalStatus.acceptance_criteria
+ * - 持久化：用 writeGoalStatus 原子写入
+ *
+ * @param goalId       目标 Goal 标识
+ * @param input        Spec Kit 输入（spec + tasks + acceptance）
+ * @param options      可选配置：workspaceRoot 用于测试
+ * @returns SpecKitImportResult
+ */
+export declare function importSpecKitTasks(goalId: string, input: SpecKitInput, options?: {
+    workspaceRoot?: string;
+}): SpecKitImportResult;

package/dist/goal/specKitImport.js

@@ -0,0 +1,221 @@
+/**
+ * v0.8.0: Spec Kit tasks 导入 — 将 Spec Kit 的 spec/tasks 结构转换为 Goal Session 子目标。
+ *
+ * - 解析 Spec Kit JSON（parseSpecKitJson）
+ * - 幂等导入：按 external_ref 去重，重复导入不产生重复 subgoal
+ * - 依赖解析：将 task.depends_on（external_ref 引用）解析为本地 subgoal id
+ * - 验收标准映射：input.acceptance → GoalStatus.acceptance_criteria
+ *
+ * 不引入第三方依赖，仅用 Node.js 内置模块。
+ */
+import { PatchWardenError } from "../errors.js";
+import { addSubgoal } from "./goalStatus.js";
+import { mutateGoalStatus } from "./goalStore.js";
+// ── JSON 解析 ─────────────────────────────────────────────────────
+/**
+ * 解析 Spec Kit JSON 文本并验证结构。
+ *
+ * 必须包含：
+ * - spec: 非空字符串
+ * - tasks: 数组，每个元素含 id（字符串）和 desc（字符串）
+ *
+ * 可选：
+ * - acceptance: 字符串数组
+ *
+ * 解析失败或结构不合法时抛出 PatchWardenError("invalid_spec_kit_json" | "invalid_spec_kit_input")。
+ */
+export function parseSpecKitJson(jsonText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (e) {
+        throw new PatchWardenError("invalid_spec_kit_json", `Failed to parse Spec Kit JSON: ${e instanceof Error ? e.message : String(e)}`, "Ensure the input is valid JSON.", true, {});
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PatchWardenError("invalid_spec_kit_input", "Spec Kit JSON must be a JSON object", 'Ensure the top-level value is an object with "spec" and "tasks" fields.', true, { actual_type: Array.isArray(parsed) ? "array" : typeof parsed });
+    }
+    const obj = parsed;
+    if (typeof obj.spec !== "string" || obj.spec === "") {
+        throw new PatchWardenError("invalid_spec_kit_input", 'Spec Kit JSON must contain a non-empty "spec" string field', 'Add a "spec" field with a non-empty string value describing the specification name.', true, { spec: obj.spec });
+    }
+    if (!Array.isArray(obj.tasks)) {
+        throw new PatchWardenError("invalid_spec_kit_input", 'Spec Kit JSON must contain a "tasks" array field', 'Add a "tasks" field with an array of task objects (each with "id" and "desc").', true, { tasks_type: Array.isArray(obj.tasks) ? "array" : typeof obj.tasks });
+    }
+    const tasks = [];
+    for (let i = 0; i < obj.tasks.length; i++) {
+        const raw = obj.tasks[i];
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new PatchWardenError("invalid_spec_kit_input", `Spec Kit task at index ${i} must be an object`, "Each task must be an object with at least \"id\" and \"desc\" string fields.", true, { task_index: i, actual_type: typeof raw });
+        }
+        const t = raw;
+        if (typeof t.id !== "string" || t.id === "") {
+            throw new PatchWardenError("invalid_spec_kit_input", `Spec Kit task at index ${i} must have a non-empty "id" string`, "Ensure each task has a unique non-empty string \"id\".", true, { task_index: i, id: t.id });
+        }
+        if (typeof t.desc !== "string") {
+            throw new PatchWardenError("invalid_spec_kit_input", `Spec Kit task at index ${i} (id="${t.id}") must have a "desc" string`, "Ensure each task has a \"desc\" string describing the task.", true, { task_index: i, id: t.id, desc_type: typeof t.desc });
+        }
+        const task = { id: t.id, desc: t.desc };
+        if (Array.isArray(t.files)) {
+            task.files = t.files.filter((f) => typeof f === "string");
+        }
+        if (Array.isArray(t.depends_on)) {
+            task.depends_on = t.depends_on.filter((d) => typeof d === "string");
+        }
+        tasks.push(task);
+    }
+    const result = { spec: obj.spec, tasks };
+    if (Array.isArray(obj.acceptance)) {
+        result.acceptance = obj.acceptance.filter((a) => typeof a === "string");
+    }
+    return result;
+}
+// ── 导入实现 ──────────────────────────────────────────────────────
+/**
+ * 将 Spec Kit tasks 导入到指定 Goal Session，创建对应的 subgoal。
+ *
+ * 行为：
+ * - 验证 input（spec 非空、tasks 为数组）
+ * - 幂等去重：按 external_ref（task.id）匹配现有 subgoal，已存在则跳过
+ * - 依赖解析：将 task.depends_on（external_ref）解析为本地 subgoal id
+ *   - 先创建无依赖的 subgoal，再处理有依赖的，支持多级依赖
+ *   - 依赖的 task 在同一批次中：用刚创建的 subgoal_id
+ *   - 依赖的 task 不存在：忽略该依赖并记录 warning（console.warn）
+ * - 验收标准：input.acceptance 非空时写入 GoalStatus.acceptance_criteria
+ * - 持久化：用 writeGoalStatus 原子写入
+ *
+ * @param goalId       目标 Goal 标识
+ * @param input        Spec Kit 输入（spec + tasks + acceptance）
+ * @param options      可选配置：workspaceRoot 用于测试
+ * @returns SpecKitImportResult
+ */
+export function importSpecKitTasks(goalId, input, options) {
+    // ── 验证 ───────────────────────────────────────────────────
+    if (!input || typeof input !== "object") {
+        throw new PatchWardenError("invalid_spec_kit_input", "Spec Kit input must be an object", "Pass a SpecKitInput object with spec, tasks, and optional acceptance fields.", true, {});
+    }
+    if (typeof input.spec !== "string" || input.spec === "") {
+        throw new PatchWardenError("invalid_spec_kit_input", 'Spec Kit input must contain a non-empty "spec" string', "Ensure input.spec is a non-empty string.", true, { spec: input.spec });
+    }
+    if (!Array.isArray(input.tasks)) {
+        throw new PatchWardenError("invalid_spec_kit_input", 'Spec Kit input must contain a "tasks" array', "Ensure input.tasks is an array of SpecKitTask objects.", true, { tasks_type: Array.isArray(input.tasks) ? "array" : typeof input.tasks });
+    }
+    const workspaceRoot = options?.workspaceRoot;
+    return mutateGoalStatus(goalId, (currentGoalStatus) => {
+        let goalStatus = currentGoalStatus;
+        // ── 构建 external_ref → subgoal_id 映射（现有 subgoal）─────
+        const refToSubgoalId = new Map();
+        for (const sg of goalStatus.subgoals) {
+            if (sg.external_ref) {
+                refToSubgoalId.set(sg.external_ref, sg.id);
+            }
+        }
+        // ── 幂等去重：区分新 task 和已存在的 task ─────────────────
+        const newTasks = [];
+        let existingCount = 0;
+        for (const task of input.tasks) {
+            if (refToSubgoalId.has(task.id)) {
+                existingCount++;
+            }
+            else {
+                newTasks.push(task);
+            }
+        }
+        // 新批次中所有 task id 集合（用于判断依赖是否在同批次）
+        const newTaskIds = new Set(newTasks.map((t) => t.id));
+        // ── 按依赖顺序创建 subgoal（拓扑排序，迭代多轮）────────────
+        const createdIds = [];
+        let remaining = [...newTasks];
+        // 辅助：创建单个 subgoal 并设置 external_ref / scope_hints
+        const createSubgoalForTask = (gs, task, resolvedDeps) => {
+            const { goalStatus: newGs, subgoalId } = addSubgoal(gs, task.desc, resolvedDeps);
+            // 新 subgoal 是数组最后一个元素，追加 external_ref 和 scope_hints
+            const subgoals = [...newGs.subgoals];
+            const lastIdx = subgoals.length - 1;
+            const updated = {
+                ...subgoals[lastIdx],
+                external_ref: task.id,
+            };
+            if (task.files && task.files.length > 0) {
+                updated.scope_hints = [...task.files];
+            }
+            subgoals[lastIdx] = updated;
+            return { goalStatus: { ...newGs, subgoals }, subgoalId };
+        };
+        while (remaining.length > 0) {
+            const stillRemaining = [];
+            let progress = false;
+            // 正向遍历：保持输入顺序，先创建的 task 可被同批次后续 task 依赖
+            for (const task of remaining) {
+                const deps = task.depends_on ?? [];
+                const resolvedDeps = [];
+                let hasUnresolvedInBatch = false;
+                for (const dep of deps) {
+                    if (refToSubgoalId.has(dep)) {
+                        // 依赖已存在（已有 subgoal 或本批次已创建）
+                        resolvedDeps.push(refToSubgoalId.get(dep));
+                    }
+                    else if (newTaskIds.has(dep)) {
+                        // 依赖同批次中尚未创建的 task
+                        hasUnresolvedInBatch = true;
+                    }
+                    else {
+                        // 依赖的 task 不存在任何地方：忽略并记录 warning
+                        console.warn(`[specKitImport] Task "${task.id}" depends on non-existent task "${dep}"; ignoring this dependency.`);
+                    }
+                }
+                if (!hasUnresolvedInBatch) {
+                    const { goalStatus: newGs, subgoalId } = createSubgoalForTask(goalStatus, task, resolvedDeps);
+                    goalStatus = newGs;
+                    refToSubgoalId.set(task.id, subgoalId);
+                    createdIds.push(subgoalId);
+                    progress = true;
+                }
+                else {
+                    stillRemaining.push(task);
+                }
+            }
+            remaining = stillRemaining;
+            if (!progress && remaining.length > 0) {
+                // 检测到循环依赖：强制创建剩余 task，忽略未解析的同批次依赖
+                for (const task of remaining) {
+                    const deps = task.depends_on ?? [];
+                    const resolvedDeps = [];
+                    for (const dep of deps) {
+                        if (refToSubgoalId.has(dep)) {
+                            resolvedDeps.push(refToSubgoalId.get(dep));
+                        }
+                        else if (newTaskIds.has(dep)) {
+                            console.warn(`[specKitImport] Circular dependency detected: task "${task.id}" depends on "${dep}" which could not be resolved; ignoring this dependency.`);
+                        }
+                        else {
+                            console.warn(`[specKitImport] Task "${task.id}" depends on non-existent task "${dep}"; ignoring this dependency.`);
+                        }
+                    }
+                    const { goalStatus: newGs, subgoalId } = createSubgoalForTask(goalStatus, task, resolvedDeps);
+                    goalStatus = newGs;
+                    refToSubgoalId.set(task.id, subgoalId);
+                    createdIds.push(subgoalId);
+                }
+                break;
+            }
+        }
+        // ── 验收标准 ───────────────────────────────────────────────
+        if (input.acceptance && input.acceptance.length > 0) {
+            goalStatus = {
+                ...goalStatus,
+                acceptance_criteria: [...input.acceptance],
+            };
+        }
+        return {
+            next: goalStatus,
+            result: {
+                goal_id: goalId,
+                spec_name: input.spec,
+                created_count: createdIds.length,
+                existing_count: existingCount,
+                subgoal_ids: createdIds,
+            },
+        };
+    }, workspaceRoot);
+}

package/dist/goal/subgoalSync.js

@@ -8,8 +8,9 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { mutateGoalStatus } from "./goalStore.js";
 import { updateSubgoalStatus } from "./goalStatus.js";
+import { logger } from "../logging.js";
 // ── 同步函数 ──────────────────────────────────────────────────────
 /**
  * v0.8.0: 当任务状态变为 done_by_agent 时，同步更新关联的 subgoal 状态。
@@ -31,18 +32,20 @@ export function syncSubgoalOnTaskDone(taskId, taskMeta, workspaceRoot) {
     if (!goalId || !subgoalId)
         return;
     try {
-        const goalStatus = readGoalStatus(goalId, workspaceRoot);
-        const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
-        if (!subgoal)
-            return;
-        if (subgoal.status !== "running")
-            return;
-        const updated = updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent");
-        writeGoalStatus(goalId, updated, workspaceRoot);
+        mutateGoalStatus(goalId, (goalStatus) => {
+            const subgoal = goalStatus.subgoals.find((entry) => entry.id === subgoalId);
+            if (!subgoal || subgoal.status !== "running") {
+                return { result: undefined };
+            }
+            return {
+                next: updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent"),
+                result: undefined,
+            };
+        }, workspaceRoot);
     }
     catch (err) {
         // subgoal 同步失败不应影响任务完成流程，只记录到 stderr
-        console.error(`[goal] syncSubgoalOnTaskDone failed for task ${taskId}: ${err instanceof Error ? err.message : String(err)}`);
+        logger.error(`[goal] syncSubgoalOnTaskDone failed for task ${taskId}`, { error: err instanceof Error ? err.message : String(err) });
     }
 }
 // ── Task 元信息读取 ───────────────────────────────────────────────

package/dist/goal/worktreeManager.d.ts

@@ -31,6 +31,8 @@ export interface WorktreeStatus {
 }
 /** worktree 根目录名，放在 workspaceRoot 下。 */
 export declare const WorktreeDir = "_workspacetrees";
+/** Accept only IDs emitted by generateWorktreeId(). */
+export declare function assertValidWorktreeId(worktreeId: string): void;
 /**
  * 返回 `<workspaceRoot>/_workspacetrees` 目录路径。不自动创建目录。
  */