patchwarden 0.6.4 → 1.1.0

package/src/controlCenter.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * PatchWarden Control Center — local HTTP dashboard service.
  *
@@ -27,6 +27,7 @@ import {
   type PatchWardenConfig,
 } from "./config.js";
 import { listTasks, type TaskEntry } from "./tools/listTasks.js";
+import type { AcceptanceStatus } from "./tools/createTask.js";
 import { listAgents, type AgentAvailability } from "./tools/listAgents.js";
 import { readWatcherStatus, type WatcherStatusSnapshot } from "./watcherStatus.js";
 import { redactSensitiveContent } from "./security/contentRedaction.js";
@@ -464,6 +465,7 @@ interface StaleClassification {
 
 const TERMINAL_TASK_STATUSES = new Set([
   "done",
+  "done_by_agent",
   "failed",
   "failed_verification",
   "failed_scope_violation",
@@ -1049,13 +1051,19 @@ function handleReconcile(res: ServerResponse, taskId: string): void {
     const runtimeData = readJsonFileSafe<Record<string, unknown>>(runtimePath) ?? {};
 
     const watcher = readWatcherStatusSafe();
+    const VALID_ACCEPTANCE = ["pending", "accepted", "rejected", "needs_fix", "blocked"];
+    const taskStatus = String(statusData.status || "pending");
+    const taskAcceptanceStatus = taskStatus === "done_by_agent"
+      ? (typeof statusData.acceptance_status === "string" && VALID_ACCEPTANCE.includes(statusData.acceptance_status) ? (statusData.acceptance_status as AcceptanceStatus) : "pending" as AcceptanceStatus)
+      : null;
     const taskEntry: TaskEntry = {
       task_id: taskId,
       plan_id: String(statusData.plan_id || ""),
       title: "",
       agent: String(statusData.agent || ""),
-      status: String(statusData.status || "pending") as TaskEntry["status"],
+      status: taskStatus as TaskEntry["status"],
       phase: String(runtimeData.phase || statusData.phase || "queued") as TaskEntry["phase"],
+      acceptance_status: taskAcceptanceStatus,
       created_at: String(statusData.created_at || ""),
       updated_at: String(statusData.updated_at || ""),
       workspace_root: String(statusData.workspace_root || config.workspaceRoot),
@@ -1199,13 +1207,19 @@ function handleTaskDetail(res: ServerResponse, taskId: string): void {
     let stale: StaleClassification | null = null;
     if (statusData) {
       const watcher = readWatcherStatusSafe();
+      const VALID_ACCEPTANCE2 = ["pending", "accepted", "rejected", "needs_fix", "blocked"];
+      const taskStatus2 = String(statusData.status || "pending");
+      const taskAcceptanceStatus2 = taskStatus2 === "done_by_agent"
+        ? (typeof statusData.acceptance_status === "string" && VALID_ACCEPTANCE2.includes(statusData.acceptance_status) ? (statusData.acceptance_status as AcceptanceStatus) : "pending" as AcceptanceStatus)
+        : null;
       const entry: TaskEntry = {
         task_id: taskId,
         plan_id: String(statusData.plan_id || ""),
         title: "",
         agent: String(statusData.agent || ""),
-        status: String(statusData.status || "pending") as TaskEntry["status"],
+        status: taskStatus2 as TaskEntry["status"],
         phase: String(runtimeData?.phase || statusData.phase || "queued") as TaskEntry["phase"],
+        acceptance_status: taskAcceptanceStatus2,
         created_at: String(statusData.created_at || ""),
         updated_at: String(statusData.updated_at || ""),
         workspace_root: String(statusData.workspace_root || config.workspaceRoot),

package/src/doctor.ts

@@ -19,6 +19,9 @@ import { guardPlanContent } from "./security/planGuard.js";
 import { TASK_READ_ONLY_FILES } from "./tools/getTaskFile.js";
 import { getToolDefs } from "./tools/registry.js";
 import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, selectToolsForProfile } from "./tools/toolCatalog.js";
+import { buildToolRegistry } from "./tools/toolRegistry.js";
+import { runAllSchemaDriftChecks } from "./tools/schemaDriftCheck.js";
+import { runReleaseGateCheck } from "./release/releaseGate.js";
 import { PATCHWARDEN_VERSION } from "./version.js";
 
 // ── State ──────────────────────────────────────────────────────────
@@ -245,7 +248,7 @@ try {
   const coreTools = selectToolsForProfile(fullTools, "chatgpt_core", config?.enableDirectProfile);
   const createSchema = coreTools.find((tool) => tool.name === "create_task")?.inputSchema as any;
   const waitSchema = coreTools.find((tool) => tool.name === "wait_for_task")?.inputSchema as any;
-  check("Full tool profile exposes 30 tools", fullTools.length === 30, `${fullTools.length} tools`);
+  check("Full tool profile exposes 54 tools", fullTools.length === 54, `${fullTools.length} tools`);
   check(
     `chatgpt_core profile exposes the exact ${CHATGPT_CORE_TOOL_NAMES.length}-tool manifest`,
     JSON.stringify(coreTools.map((tool) => tool.name)) === JSON.stringify(CHATGPT_CORE_TOOL_NAMES),
@@ -280,11 +283,43 @@ try {
     results.push(`[OK]   chatgpt_direct enabled check skipped (enableDirectProfile=false)`);
     ok++;
   }
+
+  // 16. Schema drift 检查（v0.9.0）—— warn 级别，不阻断 doctor:ci
+  // 用 fullTools 同时构建 registry 和 toolDefs Map，确保 schema digest 比对基准一致。
+  const driftRegistry = buildToolRegistry(fullTools);
+  const driftToolDefs = new Map<string, { inputSchema: unknown }>();
+  for (const tool of fullTools) {
+    driftToolDefs.set(tool.name, { inputSchema: tool.inputSchema });
+  }
+  const driftResult = runAllSchemaDriftChecks(driftRegistry, driftToolDefs);
+  if (driftResult.ok) {
+    results.push(`[OK]   Schema drift check — no drift detected`);
+    ok++;
+  } else {
+    // 每个 warning 单独输出为 WARN，与其他自检项的多警告模式一致
+    for (const w of driftResult.warnings) {
+      results.push(`[WARN] Schema drift: ${w}`);
+      warn++;
+    }
+  }
 } finally {
   if (previousProfile === undefined) delete process.env.PATCHWARDEN_TOOL_PROFILE;
   else process.env.PATCHWARDEN_TOOL_PROFILE = previousProfile;
 }
 
+// 17. Release gate module loadable (v1.0.0) — module integrity only.
+// Does NOT execute local_ready (would recurse into doctor:ci).
+try {
+  const releaseGateReady = typeof runReleaseGateCheck === "function";
+  check(
+    "Release gate module loadable",
+    releaseGateReady,
+    releaseGateReady ? "runReleaseGateCheck exported" : "runReleaseGateCheck missing or invalid",
+  );
+} catch (error) {
+  check("Release gate module loadable", false, error instanceof Error ? error.message : String(error));
+}
+
 // 9. HTTP port check
 const httpPort = (config as any)?.http?.port || 7331;
 try {

package/src/goal/acceptanceEngine.ts

@@ -0,0 +1,160 @@
+/**
+ * v0.7.2: 验收引擎 — 基于证据推导 4 级验收结论。
+ *
+ * 输入：status.json、task_meta（goal/scope/forbidden/verification/done_evidence）、
+ *       audit checks（pass/warn/fail）、release claims、artifact 信息
+ * 输出：ACCEPTED / NEEDS_FIX / REJECTED / BLOCKED_BY_APPROVAL
+ *       + reasons + required_evidence + next_suggested_task
+ *
+ * 决策规则：
+ *   1. 存在 fail 级检查项 → REJECTED
+ *   2. 存在 release claims 但无法验证远端 → BLOCKED_BY_APPROVAL
+ *   3. 存在 warn 级检查项或文档不同步 → NEEDS_FIX
+ *   4. 所有检查通过 → ACCEPTED
+ */
+
+import type { AcceptanceStatus } from "../tools/createTask.js";
+
+// ── 类型定义 ──────────────────────────────────────────────────────
+
+export type AcceptanceVerdict = "ACCEPTED" | "NEEDS_FIX" | "REJECTED" | "BLOCKED_BY_APPROVAL";
+
+export interface AcceptanceCheck {
+  name: string;
+  result: "pass" | "warn" | "fail";
+  detail: string;
+}
+
+export interface AcceptanceEvidence {
+  task_id: string;
+  task_status: string;
+  // 证据文件是否存在
+  result_md_exists: boolean;
+  result_json_exists: boolean;
+  verify_json_exists: boolean;
+  test_log_exists: boolean;
+  git_diff_exists: boolean;
+  // 验证状态
+  verify_status: "passed" | "failed" | "skipped" | null;
+  // 范围违规
+  new_out_of_scope_changes: Array<{ path: string; change: string }>;
+  // 任务元数据（来自 create_task 的结构化验收标准）
+  goal: string | null;
+  scope: string[] | null;
+  forbidden: string[] | null;
+  verification: string[] | null;
+  done_evidence: string[] | null;
+  // artifact 信息
+  artifact_status: string | null;
+  // release claims（auditTask 扫描到的发布声明）
+  release_claims_unverified: boolean;
+  // audit checks（来自 auditTask 的完整检查列表）
+  checks: AcceptanceCheck[];
+}
+
+export interface AcceptanceResult {
+  verdict: AcceptanceVerdict;
+  acceptance_status: AcceptanceStatus;
+  reason: string;
+  reasons: string[];
+  required_evidence: string[];
+  next_suggested_task: string;
+  fail_checks: AcceptanceCheck[];
+  warn_checks: AcceptanceCheck[];
+}
+
+// ── 验收决策 ──────────────────────────────────────────────────────
+
+/**
+ * 核心验收决策函数。
+ * 输入所有证据，输出 4 级验收结论。
+ */
+export function evaluateAcceptance(evidence: AcceptanceEvidence): AcceptanceResult {
+  const reasons: string[] = [];
+  const requiredEvidence: string[] = [];
+  const failChecks: AcceptanceCheck[] = [];
+  const warnChecks: AcceptanceCheck[] = [];
+
+  // 收集 fail 和 warn 检查项
+  for (const check of evidence.checks) {
+    if (check.result === "fail") {
+      failChecks.push(check);
+    } else if (check.result === "warn") {
+      warnChecks.push(check);
+    }
+  }
+
+  // ── Rule 1: fail 级检查项 → REJECTED ──────────────────────
+  if (failChecks.length > 0) {
+    for (const check of failChecks) {
+      reasons.push(`[FAIL] ${check.name}: ${check.detail}`);
+    }
+    return {
+      verdict: "REJECTED",
+      acceptance_status: "rejected",
+      reason: `${failChecks.length} fail-level check(s): ${failChecks.map((c) => c.name).join(", ")}`,
+      reasons,
+      required_evidence: requiredEvidence.length > 0 ? requiredEvidence : ["Fix all fail-level issues and re-run audit_task"],
+      next_suggested_task: `Fix fail-level issues: ${failChecks.map((c) => c.name).join(", ")}`,
+      fail_checks: failChecks,
+      warn_checks: warnChecks,
+    };
+  }
+
+  // ── Rule 2: release claims 无法验证 → BLOCKED_BY_APPROVAL ──
+  if (evidence.release_claims_unverified) {
+    reasons.push("[BLOCKED] Release claims detected but remote state cannot be verified");
+    requiredEvidence.push("Verify remote release state (npm publish, GitHub release, git tag)");
+    return {
+      verdict: "BLOCKED_BY_APPROVAL",
+      acceptance_status: "blocked",
+      reason: "Release claims require manual verification of remote state",
+      reasons,
+      required_evidence: requiredEvidence,
+      next_suggested_task: "Manually verify remote release state, then re-run audit_task",
+      fail_checks: failChecks,
+      warn_checks: warnChecks,
+    };
+  }
+
+  // ── Rule 3: warn 级检查项 → NEEDS_FIX ──────────────────────
+  if (warnChecks.length > 0) {
+    for (const check of warnChecks) {
+      reasons.push(`[WARN] ${check.name}: ${check.detail}`);
+    }
+    return {
+      verdict: "NEEDS_FIX",
+      acceptance_status: "needs_fix",
+      reason: `${warnChecks.length} warn-level check(s) require fixes: ${warnChecks.map((c) => c.name).join(", ")}`,
+      reasons,
+      required_evidence: requiredEvidence.length > 0 ? requiredEvidence : ["Resolve all warn-level issues"],
+      next_suggested_task: `Fix warn-level issues: ${warnChecks.map((c) => c.name).join(", ")}`,
+      fail_checks: failChecks,
+      warn_checks: warnChecks,
+    };
+  }
+
+  // ── Rule 4: 所有检查通过 → ACCEPTED ───────────────────────
+  return {
+    verdict: "ACCEPTED",
+    acceptance_status: "accepted",
+    reason: "All acceptance checks passed",
+    reasons: ["All checks passed, no warnings or failures"],
+    required_evidence: [],
+    next_suggested_task: "Task accepted. Proceed to next goal or task.",
+    fail_checks: failChecks,
+    warn_checks: warnChecks,
+  };
+}
+
+/**
+ * 将 AcceptanceVerdict 映射到 AcceptanceStatus（用于回写 status.json）。
+ */
+export function verdictToStatus(verdict: AcceptanceVerdict): AcceptanceStatus {
+  switch (verdict) {
+    case "ACCEPTED": return "accepted";
+    case "REJECTED": return "rejected";
+    case "NEEDS_FIX": return "needs_fix";
+    case "BLOCKED_BY_APPROVAL": return "blocked";
+  }
+}

package/src/goal/acceptanceTemplate.ts

@@ -0,0 +1,121 @@
+/**
+ * v0.7.2: ACCEPTANCE.md 模板生成 — 人类可读的验收报告导出。
+ *
+ * 将 AcceptanceResult 渲染为 Markdown，落盘到 .patchwarden/tasks/{task_id}/ACCEPTANCE.md。
+ */
+
+import type { AcceptanceResult, AcceptanceEvidence } from "./acceptanceEngine.js";
+import { PATCHWARDEN_VERSION } from "../version.js";
+
+/**
+ * 生成 ACCEPTANCE.md 内容。
+ */
+export function renderAcceptanceMarkdown(
+  taskId: string,
+  result: AcceptanceResult,
+  evidence: AcceptanceEvidence
+): string {
+  const lines: string[] = [];
+  const now = new Date().toISOString();
+
+  lines.push("# Acceptance Report — " + taskId);
+  lines.push("");
+  lines.push("Generated: " + now);
+  lines.push("");
+
+  // ── Verdict ──────────────────────────────────────────────
+  lines.push("## Verdict");
+  lines.push("");
+  lines.push("| Field | Value |");
+  lines.push("| --- | --- |");
+  lines.push("| Verdict | **" + result.verdict + "** |");
+  lines.push("| Acceptance Status | " + (result.acceptance_status ?? "null") + " |");
+  lines.push("| Reason | " + result.reason + " |");
+  lines.push("| Next Suggested Task | " + result.next_suggested_task + " |");
+  lines.push("");
+
+  // ── Evidence Summary ────────────────────────────────────
+  lines.push("## Evidence Summary");
+  lines.push("");
+  lines.push("| Evidence | Present |");
+  lines.push("| --- | --- |");
+  lines.push("| result.md | " + (evidence.result_md_exists ? "YES" : "NO") + " |");
+  lines.push("| result.json | " + (evidence.result_json_exists ? "YES" : "NO") + " |");
+  lines.push("| verify.json | " + (evidence.verify_json_exists ? "YES" : "NO") + " |");
+  lines.push("| test.log | " + (evidence.test_log_exists ? "YES" : "NO") + " |");
+  lines.push("| git.diff | " + (evidence.git_diff_exists ? "YES" : "NO") + " |");
+  lines.push("| verify_status | " + (evidence.verify_status ?? "N/A") + " |");
+  lines.push("| artifact_status | " + (evidence.artifact_status ?? "N/A") + " |");
+  lines.push("| out_of_scope_changes | " + evidence.new_out_of_scope_changes.length + " |");
+  lines.push("| release_claims_unverified | " + (evidence.release_claims_unverified ? "YES" : "NO") + " |");
+  lines.push("");
+
+  // ── Task Metadata ────────────────────────────────────────
+  if (evidence.goal || evidence.scope || evidence.forbidden || evidence.verification || evidence.done_evidence) {
+    lines.push("## Task Acceptance Criteria");
+    lines.push("");
+    if (evidence.goal) {
+      lines.push("- **Goal**: " + evidence.goal);
+    }
+    if (evidence.scope && evidence.scope.length > 0) {
+      lines.push("- **Scope**: " + evidence.scope.join(", "));
+    }
+    if (evidence.forbidden && evidence.forbidden.length > 0) {
+      lines.push("- **Forbidden**: " + evidence.forbidden.join(", "));
+    }
+    if (evidence.verification && evidence.verification.length > 0) {
+      lines.push("- **Verification**: " + evidence.verification.join(", "));
+    }
+    if (evidence.done_evidence && evidence.done_evidence.length > 0) {
+      lines.push("- **Done Evidence**: " + evidence.done_evidence.join(", "));
+    }
+    lines.push("");
+  }
+
+  // ── Fail Checks ─────────────────────────────────────────
+  if (result.fail_checks.length > 0) {
+    lines.push("## Fail-Level Checks");
+    lines.push("");
+    for (const check of result.fail_checks) {
+      lines.push("- **" + check.name + "**: " + check.detail);
+    }
+    lines.push("");
+  }
+
+  // ── Warn Checks ─────────────────────────────────────────
+  if (result.warn_checks.length > 0) {
+    lines.push("## Warn-Level Checks");
+    lines.push("");
+    for (const check of result.warn_checks) {
+      lines.push("- **" + check.name + "**: " + check.detail);
+    }
+    lines.push("");
+  }
+
+  // ── Reasons ─────────────────────────────────────────────
+  if (result.reasons.length > 0) {
+    lines.push("## Reasons");
+    lines.push("");
+    for (const reason of result.reasons) {
+      lines.push("- " + reason);
+    }
+    lines.push("");
+  }
+
+  // ── Required Evidence ────────────────────────────────────
+  if (result.required_evidence.length > 0) {
+    lines.push("## Required Evidence");
+    lines.push("");
+    for (const reqEvidence of result.required_evidence) {
+      lines.push("- " + reqEvidence);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("");
+  lines.push("This report was generated by PatchWarden v" + PATCHWARDEN_VERSION + " acceptanceEngine.");
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/goal/goalGraph.ts

@@ -0,0 +1,225 @@
+/**
+ * v0.8.0: Goal Session 依赖图 — 就绪/阻塞判定、下一子目标建议、环检测、拓扑排序。
+ *
+ * 所有函数均为纯函数，不修改传入的 goalStatus 对象。
+ * 依赖语义：subgoal.depends_on 引用其他 subgoal 的 id，被引用者 status 必须为
+ * "accepted" 才算依赖满足。引用不存在的 id 视为数据不一致，按阻塞处理。
+ */
+
+import type { GoalStatus, Subgoal } from "./goalStatus.js";
+import { PatchWardenError } from "../errors.js";
+
+// ── 内部工具 ──────────────────────────────────────────────────────
+
+/**
+ * 构建 subgoal_id → Subgoal 的查找表。
+ */
+function buildSubgoalMap(goalStatus: GoalStatus): Map<string, Subgoal> {
+  const map = new Map<string, Subgoal>();
+  for (const s of goalStatus.subgoals) {
+    map.set(s.id, s);
+  }
+  return map;
+}
+
+/**
+ * 判断单个 subgoal 的依赖是否全部满足（所有 depends_on 引用存在且 status 为 accepted）。
+ * depends_on 为空视为依赖满足。引用不存在的 id 视为未满足。
+ */
+function areDependenciesMet(subgoal: Subgoal, subgoalMap: Map<string, Subgoal>): boolean {
+  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: GoalStatus): Subgoal[] {
+  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: GoalStatus
+): Array<{ subgoal: Subgoal; blocked_by: string[] }> {
+  const subgoalMap = buildSubgoalMap(goalStatus);
+  const result: Array<{ subgoal: Subgoal; blocked_by: string[] }> = [];
+
+  for (const s of goalStatus.subgoals) {
+    if (s.status !== "ready") continue;
+    const blockedBy: string[] = [];
+    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: GoalStatus): {
+  subgoal_id: string | null;
+  title?: string;
+  depends_on?: string[];
+  reason?: string;
+  blocked_by?: string[];
+} {
+  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: GoalStatus): string[] | null {
+  const subgoalMap = buildSubgoalMap(goalStatus);
+
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  for (const s of goalStatus.subgoals) {
+    color.set(s.id, WHITE);
+  }
+
+  let cycle: string[] | null = null;
+
+  const dfs = (id: string, path: string[]): boolean => {
+    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: GoalStatus): string[] {
+  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<string>();
+  const result: string[] = [];
+
+  const visit = (id: string): void => {
+    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;
+}