@ifrankwang/openspec-agents 0.131.0 → 0.132.0

package/.mcp-server/cli.mjs

@@ -29694,6 +29694,7 @@ var REVIEW_DIMENSIONS = [...CODE_DIMENSIONS];
 var BUILD_PHASE_TARGETS = ["task_analysis", "dev_impl", "review"];
 var REVIEW_LAYERS = ["tool", "task", "quality"];
 var REVIEW_VERIFY_STEPS = ["verify_tool", "verify_task", "verify_quality"];
+var SIMPLE_REVIEW_STEPS = ["quality_review"];
 
 // src/core/constants.ts
 var STATE_DIR_NAME = "openspec";
@@ -30119,6 +30120,48 @@ function stepAgentIds(step) {
   return step.agents.map((a) => a.id);
 }
 
+// src/core/task-children.ts
+function taskChildrenOf(item) {
+  return (item.children ?? []).filter((c) => c.type === "task");
+}
+function issueChildrenOf(item) {
+  return (item.children ?? []).filter((c) => c.type === "issue");
+}
+function taskChildById(item, id) {
+  return item.children.find((c) => c.type === "task" && (c.id === id || c.externalId === id)) ?? null;
+}
+function normalizeTaskChildIds(rawIds, item) {
+  const byNumber = new Map;
+  for (const c of taskChildrenOf(item)) {
+    if (c.externalId !== undefined)
+      byNumber.set(c.externalId, c.id);
+  }
+  return rawIds.map((id) => byNumber.get(id) ?? id);
+}
+function phaseToTaskStatus(phase, hasRejectReason) {
+  switch (phase) {
+    case "review":
+      return "submitted";
+    case "done":
+    case "cancelled":
+      return "verified";
+    case "todo":
+      return hasRejectReason ? "rejected" : "open";
+    default:
+      return "open";
+  }
+}
+function taskListOf(item) {
+  return taskChildrenOf(item).map((c) => ({
+    id: c.id,
+    specTrace: typeof c.metadata["specTrace"] === "string" ? c.metadata["specTrace"] : "",
+    title: c.title,
+    status: phaseToTaskStatus(c.phase, c.metadata["reject_reason"] !== undefined),
+    taskNumber: typeof c.externalId === "string" ? c.externalId : "",
+    rejectReason: typeof c.metadata["reject_reason"] === "string" ? c.metadata["reject_reason"] : null
+  }));
+}
+
 // src/core/workflow/engine.ts
 var REVIEW_STEP_TO_LAYER = {
   verify_tool: "tool",
@@ -30501,6 +30544,14 @@ function recommendForItem(item, workflow) {
     }
     const gateBlock = forwardAdvanceBlockReason(item, workflow, current.step);
     if (gateBlock) {
+      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,
@@ -30523,48 +30574,6 @@ function recommendForItem(item, workflow) {
   };
 }
 
-// src/core/task-children.ts
-function taskChildrenOf(item) {
-  return (item.children ?? []).filter((c) => c.type === "task");
-}
-function issueChildrenOf(item) {
-  return (item.children ?? []).filter((c) => c.type === "issue");
-}
-function taskChildById(item, id) {
-  return item.children.find((c) => c.type === "task" && (c.id === id || c.externalId === id)) ?? null;
-}
-function normalizeTaskChildIds(rawIds, item) {
-  const byNumber = new Map;
-  for (const c of taskChildrenOf(item)) {
-    if (c.externalId !== undefined)
-      byNumber.set(c.externalId, c.id);
-  }
-  return rawIds.map((id) => byNumber.get(id) ?? id);
-}
-function phaseToTaskStatus(phase, hasRejectReason) {
-  switch (phase) {
-    case "review":
-      return "submitted";
-    case "done":
-    case "cancelled":
-      return "verified";
-    case "todo":
-      return hasRejectReason ? "rejected" : "open";
-    default:
-      return "open";
-  }
-}
-function taskListOf(item) {
-  return taskChildrenOf(item).map((c) => ({
-    id: c.id,
-    specTrace: typeof c.metadata["specTrace"] === "string" ? c.metadata["specTrace"] : "",
-    title: c.title,
-    status: phaseToTaskStatus(c.phase, c.metadata["reject_reason"] !== undefined),
-    taskNumber: typeof c.externalId === "string" ? c.externalId : "",
-    rejectReason: typeof c.metadata["reject_reason"] === "string" ? c.metadata["reject_reason"] : null
-  }));
-}
-
 // src/core/workflow/submit.ts
 function resolveReviewStepForSource(workflow, source) {
   for (const phase of workflow.phases) {
@@ -35704,6 +35713,7 @@ function renderAnalyzeBlockers(item) {
 }
 function renderDeveloperChildren(item, ctxAgent, exemptionCtx) {
   const lines = [];
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_DEV));
   const toFix = issueChildrenOf(item).filter((c) => isAgentOwnedIssue(c, ctxAgent));
   if (toFix.length === 0)
     return lines;
@@ -35844,6 +35854,21 @@ function renderToolAdjudicateOnly(item, rec, ctxAgent, exemptedHits, exemptionCt
   return lines.join(`
 `);
 }
+var BLOCKER_TRAIL_TITLE_REVIEW = "## Blocker 留痕（人工/不可验证任务的申报依据）";
+var BLOCKER_TRAIL_TITLE_DEV = "## Blocker 留痕（已处理 blocker 的用户确认，凭记录申报完成）";
+function renderBlockerTrail(item, title) {
+  const resolved = readBlockers(item).filter((b) => b.status === "resolved" && b.userResponse);
+  if (resolved.length === 0)
+    return [];
+  const lines = [title, ""];
+  for (const b of resolved) {
+    lines.push(`- Blocker #${b.id}${b.taskId ? ` | Task #${b.taskId}` : ""} | ${b.category}`);
+    lines.push(`  - 描述：${b.description}`);
+    lines.push(`  - 用户确认：${b.userResponse}`);
+  }
+  lines.push("");
+  return lines;
+}
 function renderTaskChildren(item, ctxAgent, exemptionCtx) {
   const lines = [];
   const pendingTasks = readTasks(item).filter((t) => t.status === "submitted");
@@ -35853,6 +35878,7 @@ function renderTaskChildren(item, ctxAgent, exemptionCtx) {
       lines.push(renderTaskItem(t));
     lines.push("");
   }
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_REVIEW));
   const issues = issueChildrenOf(item);
   const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent));
   lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx));
@@ -35881,6 +35907,7 @@ function renderMergedChildren(item, ctxAgent, exemptionCtx) {
       lines.push(renderTaskItem(t));
     lines.push("");
   }
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_REVIEW));
   const issues = issueChildrenOf(item);
   const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent));
   lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx));
@@ -36077,6 +36104,9 @@ function applyRecoveryState(item, recovery, parsedTasks, mode) {
           delete item.tags[key];
       }
     }
+    if ((recovery?.reset_steps ?? []).includes("quality_review")) {
+      clearStepTags(item, "quality_review");
+    }
     item.currentStep = "quality_review";
     syncTaskChildren(item, parsedTasks, { defaultStatus: "done" });
     return;
@@ -36146,12 +36176,17 @@ function assertValidRecovery(recovery) {
       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.includes(stepId)) {
-        throw new Error(`reset_steps 中的 step "${stepId}" 不合法，合法值：${REVIEW_VERIFY_STEPS.join("、")}。传入值："${stepId}"。`);
-      }
+  }
+}
+function assertValidResetStepValues(recovery, mode) {
+  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.includes(stepId)) {
+      throw new Error(`reset_steps 中的 step "${stepId}" 不属于当前模式（${mode}）的审查 step，` + `合法值：${valid.join("、")}。传入值："${stepId}"。`);
     }
   }
 }
@@ -36234,6 +36269,7 @@ async function initExecute(params, ctx) {
     state.baseBranch = state.baseBranch || baseBranch;
     state.isolationNamespace = state.isolationNamespace || generateIsolationNamespace(state.changeId);
   }
+  assertValidResetStepValues(args.recovery, state.mode ?? "full");
   for (const group of parsedGroups) {
     const isCurrent = group.id === args.task_group_id;
     const groupTasks = tasksByGroup.get(group.id) ?? [];
@@ -36324,6 +36360,11 @@ async function initExecute(params, ctx) {
     parts.push(`已恢复到 ${args.recovery.phase} 阶段。`);
   if (modeSwitchNote)
     parts.push(modeSwitchNote);
+  if (args.recovery?.review_layer && (state.mode ?? "full") === "simple") {
+    parts.push(`
+
+⚠️ simple 模式无 review 子层（仅 quality_review 单层审查），recovery.review_layer 参数未生效。`);
+  }
   return parts.join("");
 }
 async function bindWorktreeRefs(item, worktreePath, branch, baseBranch, opts = {}) {
@@ -36593,6 +36634,14 @@ function isSupplementOnly(params) {
     return false;
   return (params.fixed_issue_ids?.length ?? 0) === 0 && (params.exempt_issue_ids?.length ?? 0) === 0 && (params.new_children?.length ?? 0) === 0 && (params.verified_tasks?.length ?? 0) === 0 && (params.failed_tasks?.length ?? 0) === 0 && !params.boundary_expansion && (params.validation_steps?.length ?? 0) === 0 && params.test_results === undefined;
 }
+function isTaskVerificationSupplement(params) {
+  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;
+}
+function isTaskVerifySupplementAllowed(item, params, stepId, agent) {
+  return isTaskVerificationSupplement(params) && getStepVerdict(item, stepId, agent) === "passed" && taskChildrenOf(item).some((c) => c.phase === "review");
+}
 function assertRejectedAdjudicationNotPassed(params) {
   if (params.verdict !== "passed")
     return;
@@ -36708,6 +36757,8 @@ function clearReviewVerificationTags(item) {
 }
 function resetTasksForBlocker(item) {
   for (const child of taskChildrenOf(item)) {
+    if (child.phase === "done")
+      continue;
     child.phase = "todo";
     delete child.metadata["reject_reason"];
   }
@@ -36739,6 +36790,10 @@ function handleAnalyzeParams(item, params) {
 }
 function handleImplementParams(item, params) {
   if (params.blocker) {
+    if (params.blocker_updates?.length) {
+      throw new Error(`不可在同一轮提交中同时上报新 blocker（blocker 参数）与更新旧 blocker（blocker_updates）。
+` + "请分两轮处理：先以 verdict=failed + blocker 上报新阻塞；用户确认后，下一轮再携带 blocker_updates 记录答复并重新提交。");
+    }
     if (params.verdict !== "failed") {
       throw new Error("blocker 参数仅支持 verdict=failed 提交（on_fail 回退 analyze）。");
     }
@@ -36746,6 +36801,20 @@ function handleImplementParams(item, params) {
     resetTasksForBlocker(item);
     return;
   }
+  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));
@@ -36767,7 +36836,7 @@ function handleImplementParams(item, params) {
     throw new Error(`以下 task 处于 open/rejected 状态且未在 completed_task_ids 中：
 ` + remaining.map((t) => `- #${t.id}(${t.status}) ${t.title}`).join(`
 `) + `
-请将未完成的 task 列在 completed_task_ids 中，或改用 blocker 上报阻塞。`);
+completed_task_ids 仅申报已完成可供验证的任务；无法完成或人工执行的任务不得虚报，` + `应以 verdict=failed + blocker 上报（task_id 指向该任务），经用户确认后凭 blocker 留痕重新申报。`);
   }
   if (params.self_check_results) {
     item.metadata["self_check_results"] = params.self_check_results;
@@ -36805,7 +36874,7 @@ function assertFailedHasReason(item, params, newChildren, stepId, agent) {
     hasReason = hasNewBlocking || existingBlocking.length > 0;
   } else if (stepId === "quality_review") {
     layerName = "AI 审查层";
-    hasReason = hasNewBlocking || existingBlocking.some((c) => resolveChildIssueFields(c).sourcePhase === "quality");
+    hasReason = (params.failed_tasks?.length ?? 0) > 0 || hasNewBlocking || existingBlocking.some((c) => resolveChildIssueFields(c).sourcePhase === "quality");
   } else {
     const dimension = agentToReviewDimension(agent);
     layerName = dimension ? `AI 审查层(${dimension})` : "AI 审查层";
@@ -36839,7 +36908,8 @@ function handleReviewParams(item, params, newChildren, stepId, opts) {
 ` + `请按已加载质量门类 skill 的必做清单逐项执行并逐项申报结果（completed=true）；` + `确实无法执行的必做项须以结构化 skip_reason 申报降级理由` + `（格式：${SKIP_REASON_FORMAT}）。` + `低成本必做项必须实跑后申报；核验申报仅限 workflow 指令白名单限定的高成本必做项。`);
     }
   }
-  if (params.verified_tasks?.length || params.failed_tasks?.length) {
+  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);
@@ -36862,7 +36932,8 @@ function handleReviewParams(item, params, newChildren, stepId, opts) {
     if (uncovered.length > 0) {
       throw new Error(`以下 submitted task 未被 verified_tasks 或 failed_tasks 覆盖：
 ` + uncovered.map((t) => `- #${t.id} ${t.title}`).join(`
-`));
+`) + `
+verified_tasks 用于逐项确认已完成的任务；验证未通过的任务须以 failed_tasks 逐项驳回并设 verdict=failed 回退；` + `人工执行或环境不可验证的任务不得虚报确认，应以 verdict=failed + failed_tasks 驳回，` + `由开发者经 verdict=failed + blocker（task_id 指向该任务）上报、用户确认留痕后凭记录重新申报完成。`);
     }
     for (const id of verified) {
       const child = taskChildById(item, id);
@@ -36939,7 +37010,7 @@ async function agentSubmitExecute(params, ctx) {
       }
     }
     const guardStepPhase = workflow.stepMap.get(params.step_id)?.phase.name;
-    if (guardStepPhase === "review" && getStepVerdict(item, params.step_id, ctx.agent) === "passed" && !isSupplementOnly(params)) {
+    if (guardStepPhase === "review" && getStepVerdict(item, params.step_id, ctx.agent) === "passed" && !isSupplementOnly(params) && !isTaskVerifySupplementAllowed(item, params, params.step_id, ctx.agent)) {
       throw new Error(`重复提交守卫：agent "${ctx.agent}" 已在 step "${params.step_id}" 以 passed 通过，不允许重复提交。`);
     }
     assertRejectedAdjudicationNotPassed(params);
@@ -37009,7 +37080,7 @@ async function agentSubmitExecute(params, ctx) {
       const agentCfg = stepCfg.agents.find((a) => a.id === ctx.agent);
       handleReviewParams(item, params, newChildren, params.step_id, {
         capabilityTags: agentCfg?.capability_tags ?? [],
-        skipMustDoGate: isSupplementOnly(params)
+        skipMustDoGate: isSupplementOnly(params) || isTaskVerifySupplementAllowed(item, params, params.step_id, ctx.agent)
       });
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params);
@@ -37334,8 +37405,8 @@ var recoverySchema = {
     },
     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"] }
+      description: "重置指定审查 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"],
@@ -37447,7 +37518,7 @@ var agentSubmitSchema = {
     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: {
@@ -37483,12 +37554,12 @@ var agentSubmitSchema = {
     },
     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
     }
   },
@@ -37613,7 +37684,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.131.0";
+var PKG_VERSION = "0.132.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/README.md

@@ -12,9 +12,9 @@
 - **多工具支持**：Claude Code、Codex、ZCode、DeepSeek Harness（DSH）、OpenCode 均可原生接入。
 - **规范驱动**：直接消费 OpenSpec 变更规范（proposal / design / tasks / specs），流程与规范一一对应。
 - **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
-- **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。simple 模式下验证按性质分流——开发者执行确定性检查并申报，审查者分级复验（低成本项实跑、高成本项核验申报加抽样重放）并专注对抗性判断。
+- **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。任务验证层（任务审查 / 合并审查）以通过（passed）提交时必须逐项确认全部已申报任务（verified_tasks 全覆盖为工具强制门禁）；已通过但漏带确认导致阻塞时，审查者可补交确认结果解除阻塞。simple 模式下验证按性质分流——开发者执行确定性检查并申报，审查者分级复验（低成本项实跑、高成本项核验申报加抽样重放）并专注对抗性判断。
 - **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
-- **过程可审计**：进度、结论、豁免与恢复点全程记录，随时可以接着上次的进度继续。
+- **过程可审计**：进度、结论、豁免与恢复点全程记录，随时可以接着上次的进度继续。人工执行或环境不可验证的任务经 blocker 上报、用户确认留痕（blocker_updates）后凭记录申报完成；恢复参数 reset_steps 按流程模式（full / simple）校验各自的审查步骤值域后生效。
 
 ## 快速开始
 

package/assets/workflows/task-simple.yaml

@@ -46,7 +46,8 @@ phases:
           - "修复完成的 issue 经 fixed_issue_ids 上报后进入待复核（review）状态，终态由报源 reviewer 复核裁定；不可修 issue 经 exempt_issue_ids 申请豁免（申请后进入待裁定（review）状态，由报源 reviewer 在后续审查轮次裁定，被驳回的 issue 回待修复）；Info 级 issue 不阻塞提交，无需申请豁免；全部 blocking issue 均已上报修复或申请豁免后才可 passed 提交推进"
           - "确定性质量工具检查出的问题不得以压制手段（压制注解/注释抑制/规则排除配置/平台状态标注/构建跳过开关等）静默规避：确需压制时，必须在压制处代码注释说明清楚理由（commit message 可补充），并经 exempt_issue_ids 申请豁免由报源 reviewer 裁定；不得以 fixed_issue_ids 冒充修复；被驳回后须移除压制并真实修复"
           - "遇外部依赖、凭证、真实输入或必须 stub/降级/跳过验收才能继续时，以 verdict=failed 提交 blocker（含 source_role、task_id、category、description、evidence、attempted_actions、options）"
-          - "提交 opx_agent_submit：passed 时存在未完成或被驳回（open/rejected）的子任务必须全部列入 completed_task_ids（数字 id 如 1、2，或任务编号如 1.1），全部子任务已验证时可省略；不可修 issue 申请豁免（exempt_issue_ids）"
+          - "blocker 上报后经 question 向用户确认处理方式，确认结果经 blocker_updates（blocker_id + user_response）上报置 resolved；人工执行任务凭用户确认留痕列入 completed_task_ids 重新提交（申报依据为 blocker 记录，不得凭空申报）"
+          - "提交 opx_agent_submit：passed 提交前须将全部已完成（含被驳回后修复的）子任务列入 completed_task_ids（数字 id 如 1、2，或任务编号如 1.1）申报，全部子任务已验证时可省略；无法完成或人工执行的任务不得虚报，应经 verdict=failed + blocker 上报后凭留痕申报；不可修 issue 申请豁免（exempt_issue_ids）"
         constraints:
           - "禁用 edit/write 修改 `{{worktree_path}}/openspec/changes/` 下任何文档（spec/design/tasks/clarify）；唯一例外：所提交 fixed_issue_ids 中某 issue 的 file 字段指向该目录下文档时，仅允许按该 issue 的要求修改对应文档，不得扩大范围；本约束为提示词级约束，工具层不校验实际改动的文件"
           - "执行边界默认整个 worktree（无 analyze 环节，不生成边界白名单）"
@@ -83,6 +84,7 @@ phases:
           - "对视图「待裁定是否可豁免」区块中的豁免申请经 exempt_adjudications 裁定（dismissed/rejected）"
           - "审查变更 diff 与 git log，识别变更中新增的压制手段（压制注解/注释抑制/规则排除配置/平台状态标注/构建跳过开关等）：视为豁免申请，核对 dev 是否已在压制处代码注释或 commit message 说明理由并申报豁免；未申报或理由不成立 → 报 issue（file=压制位置、line=压制行、rule=被压制规则名，severity 至少 Low，description/suggestion 写明判定门槛与理由），要求移除压制真实修复或补申报；理由成立 → 经 exempt_adjudications 裁定 dismissed"
           - "有 task 未通过时必须 verdict=failed 并经 failed_tasks 上报（task_id + reason）；passed 时不允许提供 failed_tasks"
+          - "对标注人工执行/环境不可验证的任务，核验视图 Blocker 留痕区块（resolved 且 user_response 记录用户确认）后经 verified_tasks 确认并在 validation_steps 留痕；无留痕且无法自行验证 → verdict=failed 经 failed_tasks 驳回并说明理由"
           - "报静态分析类 issue 时，rule 字段必填官方规则全名（命名格式遵循已加载的质量门类 skill 的规则导航索引），漏填将导致项目级豁免清单无法生效"
           - "报静态分析类 issue 时，description 必须含：①复现命令（非静默形态，含必要开关）；②实测数据（命中类清单/计数）；③规则默认阈值与当前项目配置对比（引用可改的配置文件路径）"
           - "按 opx_status 操作指引完成全部验证项，提交前将每项验证结果与证据填入 validation_steps 参数（未执行的项须填 skip_reason 注明原因），不得省略任何一项"

package/assets/workflows/task.yaml

@@ -77,7 +77,8 @@ phases:
           - "修复完成的 issue 经 fixed_issue_ids 上报后进入待复核（review）状态，终态由报源 reviewer 复核裁定；不可修 issue 经 exempt_issue_ids 申请豁免（申请后进入待裁定（review）状态，由报源 reviewer 在后续审查轮次裁定，被驳回的 issue 回待修复）；Info 级 issue 不阻塞提交，无需申请豁免；全部 blocking issue 均已上报修复或申请豁免后才可 passed 提交推进"
           - "确定性质量工具检查出的问题不得以压制手段（压制注解/注释抑制/规则排除配置/平台状态标注/构建跳过开关等）静默规避：确需压制时，必须在压制处代码注释说明清楚理由（commit message 可补充），并经 exempt_issue_ids 申请豁免由报源 reviewer 裁定；不得以 fixed_issue_ids 冒充修复；被驳回后须移除压制并真实修复"
           - "遇外部依赖、凭证、真实输入或必须 stub/降级/跳过验收才能继续时，以 verdict=failed 提交 blocker（含 source_role、task_id、category、description、evidence、attempted_actions、options）"
-          - "提交 opx_agent_submit：passed 时存在未完成或被驳回（open/rejected）的子任务必须全部列入 completed_task_ids（数字 id 如 1、2，或任务编号如 1.1），全部子任务已验证时可省略；不可修 issue 申请豁免（exempt_issue_ids）"
+          - "blocker 上报后经 question 向用户确认处理方式，确认结果经 blocker_updates（blocker_id + user_response）上报置 resolved；人工执行任务凭用户确认留痕列入 completed_task_ids 重新提交（申报依据为 blocker 记录，不得凭空申报）"
+          - "提交 opx_agent_submit：passed 提交前须将全部已完成（含被驳回后修复的）子任务列入 completed_task_ids（数字 id 如 1、2，或任务编号如 1.1）申报，全部子任务已验证时可省略；无法完成或人工执行的任务不得虚报，应经 verdict=failed + blocker 上报后凭留痕申报；不可修 issue 申请豁免（exempt_issue_ids）"
         constraints:
           - "禁用 edit/write 修改 `{{worktree_path}}/openspec/changes/` 下任何文档（spec/design/tasks/clarify）；唯一例外：所提交 fixed_issue_ids 中某 issue 的 file 字段指向该目录下文档时，仅允许按该 issue 的要求修改对应文档，不得扩大范围；本约束为提示词级约束，工具层不校验实际改动的文件"
           - "允许变更目录范围：{{allowed_directories}}"
@@ -130,6 +131,7 @@ phases:
           - "本次变更仅含测试代码（判定：视图「变更范围」文件清单全部命中已加载技术栈 skill 定义的测试代码路径，且无生产代码、接口契约、构建与测试配置等非测试文件）时，豁免②启动服务并检查健康与③独立执行全量 API 测试，仅验证①④；豁免时 validation_steps 中②③置 completed=false，并以结构化 skip_reason 申报（格式：{\"item\":\"<对应验证项>\",\"category\":\"<降级类别>\",\"adjudication\":\"user_response|unattended_auto|env_unavailable\",\"note\":\"<说明>\"}），note 注明「本次变更仅含测试代码，豁免启动服务与 API 测试」及判定依据；⑤⑥的实现核验在纯测试代码变更场景无对象，其断言证据核验并入④测试代码质量"
           - "读取 design.md 的 API 定义（请求/响应结构、数据模型）与 specs/ 下相关 spec.md（需求细节、验收标准与数据产出要求），用于准备测试数据与对照 API 合约"
           - "有 task 未通过时必须 verdict=failed 并经 failed_tasks 上报（task_id + reason）；passed 时不允许提供 failed_tasks"
+          - "对标注人工执行/环境不可验证的任务，核验视图 Blocker 留痕区块（resolved 且 user_response 记录用户确认）后经 verified_tasks 确认并在 validation_steps 留痕；无留痕且无法自行验证 → verdict=failed 经 failed_tasks 驳回并说明理由"
           - "当发现修复需要调整 openspec/changes/ 下文档时，所报 issue 的 file 字段必须指向目标文档"
           - "报 issue 时必须显式声明归因维度 dimension（style/architecture/performance/security/maintainability）：本 reviewer 不归属任一质量维度，dimension 即该 issue 归属的目标质量维度"
           - "复核本层已修复待复核（review 态）issue：通过置 done，不通过驳回（附驳回原因，issue 回待修复并累计修复未过次数）"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.131.0",
+  "version": "0.132.0",
   "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
   "author": "ifrankwang",
   "license": "MIT",

package/src/core/tools/lifecycle.ts

@@ -1,7 +1,7 @@
 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, removeTaskGroupWorktree, type DetectChangesResult } from "../git.ts"
 import { readStateByWorktree, readStateByChangeId, writeState, writeContextToWorktree } from "../state.ts"
@@ -135,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,
@@ -176,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
@@ -241,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
@@ -267,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}"。`
+      )
     }
   }
 }
@@ -389,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
@@ -491,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("")
 }
 

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,

package/src/core/workflow/status.ts

@@ -717,6 +717,11 @@ function renderAnalyzeBlockers(item: WorkItem): string[] {
 /** implement step：developer 待修复 children（仅 todo 态：review 态由对应 reviewer 复核、豁免申请走待裁定区块）。 */
 function renderDeveloperChildren(item: WorkItem, ctxAgent: string, exemptionCtx?: ExemptionHintCtx): string[] {
   const lines: string[] = []
+  // 已处理 blocker 的用户确认留痕：dev 凭该记录将人工执行/环境不可验证任务重新列入
+  // completed_task_ids 申报（full 模式下 architect 代为 resolve 后，dev 在 implement 视图
+  // 读取用户确认内容——凭留痕申报的依据链在此闭合）。置于待修复清单早退之前，无待修复
+  // issue 时留痕仍渲染。
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_DEV))
   // 仅 issue child 进入修复清单（task child 不得混入 issue 渲染）
   const toFix = issueChildrenOf(item).filter((c) => isAgentOwnedIssue(c, ctxAgent))
   if (toFix.length === 0) return lines
@@ -928,6 +933,29 @@ function renderToolAdjudicateOnly(item: WorkItem, rec: EngineRecommendation, ctx
   return lines.join("\n")
 }
 
+/** blocker 留痕区块标题（审查者视角）：任务验证视图的申报核验依据口径。 */
+const BLOCKER_TRAIL_TITLE_REVIEW = "## Blocker 留痕（人工/不可验证任务的申报依据）"
+/** blocker 留痕区块标题（开发者视角）：已处理 blocker 的用户确认记录，dev 凭记录重新申报完成。 */
+const BLOCKER_TRAIL_TITLE_DEV = "## Blocker 留痕（已处理 blocker 的用户确认，凭记录申报完成）"
+
+/** blocker 留痕区块（任务验证视图 verify_task / quality_review 与 developer implement 视图共用同一实现）：
+ *  渲染已 resolved 且带用户答复留痕的 blocker 摘要（task_id / 描述 / 用户确认）——「人工执行/
+ *  环境不可验证」任务经 blocker 上报、用户确认留痕后由开发者凭记录重新申报，审查者核验该留痕
+ *  后方可经 verified_tasks 确认（人工任务协议的申报依据）。复用 readBlockers 读取，无留痕不渲染；
+ *  经 title 参数区分视角措辞（审查者核验申报 / 开发者凭记录申报）。 */
+function renderBlockerTrail(item: WorkItem, title: string): string[] {
+  const resolved = readBlockers(item).filter((b) => b.status === "resolved" && b.userResponse)
+  if (resolved.length === 0) return []
+  const lines = [title, ""]
+  for (const b of resolved) {
+    lines.push(`- Blocker #${b.id}${b.taskId ? ` | Task #${b.taskId}` : ""} | ${b.category}`)
+    lines.push(`  - 描述：${b.description}`)
+    lines.push(`  - 用户确认：${b.userResponse}`)
+  }
+  lines.push("")
+  return lines
+}
+
 /** verify_task step：task children 待验证列表 + task 层 issue 主区块 + 调用者可裁定的豁免申请（待裁定）。 */
 function renderTaskChildren(item: WorkItem, ctxAgent: string, exemptionCtx?: ExemptionHintCtx): string[] {
   const lines: string[] = []
@@ -937,6 +965,7 @@ function renderTaskChildren(item: WorkItem, ctxAgent: string, exemptionCtx?: Exe
     for (const t of pendingTasks) lines.push(renderTaskItem(t))
     lines.push("")
   }
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_REVIEW))
   const issues = issueChildrenOf(item)
   const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent))
   lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx))
@@ -971,6 +1000,7 @@ function renderMergedChildren(item: WorkItem, ctxAgent: string, exemptionCtx?: E
     for (const t of pendingTasks) lines.push(renderTaskItem(t))
     lines.push("")
   }
+  lines.push(...renderBlockerTrail(item, BLOCKER_TRAIL_TITLE_REVIEW))
   const issues = issueChildrenOf(item)
   const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent))
   lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx))