bmad-speckit-sdd-flow 1.0.2 → 1.0.3

package/README.md

@@ -46,10 +46,11 @@ Traditional AI tooling often stops at prompt orchestration. BMAD-Speckit-SDD-Flo
 ## Runtime Governance At A Glance
 
 - **Four-Signal readiness gate** runs before implementation entry and keeps readiness scoring separate from implementation scoring.
-- **Runtime gates loop** keeps workflow progression aligned with stage truth instead of letting hosts continue optimistically.
-- **Rerun gates** carry remediation and re-entry through the same governed path after fixes.
-- **Packet execution closure** preserves evidence for every governed execution outcome across Cursor and Claude Code hosts.
-- **Post-audit close-out** feeds scoring, dashboard, coach, and SFT extraction from the same runtime close-out path.
+- **`main-agent-orchestration inspect` is the first read**: the main agent reads the repo-native authoritative surface before choosing the next global branch.
+- **`dispatch-plan` is conditional**: only materialize a plan when the surface says the next branch should dispatch a packet.
+- **Child agents only execute a bounded packet**: they return packet results, but they do not choose the next global branch.
+- **`runAuditorHost` is post-audit close-out only**: it closes approved audits into scoring, dashboard, coach, and SFT outputs, then the main agent re-reads `inspect`.
+- **Legacy worker/manual close-out playbooks are historical evidence**: keep them for auditability, but they are not the active accepted runtime path.
 
 ## Dashboard And MCP
 
@@ -164,16 +165,16 @@ This only removes installer-managed entries. It does not delete `.cursor`, `.cla
 
 ### Core Components
 
-| Component                   | Purpose                                                                                             |
-| :-------------------------- | :-------------------------------------------------------------------------------------------------- |
-| **`_bmad/`**                | Canonical source of truth for workflow modules, hooks, prompts, routing, and host-facing assets.    |
-| **`packages/scoring/`**     | Scoring engine, readiness drift evaluation, dashboard projection, coach inputs, and SFT extraction. |
-| **`dashboard`**             | Default runtime observability surface: live dashboard, runtime snapshots, and scoring projections.  |
-| **`runtime-mcp`**           | Optional MCP surface for agent tools over runtime data; enabled explicitly with `--with-mcp`.       |
-| **`speckit-workflow`**      | Specify -> Plan -> GAPS -> Tasks -> TDD with mandatory audit loops.                                 |
-| **`bmad-story-assistant`**  | Story lifecycle path: Create Story -> Party Mode -> Dev Story -> Implement.                         |
-| **`bmad-bug-assistant`**    | Bug lifecycle path: RCA -> Party Mode -> BUGFIX -> Implement.                                       |
-| **`bmad-standalone-tasks`** | Standalone execution path for TASKS or BUGFIX documents through governed subagent delivery.         |
+| Component                   | Purpose                                                                                                                                    |
+| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
+| **`_bmad/`**                | Canonical source of truth for workflow modules, hooks, prompts, routing, and host-facing assets.                                           |
+| **`packages/scoring/`**     | Scoring engine, readiness drift evaluation, dashboard projection, coach inputs, and SFT extraction.                                        |
+| **`dashboard`**             | Default runtime observability surface: live dashboard, runtime snapshots, and scoring projections.                                         |
+| **`runtime-mcp`**           | Optional MCP surface for agent tools over runtime data; enabled explicitly with `--with-mcp`.                                              |
+| **`speckit-workflow`**      | Specify -> Plan -> GAPS -> Tasks -> TDD with mandatory audit loops.                                                                        |
+| **`bmad-story-assistant`**  | Story lifecycle entry: main agent reads `inspect`, dispatches bounded packets when needed, and closes post-audit through `runAuditorHost`. |
+| **`bmad-bug-assistant`**    | Bug lifecycle path: RCA -> Party Mode -> BUGFIX -> Implement, while the main Agent still owns the global `inspect -> dispatch-plan -> closeout` chain. |
+| **`bmad-standalone-tasks`** | TASKS/BUGFIX execution still follows the main-agent path: `inspect` first, `dispatch-plan` only when needed, then bounded subagent work.             |
 
 <details>
 <summary><b>View Folder Structure</b></summary>
@@ -197,6 +198,7 @@ BMAD-Speckit-SDD-Flow/
 Key entry points:
 
 - [Getting Started](docs/tutorials/getting-started.md)
+- [Main-Agent Orchestration Reference](docs/reference/main-agent-orchestration.md)
 - [Consumer Installation Guide](docs/how-to/consumer-installation.md)
 - [Runtime Dashboard Guide](docs/how-to/runtime-dashboard.md)
 - [Runtime MCP Installation](docs/how-to/runtime-mcp-installation.md)

package/README.zh-CN.md

@@ -46,10 +46,11 @@
 ## 运行时管控一览
 
 - **四信号就绪检查**：在进入实现阶段前执行，与实现评分保持独立
-- **运行时管控循环**：工作流推进与阶段事实保持一致，不允许宿主"乐观继续"
-- **重跑检查点**：修复后沿同一条治理路径回到重试或重新进入
-- **执行闭环证据**：Cursor 与 Claude Code 两侧都保留完整的治理执行记录
-- **事后审计收口**：通过同一条运行时收口路径驱动评分、看板、诊断和训练数据提取
+- **先读 `main-agent-orchestration inspect`**：主 Agent 必须先读取 repo-native authoritative surface，再决定下一条全局分支
+- **按需执行 `dispatch-plan`**：只有 surface 明确需要 materialize packet 时，才生成正式派发计划
+- **子代理只执行 `bounded packet`**：子代理只返回 packet 结果，不负责决定下一条全局执行链
+- **`runAuditorHost` 只负责 post-audit close-out**：审计通过后统一写入评分、看板、诊断和训练数据，然后主 Agent 重新读取 `inspect`
+- **旧 worker / 手工 close-out 口径仅保留为历史证据**：可继续审计追溯，但不再是当前 accepted runtime path
 
 ## 看板与 MCP
 
@@ -164,16 +165,16 @@ npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit uninstall
 
 ### 核心组件
 
-| 组件                        | 说明                                                                  |
-| :-------------------------- | :-------------------------------------------------------------------- |
-| **`_bmad/`**                | 工作流模块、钩子、提示词、路由与宿主侧资产的规范源                    |
-| **`packages/scoring/`**     | 评分引擎、就绪漂移评估、看板投影、诊断输入与训练数据提取              |
-| **`dashboard`**             | 默认运行时可观测层：实时看板、运行时快照、评分投影                    |
-| **`runtime-mcp`**           | 可选的 MCP 工具接口，通过 `--with-mcp` 显式启用                       |
-| **`speckit-workflow`**      | Specify → Plan → GAPS → Tasks → TDD，并带强制审计循环                 |
-| **`bmad-story-assistant`**  | Story 生命周期路径：Create Story → Party Mode → Dev Story → Implement |
-| **`bmad-bug-assistant`**    | Bug 生命周期路径：RCA → Party Mode → BUGFIX → Implement               |
-| **`bmad-standalone-tasks`** | 针对 TASKS 或 BUGFIX 文档的独立受管子代理执行路径                     |
+| 组件                        | 说明                                                                                                               |
+| :-------------------------- | :----------------------------------------------------------------------------------------------------------------- |
+| **`_bmad/`**                | 工作流模块、钩子、提示词、路由与宿主侧资产的规范源                                                                 |
+| **`packages/scoring/`**     | 评分引擎、就绪漂移评估、看板投影、诊断输入与训练数据提取                                                           |
+| **`dashboard`**             | 默认运行时可观测层：实时看板、运行时快照、评分投影                                                                 |
+| **`runtime-mcp`**           | 可选的 MCP 工具接口，通过 `--with-mcp` 显式启用                                                                    |
+| **`speckit-workflow`**      | Specify → Plan → GAPS → Tasks → TDD，并带强制审计循环                                                              |
+| **`bmad-story-assistant`**  | Story 生命周期入口：主 Agent 先读 `inspect`，按需派发 bounded packet，并在 post-audit 后通过 `runAuditorHost` 收口 |
+| **`bmad-bug-assistant`**    | Bug 生命周期路径：RCA → Party Mode → BUGFIX → Implement，但全局 `inspect -> dispatch-plan -> closeout` 主链仍由主 Agent 控制 |
+| **`bmad-standalone-tasks`** | 针对 TASKS 或 BUGFIX 文档的执行仍先经过主 Agent `inspect`，必要时 `dispatch-plan`，再进入 bounded 子代理实施       |
 
 <details>
 <summary><b>查看目录结构</b></summary>
@@ -195,6 +196,7 @@ BMAD-Speckit-SDD-Flow/
 ## 文档入口
 
 - [快速开始](docs/tutorials/getting-started.md)
+- [主 Agent 编排参考](docs/reference/main-agent-orchestration.md)
 - [消费项目安装指南](docs/how-to/consumer-installation.md)
 - [运行时看板指南](docs/how-to/runtime-dashboard.md)
 - [运行时 MCP 安装](docs/how-to/runtime-mcp-installation.md)

package/_bmad/_config/governance-remediation.yaml

@@ -4,6 +4,32 @@ packetHosts:
   - cursor
   - claude
   - codex
+execution:
+  enabled: true
+  interactiveMode: main-agent
+  fallbackAutonomousMode: false
+  authoritativeHost: cursor
+  fallbackHosts:
+    - claude
+    - codex
+  dispatch:
+    leaseTimeoutSeconds: 900
+    heartbeatIntervalSeconds: 60
+    maxDispatchAttempts: 3
+  execution:
+    timeoutMinutes: 30
+    maxExecutionAttempts: 2
+  rerunGate:
+    required: true
+    autoSchedule: true
+    maxGateRetries: 2
+  escalation:
+    afterDispatchFailures: 3
+    afterExecutionFailures: 2
+    afterGateFailures: 2
+  projections:
+    emitNonAuthoritativePackets: true
+    archivePath: _bmad-output/runtime/governance/archive
 provider:
   mode: openai-compatible
   id: openai-governance

package/_bmad/claude/agents/auditors/auditor-bugfix.md

@@ -70,6 +70,8 @@ BUGFIX 文档严格审计 Agent，面向 bugfix 流程中的 BUGFIX 文档与修
   - `convergence_status`
   - `next_action`
   - `ready`
+  - `mainAgentNextAction`
+  - `mainAgentReady`
 
 ## Mandatory Startup
 
@@ -141,8 +143,12 @@ handoff:
   next_action: revise_bugfix_doc|implement_bugfix
   next_agent: auditor-bugfix|bmad-bug-agent
   ready: true|false
+  mainAgentNextAction: dispatch_remediation|dispatch_implement
+  mainAgentReady: true|false
 ```
 
+说明：这里的 `next_agent`、`mainAgentNextAction`、`mainAgentReady` 只作为 compatibility hint。审计返回后，真正的下一条全局分支必须回到主 Agent，并重新读取 `main-agent-orchestration` surface 后决定。
+
 ## Lifecycle
 
 1. Pre-Audit

package/_bmad/claude/agents/auditors/auditor-spec.md

@@ -141,7 +141,7 @@ Gap 修复决策:
 
 - `artifactDocPath`: 被审 spec.md 文件路径（必填）
 - `reportPath`: 审计报告保存路径（必填）
-- `storyPath`: 原始 Story 文档路径（可选）
+- `storyPath`: 原始 Story 文档路径（**Story-flow 下必填**；standalone speckit 可不传）
 - `prdPath`: PRD 文档路径（可选）
 - `archPath`: 架构文档路径（可选）
 - `epic`: Epic 编号
@@ -157,9 +157,15 @@ Gap 修复决策:
 2. **读取批判审计员规范**：`.claude/skills/speckit-workflow/references/audit-prompts-critical-auditor-appendix.md`
 3. **读取文档迭代规则**：`.claude/skills/speckit-workflow/references/audit-document-iteration-rules.md`
 4. **读取被审文档**：`artifactDocPath` 指定的spec.md
-5. **读取原始需求文档**：Story/PRD/ARCH（如果提供路径）
+5. **读取原始需求文档**：Story/PRD/ARCH（如果提供路径；若当前为 Story-flow，则必须读取 `storyPath`）
 6. **检查前置审计标记**：查看spec.md 末尾是否有`<!-- AUDIT: PASSED` 标记
 
+### Story-flow 硬约束
+
+- 若 `artifactDocPath` 属于 Story-flow `spec-E{epic}-S{story}.md`，则 `storyPath` 为**强制输入**，不得省略。
+- 审计报告控制字段中必须显式回传 `storyPath: <path>`，供 `runAuditorHost` 执行 `Story -> Spec` 版本锁。
+- 缺失 `storyPath` 时，结论不得视为可 closeout。
+
 ## Execution Flow
 
 ### Step 1: 模型选择信息输出

package/_bmad/claude/agents/auditors/auditor-tasks-doc.md

@@ -70,6 +70,8 @@
   - `convergence_status`
   - `next_action`
   - `ready`
+  - `mainAgentNextAction`
+  - `mainAgentReady`
 
 ## Mandatory Startup
 
@@ -141,8 +143,12 @@ handoff:
   next_action: revise_tasks_doc|execute_standalone_tasks
   next_agent: auditor-tasks-doc|bmad-standalone-tasks
   ready: true|false
+  mainAgentNextAction: dispatch_remediation|dispatch_implement
+  mainAgentReady: true|false
 ```
 
+说明：这里的 `next_agent`、`mainAgentNextAction`、`mainAgentReady` 只作为 compatibility hint。审计返回后，真正的下一条全局分支必须回到主 Agent，并重新读取 `main-agent-orchestration` surface 后决定。
+
 ## Lifecycle
 
 1. Pre-Audit

package/_bmad/claude/agents/bmad-epic-audit.md

@@ -274,9 +274,10 @@ PROMPT_PATH="_bmad-output/epic-{epic}-{epic-slug}/PROMPT_audit-epic-{epic}_round
 #### Step 3.2: 调用审计 Agent
 
 **Primary Executor**: `auditor-epic`
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计 Epic {epic} 完成状态",
   subagent_type: "general-purpose",
   prompt: `
@@ -392,6 +393,8 @@ completion_report: "_bmad-output/epic-E001-test-epic/EPIC_COMPLETION_REPORT.md"
 next_action: "proceed_to_layer_5"  # 进入收尾层
 ```
 
+说明：该 handoff 只作为 compatibility hint。Epic 审计后是否进入下一层，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/bmad-master.md

@@ -34,15 +34,27 @@ BMAD Speckit SDD 流程的总控 Agent，负责多 Story 管理、阶段门控
    - `.claude/protocols/audit-result-schema.md`
    - `.claude/protocols/handoff-schema.md`
    - `.claude/protocols/commit-protocol.md`
+7. Read repo-native orchestration surface:
+   - `npm run main-agent-orchestration -- --cwd {project-root} --action inspect`
+   - if dispatch is needed: `--action dispatch-plan|claim|dispatch|complete|invalidate`
 
 ### Auto-Continue Detection
 
 `bmad-master` 必须区分：
 
-1. **handoff readiness**：story state / handoff 中是否提供了 `next_action` 与 `ready: true`
-2. **runtime permission to continue**：当前运行时是否显式启用了 auto-continue（CLI `--continue`、环境变量 `BMAD_AUTO_CONTINUE=true`、或配置文件 `auto_continue.enabled: true`）
+1. **stage handoff semantics**：story state / handoff 中可保留 `next_action` 与 `ready`，用于表达子阶段推荐结果
+2. **authoritative main-agent readiness**：优先读取 repo-native `main-agent-orchestration` surface；若该 surface 不可用，再读取 story state / handoff 中的 `mainAgentNextAction` 与 `mainAgentReady: true`
+3. **runtime permission to continue**：当前运行时是否显式启用了 auto-continue（CLI `--continue`、环境变量 `BMAD_AUTO_CONTINUE=true`、或配置文件 `auto_continue.enabled: true`）
 
-只有两者同时满足时，才允许自动推进。
+只有 2 与 3 同时满足时，才允许自动推进；若 repo-native `main-agent-orchestration` surface 与 `mainAgentNextAction / mainAgentReady` 冲突，以前者为准；若 `next_action` / `ready` 与 `mainAgentNextAction / mainAgentReady` 冲突，以后者为准。**但当 repo-native surface 可用时，不得直接从 handoff 或 story state 派发下一执行体。**
+
+### Canonical Runtime Surface
+
+主 Agent 的正式消费顺序是：
+
+1. `main-agent-orchestration`
+2. `mainAgentNextAction / mainAgentReady`
+3. `next_action / ready`
 
 ```yaml
 auto_continue_check:
@@ -54,36 +66,39 @@ auto_continue_check:
 
   conditions:
     - auto_continue.enabled === true
-    - story_state.next_action 存在
-    - story_state.ready === true
+    - orchestration_surface.mainAgentNextAction 存在
+    - orchestration_surface.mainAgentReady === true
+    - orchestration_surface.source in [orchestration_state, implementation_entry_gate, reviewer_closeout]
 
   action:
-    - 自动解析 next_action 对应的 stage
+    - 自动解析 mainAgentNextAction 对应的主控分支
+    - 如需派发，先执行 dispatch-plan / claim / dispatch
     - 更新 story state stage / follow_up
     - 路由到下一个执行体
     - 输出:
         auto_proceed: true
-        reason: "auto_continue enabled 且 handoff.next_action={action} 且 ready=true"
+        reason: "auto_continue enabled 且 orchestration_surface.mainAgentNextAction={action} 且 mainAgentReady=true"
 ```
 
-若 `next_action` / `ready` 满足，但 `auto_continue.enabled !== true`，则：
+若 repo-native orchestration surface 已就绪，但 `auto_continue.enabled !== true`，则：
 - 不自动推进
 - 仅输出建议下一步
 - 等待用户确认或显式用 `--continue` 重入
 
-**next_action 到 stage 的映射**：
+若 repo-native orchestration surface 不可用，且仅 handoff 中的 `mainAgentNextAction / mainAgentReady` 已就绪，则：
+- 这只属于 compatibility fallback
+- 不得据此绕过 surface-first 规则重定义 accepted runtime path
+- 仅在兼容恢复 / 旧 story state 回放时使用
+
+**mainAgentNextAction 到主控分支的映射**：
 
 ```yaml
-action_to_stage_map:
-  story_audit: story_audit_passed
-  specify: specify_passed
-  plan: plan_passed
-  gaps: gaps_passed
-  tasks: tasks_passed
-  implement: implement_passed
-  document_audit: document_audit_passed
-  commit_gate: commit_gate_passed
-  commit: commit_ready
+main_agent_action_map:
+  dispatch_review: route_to_auditor_or_reviewer
+  dispatch_implement: route_to_implementation_executor
+  dispatch_remediation: rerun_fix_or_document_loop
+  run_closeout: enter_closeout_or_commit_gate
+  await_user: stop_and_wait_for_user
 ```
 
 **Output 增强**：
@@ -91,15 +106,15 @@ action_to_stage_map:
 当 auto-continue 触发时，输出：
 ```yaml
 auto_proceed: true
-reason: "auto_continue enabled 且 handoff.next_action={action} 且 ready=true"
-follow_up: <next_agent>
+reason: "auto_continue enabled 且 orchestration_surface.mainAgentNextAction={action} 且 mainAgentReady=true"
+follow_up: <next_agent|dispatch>
 ```
 
 当 handoff 已就绪但未开启 auto-continue 时，输出：
 ```yaml
 auto_proceed: false
-reason: "handoff 已就绪，但未启用 --continue / BMAD_AUTO_CONTINUE / auto_continue.enabled"
-follow_up: <next_agent>
+reason: "main-agent handoff 已就绪，但未启用 --continue / BMAD_AUTO_CONTINUE / auto_continue.enabled"
+follow_up: <next_agent|dispatch>
 suggested_command: "@bmad-master 继续 {epic}-{story} --continue"
 ```
 
@@ -500,7 +515,7 @@ Always state:
 4. `denial_reason` (if deny)
 5. `follow_up`: next agent/action
 6. `state_patch`: 应写回 story state 的变更
-7. `auto_proceed`: true (当 next_action 存在且 ready=true 时)
+7. `auto_proceed`: true (当 mainAgentNextAction 存在且 mainAgentReady=true 时)
 8. `reason`: auto_proceed 触发原因
 
 ## Example Usage

package/_bmad/claude/agents/bmad-story-audit.md

@@ -201,7 +201,7 @@ Claude 端 Stage 2 Story 审计执行体，负责审计 Story 文档并决定是
 
 ### Runtime Contracts
 - 审计报告路径：`_bmad-output/implementation-artifacts/epic-{epic_num}-{epic_slug}/story-{story_num}-{story_slug}/AUDIT_story-{epic_num}-{story_num}.md`（与 create-story workflow、bmad-story-assistant 一致：story 子目录为 `story-{story}-{slug}`）
-- 审计通过：更新 story state 为 `story_audit_passed`，handoff 到 `speckit-implement`
+- 审计通过：更新 story state 为 `story_audit_passed`；`handoff -> speckit-implement` 只作为 compatibility hint，真正是否进入 Dev Story 必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration` surface 后决定
 - 审计失败：更新 story state 为 `story_audit_failed`，要求修 Story 文档后重新审计
 
 ## Repo Add-ons
@@ -223,6 +223,8 @@ next_action: dev_story
 next_agent: speckit-implement
 ```
 
+说明：`next_agent: speckit-implement` 只作为 compatibility hint。
+
 ### FAIL
 ```yaml
 layer: 3
@@ -232,3 +234,5 @@ auditReportPath: _bmad-output/implementation-artifacts/epic-{epic_num}-{epic_slu
 next_action: revise_story
 next_agent: bmad-story-create
 ```
+
+说明：`next_agent: bmad-story-create` 同样只作为 compatibility hint。

package/_bmad/claude/agents/bmad-story-create.md

@@ -159,7 +159,7 @@ Claude 端 Stage 1 Create Story 执行体，负责在 BMAD Story 流程中生成
 ### Runtime Contracts
 - 产物路径：`_bmad-output/implementation-artifacts/epic-{epic_num}-{epic_slug}/story-{story_num}-{story_slug}/{epic_num}-{story_num}-{story_slug}.md`（与 create-story workflow、bmad-story-assistant 一致：story 子目录为 `story-{story}-{slug}`，不含 epic 编号）
 - Story 产出完成后，必须将 story state 更新为 `story_created`
-- 必须写入 handoff，交由 `bmad-story-audit` 执行 Stage 2
+- 必须写入 handoff；`next_agent: bmad-story-audit` 只作为 compatibility hint，真正是否进入 Stage 2 必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration` surface 后决定
 - 若用户明确跳过 Create Story，必须记录跳过依据并直接进入 Story 审计
 
 ## Repo Add-ons
@@ -180,3 +180,5 @@ artifactPath: _bmad-output/implementation-artifacts/epic-{epic_num}-{epic_slug}/
 next_action: story_audit
 next_agent: bmad-story-audit
 ```
+
+说明：本执行体不得直接把控制链交给 `bmad-story-audit`；handoff 只是给主 Agent 的兼容提示。

package/_bmad/claude/agents/layers/bmad-bug-agent.md

@@ -56,8 +56,9 @@ Bug 修复专用流程。
 - BUGFIX 文档审计未执行、未通过或结论不明时，一律视为实现前阻断
 - 修复完成后必须进行实施后审计
 - 提交仅允许通过 `bmad-master` 的 `commit_request`
-- 返回必须包含：`execution_summary`、`artifacts`、`handoff`、`next_action`、`ready`
+- 返回必须包含：`execution_summary`、`artifacts`、`handoff`、`next_action`、`ready`、`mainAgentNextAction`、`mainAgentReady`
 - 修复流程必须保留 RCA / BUGFIX / repro test / post-audit 的完整链路证据
+- parent 主 Agent 在发起或回收本执行体前，必须优先读取 `npm run main-agent-orchestration -- --cwd {project-root} --action inspect|dispatch-plan`
 
 ## Repo Add-ons
 
@@ -109,6 +110,7 @@ Bug 修复专用流程。
 
 - 主 Agent 调用执行体时，必须完整复制 Cursor 侧 bug assistant / bugfix workflow 的对应正文模板，不得摘要化
 - 不得只传文件路径让执行体自行推断规则
+- parent 主 Agent 不得只根据 `mainAgentNextAction / mainAgentReady` 派发本执行体；若 repo-native orchestration surface 可用，必须优先消费该 surface
 - 必须显式传入：
   - bug 描述
   - RCA 摘要或 RCA 文档路径
@@ -130,8 +132,12 @@ handoff:
   next_action: implement_bugfix|post_audit|commit_gate|revise_bugfix_doc
   next_agent: bmad-bug-agent|auditor-implement|bmad-master|auditor-bugfix
   ready: true|false
+  mainAgentNextAction: dispatch_implement|dispatch_review|dispatch_remediation|run_closeout|await_user
+  mainAgentReady: true|false
 ```
 
+说明：这里的 `next_agent`、`mainAgentNextAction`、`mainAgentReady` 只作为 compatibility hint。bugfix 子执行体返回后，主 Agent 必须重新读取 `main-agent-orchestration` surface，再决定下一条全局分支。
+
 ## State Updates
 
 ```yaml

package/_bmad/claude/agents/layers/bmad-code-reviewer-lifecycle.md

@@ -136,8 +136,12 @@ handoff:
   next_action: scoring_trigger|return_to_auditor
   next_agent: bmad-master|auditor-implement
   ready: true|false
+  mainAgentNextAction: dispatch_review
+  mainAgentReady: true|false
 ```
 
+说明：这里的 `next_agent`、`mainAgentNextAction`、`mainAgentReady` 只作为 compatibility hint。review 返回后，主 Agent 必须重新读取 `main-agent-orchestration` surface，再决定下一条全局分支。
+
 ## State Updates
 
 ```yaml

package/_bmad/claude/agents/layers/bmad-layer4-speckit-gaps.md

@@ -243,9 +243,10 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
 #### Step 3.2: 调用审计 Agent
 
 **Primary Executor**: `auditor-gaps` 通过 `subagent_type: general-purpose` 调用
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计 IMPLEMENTATION_GAPS-E{epic}-S{story}.md",
   subagent_type: "general-purpose",
   prompt: `
@@ -337,6 +338,8 @@ auditReportPath: specs/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/AUDIT_
 next_action: proceed_to_tasks
 ```
 
+说明：handoff 只作为 compatibility hint；是否进入 `tasks`，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/layers/bmad-layer4-speckit-implement.md

@@ -420,9 +420,10 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
 #### Step 5.2: 调用审计 Agent
 
 **Primary Executor**: `auditor-implement` 通过 `subagent_type: general-purpose` 调用
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计 implement 阶段代码实现",
   subagent_type: "general-purpose",
   prompt: `
@@ -547,6 +548,8 @@ tddSummary:
 next_action: commit_gate
 ```
 
+说明：handoff 只作为 compatibility hint；是否进入 closeout / commit gate，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/layers/bmad-layer4-speckit-plan.md

@@ -253,9 +253,10 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
 #### Step 4.2: 调用审计 Agent
 
 **Primary Executor**: `auditor-plan` 通过 `subagent_type: general-purpose` 调用
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计 plan-E{epic}-S{story}.md",
   subagent_type: "general-purpose",
   prompt: `
@@ -363,6 +364,8 @@ auditReportPath: specs/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/AUDIT_
 next_action: proceed_to_gaps
 ```
 
+说明：handoff 只作为 compatibility hint；是否进入 `gaps`，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/layers/bmad-layer4-speckit-specify.md

@@ -228,6 +228,9 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
   - `_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/PROMPT_audit-spec-E{epic}-S{story}_round{N}.md`
 - 审计报告输出路径:
   - `specs/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/AUDIT_spec-E{epic}-S{story}.md`
+- Story-flow 约束:
+  - 若当前产物为 `spec-E{epic}-S{story}.md`，则审计子任务必须显式携带 `storyPath`
+  - 审计报告控制字段必须回传 `storyPath: <Story 文档路径>`，供 `runAuditorHost` 执行 `Story -> Spec` source_hash 版本锁
 - 审计失败处理:
   - 主 Agent 根据 required_fixes 修改 spec 文档后重新发起下一轮审计- 审计通过处理:
   - 追加通过标记
@@ -260,9 +263,10 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
 
 **子任务prompt 不得再只是"读取并执行某个 Prompt 文件"。**
 **必须保证子任务收到的主文本基线仍然是 Cursor §1，而不是无法区分来源的本地重写版。**
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计spec-E{epic}-S{story}.md",
   subagent_type: "general-purpose",
   prompt: `
@@ -275,6 +279,8 @@ Task({
 **Claude/OMC Runtime Adapter**
 - 审计报告输出至
   specs/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/AUDIT_spec-E{epic}-S{story}.md
+- Story-flow 必须携带
+  - `storyPath: _bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/{epic}-{story}-{story-slug}.md`
 - 同时保存本轮 Prompt 存档至
   _bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/PROMPT_audit-spec-E{epic}-S{story}_round{N}.md
 
@@ -363,6 +369,8 @@ auditReportPath: specs/epic-{epic}-{epic-slug}/story-{story}-{story-slug}/AUDIT_
 next_action: proceed_to_plan
 ```
 
+说明：handoff 只作为 compatibility hint；是否进入 `plan`，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/layers/bmad-layer4-speckit-tasks.md

@@ -320,9 +320,10 @@ PROMPT_PATH="_bmad-output/implementation-artifacts/epic-{epic}-{epic-slug}/story
 #### Step 4.2: 调用审计 Agent
 
 **Primary Executor**: `auditor-tasks` 通过 `subagent_type: general-purpose` 调用
+**当前 accepted path（强制）**：本执行体不得在自身上下文里直接 `Task(...)` 派发 auditor；以下内容只能作为返回给主 Agent 的 dispatch request / compatibility hint。真实派发必须回到主 Agent，由主 Agent 重新读取 `main-agent-orchestration inspect`，必要时执行 `dispatch-plan`，再决定是否派发 auditor。
 
 ```typescript
-Task({
+MainAgentDispatchRequest({
   description: "审计 tasks-E{epic}-S{story}.md",
   subagent_type: "general-purpose",
   prompt: `
@@ -421,6 +422,8 @@ next_action: proceed_to_implement
 next_agent: speckit-implement
 ```
 
+说明：`next_agent: speckit-implement` 只作为 compatibility hint；是否进入 implement，必须回到主 Agent，由主 Agent 重新读取 authoritative surface 后决定。
+
 ## Constraints
 
 - **禁止自行 commit**

package/_bmad/claude/agents/layers/bmad-standalone-tasks.md

@@ -52,8 +52,9 @@
 - 前置门控未执行、未通过或结论不明时，一律视为实施前阻断
 - 批次门控：每批任务完成后调用实现审计
 - 提交门控：仅允许向 `bmad-master` 返回 `commit_request`，禁止自行 commit
-- 返回必须包含：`execution_summary`、`artifacts`、`handoff`、`next_action`、`ready`
+- 返回必须包含：`execution_summary`、`artifacts`、`handoff`、`next_action`、`ready`、`mainAgentNextAction`、`mainAgentReady`
 - 实施过程必须维护 standalone 模式下的 prd/progress 产物
+- parent 主 Agent 在发起或回收本执行体前，必须优先读取 `npm run main-agent-orchestration -- --cwd {project-root} --action inspect|dispatch-plan`
 
 ## Repo Add-ons
 
@@ -112,6 +113,7 @@
 
 - 主 Agent 调用实施子代理时，必须完整复制 Cursor 侧对应正文模板，不得摘要化
 - 不得只传文件路径让子代理自行推断规则
+- parent 主 Agent 不得只根据 `mainAgentNextAction / mainAgentReady` 派发本执行体；若 repo-native orchestration surface 可用，必须优先消费该 surface
 - 必须显式传入：
   - 文档路径
   - 未完成任务清单
@@ -134,8 +136,12 @@ handoff:
   next_action: implement_next_batch|post_batch_audit|commit_gate|revise_tasks_doc
   next_agent: bmad-standalone-tasks|auditor-implement|bmad-master|auditor-tasks-doc
   ready: true|false
+  mainAgentNextAction: dispatch_implement|dispatch_review|dispatch_remediation|run_closeout|await_user
+  mainAgentReady: true|false
 ```
 
+说明：这里的 `next_agent`、`mainAgentNextAction`、`mainAgentReady` 只作为 compatibility hint。standalone 执行体返回后，主 Agent 必须重新读取 `main-agent-orchestration` surface，再决定下一条全局分支。
+
 ## State Updates
 
 ```yaml