@ifrankwang/openspec-agents 0.130.0 → 0.132.0

package/.mcp-server/cli.mjs

@@ -29686,6 +29686,7 @@ var EMPTY_COMPLETION_RESULT = {
 
 // src/core/tools/lifecycle.ts
 import path6 from "path";
+import { rmdir } from "node:fs/promises";
 
 // src/core/types.ts
 var CODE_DIMENSIONS = ["style", "architecture", "performance", "security", "maintainability"];
@@ -29693,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";
@@ -29742,7 +29744,15 @@ function reviewLayerFromMetadata(child) {
 // src/core/git.ts
 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";
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function execGit(args) {
   return new Promise((resolve) => {
     const child = execFile("git", args, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
@@ -29775,6 +29785,55 @@ async function runGit(worktree, args) {
 async function runGitChecked(worktree, args) {
   return gitRunner.runChecked(worktree, args);
 }
+async function removeTaskGroupWorktree(repoRoot, wtPath, opts = {}) {
+  const result = { 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)) {
+      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;
+}
 async function getCurrentHead(worktree) {
   return runGit(worktree, ["rev-parse", "HEAD"]);
 }
@@ -30061,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",
@@ -30443,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,
@@ -30465,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) {
@@ -32695,16 +32762,21 @@ function requireLoader() {
       state.result += _result;
     }
   }
+  function chargeMergeWork(state) {
+    state.totalMergeKeys++;
+    if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+      throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+    }
+  }
   function mergeMappings(state, destination, source, overridableKeys) {
     if (!common2.isObject(source)) {
       throwError(state, "cannot merge mappings; the provided source object is unacceptable");
     }
+    chargeMergeWork(state);
     const sourceKeys = Object.keys(source);
     for (let index = 0, quantity = sourceKeys.length;index < quantity; index += 1) {
       const key = sourceKeys[index];
-      if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-        throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-      }
+      chargeMergeWork(state);
       if (!_hasOwnProperty.call(destination, key)) {
         setProperty(destination, key, source[key]);
         overridableKeys[key] = true;
@@ -32732,6 +32804,9 @@ function requireLoader() {
     }
     if (keyTag === "tag:yaml.org,2002:merge") {
       if (Array.isArray(valueNode)) {
+        if (valueNode.length > 100) {
+          throwError(state, "abnormal merge sequence size");
+        }
         for (let index = 0, quantity = valueNode.length;index < quantity; index += 1) {
           mergeMappings(state, _result, valueNode[index], overridableKeys);
         }
@@ -35638,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;
@@ -35778,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");
@@ -35787,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));
@@ -35815,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));
@@ -36011,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;
@@ -36080,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}"。`);
     }
   }
 }
@@ -36168,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) ?? [];
@@ -36258,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 = {}) {
@@ -36329,13 +36436,15 @@ async function setWorktreeExecute(params, ctx) {
         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}`);
+        const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch });
+        if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
+          const problems = [];
+          if (!cleanup.dirResolved)
+            problems.push(`无法清理已有 worktree "${existingPath}"`);
+          if (cleanup.branchDeleted === false)
+            problems.push(`无法清理已有分支 "${branch}"`);
+          throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}
+请手动处理后重试。`);
         }
       }
     }
@@ -36399,6 +36508,19 @@ async function statusExecute(params, ctx) {
   const exemptionItems = (await readExemptions(ctx.worktree)).items;
   return renderWorkflowStatusView(item, workflow, rec, { agent, orchestrator: ctx.orchestrator, identityDeclared: ctx.identityDeclared }, { state, tg, mainPollution, toolChanges, exemptedHits, exemptionItems });
 }
+async function sweepEmptyWorktreeParents(repoRoot, removedDir, changeId) {
+  const repoRootAbs = path6.resolve(repoRoot);
+  const groupLevelDir = path6.join(repoRootAbs, ".worktree", changeId);
+  const worktreeLevelDir = path6.join(repoRootAbs, ".worktree");
+  if (path6.dirname(path6.resolve(removedDir)) === groupLevelDir) {
+    try {
+      await rmdir(groupLevelDir);
+    } catch {}
+  }
+  try {
+    await rmdir(worktreeLevelDir);
+  } catch {}
+}
 async function completeTaskGroupExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_complete_task_group");
   const state = await readStateByWorktree(ctx.worktree, params.change_id);
@@ -36453,17 +36575,42 @@ async function completeTaskGroupExecute(params, ctx) {
 `);
     }
   }
-  if (worktreePath && branchName) {
-    try {
-      await runGit(ctx.worktree, ["worktree", "remove", worktreePath, "--force"]);
-      await runGit(ctx.worktree, ["branch", "-D", branchName]);
-    } catch {}
+  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 = [];
+      if (cleanup.dirResolvedByFallback) {
+        successNotes.push("- **cleanup**: git worktree remove 未直接移除目录，已按文件系统兜底删除并 prune 管理记录。");
+      }
+      if (cleanup.errors.length > 0) {
+        successNotes.push(`- **cleanup 部分告警**: ${cleanup.errors.join("；")}`);
+      }
+      cleanupNote = successNotes.join(`
+`);
+    } 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(`
+`);
+    }
   }
   item.metadata["completed_at"] = new Date().toISOString();
   await writeState(ctx.worktree, state);
   const doneMessage = `任务组已完成并合并到 "${mergeTarget}"。`;
-  return checkboxWarning ? `${doneMessage}
-${checkboxWarning}` : doneMessage;
+  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
+  return notes.length > 0 ? `${doneMessage}
+${notes.join(`
+`)}` : doneMessage;
 }
 async function setUnattendedExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_set_unattended");
@@ -36487,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;
@@ -36602,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"];
   }
@@ -36633,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）。");
     }
@@ -36640,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));
@@ -36661,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;
@@ -36699,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 审查层";
@@ -36733,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);
@@ -36756,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);
@@ -36833,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);
@@ -36903,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);
@@ -37228,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"],
@@ -37341,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: {
@@ -37377,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
     }
   },
@@ -37507,7 +37684,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.130.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.130.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",