patchwarden 0.6.4 → 1.5.0

package/dist/goal/goalGraph.d.ts

@@ -0,0 +1,58 @@
+/**
+ * v0.8.0: Goal Session 依赖图 — 就绪/阻塞判定、下一子目标建议、环检测、拓扑排序。
+ *
+ * 所有函数均为纯函数，不修改传入的 goalStatus 对象。
+ * 依赖语义：subgoal.depends_on 引用其他 subgoal 的 id，被引用者 status 必须为
+ * "accepted" 才算依赖满足。引用不存在的 id 视为数据不一致，按阻塞处理。
+ */
+import type { GoalStatus, Subgoal } from "./goalStatus.js";
+/**
+ * 返回所有 status 为 "ready" 且依赖全部满足的子目标。
+ * 依赖满足 = depends_on 中所有 id 都存在且对应 subgoal status 为 "accepted"。
+ * depends_on 为空数组视为依赖满足。
+ * depends_on 引用不存在的 subgoal 时，该子目标不算 ready（跳过）。
+ */
+export declare function getReadySubgoals(goalStatus: GoalStatus): Subgoal[];
+/**
+ * 返回所有 status 为 "ready" 但依赖未全部满足的子目标，附带阻塞它的依赖 id 列表。
+ * blocked_by 包含 depends_on 中 status 不为 "accepted" 的 subgoal_id，
+ * 以及引用不存在的 id。
+ */
+export declare function getBlockedSubgoals(goalStatus: GoalStatus): Array<{
+    subgoal: Subgoal;
+    blocked_by: string[];
+}>;
+/**
+ * 建议下一个可执行的子目标。
+ *
+ * 优先级：
+ *   1. 有 ready 子目标 → 返回第一个（按 subgoal 添加顺序）的 { subgoal_id, title, depends_on }
+ *   2. 无 ready 但有 blocked → 返回 { subgoal_id: null, reason: "dependencies_not_met", blocked_by: [...] }
+ *   3. 无 ready 无 blocked → 返回 { subgoal_id: null, reason: "no_ready_subgoal" }
+ */
+export declare function suggestNextSubgoal(goalStatus: GoalStatus): {
+    subgoal_id: string | null;
+    title?: string;
+    depends_on?: string[];
+    reason?: string;
+    blocked_by?: string[];
+};
+/**
+ * 检测 subgoal 依赖图是否有环（DFS 三色标记法）。
+ *
+ * 沿 depends_on 深度优先遍历，遇到当前路径上正在访问的节点即为环。
+ * depends_on 引用不存在的 subgoal 不算环（忽略）。
+ *
+ * @returns 有环时返回环上的 subgoal_id 数组（任一环即可）；无环返回 null。
+ */
+export declare function detectCycle(goalStatus: GoalStatus): string[] | null;
+/**
+ * 对 subgoal 做拓扑排序（依赖在前）。
+ *
+ * 如果 B depends_on A，则 A 排在 B 之前。
+ * depends_on 引用不存在的 id 会被忽略（不影响排序）。
+ *
+ * @throws {PatchWardenError} reason="dependency_cycle" 当依赖图存在环时。
+ * @returns subgoal_id 数组，依赖项在前。
+ */
+export declare function topologicalSort(goalStatus: GoalStatus): string[];

package/dist/goal/goalGraph.js

@@ -0,0 +1,189 @@
+/**
+ * v0.8.0: Goal Session 依赖图 — 就绪/阻塞判定、下一子目标建议、环检测、拓扑排序。
+ *
+ * 所有函数均为纯函数，不修改传入的 goalStatus 对象。
+ * 依赖语义：subgoal.depends_on 引用其他 subgoal 的 id，被引用者 status 必须为
+ * "accepted" 才算依赖满足。引用不存在的 id 视为数据不一致，按阻塞处理。
+ */
+import { PatchWardenError } from "../errors.js";
+// ── 内部工具 ──────────────────────────────────────────────────────
+/**
+ * 构建 subgoal_id → Subgoal 的查找表。
+ */
+function buildSubgoalMap(goalStatus) {
+    const map = new Map();
+    for (const s of goalStatus.subgoals) {
+        map.set(s.id, s);
+    }
+    return map;
+}
+/**
+ * 判断单个 subgoal 的依赖是否全部满足（所有 depends_on 引用存在且 status 为 accepted）。
+ * depends_on 为空视为依赖满足。引用不存在的 id 视为未满足。
+ */
+function areDependenciesMet(subgoal, subgoalMap) {
+    for (const depId of subgoal.depends_on) {
+        const dep = subgoalMap.get(depId);
+        if (!dep)
+            return false;
+        if (dep.status !== "accepted")
+            return false;
+    }
+    return true;
+}
+// ── 公共 API ──────────────────────────────────────────────────────
+/**
+ * 返回所有 status 为 "ready" 且依赖全部满足的子目标。
+ * 依赖满足 = depends_on 中所有 id 都存在且对应 subgoal status 为 "accepted"。
+ * depends_on 为空数组视为依赖满足。
+ * depends_on 引用不存在的 subgoal 时，该子目标不算 ready（跳过）。
+ */
+export function getReadySubgoals(goalStatus) {
+    const subgoalMap = buildSubgoalMap(goalStatus);
+    return goalStatus.subgoals.filter((s) => s.status === "ready" && areDependenciesMet(s, subgoalMap));
+}
+/**
+ * 返回所有 status 为 "ready" 但依赖未全部满足的子目标，附带阻塞它的依赖 id 列表。
+ * blocked_by 包含 depends_on 中 status 不为 "accepted" 的 subgoal_id，
+ * 以及引用不存在的 id。
+ */
+export function getBlockedSubgoals(goalStatus) {
+    const subgoalMap = buildSubgoalMap(goalStatus);
+    const result = [];
+    for (const s of goalStatus.subgoals) {
+        if (s.status !== "ready")
+            continue;
+        const blockedBy = [];
+        for (const depId of s.depends_on) {
+            const dep = subgoalMap.get(depId);
+            if (!dep) {
+                blockedBy.push(depId);
+            }
+            else if (dep.status !== "accepted") {
+                blockedBy.push(depId);
+            }
+        }
+        if (blockedBy.length > 0) {
+            result.push({ subgoal: s, blocked_by: blockedBy });
+        }
+    }
+    return result;
+}
+/**
+ * 建议下一个可执行的子目标。
+ *
+ * 优先级：
+ *   1. 有 ready 子目标 → 返回第一个（按 subgoal 添加顺序）的 { subgoal_id, title, depends_on }
+ *   2. 无 ready 但有 blocked → 返回 { subgoal_id: null, reason: "dependencies_not_met", blocked_by: [...] }
+ *   3. 无 ready 无 blocked → 返回 { subgoal_id: null, reason: "no_ready_subgoal" }
+ */
+export function suggestNextSubgoal(goalStatus) {
+    const ready = getReadySubgoals(goalStatus);
+    if (ready.length > 0) {
+        const first = ready[0];
+        return {
+            subgoal_id: first.id,
+            title: first.title,
+            depends_on: [...first.depends_on],
+        };
+    }
+    const blocked = getBlockedSubgoals(goalStatus);
+    if (blocked.length > 0) {
+        return {
+            subgoal_id: null,
+            reason: "dependencies_not_met",
+            blocked_by: blocked.map((b) => b.subgoal.id),
+        };
+    }
+    return {
+        subgoal_id: null,
+        reason: "no_ready_subgoal",
+    };
+}
+/**
+ * 检测 subgoal 依赖图是否有环（DFS 三色标记法）。
+ *
+ * 沿 depends_on 深度优先遍历，遇到当前路径上正在访问的节点即为环。
+ * depends_on 引用不存在的 subgoal 不算环（忽略）。
+ *
+ * @returns 有环时返回环上的 subgoal_id 数组（任一环即可）；无环返回 null。
+ */
+export function detectCycle(goalStatus) {
+    const subgoalMap = buildSubgoalMap(goalStatus);
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    for (const s of goalStatus.subgoals) {
+        color.set(s.id, WHITE);
+    }
+    let cycle = null;
+    const dfs = (id, path) => {
+        color.set(id, GRAY);
+        path.push(id);
+        const node = subgoalMap.get(id);
+        if (node) {
+            for (const depId of node.depends_on) {
+                if (!subgoalMap.has(depId))
+                    continue; // 引用不存在，忽略
+                const depColor = color.get(depId);
+                if (depColor === GRAY) {
+                    // 发现环：截取从依赖节点到当前节点的路径
+                    const cycleStart = path.indexOf(depId);
+                    cycle = path.slice(cycleStart);
+                    return true;
+                }
+                if (depColor === WHITE) {
+                    if (dfs(depId, path))
+                        return true;
+                }
+            }
+        }
+        path.pop();
+        color.set(id, BLACK);
+        return false;
+    };
+    for (const s of goalStatus.subgoals) {
+        if (color.get(s.id) === WHITE) {
+            if (dfs(s.id, []))
+                return cycle;
+        }
+    }
+    return null;
+}
+/**
+ * 对 subgoal 做拓扑排序（依赖在前）。
+ *
+ * 如果 B depends_on A，则 A 排在 B 之前。
+ * depends_on 引用不存在的 id 会被忽略（不影响排序）。
+ *
+ * @throws {PatchWardenError} reason="dependency_cycle" 当依赖图存在环时。
+ * @returns subgoal_id 数组，依赖项在前。
+ */
+export function topologicalSort(goalStatus) {
+    const cycle = detectCycle(goalStatus);
+    if (cycle) {
+        throw new PatchWardenError("dependency_cycle", `Dependency cycle detected among subgoals: ${cycle.join(" -> ")}`, "Remove the circular dependency among subgoals before performing topological sort.", true, { cycle });
+    }
+    const subgoalMap = buildSubgoalMap(goalStatus);
+    const visited = new Set();
+    const result = [];
+    const visit = (id) => {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const node = subgoalMap.get(id);
+        if (node) {
+            for (const depId of node.depends_on) {
+                if (subgoalMap.has(depId)) {
+                    visit(depId);
+                }
+            }
+        }
+        result.push(id);
+    };
+    for (const s of goalStatus.subgoals) {
+        visit(s.id);
+    }
+    return result;
+}

package/dist/goal/goalProgress.d.ts

@@ -0,0 +1,81 @@
+/**
+ * v0.8.0: Goal Session 子目标验收业务逻辑 — accept / reject / summarize。
+ *
+ * 三个公共函数：
+ *   - acceptSubgoal：校验所有关联 task 已 accepted 后，将 subgoal 置为 accepted
+ *   - rejectSubgoal：从任意非终态拒绝 subgoal，记录 rejected_reason
+ *   - summarizeGoalProgress：统计 goal 进度，返回 completion_rate / blocked / risks
+ *
+ * 任务 status.json 路径解析：
+ *   优先用 getConfig().tasksDir（绝对路径直接用，相对路径 join workspaceRoot）。
+ *   所有函数接受可选的 workspaceRoot 参数用于测试。
+ */
+export interface GoalProgressSummary {
+    goal_id: string;
+    title: string;
+    total: number;
+    accepted: number;
+    rejected: number;
+    running: number;
+    ready: number;
+    needs_fix: number;
+    done_by_agent: number;
+    completion_rate: string;
+    blocked_subgoals: Array<{
+        subgoal_id: string;
+        title: string;
+        blocked_by: string[];
+    }>;
+    risks: Array<{
+        subgoal_id: string;
+        title: string;
+        status: string;
+        reason: string;
+    }>;
+}
+/**
+ * 验收子目标：校验所有关联 task 已 accepted 后，将 subgoal 置为 accepted。
+ *
+ * 校验规则（理解 B — 更严格）：
+ *   1. task_ids 不能为空（无关联任务无法验收）
+ *   2. 所有 task_ids 对应的 task status 必须为 "accepted"
+ *   3. 通过 updateSubgoalStatus 状态机校验（要求 subgoal 当前为 done_by_agent）
+ *
+ * @param goalId        Goal 标识
+ * @param subgoalId     Subgoal 标识
+ * @param workspaceRoot 可选，用于测试
+ * @returns { subgoal_id, status, accepted_at }
+ * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "subgoal_not_ready" | "invalid_status_transition"
+ */
+export declare function acceptSubgoal(goalId: string, subgoalId: string, workspaceRoot?: string): {
+    subgoal_id: string;
+    status: "accepted";
+    accepted_at: string;
+};
+/**
+ * 拒绝子目标：从任意非终态（ready/running/done_by_agent/needs_fix）拒绝 subgoal。
+ *
+ * 不使用 updateSubgoalStatus 的状态机校验（因为状态机只允许 done_by_agent → rejected），
+ * 直接手动设置 status 和 rejected_reason。
+ *
+ * @param goalId        Goal 标识
+ * @param subgoalId     Subgoal 标识
+ * @param reason        拒绝原因
+ * @param workspaceRoot 可选，用于测试
+ * @returns { subgoal_id, status, rejected_reason }
+ * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "invalid_status_transition"
+ */
+export declare function rejectSubgoal(goalId: string, subgoalId: string, reason: string, workspaceRoot?: string): {
+    subgoal_id: string;
+    status: "rejected";
+    rejected_reason: string;
+};
+/**
+ * 汇总 Goal 进度：统计各状态数量、完成率、阻塞子目标、风险项。
+ *
+ * @param goalId        Goal 标识
+ * @param workspaceRoot 可选，用于测试
+ * @returns GoalProgressSummary
+ * @throws {PatchWardenError} reason="goal_not_found"
+ */
+export declare function summarizeGoalProgress(goalId: string, workspaceRoot?: string): GoalProgressSummary;

package/dist/goal/goalProgress.js

@@ -0,0 +1,216 @@
+/**
+ * v0.8.0: Goal Session 子目标验收业务逻辑 — accept / reject / summarize。
+ *
+ * 三个公共函数：
+ *   - acceptSubgoal：校验所有关联 task 已 accepted 后，将 subgoal 置为 accepted
+ *   - rejectSubgoal：从任意非终态拒绝 subgoal，记录 rejected_reason
+ *   - summarizeGoalProgress：统计 goal 进度，返回 completion_rate / blocked / risks
+ *
+ * 任务 status.json 路径解析：
+ *   优先用 getConfig().tasksDir（绝对路径直接用，相对路径 join workspaceRoot）。
+ *   所有函数接受可选的 workspaceRoot 参数用于测试。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { getConfig } from "../config.js";
+import { PatchWardenError } from "../errors.js";
+import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { updateSubgoalStatus } from "./goalStatus.js";
+import { getBlockedSubgoals } from "./goalGraph.js";
+// ── 辅助：解析 workspaceRoot ──────────────────────────────────────
+function resolveWorkspaceRoot(workspaceRoot) {
+    return workspaceRoot ?? getConfig().workspaceRoot;
+}
+/**
+ * 解析任务 status.json 路径。
+ * 读取 getConfig().tasksDir：绝对路径直接用，相对路径 join workspaceRoot。
+ */
+function resolveTaskStatusPath(taskId, workspaceRoot) {
+    const config = getConfig();
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    const tasksDir = config.tasksDir;
+    const resolvedTasksDir = isAbsolute(tasksDir) ? tasksDir : join(wsRoot, tasksDir);
+    return join(resolvedTasksDir, taskId, "status.json");
+}
+/**
+ * 读取单个任务的 status 字段。
+ * 如果 status.json 不存在或无法解析，返回 null（视为未 accepted）。
+ */
+function readTaskStatus(taskId, workspaceRoot) {
+    const statusPath = resolveTaskStatusPath(taskId, workspaceRoot);
+    if (!existsSync(statusPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(statusPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.status === "string" ? parsed.status : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── 公共 API ──────────────────────────────────────────────────────
+/**
+ * 验收子目标：校验所有关联 task 已 accepted 后，将 subgoal 置为 accepted。
+ *
+ * 校验规则（理解 B — 更严格）：
+ *   1. task_ids 不能为空（无关联任务无法验收）
+ *   2. 所有 task_ids 对应的 task status 必须为 "accepted"
+ *   3. 通过 updateSubgoalStatus 状态机校验（要求 subgoal 当前为 done_by_agent）
+ *
+ * @param goalId        Goal 标识
+ * @param subgoalId     Subgoal 标识
+ * @param workspaceRoot 可选，用于测试
+ * @returns { subgoal_id, status, accepted_at }
+ * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "subgoal_not_ready" | "invalid_status_transition"
+ */
+export function acceptSubgoal(goalId, subgoalId, workspaceRoot) {
+    const goalStatus = readGoalStatus(goalId, workspaceRoot);
+    const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
+    if (!subgoal) {
+        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId });
+    }
+    // 校验 1：task_ids 不能为空
+    if (subgoal.task_ids.length === 0) {
+        throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" has no associated tasks; cannot accept without task verification.`, "Link tasks to the subgoal and run audit_task on each before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId, task_ids: [] });
+    }
+    // 校验 2：所有 task 必须为 accepted
+    const unacceptedTasks = [];
+    for (const taskId of subgoal.task_ids) {
+        const taskStatus = readTaskStatus(taskId, workspaceRoot);
+        if (taskStatus !== "accepted") {
+            unacceptedTasks.push({
+                task_id: taskId,
+                current_status: taskStatus ?? "missing",
+            });
+        }
+    }
+    if (unacceptedTasks.length > 0) {
+        throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" cannot be accepted: ${unacceptedTasks.length} task(s) are not in "accepted" status.`, "Run audit_task on each unaccepted task first.", true, {
+            subgoal_id: subgoalId,
+            goal_id: goalId,
+            unaccepted_tasks: unacceptedTasks,
+        });
+    }
+    // 校验 3：通过状态机转换（要求 subgoal 当前为 done_by_agent）
+    const updatedGoalStatus = updateSubgoalStatus(goalStatus, subgoalId, "accepted");
+    writeGoalStatus(goalId, updatedGoalStatus, workspaceRoot);
+    const updatedSubgoal = updatedGoalStatus.subgoals.find((s) => s.id === subgoalId);
+    return {
+        subgoal_id: subgoalId,
+        status: "accepted",
+        accepted_at: updatedSubgoal.accepted_at,
+    };
+}
+/**
+ * 拒绝子目标：从任意非终态（ready/running/done_by_agent/needs_fix）拒绝 subgoal。
+ *
+ * 不使用 updateSubgoalStatus 的状态机校验（因为状态机只允许 done_by_agent → rejected），
+ * 直接手动设置 status 和 rejected_reason。
+ *
+ * @param goalId        Goal 标识
+ * @param subgoalId     Subgoal 标识
+ * @param reason        拒绝原因
+ * @param workspaceRoot 可选，用于测试
+ * @returns { subgoal_id, status, rejected_reason }
+ * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "invalid_status_transition"
+ */
+export function rejectSubgoal(goalId, subgoalId, reason, workspaceRoot) {
+    const goalStatus = readGoalStatus(goalId, workspaceRoot);
+    const index = goalStatus.subgoals.findIndex((s) => s.id === subgoalId);
+    if (index === -1) {
+        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before rejecting.", true, { subgoal_id: subgoalId, goal_id: goalId });
+    }
+    const current = goalStatus.subgoals[index];
+    // 终态检查：accepted 和 rejected 不允许再 reject
+    if (current.status === "accepted" || current.status === "rejected") {
+        throw new PatchWardenError("invalid_status_transition", `Cannot reject subgoal "${subgoalId}" in terminal state "${current.status}".`, "Reject is only allowed from non-terminal states (ready, running, done_by_agent, needs_fix).", true, {
+            subgoal_id: subgoalId,
+            goal_id: goalId,
+            from_status: current.status,
+            to_status: "rejected",
+        });
+    }
+    // 手动更新 status 和 rejected_reason（绕过状态机）
+    const updatedSubgoal = {
+        ...current,
+        status: "rejected",
+        rejected_reason: reason,
+    };
+    const newSubgoals = [...goalStatus.subgoals];
+    newSubgoals[index] = updatedSubgoal;
+    const updatedGoalStatus = {
+        ...goalStatus,
+        subgoals: newSubgoals,
+        updated_at: new Date().toISOString(),
+    };
+    writeGoalStatus(goalId, updatedGoalStatus, workspaceRoot);
+    return {
+        subgoal_id: subgoalId,
+        status: "rejected",
+        rejected_reason: reason,
+    };
+}
+/**
+ * 汇总 Goal 进度：统计各状态数量、完成率、阻塞子目标、风险项。
+ *
+ * @param goalId        Goal 标识
+ * @param workspaceRoot 可选，用于测试
+ * @returns GoalProgressSummary
+ * @throws {PatchWardenError} reason="goal_not_found"
+ */
+export function summarizeGoalProgress(goalId, workspaceRoot) {
+    const goalStatus = readGoalStatus(goalId, workspaceRoot);
+    const subgoals = goalStatus.subgoals;
+    const total = subgoals.length;
+    const accepted = subgoals.filter((s) => s.status === "accepted").length;
+    const rejected = subgoals.filter((s) => s.status === "rejected").length;
+    const running = subgoals.filter((s) => s.status === "running").length;
+    const ready = subgoals.filter((s) => s.status === "ready").length;
+    const needsFix = subgoals.filter((s) => s.status === "needs_fix").length;
+    const doneByAgent = subgoals.filter((s) => s.status === "done_by_agent").length;
+    const completionRate = total > 0
+        ? `${Math.round((accepted / total) * 100)}%`
+        : "0%";
+    // 阻塞子目标
+    const blockedSubgoals = getBlockedSubgoals(goalStatus).map((b) => ({
+        subgoal_id: b.subgoal.id,
+        title: b.subgoal.title,
+        blocked_by: [...b.blocked_by],
+    }));
+    // 风险项：needs_fix 和 running
+    const risks = [];
+    for (const s of subgoals) {
+        if (s.status === "needs_fix") {
+            risks.push({
+                subgoal_id: s.id,
+                title: s.title,
+                status: s.status,
+                reason: "needs_fix",
+            });
+        }
+        else if (s.status === "running") {
+            risks.push({
+                subgoal_id: s.id,
+                title: s.title,
+                status: s.status,
+                reason: "running",
+            });
+        }
+    }
+    return {
+        goal_id: goalStatus.goal_id,
+        title: goalStatus.title,
+        total,
+        accepted,
+        rejected,
+        running,
+        ready,
+        needs_fix: needsFix,
+        done_by_agent: doneByAgent,
+        completion_rate: completionRate,
+        blocked_subgoals: blockedSubgoals,
+        risks,
+    };
+}

package/dist/goal/goalStatus.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v0.8.0: Goal Session 子目标状态机 — 不可变更新 + 状态机校验。
+ *
+ * 类型定义：SubgoalStatus / Subgoal / GoalStatus
+ * 状态机合法转换：
+ *   ready → running
+ *   running → done_by_agent
+ *   done_by_agent → accepted | rejected | needs_fix
+ *   needs_fix → running
+ *
+ * 所有更新函数返回新的 GoalStatus 对象，不修改原对象。
+ */
+export type SubgoalStatus = "ready" | "running" | "done_by_agent" | "accepted" | "rejected" | "needs_fix";
+export interface Subgoal {
+    id: string;
+    title: string;
+    status: SubgoalStatus;
+    depends_on: string[];
+    task_ids: string[];
+    accepted_at?: string;
+    rejected_reason?: string;
+}
+export interface GoalStatus {
+    goal_id: string;
+    title: string;
+    status: "active" | "completed" | "abandoned";
+    repo_path: string;
+    created_at: string;
+    updated_at: string;
+    subgoals: Subgoal[];
+}
+/**
+ * 创建初始 GoalStatus，用于新 goal。
+ * status 为 "active"，subgoals 为空数组，时间戳为当前 ISO 时间。
+ */
+export declare function createInitialGoalStatus(goalId: string, title: string, repoPath: string): GoalStatus;
+/**
+ * 向 goalStatus 添加一个新 subgoal。
+ * subgoal_id 格式：`subgoal-{NNN}`，NNN 三位补零，从 001 开始递增。
+ * 校验 dependsOn 中每个 id 是否存在于现有 subgoals。
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export declare function addSubgoal(goalStatus: GoalStatus, title: string, dependsOn?: string[]): {
+    goalStatus: GoalStatus;
+    subgoalId: string;
+};
+/**
+ * 更新指定 subgoal 的状态，校验状态机合法转换。
+ * - accepted：设置 accepted_at
+ * - rejected：需要 options.rejected_reason
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export declare function updateSubgoalStatus(goalStatus: GoalStatus, subgoalId: string, newStatus: SubgoalStatus, options?: {
+    rejected_reason?: string;
+}): GoalStatus;
+/**
+ * 将 taskId 关联到指定 subgoal（去重）。
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export declare function linkTaskToSubgoal(goalStatus: GoalStatus, subgoalId: string, taskId: string): GoalStatus;