@ifrankwang/openspec-agents 0.130.0 → 0.132.0

package/src/core/git.ts

@@ -1,6 +1,16 @@
 import path from "path"
 import { execFile } from "node:child_process"
-import { readFile, writeFile, stat } from "node:fs/promises"
+import { readFile, writeFile, stat, rm } from "node:fs/promises"
+
+/** 判断路径是否存在于磁盘（fs 层判断，git 命令结果不作为存在性依据）。 */
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
 
 export interface GitRunner {
   run(worktree: string, args: string[]): Promise<string>
@@ -54,6 +64,85 @@ export async function runGitChecked(
   return gitRunner.runChecked(worktree, args)
 }
 
+/** worktree 清理结果：成功判定以目录从磁盘真实消失为准，不信任单条 git 命令的退出码。 */
+export interface WorktreeRemovalResult {
+  /** 目录最终是否已从磁盘消失。 */
+  dirResolved: boolean
+  /** 目录是否经文件系统兜底删除后才消失（true 表示主路径未直接达成，发生了补救）。 */
+  dirResolvedByFallback: boolean
+  /** worktree prune 是否执行成功（幽灵管理记录清理）。 */
+  pruned: boolean
+  /** 分支删除结果：null=未指定分支或因目录残留被跳过；true/false=删除断言结果。 */
+  branchDeleted: boolean | null
+  /** 各环节失败原因聚合（人类可读），全部成功时为空数组。 */
+  errors: string[]
+}
+
+/**
+ * 删除任务组 worktree 并清理关联管理记录（收尾清理与 set_worktree 复用失败重建共用）。
+ *
+ * 序列：
+ * 1. 目录不存在 → 直接 prune（清理只残留管理记录的幽灵 worktree）；
+ * 2. 目录存在 → `git worktree remove --force`；命令失败或目录仍在磁盘时走补救链：
+ *    fs 递归删除 + prune（prune 失败仅记入 errors，不阻断）；
+ * 3. 目录确认消失后才 `git branch -D`；仍残留则跳过删分支并记入 errors，
+ *    防止孤儿分支掩盖问题、以及向不完整状态发出被 git 拒绝的命令。
+ *
+ * @param repoRoot 主仓库根路径（worktree 管理命令的 -C 目标）
+ * @param wtPath 待删除的 worktree 路径
+ * @param opts.branchName 关联分支名；缺省/null 时只做 worktree 侧清理
+ */
+export async function removeTaskGroupWorktree(
+  repoRoot: string,
+  wtPath: string,
+  opts: { branchName?: string | null } = {},
+): Promise<WorktreeRemovalResult> {
+  const result: WorktreeRemovalResult = { dirResolved: false, dirResolvedByFallback: false, pruned: false, branchDeleted: null, errors: [] }
+
+  if (!(await pathExists(wtPath))) {
+    const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"])
+    if (pruneRes.success) result.pruned = true
+    else result.errors.push(`worktree prune 失败：${pruneRes.stderr}`)
+    result.dirResolved = true
+  } else {
+    const rmRes = await runGitChecked(repoRoot, ["worktree", "remove", wtPath, "--force"])
+    if (!rmRes.success) result.errors.push(`git worktree remove 失败：${rmRes.stderr}`)
+    if (await pathExists(wtPath)) {
+      // 补救链：fs 物理删除目录 + prune 清理残留管理记录
+      try {
+        await rm(wtPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+      } catch (e) {
+        result.errors.push(`文件系统兜底删除 "${wtPath}" 失败：${e instanceof Error ? e.message : String(e)}`)
+      }
+      const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"])
+      if (pruneRes.success) result.pruned = true
+      else result.errors.push(`worktree prune 失败：${pruneRes.stderr}`)
+      if (!(await pathExists(wtPath))) {
+        result.dirResolved = true
+        result.dirResolvedByFallback = true
+      }
+    } else {
+      result.dirResolved = true
+    }
+  }
+
+  if (!result.dirResolved) {
+    if (opts.branchName) {
+      result.errors.push(`目录 "${wtPath}" 未能删除，跳过分支 "${opts.branchName}" 的删除以保留排查线索`)
+    }
+    return result
+  }
+  if (opts.branchName) {
+    const branchRes = await runGitChecked(repoRoot, ["branch", "-D", opts.branchName])
+    if (branchRes.success) result.branchDeleted = true
+    else {
+      result.branchDeleted = false
+      result.errors.push(`删除分支 "${opts.branchName}" 失败：${branchRes.stderr}`)
+    }
+  }
+  return result
+}
+
 export async function getCurrentHead(worktree: string): Promise<string> {
   return runGit(worktree, ["rev-parse", "HEAD"])
 }

package/src/core/tools/lifecycle.ts

@@ -1,8 +1,9 @@
 import path from "path"
+import { rmdir } from "node:fs/promises"
 import type { OrchestrateState, TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
-import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../types.ts"
+import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS, SIMPLE_REVIEW_STEPS } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
-import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, type DetectChangesResult } from "../git.ts"
+import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, removeTaskGroupWorktree, type DetectChangesResult } from "../git.ts"
 import { readStateByWorktree, readStateByChangeId, writeState, writeContextToWorktree } from "../state.ts"
 import { generateIsolationNamespace } from "../namespace.ts"
 import { readExemptions } from "../exemptions.ts"
@@ -134,8 +135,9 @@ function firstUnpassedReviewStep(item: WorkItem, workflow: LoadedWorkflow): stri
  * simple 分支（mode === "simple"，3.2）：无 analyze / verify_* step，task_analysis / dev_impl 均落
  *   in_progress/implement（task_analysis 重置 task children 全 todo，dev_impl 保留既有进度）；review 落
  *   review/quality_review——implement 置 passed、quality_review 的 failed tag 删除回 pending（passed 保留）、
- *   task children 缺省 done；reset_steps / review_layer 参数在 simple 下接受但空操作（值域校验不变，
- *   simple 无对应 verify step 可操作，文档标注无效）。
+ *   task children 缺省 done；reset_steps 按模式生效（simple 仅接受 quality_review，含该值时清空
+ *   quality_review 全部 tags——passed 也清，强制重审正是该参数的目的，清空后引擎重派该 step 审查者）；
+ *   review_layer 在 simple 下无对应子层（仅 quality_review 单层），接受但不生效，init 返回体输出警告。
  */
 function applyRecoveryState(
   item: WorkItem,
@@ -175,7 +177,12 @@ function applyRecoveryState(
         if (item.tags[key] !== "passed") delete item.tags[key]
       }
     }
-    // reset_steps / review_layer 在 simple 下接受但空操作（值域校验在 assertValidRecovery 不变）
+    // reset_steps（simple 模式仅 quality_review）：含该值时清空该 step 全部 tags（passed 也清——
+    // 强制重审正是该参数的目的，含「已通过但任务验证/裁定遗漏」场景），tag 清空后引擎重派该 step 审查者
+    if (((recovery?.reset_steps ?? []) as string[]).includes("quality_review")) {
+      clearStepTags(item, "quality_review")
+    }
+    // review_layer 在 simple 下无对应子层，接受但不生效（init 返回体对该组合输出警告）
     item.currentStep = "quality_review"
     syncTaskChildren(item, parsedTasks, { defaultStatus: "done" })
     return
@@ -240,8 +247,10 @@ function applyRecoveryState(
  * - phase 必须为合法恢复阶段（task_analysis/dev_impl/review），缺失/非法即抛错并列出合法值；
  * - review_layer 必须为合法子层（tool/task/quality），非法即抛错；
  * - review_layer 仅当 phase=review 时允许存在，其余 phase 组合复用既有组合错误消息；
- * - reset_steps 必须为合法 verify step（verify_tool/verify_task/verify_quality），非空数组，
- *   仅当 phase=review 时允许存在，且与 review_layer 互斥（二者都操纵哪些 review step 通过）。
+ * - reset_steps 必须为非空数组，仅当 phase=review 时允许存在，且与 review_layer 互斥
+ *   （二者都操纵哪些 review step 通过）。reset_steps 的 step 值域按模式生效（full 仅
+ *   verify_tool/verify_task/verify_quality，simple 仅 quality_review），由
+ *   assertValidResetStepValues 在 state 读取后做模式感知校验——本函数仅做与模式无关的组合校验。
  */
 function assertValidRecovery(recovery: InitParams["recovery"]): void {
   if (recovery === undefined) return
@@ -266,14 +275,28 @@ function assertValidRecovery(recovery: InitParams["recovery"]): void {
       throw new Error("reset_steps 与 review_layer 互斥，不可同时使用。")
     }
     if (recovery.reset_steps.length === 0) {
-      throw new Error("reset_steps 不能为空数组，请至少指定一个 verify step。")
+      throw new Error("reset_steps 不能为空数组，请至少指定一个审查 step。")
     }
-    for (const stepId of recovery.reset_steps) {
-      if (!(REVIEW_VERIFY_STEPS as readonly string[]).includes(stepId)) {
-        throw new Error(
-          `reset_steps 中的 step "${stepId}" 不合法，合法值：${REVIEW_VERIFY_STEPS.join("、")}。传入值："${stepId}"。`
-        )
-      }
+  }
+}
+
+/**
+ * reset_steps 值域的模式感知校验（state 读取/固化后调用——有效模式 = state.mode ?? "full"）：
+ * - full 模式仅接受 verify_tool/verify_task/verify_quality；
+ * - simple 模式仅接受 quality_review；
+ * 跨模式值抛错并列出当前模式的合法值。phase/review_layer/组合校验在 assertValidRecovery 前置
+ * （错误早于任何状态变更且不落盘），值域校验依赖 state.mode 故后置到 state 读取之后——
+ * state 读取不是状态变更，该原则不破坏。
+ */
+function assertValidResetStepValues(recovery: InitParams["recovery"], mode: WorkflowMode): void {
+  if (!recovery?.reset_steps?.length) return
+  const valid = mode === "simple" ? SIMPLE_REVIEW_STEPS : REVIEW_VERIFY_STEPS
+  for (const stepId of recovery.reset_steps) {
+    if (!(valid as readonly string[]).includes(stepId)) {
+      throw new Error(
+        `reset_steps 中的 step "${stepId}" 不属于当前模式（${mode}）的审查 step，` +
+        `合法值：${valid.join("、")}。传入值："${stepId}"。`
+      )
     }
   }
 }
@@ -388,6 +411,10 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
     state.isolationNamespace = state.isolationNamespace || generateIsolationNamespace(state.changeId)
   }
 
+  // reset_steps 值域的模式感知校验：位于 state 读取/固化之后（有效模式 = state.mode ?? "full"，
+  // 与 applyRecoveryState 消费的生效模式一致）、一切状态变更与落盘之前，跨模式值报错不落盘
+  assertValidResetStepValues(args.recovery, state.mode ?? "full")
+
   // 按 tasks.md 构造全部任务组的 task WorkItem（单轨：workItems 为唯一事实源）
   for (const group of parsedGroups) {
     const isCurrent = group.id === args.task_group_id
@@ -490,6 +517,11 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
   const parts = ["编排会话已初始化。"]
   if (args.recovery) parts.push(`已恢复到 ${args.recovery.phase} 阶段。`)
   if (modeSwitchNote) parts.push(modeSwitchNote)
+  // review_layer 在 simple 模式下无对应子层（仅 quality_review 单层审查），该参数接受但不生效：
+  // 返回体显式警告，避免调用方误以为已按子层恢复
+  if (args.recovery?.review_layer && (state.mode ?? "full") === "simple") {
+    parts.push("\n\n⚠️ simple 模式无 review 子层（仅 quality_review 单层审查），recovery.review_layer 参数未生效。")
+  }
   return parts.join("")
 }
 
@@ -576,13 +608,13 @@ export async function setWorktreeExecute(params: SetWorktreeParams, ctx: ToolCon
         await bindWorktreeRefs(item, existingPath, branch, state.baseBranch)
         reused = true
       } else {
-        const rmResult = await runGitChecked(repoRoot, ["worktree", "remove", existingPath, "--force"])
-        if (!rmResult.success) {
-          throw new Error(`无法清理已有 worktree "${existingPath}"：${rmResult.stderr}`)
-        }
-        const branchRmResult = await runGitChecked(repoRoot, ["branch", "-D", branch])
-        if (!branchRmResult.success) {
-          throw new Error(`无法清理已有分支 "${branch}"：${branchRmResult.stderr}`)
+        // 复用失败的清理走共享清理函数：目录侧（git remove + fs 兜底 + prune）与分支删除统一语义
+        const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch })
+        if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
+          const problems: string[] = []
+          if (!cleanup.dirResolved) problems.push(`无法清理已有 worktree "${existingPath}"`)
+          if (cleanup.branchDeleted === false) problems.push(`无法清理已有分支 "${branch}"`)
+          throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}\n请手动处理后重试。`)
         }
       }
     }
@@ -667,6 +699,22 @@ export async function statusExecute(params: StatusParams, ctx: ToolContext): Pro
   return renderWorkflowStatusView(item, workflow, rec, { agent, orchestrator: ctx.orchestrator, identityDeclared: ctx.identityDeclared }, { state, tg, mainPollution, toolChanges, exemptedHits, exemptionItems })
 }
 
+/**
+ * 收尾后清扫默认布局的空父目录（`.worktree/<changeId>` 与 `.worktree`）：
+ * 仅对这两级字面路径做非递归 rmdir（空目录才会成功），任一失败静默忽略。
+ * 自定义 worktree_path 时以「被删目录的实际 dirname === `.worktree/<changeId>`」判定是否可扫第一级，
+ * 第二级固定只试 `.worktree` 本身；其余任意父路径一律不做处理。
+ */
+async function sweepEmptyWorktreeParents(repoRoot: string, removedDir: string, changeId: string): Promise<void> {
+  const repoRootAbs = path.resolve(repoRoot)
+  const groupLevelDir = path.join(repoRootAbs, ".worktree", changeId)
+  const worktreeLevelDir = path.join(repoRootAbs, ".worktree")
+  if (path.dirname(path.resolve(removedDir)) === groupLevelDir) {
+    try { await rmdir(groupLevelDir) } catch {}
+  }
+  try { await rmdir(worktreeLevelDir) } catch {}
+}
+
 export async function completeTaskGroupExecute(params: { change_id: string }, ctx: ToolContext): Promise<string> {
   assertOrchestrator(ctx, "opx_orch_complete_task_group")
   const state = await readStateByWorktree(ctx.worktree, params.change_id)
@@ -731,17 +779,40 @@ export async function completeTaskGroupExecute(params: { change_id: string }, ct
       ].join("\n")
     }
   }
-  if (worktreePath && branchName) {
-    try {
-      await runGit(ctx.worktree, ["worktree", "remove", worktreePath, "--force"])
-      await runGit(ctx.worktree, ["branch", "-D", branchName])
-    } catch {
+  // 收尾清理：只要记录了 worktree_path 就执行；branch_name 缺省时仅做 worktree 侧清理。
+  // 残留不阻断收尾：completed_at 照写，残留信息写入 metadata.cleanup_residual 并在返回体给出人工处理命令。
+  let cleanupNote = ""
+  let cleanupResidualWarning = ""
+  if (worktreePath) {
+    const cleanup = await removeTaskGroupWorktree(ctx.worktree, worktreePath, { branchName })
+    if (cleanup.dirResolved) {
+      await sweepEmptyWorktreeParents(ctx.worktree, worktreePath, params.change_id)
+      const successNotes: string[] = []
+      if (cleanup.dirResolvedByFallback) {
+        successNotes.push("- **cleanup**: git worktree remove 未直接移除目录，已按文件系统兜底删除并 prune 管理记录。")
+      }
+      if (cleanup.errors.length > 0) {
+        successNotes.push(`- **cleanup 部分告警**: ${cleanup.errors.join("；")}`)
+      }
+      cleanupNote = successNotes.join("\n")
+    } else {
+      item.metadata["cleanup_residual"] = { worktree_path: worktreePath, errors: cleanup.errors }
+      cleanupResidualWarning = [
+        "",
+        "## ⚠️ worktree 清理残留（不影响收尾）",
+        `- **残留路径**: \`${worktreePath}\``,
+        "- **原因**:",
+        ...cleanup.errors.map((e) => `  - ${e}`),
+        `- **处理**: 请人工执行 \`rm -rf '${worktreePath}' && git worktree prune\` 清理残留目录与 git 管理记录。`,
+        branchName ? `- **分支**: 分支 "${branchName}" 未删除。` : "",
+      ].filter(Boolean).join("\n")
     }
   }
   item.metadata["completed_at"] = new Date().toISOString()
   await writeState(ctx.worktree, state)
   const doneMessage = `任务组已完成并合并到 "${mergeTarget}"。`
-  return checkboxWarning ? `${doneMessage}\n${checkboxWarning}` : doneMessage
+  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean)
+  return notes.length > 0 ? `${doneMessage}\n${notes.join("\n")}` : doneMessage
 }
 
 export async function setUnattendedExecute(params: UnattendedParams, ctx: ToolContext): Promise<string> {

package/src/core/tools/schemas.ts

@@ -191,8 +191,8 @@ export const recoverySchema: JSONSchema = {
     reset_steps: {
       type: "array",
       description:
-        "重置指定 verify step 的通过标记为 pending（仅 phase=review 时有效，与 review_layer 互斥）。用于已 passed 但被本层遗漏复核/裁定阻塞的 review step 强制重新审查；恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。",
-      items: { type: "string", enum: ["verify_tool", "verify_task", "verify_quality"] },
+        "重置指定审查 step 的通过标记为 pending（仅 phase=review 时有效，与 review_layer 互斥）。用于已 passed 但被本层遗漏复核/裁定/任务验证阻塞的 review step 强制重新审查；恢复后 currentStep 落在第一个未全部通过的审查 step，可能早于被重置的 step。值按模式生效：full 模式合法值为 verify_tool/verify_task/verify_quality，simple 模式合法值为 quality_review；传入不属于当前模式的值会在运行时报错。",
+      items: { type: "string", enum: ["verify_tool", "verify_task", "verify_quality", "quality_review"] },
     },
   },
   required: ["phase"],
@@ -312,7 +312,7 @@ export const agentSubmitSchema: JSONSchema = {
     blockers: { type: "array", description: "analyze step：新增 blocker 列表", items: blockerItem },
     blocker_updates: {
       type: "array",
-      description: "analyze step：按 blocker_id 置 resolved 并记录用户答复",
+      description: "analyze / implement step：按 blocker_id 置 resolved 并记录用户答复（implement 下人工执行任务凭留痕重新申报的依据）",
       items: {
         type: "object",
         properties: {
@@ -349,12 +349,13 @@ export const agentSubmitSchema: JSONSchema = {
     },
     verified_tasks: {
       type: "array",
-      description: "verify_task step：验证通过的 task id",
+      description:
+        "verify_task / quality_review step（任务验证归属层）：逐项确认验证通过的 task id；passed 提交时 submitted task 必须被 verified_tasks/failed_tasks 全覆盖（工具强制门禁），漏带会被拒绝",
       items: { type: "string" },
     },
     failed_tasks: {
       type: "array",
-      description: "verify_task step：验证失败的 task 列表（含原因）",
+      description: "verify_task / quality_review step：验证失败的 task 列表（含原因）",
       items: taskVerifyItem,
     },
   },

package/src/core/tools/submit.ts

@@ -57,6 +57,49 @@ function isSupplementOnly(params: AgentSubmitParams): boolean {
   )
 }
 
+/**
+ * 判定本次提交是否「仅携带任务验证补交」（verified_tasks 非空，其余实质参数全空）。
+ * 供重复提交守卫的补交豁免：任务验证归属 step（verify_task/quality_review）上次 passed 提交
+ * 漏带 verified_tasks 导致 task children 卡 review 态（done 收口被拦截，见 engine
+ * recommendForItem 的 gateBlock 补交推导）时，允许仅补带 verified_tasks 重提解除阻塞；
+ * 空提交或携带其他实质参数的重复提交仍被守卫拒绝。放行须叠加「存在 review 态 task child」
+ * 条件（与引擎推导条件同源），防止放行面过宽。
+ */
+function isTaskVerificationSupplement(params: AgentSubmitParams): boolean {
+  if ((params.verified_tasks?.length ?? 0) === 0) return false
+  return (
+    (params.failed_tasks?.length ?? 0) === 0 &&
+    (params.new_children?.length ?? 0) === 0 &&
+    (params.fixed_issue_ids?.length ?? 0) === 0 &&
+    (params.exempt_issue_ids?.length ?? 0) === 0 &&
+    (params.exempt_adjudications?.length ?? 0) === 0 &&
+    (params.recheck_adjudications?.length ?? 0) === 0 &&
+    !params.boundary_expansion &&
+    (params.validation_steps?.length ?? 0) === 0 &&
+    params.test_results === undefined
+  )
+}
+
+/**
+ * 任务验证补交放行判定（重复提交守卫的豁免与必做清单门禁的跳过共用同源条件）：仅携带
+ * verified_tasks 的严格补交形态，且该 agent 在该 step 已 passed、item 存在 review 态
+ * （submitted）task child——与守卫放宽、引擎 gateBlock 补交推导条件同源。
+ * 必做门禁的跳过绑定本条件（而非仅形态判定）：首次提交（step 尚未 passed）不得借补交形态
+ * 跳过必做清单覆盖度校验——补交跳过的理由是完整审查在首次 passed 时已做过。
+ */
+function isTaskVerifySupplementAllowed(
+  item: WorkItem,
+  params: AgentSubmitParams,
+  stepId: string,
+  agent: string,
+): boolean {
+  return (
+    isTaskVerificationSupplement(params) &&
+    getStepVerdict(item, stepId, agent) === "passed" &&
+    taskChildrenOf(item).some((c) => c.phase === "review")
+  )
+}
+
 /**
  * 统一裁定一致性守卫：任一裁定参数含「驳回（rejected）」时，提交级 verdict 必须为 failed。
  * - exempt_adjudications 含 action==="rejected"（issue 回 todo 继续修复）→ verdict 必须为 failed
@@ -232,9 +275,11 @@ function clearReviewVerificationTags(item: WorkItem): void {
   clearStepTags(item, "verify_quality")
 }
 
-/** blocker 提交后的 reset 助手：task children 全 todo + 清 review 层验证标记（对齐旧 resetForBlocker）。 */
+/** blocker 提交后的 reset 助手：task children 仅 todo/review 态回 todo（done 已验证不得降级，
+ *  对齐 handleImplementParams 提交时对 done 态的跳过语义）+ 清 review 层验证标记（对齐旧 resetForBlocker）。 */
 function resetTasksForBlocker(item: WorkItem): void {
   for (const child of taskChildrenOf(item)) {
+    if (child.phase === "done") continue
     child.phase = "todo"
     delete child.metadata["reject_reason"]
   }
@@ -264,10 +309,19 @@ function handleAnalyzeParams(item: WorkItem, params: AgentSubmitParams): void {
   }
 }
 
-/** implement step 参数处理：blocker（on_fail）、completed_task_ids + 覆盖门禁、self_check_results /
- *  test_results 申报存档。 */
+/** implement step 参数处理：blocker（on_fail）、blocker_updates 消费闭环 + 无未解决 blocker 门禁、
+ *  completed_task_ids + 覆盖门禁、self_check_results / test_results 申报存档。 */
 function handleImplementParams(item: WorkItem, params: AgentSubmitParams): void {
   if (params.blocker) {
+    // 同轮组合显式拒绝（置于分支最前，先于一切写入）：blocker 分支在下方 return，同轮携带的
+    // blocker_updates 会被静默丢弃（丢失申报）。校验放行面只有分两轮：先 failed+blocker 上报新
+    // 阻塞，用户确认后下一轮再 blocker_updates + 重新提交。
+    if (params.blocker_updates?.length) {
+      throw new Error(
+        "不可在同一轮提交中同时上报新 blocker（blocker 参数）与更新旧 blocker（blocker_updates）。\n" +
+        "请分两轮处理：先以 verdict=failed + blocker 上报新阻塞；用户确认后，下一轮再携带 blocker_updates 记录答复并重新提交。"
+      )
+    }
     if (params.verdict !== "failed") {
       throw new Error("blocker 参数仅支持 verdict=failed 提交（on_fail 回退 analyze）。")
     }
@@ -276,6 +330,23 @@ function handleImplementParams(item: WorkItem, params: AgentSubmitParams): void
     return
   }
 
+  // blocker_updates 消费闭环（校验语义与 handleAnalyzeParams 一致）：按 blocker_id 置 resolved 并记录
+  // 用户答复。task 指向型 blocker（人工执行/环境不可验证任务）经用户确认留痕后，开发者凭该记录将对应
+  // 任务列入 completed_task_ids 重新申报，审查者核验留痕后方可在任务验证层确认。
+  // 位于 blocker 分支之外：blocker 是本轮上报参数（上方分支 return），blocker_updates 是后续轮次参数。
+  if (params.blocker_updates?.length) {
+    for (const u of params.blocker_updates) {
+      const blocker = itemBlockers(item).find((b) => b.id === u.blocker_id)
+      if (!blocker) throw new Error(`blocker "${u.blocker_id}" 不存在于 metadata.blockers 中。`)
+      if (blocker.status !== "awaiting_user") throw new Error(`blocker "${u.blocker_id}" 状态不是 awaiting_user，无法更新。`)
+      blocker.userResponse = u.user_response
+      blocker.status = "resolved"
+    }
+  }
+  if (params.verdict === "passed" && itemBlockers(item).some((b) => b.status !== "resolved")) {
+    throw new Error("存在未解决的 blocker，无法以 passed 提交 implement step。请先通过 blocker_updates 处理全部 blocker。")
+  }
+
   const tasks = taskListOf(item)
   const completed = normalizeTaskChildIds(params.completed_task_ids ?? [], item)
   const validIds = new Set(tasks.map((t) => t.id))
@@ -305,7 +376,8 @@ function handleImplementParams(item: WorkItem, params: AgentSubmitParams): void
     throw new Error(
       `以下 task 处于 open/rejected 状态且未在 completed_task_ids 中：\n` +
       remaining.map((t) => `- #${t.id}(${t.status}) ${t.title}`).join("\n") +
-      `\n请将未完成的 task 列在 completed_task_ids 中，或改用 blocker 上报阻塞。`
+      `\ncompleted_task_ids 仅申报已完成可供验证的任务；无法完成或人工执行的任务不得虚报，` +
+      `应以 verdict=failed + blocker 上报（task_id 指向该任务），经用户确认后凭 blocker 留痕重新申报。`
     )
   }
 
@@ -342,9 +414,10 @@ function mergeBoundaryInto(item: WorkItem, expansion: NonNullable<AgentSubmitPar
  * - verify_tool：本次 new_children 含 Low+，或存在未终态的 Low+ tool 报源层阻塞 child
  * - verify_quality：本次 new_children 含 Low+ 且维度属于当前提交 agent，或存在未终态的 Low+ quality 报源层
  *   阻塞 child 且 dimension 属于当前提交 agent 维度（新报与遗留理由均按维度过滤，F3；报源层由 source 反推）
- * - quality_review（simple 合并审查）：本次 new_children 含 Low+，或存在未终态的 Low+ quality 报源层阻塞
- *   child（不按维度过滤——openspec-reviewer 无固定维度，对全部质量层负责；按 agentToReviewDimension 过滤
- *   会对该身份恒为 undefined 导致 failed 提交死锁）
+ * - quality_review（simple 合并审查）：本次 failed_tasks 非空，或 new_children 含 Low+，或存在未终态的
+ *   Low+ quality 报源层阻塞 child（不按维度过滤——openspec-reviewer 无固定维度，对全部质量层负责；按
+ *   agentToReviewDimension 过滤会对该身份恒为 undefined 导致 failed 提交死锁。simple 审查者合并承担任务
+ *   验证语义，failed_tasks 驳回任务与 Low+ issue 同为合法 failed 理由，与 verify_task 分支对齐）
  * - verify_cleanup：本次 new_children 含 Low+，或存在未终态的 Low+ 阻塞 child（不按维度/报源层过滤——
  *   收尾层须对全部残留阻塞负责，任何层的遗留阻塞都构成不通过理由）
  * 理由判定在 dedupeNewChildren 之后调用（F4）：传入的 newChildren 为已去重的 accepted，重复新报不构成理由。
@@ -376,11 +449,14 @@ function assertFailedHasReason(
   } else if (stepId === "quality_review") {
     // simple 合并审查 step：审查者（openspec-reviewer）不归属固定质量维度，理由判定不按
     // agentToReviewDimension 过滤（该值对 openspec-reviewer 为 undefined，按维度过滤会导致任何
-    // failed 提交都报「不存在未解决的阻塞 issue」死锁）。本次新报含 Low+ issue，或存在 quality
-    // 报源（sourcePhase === "quality"）未终态阻塞 issue，均构成不通过理由——simple 审查者对
-    // 全部质量层负责，与 full 模式 verify_quality 各维度分支互不影响。
+    // failed 提交都报「不存在未解决的阻塞 issue」死锁）。simple 审查者承担任务验证（verify_task
+    // 语义），failed_tasks 与 Low+ issue 同为合法 failed 理由：本次 failed_tasks 非空（驳回任务回退
+    // implement），或本次新报含 Low+ issue，或存在 quality 报源（sourcePhase === "quality"）未终态
+    // 阻塞 issue，均构成不通过理由——simple 审查者对全部质量层负责，与 full 模式 verify_quality
+    // 各维度分支互不影响。
     layerName = "AI 审查层"
     hasReason =
+      (params.failed_tasks?.length ?? 0) > 0 ||
       hasNewBlocking ||
       existingBlocking.some((c) => resolveChildIssueFields(c).sourcePhase === "quality")
   } else {
@@ -453,7 +529,17 @@ function handleReviewParams(
     }
   }
 
-  if (params.verified_tasks?.length || params.failed_tasks?.length) {
+  // 任务验证覆盖门禁（兜底）：verify_task / quality_review（任务验证归属 step）以 passed 提交时，
+  // 「submitted task 必须被 verified/failed 全覆盖」为无条件必查——reviewer 不得 passed 而不对任何
+  // 已申报任务表态（漏带 verified_tasks 会让 task children 卡 review 态，done 收口被拦截形成死锁）。
+  // 其余 review step 维持既有条件式（携带任一数组才进入校验）；verdict=failed 不做此强制
+  // （报 issue 回退时无须给全部任务表态）。
+  const isTaskVerifyStep = stepId === "verify_task" || stepId === "quality_review"
+  if (
+    params.verified_tasks?.length ||
+    params.failed_tasks?.length ||
+    (params.verdict === "passed" && isTaskVerifyStep)
+  ) {
     const tasks = taskListOf(item)
     const validIds = new Set(tasks.map((t) => t.id))
     const verified = normalizeTaskChildIds(params.verified_tasks ?? [], item)
@@ -476,7 +562,10 @@ function handleReviewParams(
     if (uncovered.length > 0) {
       throw new Error(
         `以下 submitted task 未被 verified_tasks 或 failed_tasks 覆盖：\n` +
-        uncovered.map((t) => `- #${t.id} ${t.title}`).join("\n")
+        uncovered.map((t) => `- #${t.id} ${t.title}`).join("\n") +
+        `\nverified_tasks 用于逐项确认已完成的任务；验证未通过的任务须以 failed_tasks 逐项驳回并设 verdict=failed 回退；` +
+        `人工执行或环境不可验证的任务不得虚报确认，应以 verdict=failed + failed_tasks 驳回，` +
+        `由开发者经 verdict=failed + blocker（task_id 指向该任务）上报、用户确认留痕后凭记录重新申报完成。`
       )
     }
     for (const id of verified) {
@@ -572,17 +661,22 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
 
     // 重复提交守卫（仅 review step）：同 step 同 agent 已以 passed 通过后不允许重复提交；failed 允许重提
     // （回退重审期 failed tag 未被归因清空时须可重提，如 verify_task 仅 failed_tasks 驳回）。
-    // 补交豁免：仅携带裁定类参数（recheck_adjudications / exempt_adjudications，无其他实质参数）的补交放行——
-    // 上次提交漏带复核/豁免裁定导致本层 review 态 issue 阻塞门禁时（engine.blockedSupplementAgents 已推导
-    // 应补交的报源 reviewer），reviewer 可补带裁定重提解除阻塞；空提交/携带其他实质参数（含 fixed_issue_ids /
-    // exempt_issue_ids）的重复提交仍被拒绝。
+    // 补交豁免（两条对称通道，均要求严格形态——仅携带对应补交参数，无其他实质提交内容）：
+    // - 裁定补交：仅携带 recheck_adjudications / exempt_adjudications——上次提交漏带复核/豁免裁定导致
+    //   本层 review 态 issue 阻塞门禁时（engine.blockedSupplementAgents 已推导应补交的报源 reviewer），
+    //   reviewer 可补带裁定重提解除阻塞；
+    // - 任务验证补交：仅携带 verified_tasks 且存在 review 态 task child（与引擎 gateBlock 补交推导
+    //   条件同源）——任务验证归属 step 上次 passed 漏带 verified_tasks 导致 task children 卡 review
+    //   态、done 收口被拦截时，审查者可补交 verified_tasks 覆盖待验证任务后推进。
+    // 空提交或携带其他实质参数（含 fixed_issue_ids / exempt_issue_ids / new_children）的重复提交仍被拒绝。
     // 守卫在一切裁定（豁免/复核）之前执行，保证守卫拒绝时零副作用。step 归属按 stepMap 直接判定
     // （不依赖 assertSubmitRouting，保持越权 step 提交的裁定拦截语义不变）。
     const guardStepPhase = workflow.stepMap.get(params.step_id)?.phase.name
     if (
       guardStepPhase === "review" &&
       getStepVerdict(item, params.step_id, ctx.agent) === "passed" &&
-      !isSupplementOnly(params)
+      !isSupplementOnly(params) &&
+      !isTaskVerifySupplementAllowed(item, params, params.step_id, ctx.agent)
     ) {
       throw new Error(`重复提交守卫：agent "${ctx.agent}" 已在 step "${params.step_id}" 以 passed 通过，不允许重复提交。`)
     }
@@ -693,8 +787,13 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
       const agentCfg = stepCfg.agents.find((a) => a.id === ctx.agent)
       handleReviewParams(item, params, newChildren, params.step_id, {
         capabilityTags: agentCfg?.capability_tags ?? [],
-        // 补交豁免（仅裁定参数，无实质提交）不重复校验必做清单覆盖度
-        skipMustDoGate: isSupplementOnly(params),
+        // 补交豁免（仅裁定参数 / 仅 verified_tasks 的任务验证补交，均无实质审查内容）不重复校验
+        // 必做清单覆盖度——完整审查在首次 passed 时已做过。任务验证补交的跳过与守卫放宽同源
+        //（isTaskVerifySupplementAllowed：已 passed 且存在 review 态 task child），首次提交
+        //（step 尚未 passed）不借补交形态跳过必做门禁。
+        skipMustDoGate:
+          isSupplementOnly(params) ||
+          isTaskVerifySupplementAllowed(item, params, params.step_id, ctx.agent),
       })
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params)

package/src/core/tools/types.ts

@@ -1,4 +1,4 @@
-import type { BuildPhaseTarget, ReviewLayer, ReviewVerifyStep, WorkflowMode } from "../types.ts"
+import type { BuildPhaseTarget, ReviewLayer, ReviewVerifyStep, SimpleReviewStep, WorkflowMode } from "../types.ts"
 
 export interface ToolContext {
   worktree: string
@@ -24,9 +24,11 @@ export interface InitParams {
     phase: BuildPhaseTarget
     review_layer?: ReviewLayer
     reopenIssues?: boolean
-    /** 重置指定 verify step 的审查 tags 为 pending（仅 phase=review 时有效，与 review_layer 互斥），
-     *  恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。 */
-    reset_steps?: ReviewVerifyStep[]
+    /** 重置指定审查 step 的审查 tags 为 pending（仅 phase=review 时有效，与 review_layer 互斥），
+     *  恢复后 currentStep 落在第一个未全部通过的审查 step，可能早于被重置的 step。
+     *  值按模式生效：full 模式为 verify_tool/verify_task/verify_quality，simple 模式为 quality_review
+     *  （跨模式值在运行时报错）。 */
+    reset_steps?: ReviewVerifyStep[] | SimpleReviewStep[]
   }
   /** 流程模式（full/simple）：首次新建编排状态时固化；已开始的变更仅在切组（其他任务组均已完成
    *  或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）

package/src/core/types.ts

@@ -20,9 +20,13 @@ export type BuildPhaseTarget = typeof BUILD_PHASE_TARGETS[number]
 export const REVIEW_LAYERS = ["tool", "task", "quality"] as const
 export type ReviewLayer = typeof REVIEW_LAYERS[number]
 
-/** review 三个验证 step 合法值（recovery.reset_steps 值域）。 */
+/** review 三个验证 step 合法值（recovery.reset_steps 在 full 模式的值域）。 */
 export const REVIEW_VERIFY_STEPS = ["verify_tool", "verify_task", "verify_quality"] as const
 export type ReviewVerifyStep = typeof REVIEW_VERIFY_STEPS[number]
+
+/** simple 模式 review 合并审查 step 合法值（recovery.reset_steps 在 simple 模式的值域）。 */
+export const SIMPLE_REVIEW_STEPS = ["quality_review"] as const
+export type SimpleReviewStep = typeof SIMPLE_REVIEW_STEPS[number]
 export type OrchestrateStatus = "not_started" | "in_progress" | "completed"
 export type DimensionVerdict = "pending" | "passed" | "failed"
 export type QualityLayerProgress = Record<ReviewDimension, DimensionVerdict>

package/src/core/workflow/engine.ts

@@ -9,6 +9,7 @@ import { WORK_ITEM_PHASES, BLOCKING_SEVERITIES, stepAgentIds, EXEMPT_REQUEST_KEY
 import type { LoadedWorkflow } from "./loader.ts"
 import { tagKey } from "./types.ts"
 import { reviewLayerFromMetadata, readIssueSource } from "../constants.ts"
+import { taskChildrenOf } from "../task-children.ts"
 
 const TERMINAL_PHASES: WorkItemPhase[] = ["done", "cancelled"]
 
@@ -555,6 +556,19 @@ export function recommendForItem(item: WorkItem, workflow: LoadedWorkflow): Engi
     // 避免"step 已通过"误导造成无人再触发迁移的静默死锁。
     const gateBlock = forwardAdvanceBlockReason(item, workflow, current.step)
     if (gateBlock) {
+      // 任务验证补交推导：review 阶段 step 全 passed 但门禁被 review 态 task child 拦截（任务验证
+      // 归属 step——verify_task/quality_review——passed 提交漏带 verified_tasks，或 full 模式下游
+      // 收尾 step 推进到 done 时暴露）时，返回该 step 全部 agent 由其经 opx_agent_submit 补交
+      // verified_tasks 覆盖全部待验证任务后推进（与 submit 重复提交守卫的补交放行条件同源：
+      // 仅携带 verified_tasks + 存在 review 态 task child），不再恒返回 agents=[] 形成静默死锁。
+      if (current.phaseName === "review" && taskChildrenOf(item).some((c) => c.phase === "review")) {
+        return {
+          status: "blocked",
+          stepId: current.step.id,
+          agents: stepAgentIds(current.step),
+          blockedReason: `${gateBlock}需该 step 审查者经 opx_agent_submit 补交 verified_tasks（覆盖全部待验证任务）后推进。`,
+        }
+      }
       return {
         status: "blocked",
         stepId: current.step.id,