@ifrankwang/openspec-agents 0.120.1 → 0.121.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.120.1",
+  "version": "0.121.1",
   "type": "module",
   "main": "./src/core/index.ts",
   "exports": {

package/src/adapters/codex/index.ts

@@ -13,10 +13,11 @@ import { join, dirname } from "node:path"
 import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
 import { buildPluginPackage, PLUGIN_NAME, PLUGIN_DESCRIPTION, PLUGIN_AUTHOR, type PluginPackageResult } from "../plugin-common/index.ts"
 
-/** codex agent 工具白名单（按职责收敛，审查/分析角色不含写文件工具）。 */
+/** codex agent 工具白名单（按职责收敛，其余身份统一走 default 白名单）。 */
 const AGENT_TOOLS: Record<string, string[]> = {
-  "openspec-architect": ["read", "grep", "glob", "ls", "bash", "web"],
   "openspec-developer": ["read", "grep", "glob", "ls", "bash", "apply_patch", "web"],
+  // 审查者仅可直改文档/注释，需要 apply_patch；逻辑类修改一律只报（openspec-reviewer.md 角色约束）
+  "openspec-reviewer": ["read", "grep", "glob", "ls", "bash", "apply_patch", "web"],
   default: ["read", "grep", "glob", "ls", "bash"],
 }
 

package/src/adapters/mcp-common/server.ts

@@ -73,7 +73,7 @@ const TOOL_SPECS: Record<string, ToolSpec> = {
   },
 }
 
-/** 附加 _agent 身份参数到 P1 schema（仅 MCP 暴露层；OpenCode 直载形态无此参数）。 */
+/** 附加 _agent 身份参数到 P1 schema（仅 MCP 暴露层）。 */
 function withAgentArg(schema: JSONSchema): JSONSchema {
   return {
     ...schema,

package/src/adapters/opencode/agents.ts

@@ -21,22 +21,7 @@ function mapPermission(
 
 const AGENTS_ROOT = resolve("assets", "agents")
 
-/** 已知主代理名集合：注入的 openspec-main + 用户既有 primary agent + opencode 默认主代理 "primary"。 */
-const primaryAgents = new Set<string>(["primary"])
-
-/** 编排视角角色判定：调用者是否为主代理（承担编排者职责），替代 agent 名硬编码。 */
-export function isPrimaryAgent(agent: string): boolean {
-  return primaryAgents.has(agent)
-}
-
 export function injectAgents(config: Record<string, unknown>): void {
-  // 探测主代理名：config.agent 中 mode=primary 的条目（用户自定义 + 注入的主代理模板）
-  const existingAgents = (config.agent as Record<string, unknown>) ?? {}
-  for (const [name, cfg] of Object.entries(existingAgents)) {
-    if (typeof cfg === "object" && cfg !== null && (cfg as Record<string, unknown>).mode === "primary") {
-      primaryAgents.add(name)
-    }
-  }
   if (existsSync(AGENTS_ROOT)) {
     const files = readdirSync(AGENTS_ROOT).filter((f) => f.endsWith(".md"))
     for (const file of files) {
@@ -60,10 +45,6 @@ export function injectAgents(config: Record<string, unknown>): void {
       const perm = mapPermission(frontmatter)
       if (perm) agentConfig.permission = perm
 
-      if (frontmatter.mode === "primary") {
-        primaryAgents.add(name)
-      }
-
       const existingAgentsMap = (config.agent as Record<string, unknown>) ?? {}
       const existingAgent = existingAgentsMap[name] as Record<string, unknown> | undefined
       config.agent = {

package/src/adapters/opencode/index.ts

@@ -1,34 +1,41 @@
 import { type Plugin } from "@opencode-ai/plugin"
 import { injectSkills } from "./skills.ts"
 import { injectAgents } from "./agents.ts"
-
-import {
-  init,
-  set_worktree,
-  status,
-  complete_task_group,
-  set_unattended,
-  agent_submit,
-} from "./tools.ts"
+import { resolve } from "../agent-md.ts"
 
 /**
- * OpenCode 插件壳（兼容过渡入口）：配置注入（agent/skill）+ 工具直载。
- * dashboard/collector/poller 副作用已迁移至 MCP server 进程（src/adapters/mcp-common/），
- * OpenCode 建议切换为 MCP client 形态接入；插件壳保留兼容直到双轨验证完成。
+ * OpenCode 插件壳（MCP 形态）：配置注入（agent/skill）+ MCP server 配置注入（config.mcp）。
+ * 直载工具注册已移除（BREAKING，change agent-merge-and-mode-config 组 5.1）：
+ * - opx_* 工具统一经 MCP server 暴露（stdio bundle，--worktree 指向当前项目根），
+ *   与 claude-code / zcode / codex 插件的 .mcp.json 形态一致；
+ * - 身份不再由会话运行时推导，统一走 mcp-common 的 `_agent` 参数解析（缺省视为编排视角）。
+ * dashboard/collector/poller 副作用已迁移至 MCP server 进程（src/adapters/mcp-common/）。
  */
 export const OpenspecOrchestratePlugin: Plugin = async (input) => {
   return {
     config: async (config) => {
       injectAgents(config)
       injectSkills(config)
-    },
-    tool: {
-      opx_orch_init: init,
-      opx_orch_set_worktree: set_worktree,
-      opx_status: status,
-      opx_orch_complete_task_group: complete_task_group,
-      opx_orch_set_unattended: set_unattended,
-      opx_agent_submit: agent_submit,
+      // MCP server 声明：opencode config 的 mcp 段（官方形态
+      // { mcp: { <server>: { type: "local", command: [...] } } }，见 opencode docs/mcp-servers）。
+      // 入口为包内 .mcp-server/cli.mjs（prepack 构建的 MCP server 自包含 bundle），
+      // --worktree 指向当前项目根（input.worktree 即 opencode 打开的 git worktree 路径）。
+      config.mcp = {
+        ...(config.mcp ?? {}),
+        opx: {
+          type: "local",
+          command: [
+            "node",
+            resolve(".mcp-server", "cli.mjs"),
+            "--transport",
+            "stdio",
+            "--worktree",
+            input.worktree,
+            "--unattended",
+            "--strip-opx-prefix",
+          ],
+        },
+      }
     },
   }
 }

package/src/adapters/opencode/tools.ts

@@ -1,78 +1,19 @@
-import { tool } from "@opencode-ai/plugin"
-import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../../core/types.ts"
+/**
+ * OpenCode 直载工具注册已移除（BREAKING，change agent-merge-and-mode-config 组 5.1）：
+ * - 插件壳不再直载 opx_* 工具，统一经 MCP server 配置（config.mcp，stdio bundle）暴露；
+ * - 身份不再由会话运行时推导（makeCtx 与 isPrimaryAgent 判定已删），统一走 mcp-common 的 `_agent` 参数解析。
+ * 本文件仅保留测试直调核心 execute 的无状态透传壳（不注册 OpenCode 工具、无身份推导），
+ * 调用方（tests/ 既有用例）显式构造 ToolContext 传入。
+ */
 import {
   initExecute, setWorktreeExecute, statusExecute,
   completeTaskGroupExecute, setUnattendedExecute,
 } from "../../core/tools/lifecycle.ts"
 import { agentSubmitExecute } from "../../core/tools/submit.ts"
-import {
-  orchInitSchema, setWorktreeSchema, statusSchema,
-  completeTaskGroupSchema, setUnattendedSchema, agentSubmitSchema,
-} from "../../core/tools/schemas.ts"
-import { jsonSchemaToZod } from "./json-schema.ts"
-import { isPrimaryAgent } from "./agents.ts"
-import type { ToolContext } from "../../core/tools/types.ts"
-
-/** 直载形态调用上下文：agent 身份由会话运行时推导（恒显式声明），编排视角按主代理名判定。 */
-function makeCtx(context: { worktree: string; agent: string }): ToolContext {
-  return {
-    worktree: context.worktree,
-    agent: context.agent,
-    orchestrator: isPrimaryAgent(context.agent),
-    identityDeclared: true,
-  }
-}
-
-export const init = tool({
-  description:
-    "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。",
-  args: jsonSchemaToZod(orchInitSchema).shape as any,
-  async execute(args, context) {
-    return initExecute(args as any, makeCtx(context))
-  },
-})
-
-export const set_worktree = tool({
-  description:
-    "确保目标组的 git worktree 就绪。若已存在则复用，否则按规范自动创建（分支 task-group/{changeId}/{taskGroupId}，路径 .worktree/{changeId}/task-group-{taskGroupId}）。只补齐资源，不改变阶段。",
-  args: jsonSchemaToZod(setWorktreeSchema).shape as any,
-  async execute(args, context) {
-    return setWorktreeExecute(args as any, makeCtx(context))
-  },
-})
-
-export const status = tool({
-  description:
-    "统一状态/上下文查询（只读为主）。按调用者角色路由：编排视角→统计+worktree；architect→spec/blocker；developer→worktree/boundary/task/issue；reviewer-tool→tool 层控件 issue；reviewer-task→task 验证状态；quality reviewer→自维度既有 issue。",
-  args: jsonSchemaToZod(statusSchema).shape as any,
-  async execute(args, context) {
-    return statusExecute({ change_id: args.change_id as string }, makeCtx(context))
-  },
-})
-
-export const complete_task_group = tool({
-  description:
-    "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突时中止并返回 blocked（保留 worktree/分支）。",
-  args: jsonSchemaToZod(completeTaskGroupSchema).shape as any,
-  async execute(args, context) {
-    return completeTaskGroupExecute({ change_id: args.change_id as string }, makeCtx(context))
-  },
-})
-
-export const set_unattended = tool({
-  description:
-    "开启/关闭无人值守模式。开启后编排流程不再向用户提问：analyze 确认模式由架构师自行裁决（不确认用户）；重试检查点、状态异常、blocker 处理等需拍板事项由主代理按编排行为准则自行决策并提交——检查点决策是 opx_agent_submit 工具调用，主代理可自行执行，不因无人值守而抑制。",
-  args: jsonSchemaToZod(setUnattendedSchema).shape as any,
-  async execute(args, context) {
-    return setUnattendedExecute(args as any, makeCtx(context))
-  },
-})
 
-export const agent_submit = tool({
-  description:
-    "通用 step 提交，按 step_id 路由到 workflow 对应 step。校验调用者属于该 step 的 agents（越权直接拒绝），提交后推进 workflow 状态机并写回编排状态。可通过 exempt_adjudications 对已申请豁免的 issue 进行裁定（dismissed→cancelled、rejected→回 todo）；可通过 recheck_adjudications 复核已修复待复核（review 态）的 issue（passed→done、rejected→回 todo 并记 refix_count 与 reject_reason，谁提谁裁定）。",
-  args: jsonSchemaToZod(agentSubmitSchema).shape as any,
-  async execute(args, context) {
-    return agentSubmitExecute(args as any, makeCtx(context))
-  },
-})
+export const init = { execute: initExecute }
+export const set_worktree = { execute: setWorktreeExecute }
+export const status = { execute: statusExecute }
+export const complete_task_group = { execute: completeTaskGroupExecute }
+export const set_unattended = { execute: setUnattendedExecute }
+export const agent_submit = { execute: agentSubmitExecute }

package/src/core/constants.ts

@@ -22,11 +22,13 @@ export function agentToReviewDimension(agent: string): ReviewDimension | undefin
   return (Object.keys(DIMENSION_AGENT_MAP) as ReviewDimension[]).find((d) => DIMENSION_AGENT_MAP[d] === agent)
 }
 
-/** agent → issue 报源层（tool/task/quality）：tool/task reviewer 直接映射，quality reviewer 经维度反查命中即 quality。其余 agent 返回 undefined。 */
+/** agent → issue 报源层（tool/task/quality）：tool/task reviewer 直接映射，quality reviewer 经维度反查命中即 quality。
+ *  openspec-reviewer（simple 模式合并审查者）映射到 quality 层；full 模式不会分派该身份，该映射只对 simple 生效。其余 agent 返回 undefined。 */
 export function agentToReviewLayer(agent: string | undefined): ReviewLayer | undefined {
   if (!agent) return undefined
   if (agent === "openspec-reviewer-tool") return "tool"
   if (agent === "openspec-reviewer-task") return "task"
+  if (agent === "openspec-reviewer") return "quality"
   if (agentToReviewDimension(agent)) return "quality"
   return undefined
 }

package/src/core/state.ts

@@ -271,6 +271,9 @@ export async function readStateByChangeId(worktree: string, changeId: string): P
     createdAt: legacy.createdAt,
     updatedAt: legacy.updatedAt,
     unattended: legacy.unattended,
+    // 透传固化模式：state 已存在（重复初始化/切换任务组/recovery）时沿用既有 mode，
+    // 缺 mode 的旧变更保持缺省（消费端读时兜底 full，不在此写回）
+    mode: legacy.mode,
   }
   if (needsUpgrade) {
     // 迁移产物一次性落盘固定单轨形态，避免每次读取都重建（首次写新目录前幂等迁移旧数据）

package/src/core/tools/lifecycle.ts

@@ -1,5 +1,5 @@
 import path from "path"
-import type { TaskItem, TaskStatus } from "../types.ts"
+import type { TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
 import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
 import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, type DetectChangesResult } from "../git.ts"
@@ -10,7 +10,7 @@ import { parseAllTaskGroupsFromMd, parseTasksMdForGroup, extractRelevantSpecsFro
 import type { ParsedTask } from "../tasks-md.ts"
 import { assertOrchestrator, findTaskGroup } from "../derive.ts"
 import { assertPathWithin } from "../paths.ts"
-import { loadWorkflowFile, TASK_WORKFLOW_PATH, type LoadedWorkflow } from "../workflow/loader.ts"
+import { loadWorkflowFile, resolveWorkflowPath, readWorkflowModeConfig, type LoadedWorkflow } from "../workflow/loader.ts"
 import { createInitialWorkItem, isBlockingSeverity, isTerminalPhase, recommendForItem, resetInternalRetryCount, adjudicateStep, clearStepTags } from "../workflow/engine.ts"
 import { renderWorkflowStatusView } from "../workflow/status.ts"
 import { taskChildrenOf } from "../task-children.ts"
@@ -131,11 +131,17 @@ function firstUnpassedReviewStep(item: WorkItem, workflow: LoadedWorkflow): stri
  * - review：review/verify_*（增量合并——已 passed 的审查标记保留、failed 重置为 pending，currentStep
  *   前移到第一个未全 passed 的子层；review_layer 决定强制前置哪些子层）、analyze+implement 已 passed、
  *   task children 保留既有进度（无则 done——review 恢复时子任务应视为已验证，否则 G21 remaining 会让 implement 无法提交）
+ * 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 可操作，文档标注无效）。
  */
 function applyRecoveryState(
   item: WorkItem,
   recovery: InitParams["recovery"],
   parsedTasks: ParsedTask[],
+  mode?: WorkflowMode,
 ): void {
   // 恢复重建为已知状态后清除残留推进阻塞原因，避免 orchestrator 视图展示过期信息
   delete item.metadata["_advance_block_reason"]
@@ -143,6 +149,37 @@ function applyRecoveryState(
   resetInternalRetryCount(item)
   // 清除检查点标记残留：恢复重建为已知状态后 _checkpoint 已无意义（checkpoint 态属于中断中的 step）。
   delete item.metadata["_checkpoint"]
+  if (mode === "simple") {
+    const phase = recovery?.phase
+    if (!phase || phase === "task_analysis" || phase === "dev_impl") {
+      // simple 无 analyze：无 recovery（全新初始化）/ task_analysis / dev_impl 均落 in_progress/implement。
+      // tags 整体重置——不残留 implement:openspec-developer passed（否则 dev 不会重派，恢复失去意义）。
+      item.phase = "in_progress"
+      item.currentStep = "implement"
+      item.tags = {}
+      if (!phase || phase === "task_analysis") {
+        // 重置 task children 全 todo（全新开始）
+        syncTaskChildren(item, parsedTasks, { forceOpen: true })
+      } else {
+        // dev_impl 保留既有进度（无则 todo）
+        syncTaskChildren(item, parsedTasks, { defaultStatus: "todo" })
+      }
+      return
+    }
+    // review 分支：恢复进 review 时 implement 必然已通过
+    item.phase = "review"
+    item.tags["implement:openspec-developer"] = "passed"
+    // quality_review 的 failed tag 删除回 pending（passed 保留——已审查通过无需重跑）
+    for (const key of Object.keys(item.tags)) {
+      if (key.startsWith("quality_review:")) {
+        if (item.tags[key] !== "passed") delete item.tags[key]
+      }
+    }
+    // reset_steps / review_layer 在 simple 下接受但空操作（值域校验在 assertValidRecovery 不变）
+    item.currentStep = "quality_review"
+    syncTaskChildren(item, parsedTasks, { defaultStatus: "done" })
+    return
+  }
   const phase = recovery?.phase
   if (!phase || phase === "task_analysis") {
     item.phase = "todo"
@@ -181,8 +218,9 @@ function applyRecoveryState(
   if (recovery?.review_layer === "quality") {
     item.tags["verify_task:openspec-reviewer-task"] = "passed"
   }
-  // currentStep 前移：显式指向第一个未全 passed 的 review step（已全 passed 的子层跳过）
-  const workflow = loadWorkflowFile(TASK_WORKFLOW_PATH)
+  // currentStep 前移：显式指向第一个未全 passed 的 review step（已全 passed 的子层跳过）。
+  // 按 mode 选择 workflow 文件：simple 模式 review 阶段仅 quality_review 一个 step。
+  const workflow = loadWorkflowFile(resolveWorkflowPath({ mode }))
   item.currentStep = firstUnpassedReviewStep(item, workflow)
   // 全 passed 收口 done：三个 review step 全 passed 时，仅当 task children 全部终态才收口；
   // 存在未终态 task child 则停在 verify_quality（recommendForItem 会返回 blocked 而非 terminal，安全）。
@@ -293,6 +331,10 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
       workItems: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
+      // 新建 state 时固化模式：读取 <worktree>/openspec/workflow.yaml（缺失视为 full，
+      // 值域外 / YAML 解析失败抛错）；state 已存在（recovery/重复初始化/切换任务组）不读配置，
+      // 沿用 state 既有 mode；旧 state 缺 mode 由消费端读时兜底 full，不写回。
+      mode: readWorkflowModeConfig(ctx.worktree),
     }
   } else {
     state.baseBranch = state.baseBranch || baseBranch
@@ -328,7 +370,15 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
           description: group.name,
           labels: ["openspec-change"],
         })
-        item.currentStep = "analyze"
+        // 新建 item 初始 step 模式感知（3.1）：simple 无 analyze step，初始 phase=in_progress、
+        // currentStep=implement（执行边界默认整个 worktree），否则 phaseStepMismatch 会拒绝执行；
+        // full 保持 todo/analyze 既有语义。
+        if (state.mode === "simple") {
+          item.phase = "in_progress"
+          item.currentStep = "implement"
+        } else {
+          item.currentStep = "analyze"
+        }
         syncTaskChildren(item, groupTasks, { defaultStatus: "todo" })
         refreshMeta(item)
         state.workItems.push(item)
@@ -382,7 +432,7 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
       item.metadata["base_ref"] = null
     }
 
-    applyRecoveryState(item, args.recovery, groupTasks)
+    applyRecoveryState(item, args.recovery, groupTasks, state.mode)
     refreshMeta(item)
     if (!existing) state.workItems.push(item)
   }
@@ -537,7 +587,8 @@ export async function statusExecute(params: StatusParams, ctx: ToolContext): Pro
   }
 
   // 单轨：一律由工作流引擎推荐（recommendForItem）渲染动态视图，按调用者角色分流
-  const workflow = loadWorkflowFile(TASK_WORKFLOW_PATH)
+  // 按 state.mode 选择 workflow 文件（simple → task-simple.yaml；旧 state 缺 mode 兜底 full）
+  const workflow = loadWorkflowFile(resolveWorkflowPath(state))
   const rec = recommendForItem(item, workflow)
   const tg = findTaskGroup(state, state.taskGroupId)
   // 主仓库 openspec 污染诊断（56ddfe9 意图）：编排者分派视图展示主仓库污染，供编排者人工核对
@@ -637,7 +688,7 @@ export async function setUnattendedExecute(params: UnattendedParams, ctx: ToolCo
   assertOrchestrator(ctx, "opx_orch_set_unattended")
   const state = await readStateByWorktree(ctx.worktree, params.change_id)
   if (!state) throw new Error("编排会话未初始化。请先调用 opx_orch_init。")
-  // enabled 缺省按 schema 声明 default=true 兜底（跨形态一致：opencode 直载透传 input 不应用 zod default）
+  // enabled 缺省按 schema 声明 default=true 兜底（透传 input 不应用 zod default）
   state.unattended = params.enabled ?? true
   await writeState(ctx.worktree, state)
   const status = state.unattended ? "开启" : "关闭"

package/src/core/tools/submit.ts

@@ -1,7 +1,7 @@
 import type { OrchestrateState } from "../types.ts"
 import type { ToolContext, AgentSubmitParams } from "./types.ts"
 import type { WorkItem, Severity, StepConfig } from "../workflow/types.ts"
-import { loadWorkflowFile, TASK_WORKFLOW_PATH, type LoadedWorkflow } from "../workflow/loader.ts"
+import { loadWorkflowFile, resolveWorkflowPath, type LoadedWorkflow } from "../workflow/loader.ts"
 import {
   submitForStep, adjudicateExempt, adjudicateRecheck, assertSubmitRouting, chainPassAdvance,
 } from "../workflow/submit.ts"
@@ -15,7 +15,7 @@ import { agentToReviewDimension, agentToReviewLayer, readIssueSource } from "../
 import { REVIEW_DIMENSIONS } from "../types.ts"
 import type { Dimension } from "../types.ts"
 import { taskChildrenOf, taskChildById, normalizeTaskChildIds, taskListOf, issueChildrenOf } from "../task-children.ts"
-import { markTaskGroupCheckboxesComplete, reconcileMainPollution, getCurrentHead } from "../git.ts"
+import { markTaskGroupCheckboxesComplete, reconcileMainPollution, getCurrentHead, isWorktreeClean } from "../git.ts"
 import { assertIssueFilesWithin } from "../paths.ts"
 import {
   readStateByWorktree, writeState, getLockPath, acquireLock, releaseLock,
@@ -25,8 +25,8 @@ import {
   assertStructuredSkipReasons, uncoveredMustDo, isValidSkipData, SKIP_REASON_FORMAT,
 } from "./gate.ts"
 
-/** 读取 task workflow 配置（assets/workflows/task.yaml），进程内缓存。 */
-const loadTaskWorkflow = () => loadWorkflowFile(TASK_WORKFLOW_PATH)
+/** 按 state.mode 读取 workflow 配置（simple → task-simple.yaml，否则 task.yaml），进程内按路径缓存。 */
+const loadTaskWorkflow = (state: OrchestrateState) => loadWorkflowFile(resolveWorkflowPath(state))
 
 /** issue id 归一化：去 # 前缀（review 工具按 tg.issue 序号引用时可能带 #）。 */
 function normalizeIssueId(id: string): string {
@@ -336,6 +336,9 @@ 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 提交死锁）
  * - verify_cleanup：本次 new_children 含 Low+，或存在未终态的 Low+ 阻塞 child（不按维度/报源层过滤——
  *   收尾层须对全部残留阻塞负责，任何层的遗留阻塞都构成不通过理由）
  * 理由判定在 dedupeNewChildren 之后调用（F4）：传入的 newChildren 为已去重的 accepted，重复新报不构成理由。
@@ -364,6 +367,16 @@ function assertFailedHasReason(
   } else if (stepId === "verify_cleanup") {
     layerName = "收尾层"
     hasReason = hasNewBlocking || existingBlocking.length > 0
+  } 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 各维度分支互不影响。
+    layerName = "AI 审查层"
+    hasReason =
+      hasNewBlocking ||
+      existingBlocking.some((c) => resolveChildIssueFields(c).sourcePhase === "quality")
   } else {
     const dimension = agentToReviewDimension(agent)
     layerName = dimension ? `AI 审查层(${dimension})` : "AI 审查层"
@@ -488,7 +501,7 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
   try {
     const state = await readStateByWorktree(ctx.worktree, params.change_id)
     if (!state) throw new Error("编排会话未初始化。请先调用 opx_orch_init。")
-    const workflow = loadTaskWorkflow()
+    const workflow = loadTaskWorkflow(state)
     const item = resolveTaskWorkItem(state)
 
     if (params.checkpoint_decision) {
@@ -673,6 +686,18 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params)
     } else if (stepPhase === "in_progress") {
+      // simple 模式 implement 提交强检查（2.2）：工作区必须无未提交内容，不干净直接拒绝并提示先 commit。
+      // simple 无 analyze 环节、执行边界默认整个 worktree，dev 提交即收尾合并的载体，未提交内容会
+      // 让收尾裸合并携带脏状态；检查在一切参数处理与状态写入之前，拒绝时零状态变更（含内存态）。
+      // 收尾门禁（completeTaskGroupExecute 的 worktree 干净检查）仍原样保留作最终兜底。
+      if (state.mode === "simple" && params.step_id === "implement") {
+        const clean = await isWorktreeClean(wtPath)
+        if (!clean) {
+          throw new Error(
+            "simple 模式 implement 提交被拒绝：工作区存在未提交内容。\n请先 git commit 提交全部变更后再提交 implement。"
+          )
+        }
+      }
       handleImplementParams(item, params)
     }
 

package/src/core/tools/types.ts

@@ -5,7 +5,7 @@ export interface ToolContext {
   agent: string
   /** 编排视角角色判定：true 表示调用者承担编排者职责（各 agent 主代理），替代 agent 名硬编码 openspec-orchestrator。 */
   orchestrator?: boolean
-  /** 调用者 agent 身份是否显式声明：MCP 形态下为是否携带 `_agent` 参数，OpenCode 直载形态恒为 true。
+  /** 调用者 agent 身份是否显式声明：MCP 形态下为是否携带 `_agent` 参数。
    *   false 且落入编排视角时，opx_status 视图渲染补传 `_agent` 的身份提示（MCP 子代理首查死锁兜底）。 */
   identityDeclared?: boolean
   remote?: boolean

package/src/core/types.ts

@@ -27,6 +27,9 @@ export type OrchestrateStatus = "not_started" | "in_progress" | "completed"
 export type DimensionVerdict = "pending" | "passed" | "failed"
 export type QualityLayerProgress = Record<ReviewDimension, DimensionVerdict>
 
+/** 流程模式：full（默认，analyze → implement → 三重审查+收尾验证）或 simple（implement → quality_review → done）。 */
+export type WorkflowMode = "full" | "simple"
+
 export interface ExecutionBoundary {
   allowed_directories: string[]
   allowed_packages: string[]
@@ -132,4 +135,7 @@ export interface OrchestrateState {
   createdAt: string
   updatedAt: string
   unattended?: boolean
+  /** 变更开始时固化的流程模式（opx_orch_init 从 <repo>/openspec/workflow.yaml 读取后写入）。
+   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 不再被配置改动覆盖。 */
+  mode?: WorkflowMode
 }

package/src/core/workflow/engine.ts

@@ -12,11 +12,14 @@ import { reviewLayerFromMetadata, readIssueSource } from "../constants.ts"
 
 const TERMINAL_PHASES: WorkItemPhase[] = ["done", "cancelled"]
 
-/** review 三个验证 step → 其可裁定的 issue 报源层（层感知门禁归因依据）。 */
+/** review 验证 step → 其可裁定的 issue 报源层（层感知门禁归因依据）。
+ *  quality_review（simple 合并审查 step）按 quality 层口径——由 simple 审查者（openspec-reviewer）上报的
+ *  issue 归入 quality 层，blocking issue 终态才可 pass（与 full 模式 verify_quality 语义一致）。 */
 export const REVIEW_STEP_TO_LAYER: Record<string, "tool" | "task" | "quality"> = {
   verify_tool: "tool",
   verify_task: "task",
   verify_quality: "quality",
+  quality_review: "quality",
 }
 
 /** 读取 issue child 的报源层（source 反推，source_phase 仅作历史兜底，缺省 tool）。 */

package/src/core/workflow/loader.ts

@@ -13,6 +13,7 @@ import type {
 } from "./types.ts"
 import { WORK_ITEM_PHASES, stepAgentIds } from "./types.ts"
 import { DIMENSION_AGENT_MAP } from "../constants.ts"
+import type { OrchestrateState, WorkflowMode } from "../types.ts"
 
 const SPECIAL_TRANSITIONS = ["done", "halt"] as const
 const PHASE_NAMES = new Set<string>(WORK_ITEM_PHASES)
@@ -23,30 +24,76 @@ export interface LoadedWorkflow extends WorkflowConfig {
 }
 
 /**
- * 定位 task.yaml：源码（src/core/workflow/ 上溯 3 级=仓库根）、插件包 dist 形态
+ * 定位 assets/workflows/<fileName>：源码（src/core/workflow/ 上溯 3 级=仓库根）、插件包 dist 形态
  * （dist/zcode-plugin/.mcp-server/ 上溯 1 级=插件根）与 ZCode 缓存嵌套形态
  * （cache/<marketplace>/<plugin>/<version>/.mcp-server/ 上溯 1 级=版本目录）部署深度不同，
- * 故从模块所在目录逐级上溯探测 assets/workflows/task.yaml，首个命中即采用（首中即用）。
+ * 故从模块所在目录逐级上溯探测，首个命中即采用（首中即用）。
  * bundle 单文件合并后 import.meta.url 指向部署位置（cli.mjs），源码形态指向本文件自身，两者自然成立。
  */
-export function resolveTaskWorkflowPath(moduleUrl: string): string {
+function resolveWorkflowFilePath(moduleUrl: string, fileName: string): string {
   const startDir = dirname(fileURLToPath(moduleUrl))
   let dir = startDir
   let probed = 0
   for (;;) {
-    const candidate = pathResolve(dir, "assets", "workflows", "task.yaml")
+    const candidate = pathResolve(dir, "assets", "workflows", fileName)
     if (existsSync(candidate)) return candidate
     probed++
     const parent = dirname(dir)
     if (parent === dir) break // 到达文件系统根
     dir = parent
   }
-  throw new Error(`workflow 文件缺失：从 ${startDir} 上溯 ${probed} 级未找到 assets/workflows/task.yaml`)
+  throw new Error(`workflow 文件缺失：从 ${startDir} 上溯 ${probed} 级未找到 assets/workflows/${fileName}`)
+}
+
+export function resolveTaskWorkflowPath(moduleUrl: string): string {
+  return resolveWorkflowFilePath(moduleUrl, "task.yaml")
 }
 
 // 模块加载期求值，workflow 缺失即启动抛错（fail-fast）：opx_* 工具全部依赖 workflow，缺失时
 // server 无可用性，启动即抛比首次调用才报错更早且可读（可读错误替代原生 ENOENT）。
 export const TASK_WORKFLOW_PATH = resolveTaskWorkflowPath(import.meta.url)
+/** simple 流程文件（implement → quality_review → done），与 task.yaml 同目录随插件 bundle 分发。 */
+export const SIMPLE_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "task-simple.yaml")
+
+/**
+ * 按 state.mode 选择 workflow 文件：simple → task-simple.yaml，其余（full 或旧 state 缺 mode）→ task.yaml。
+ * 旧 state 无 mode 字段一律按 full 处理（读时兜底，不写回），与 D2 固化语义一致。
+ */
+export function resolveWorkflowPath(state: Pick<OrchestrateState, "mode">): string {
+  return state.mode === "simple" ? SIMPLE_WORKFLOW_PATH : TASK_WORKFLOW_PATH
+}
+
+/** 项目级模式配置文件路径（<worktree>/openspec/workflow.yaml，与 openspec/config.yaml 同级）。 */
+const WORKFLOW_MODE_CONFIG_FILE = "openspec/workflow.yaml"
+
+/**
+ * 读取项目级流程模式配置（<worktree>/openspec/workflow.yaml）：
+ * - 文件缺失 → "full"（缺省）
+ * - YAML 解析失败 → 抛错
+ * - 顶层非 YAML 映射对象 → 抛错
+ * - mode 字段缺失 → "full"（缺省）
+ * - mode 值域外（非 full/simple）→ 抛错
+ * 仅由 opx_orch_init 新建 state 时调用；已存在的 state 不读配置，沿用既有 mode。
+ */
+export function readWorkflowModeConfig(worktree: string): WorkflowMode {
+  const configPath = pathResolve(worktree, WORKFLOW_MODE_CONFIG_FILE)
+  if (!existsSync(configPath)) return "full"
+  let raw: unknown
+  try {
+    raw = yaml.load(readFileSync(configPath, "utf-8"))
+  } catch (err) {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 解析失败：${(err as Error).message}`)
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：顶层必须是 YAML 映射对象`)
+  }
+  const mode = (raw as { mode?: unknown }).mode
+  if (mode === undefined) return "full"
+  if (mode !== "full" && mode !== "simple") {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：mode 值域为 full/simple，收到 ${JSON.stringify(mode)}`)
+  }
+  return mode
+}
 
 const workflowFileCache = new Map<string, LoadedWorkflow>()