maestro-flow 0.5.45 → 0.5.47

package/.agents/skills/maestro-ralph-v2/SKILL.md

@@ -12,6 +12,7 @@ allowed-tools:
   - invoke_skill
   - ask_user
   - delegate_subagent
+  - send_message
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
@@ -44,13 +45,16 @@ Remaining      → intent (amend_mode 时为 change_request)
 </context>
 
 <invariants>
-1. **Ralph-v2 owns the full loop** — locate step → resolve args → load context → dispatch agent → extract signals → drift → complete，全部在本命令内完成
-2. **One agent per step** — 每个执行 step 派发一个 executor agent，agent 执行完返回，主流程解析结果后决定下一步
-3. **Agent is a thin wrapper** — executor agent 调 `ralph next` 获取 skill prompt 并执行，返回输出；arg resolution、context loading、signal extraction、drift analysis、ralph complete 均由主流程完成
-4. **Synchronous dispatch** — delegate_subagent() 调用是同步的（等待返回），不需要 STOP/callback 模式
+1. **Ralph-v2 owns the full loop** — locate step → resolve args → load context → dispatch agent → wait for send_message → receive → extract signals → drift → complete，全部在本命令内完成
+2. **One agent per step** — 每个执行 step 派发一个 named executor agent，agent 通过 send_message 回传结果，主流程解析结果后决定下一步
+3. **Agent is a thin wrapper** — executor agent 调 `ralph next` 获取 skill prompt 并执行，通过 send_message 回传输出；arg resolution、context loading、signal extraction、drift analysis、ralph complete 均由主流程完成
+4. **Dual dispatch model** — 执行 Agent 与评估 Agent 使用不同派发模式：
+   - **执行 Agent**（A_STEP_DISPATCH）：`delegate_subagent({name: "exe-xxx"})` — named mailbox teammate，支持内部多 agent 编排，通过 `send_message({to: "main"})` 回传结果
+   - **评估 Agent**（A_AGENT_EVALUATE / A_AGENT_GOAL_AUDIT / A_AGENT_REGROUND）：`delegate_subagent()` 不传 `name` — 同步阻塞，直接返回结果（评估 agent 只读不需要多 agent）
+   - `agent_exec_name` 既用于 display/日志，也作为执行 Agent 的 `name` 参数
 5. **主流程调 `ralph complete`** — 每个 step 完成后由主流程调 `maestro ralph complete`，非 agent 上报
-6. **Decision evaluation inline** — decision 节点不 handoff，通过 `delegate_subagent()` 启动分析 Agent 在本循环内评估
-7. **No CLI delegation** — 本命令不使用 `maestro delegate`；执行和评估均通过 delegate_subagent() 完成
+6. **Decision evaluation inline** — decision 节点不 handoff，通过 Agent 或 CLI delegate 在本循环内评估
+7. **CLI delegation for evaluation only** — CLI delegate（`maestro delegate --mode analysis`）仅限评估环节；执行仍通过 executor Agent 完成
 8. **Decision delegates read-only** — 评估 Agent 通过 prompt 中的 CONSTRAINTS 约束为只读
 9. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（由 execute Agent 完成）
 10. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
@@ -87,7 +91,8 @@ S_CONFIRM       — 用户确认
 
 S_STEP_LOCATE     — 找下一个 pending step                    PERSIST: —
 S_STEP_RESOLVE    — 解析占位符 + 丰富参数                    PERSIST: step.args (enriched)
-S_STEP_DISPATCH   — 组装上下文 + 派发 executor agent 执行单步  PERSIST: step.agent_exec_name, step.status = "running"
+S_STEP_DISPATCH   — 组装上下文 + 派发 named executor agent     PERSIST: step.agent_exec_name, step.status = "running"
+S_STEP_WAIT_MSG   — 等待 executor 的 send_message 回传          PERSIST: —
 S_STEP_ANALYZE    — 提取信号 + 组装 completion 参数            PERSIST: —
 S_STEP_DRIFT      — 产物 vs 目标偏离分析                      PERSIST: step.drift_score
 S_STEP_COMPLETE   — 调 `ralph complete` 上报                  PERSIST: step.completion_*
@@ -142,8 +147,12 @@ S_STEP_RESOLVE:
   → S_STEP_DISPATCH  DO: A_STEP_RESOLVE_ARGS
 
 S_STEP_DISPATCH:
-  → S_STEP_ANALYZE   WHEN: agent returned output               DO: A_STEP_DISPATCH
-  → S_HANDLE_FAIL    WHEN: agent returned error/null            DO: A_STEP_DISPATCH
+  → S_STEP_WAIT_MSG  WHEN: executor dispatched                  DO: A_STEP_DISPATCH
+
+S_STEP_WAIT_MSG:
+  → S_STEP_ANALYZE   WHEN: received agent-message with EXECUTOR_OUTPUT   DO: A_STEP_RECEIVE
+  → S_HANDLE_FAIL    WHEN: received agent-message with status=ERROR      DO: A_STEP_RECEIVE
+  → S_HANDLE_FAIL    WHEN: executor idle without send_message（崩溃检测）  DO: mark BLOCKED
 
 S_STEP_ANALYZE:
   → S_STEP_DRIFT     WHEN: STATUS == DONE|DONE_WITH_CONCERNS    DO: A_STEP_EXTRACT
@@ -323,14 +332,17 @@ Execution criteria: {session.execution_criteria joined by '; '}
    | debug | `dbg` |
    | Other | `run` |
 
-**4. Dispatch:**
+**4. Dispatch（named mailbox executor）:**
+
+> 执行 Agent 使用 `name` 参数派发为 named mailbox teammate，支持内部多 agent 编排。executor 通过 `send_message({to: "main"})` 回传执行结果。`resolved_agent_name` 同时用于 display 和 Agent `name` 参数。
 
 ```
 delegate_subagent({
-  subagent_type: "ralph-executor",
   name: "{resolved_agent_name}",
+  subagent_type: "ralph-executor",
   description: "执行 step {index}: {step.skill}",
   prompt: `Session: {session_id}
+Agent name: {resolved_agent_name}
 
 {goal_context 块，仅 protocol < 2 时}
 
@@ -339,11 +351,24 @@ delegate_subagent({
 })
 ```
 
-Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt 并执行。
-
 5. Write `step.agent_exec_name` to status.json
-6. Display: `[{index}/{total}] ⟶ {step.skill} → Agent:{name}`
-7. Agent 同步返回 → `agent_output` = 返回文本；返回 null → STATUS=BLOCKED
+6. Display: `[{index}/{total}] ⟶ {step.skill} → {resolved_agent_name}`
+7. delegate_subagent() 立即返回（named teammate 异步启动）→ 进入 S_STEP_WAIT_MSG 等待 executor 的 send_message
+
+### A_STEP_RECEIVE
+
+从 executor 的 `agent-message` 中提取执行输出。
+
+1. 接收到 `<agent-message from="{resolved_agent_name}">` 后，提取 message 内容
+2. 解析 `EXECUTOR_OUTPUT` 格式：
+   - `status: DONE` → agent_output = message 内容，继续 S_STEP_ANALYZE
+   - `status: DONE_WITH_CONCERNS` → agent_output = message 内容，继续 S_STEP_ANALYZE
+   - `status: ERROR` → STATUS=BLOCKED，转 S_HANDLE_FAIL
+3. idle_notification 处理（区分正常等待与崩溃）：
+   - 首次收到 `idle_notification`：executor 可能在等待 worker 回传，正常现象，继续等待
+   - 连续收到 2 次 `idle_notification` 且中间无 `agent-message`：向 executor 发送 `send_message({to: "{resolved_agent_name}", message: "请回报执行状态"})` 询问
+   - 询问后仍只收到 `idle_notification` 无 `agent-message`：STATUS=BLOCKED，转 S_HANDLE_FAIL
+4. `agent_output` = 提取的 message 内容
 
 ### A_STEP_EXTRACT
 
@@ -472,10 +497,12 @@ Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt
 
 ### A_AGENT_EVALUATE
 
-通过 Agent 在本循环内评估质量门。
+通过 Agent 和/或 CLI delegate 评估质量门。评估模式由 `step.evaluate_via` 决定。
+
+**1. Common setup:**
 
 1. Resolve artifact dir: `.workflow/scratch/{artifact.path}/` with fallback glob
-2. Parse decision metadata: `{ decision, retry_count, max_retries }`
+2. Parse decision metadata: `{ decision, retry_count, max_retries, evaluate_via }`
 3. Map result files:
 
    | Decision | Files |
@@ -486,33 +513,65 @@ Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt
    | post-test | uat.md, .tests/test-results.json |
    | post-frontend-verify | e2e-results.json |
 
-4. Dispatch evaluation Agent:
-   ```
-   delegate_subagent({
-     name: "eval-{decision}-{timestamp}",
-     description: "评估 {decision} 质量门",
-     prompt: "PURPOSE: 评估 {decision} 质量门结果
-   TASK: 读取以下结果文件 | 分析状态 | 评估严重性 | 给出建议
-   FILES: {result_file_paths}
-   SESSION: {session_dir}/status.json
-   EXPECTED: 输出以下格式：
-   ---VERDICT---
-   STATUS: PASS|FAIL|PARTIAL|BLOCKED
-   REASON: <一句话原因>
-   GAP_SUMMARY: <差距摘要>
-   CONFIDENCE: high|medium|low
-   CONFIDENCE_SCORE: 0-100
-   WEAKEST_DIMENSION: <最弱维度>
-   ---END---
-   CONSTRAINTS: 只评估不修改文件 | 置信度<60%倾向 fix | retry {n}/{max} 达上限必须 escalate"
-   })
-   ```
-5. On return: parse `---VERDICT---` block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; parse failure → fallback STATUS="fix", `parse_failed: true`, `confidence_score: 0` (invariant 18)
+4. `evaluate_via` 默认值：`"agent"`（未设置时）
+
+**2. Dispatch by mode:**
+
+**Mode: `agent`（默认）** — 同步 Agent 评估：
+
+```
+delegate_subagent({
+  description: "评估 {decision} 质量门（同步评估 Agent，不传 name）",
+  prompt: "PURPOSE: 评估 {decision} 质量门结果
+TASK: 读取以下结果文件 | 分析状态 | 评估严重性 | 给出建议
+FILES: {result_file_paths}
+SESSION: {session_dir}/status.json
+EXPECTED: 输出以下格式：
+---VERDICT---
+STATUS: PASS|FAIL|PARTIAL|BLOCKED
+REASON: <一句话原因>
+GAP_SUMMARY: <差距摘要>
+CONFIDENCE: high|medium|low
+CONFIDENCE_SCORE: 0-100
+WEAKEST_DIMENSION: <最弱维度>
+---END---
+CONSTRAINTS: 只评估不修改文件 | 置信度<60%倾向 fix | retry {n}/{max} 达上限必须 escalate"
+})
+```
+
+**Mode: `cli`** — CLI delegate 评估（异步后台）：
+
+```
+shell({
+  command: `maestro delegate "PURPOSE: 评估 ${decision} 质量门结果\nTASK: 读取 ${result_file_paths} | 分析状态 | 评估严重性\nEXPECTED: ---VERDICT--- 格式（STATUS/REASON/GAP_SUMMARY/CONFIDENCE_SCORE）\nCONSTRAINTS: 只评估不修改文件" --mode analysis --rule analysis-review-code-quality`,
+  run_in_background: true
+})
+```
+等待 delegate 完成 → `maestro delegate output {exec_id}` 获取结果 → 解析 `---VERDICT---`
+
+**Mode: `dual`** — Agent + CLI 并行评估，交叉验证：
+
+1. 先派发 CLI delegate（`run_in_background: true`）
+2. 同时派发同步 Agent（阻塞等待）
+3. Agent 返回后，检查 CLI delegate 状态（`maestro delegate status {exec_id}`）
+4. 合并裁决：
+
+   | Agent 结果 | CLI 结果 | 合并策略 |
+   |-----------|---------|---------|
+   | 两者一致 | — | 采用共识，confidence_score 取较高值 |
+   | Agent=PASS, CLI=FAIL | — | 降级为 PARTIAL，confidence_score 取平均值 |
+   | Agent=FAIL, CLI=PASS | — | 维持 FAIL（保守策略） |
+   | CLI 未返回 | — | 使用 Agent 结果，标 `"cli_pending": true` |
+
+**3. Verdict parse + adjustment（所有模式通用）:**
+
+5. Parse `---VERDICT---` block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; parse failure → fallback STATUS="fix", `parse_failed: true`, `confidence_score: 0` (invariant 18)
 6. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
 7. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
    ```json
    { "id": "DEC-{timestamp}", "timestamp": "{ISO}", "source": "ralph-v2",
      "node_id": "{step.decision}", "type": "quality-gate",
+     "evaluate_via": "{mode}", "cli_exec_id": "{exec_id|null}",
      "verdict": "{adjusted_verdict}", "confidence_score": {N},
      "parse_failed": false,
      "close_call": {N>=50 && N<=70}, "summary": "{REASON}" }
@@ -520,14 +579,13 @@ Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt
 
 ### A_AGENT_GOAL_AUDIT
 
-通过 Agent 审计子目标完成情况。
+通过 Agent 和/或 CLI delegate 审计子目标完成情况。支持 `evaluate_via` 三种模式（同 A_AGENT_EVALUATE）。
 
 1. Read `session.task_decomposition` from status.json
-2. Dispatch audit Agent:
+2. Dispatch audit（按 `evaluate_via` 模式，默认 `agent`）:
    ```
    delegate_subagent({
-     name: "goal-audit-{timestamp}",
-     description: "审计子目标完成情况",
+     description: "审计子目标完成情况（同步评估 Agent，不传 name）",
      prompt: "PURPOSE: 审计未完成子目标，判定 met / unmet
    TASK:
      1. 读取 {session_dir}/status.json 中 task_decomposition 的 status!=done 子目标
@@ -551,20 +609,19 @@ Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt
    })
    ```
 3. On return: parse verdict, update task_decomposition status
-4. Append `{session_dir}/decisions.ndjson`：`{ "type": "goal-gate", "unmet_count": N, "unmet_ids": [...] }`
+4. Append `{session_dir}/decisions.ndjson`：`{ "type": "goal-gate", "evaluate_via": "{mode}", "unmet_count": N, "unmet_ids": [...] }`
 5. Verdict routing: `all_met` + `INTENT_ALIGNED=true` → A_APPLY_GOAL_DONE；`all_met` + `INTENT_ALIGNED=false` → A_REGROUND_HALT；`has_unmet` → A_APPLY_GOAL_FIX
    GUARD: retry_count >= max_retries AND still unmet → A_APPLY_ESCALATE
 
 ### A_AGENT_REGROUND
 
-通过 Agent 执行意图保真检查。
+通过 Agent 和/或 CLI delegate 执行意图保真检查。支持 `evaluate_via` 三种模式（同 A_AGENT_EVALUATE）。
 
 1. Read status.json：intent, boundary_contract, completed steps, done goals
-2. Dispatch reground Agent:
+2. Dispatch reground（按 `evaluate_via` 模式，默认 `agent`）:
    ```
    delegate_subagent({
-     name: "reground-{timestamp}",
-     description: "意图保真检查",
+     description: "意图保真检查（同步评估 Agent，不传 name）",
      prompt: "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
    TASK:
      1. 读取 intent + boundary_contract.definition_of_done
@@ -663,8 +720,7 @@ Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt
 **Phase 3 Agent prompt:**
 ```
 delegate_subagent({
-  name: "amend-grill-{timestamp}",
-  description: "Amend impact analysis",
+  description: "Amend impact analysis（同步评估 Agent，不传 name）",
   prompt: "PURPOSE: 评估目标修改对 running session 的影响
 TASK:
   1. 读取 {session_dir}/status.json 的 task_decomposition + boundary_contract + 已完成 steps
@@ -695,7 +751,10 @@ GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 
 - **A_RETRY**: `shell("maestro ralph retry {index}")` — CLI 设 `step.retried = true`, `step.status = "pending"`, 清 `active_step_index`
 - **A_PAUSE_SESSION**: `ralph complete N --status BLOCKED --reason "..."` — CLI 写 `session.status = "paused"`
-- **A_COMPLETE_SESSION**: 校验所有 step `completion_confirmed == true` + `task_decomposition_all_done == true`（若存在），通过后写 `session.status = "completed"`
+- **A_COMPLETE_SESSION**: 校验所有 step `completion_confirmed == true` + `task_decomposition_all_done == true`（若存在），通过后写 `session.status = "completed"`。完成后向所有 idle executor 发送 shutdown_request 清理：
+  ```
+  遍历 steps[].agent_exec_name → send_message({to: name, message: {type: "shutdown_request"}})
+  ```
 
 </actions>
 
@@ -762,6 +821,7 @@ Build rules 0-14 全部适用，包括 spec-setup 预检（rule 0.5）、grill a
     "stage": "",
     "scope": null,
     "decision": null,
+    "evaluate_via": "agent|cli|dual",
     "retry_count": 0,
     "max_retries": 2,
     "command_scope": "global|project|missing|null",
@@ -826,24 +886,27 @@ E001–E006, W001–W004 适用。Agent 新增：
 
 ### Success Criteria
 
-- [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → extract → drift → complete → next
-- [ ] One agent per step — `delegate_subagent({ subagent_type: "ralph-executor" })` 每步派发一个
-- [ ] Agent 内调 `maestro ralph next` 获取 skill prompt 并执行，返回执行输出
+- [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → wait → receive → extract → drift → complete → next
+- [ ] One agent per step — `delegate_subagent({ name, subagent_type: "ralph-executor" })` 每步派发一个 named executor
+- [ ] Executor 内调 `maestro ralph next` 获取 skill prompt 并执行，支持内部多 agent 编排
+- [ ] Executor 通过 `send_message({to: "main"})` 回传 `EXECUTOR_OUTPUT` 格式结果
 - [ ] 主流程调 `maestro ralph complete` 上报（非 agent 上报）
 - [ ] 主流程负责 arg resolution、context loading、signal extraction、drift analysis
-- [ ] Agent 返回执行输出文本，主流程从中提取信号和状态
-- [ ] Agent 崩溃（返回 null）→ STATUS=BLOCKED，转 S_HANDLE_FAIL
-- [ ] 无 STOP/callback 模式 — delegate_subagent() 同步等待返回
-- [ ] Decision evaluation 通过 delegate_subagent() 同步完成
+- [ ] A_STEP_RECEIVE 从 executor 的 agent-message 中提取执行输出
+- [ ] Executor 崩溃（idle 无 send_message）→ 询问 2 次后 STATUS=BLOCKED，转 S_HANDLE_FAIL
+- [ ] Dual dispatch: 执行 Agent 传 `name`（async + send_message），评估 Agent 不传 `name`（sync）或 CLI delegate
+- [ ] Decision evaluation 支持三种模式：agent（同步）、cli（CLI delegate）、dual（并行交叉验证）
+- [ ] `evaluate_via` 字段控制评估模式，默认 `"agent"`
+- [ ] dual 模式合并策略：一致取共识、分歧保守降级、CLI 未返回用 Agent 结果
 - [ ] Verdict 解析保持 `---VERDICT---` 格式，parse 失败 → fallback fix + parse_failed: true
 - [ ] decisions.ndjson 追加：source 字段为 `"ralph-v2"`
-- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name`（执行 Agent 名称标识），含 `artifacts_produced`
+- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name`（执行 Agent name + display），含 `artifacts_produced`
 - [ ] Chain building（S_RESOLVE_PHASE through S_BUILD_CHAIN）自包含执行
 - [ ] A_STEP_DISPATCH 含前序产出加载（滑动窗口 5 step + accumulated signals + stage-specific artifacts）
-- [ ] Agent name 含 stage prefix（grl/brn/anm/ana/pln/exe/rev/tst/dbg）
+- [ ] `agent_exec_name` 含 stage prefix（grl/brn/anm/ana/pln/exe/rev/tst/dbg）——同时用于 Agent name 参数和 display
 - [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
 - [ ] CAVEATS 在 DONE_WITH_CONCERNS 时同时映射 --concerns
-- [ ] A_STEP_EXTRACT 从 agent 输出提取 artifact IDs、path signals、phase signals
+- [ ] A_STEP_EXTRACT 从 executor 输出提取 artifact IDs、path signals、phase signals
 - [ ] A_STEP_DRIFT_ANALYZE：ALIGNED/MINOR_DRIFT → complete；MAJOR_DRIFT+未重试 → retry；MAJOR_DRIFT+已重试 → DONE_WITH_CONCERNS
 - [ ] A_STEP_COMPLETE 将 context signals 写入 status.json.context
 - [ ] A_AMEND_GOAL：完整 5 步流程 + deferred_reading ralph-amend-goal.md + Agent mini grill 含完整 prompt

package/.agents/skills/maestro-swarm-workflow/SKILL.md

@@ -45,6 +45,8 @@ Remaining        → intent
 | `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
 | `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
 | `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -198,6 +200,29 @@ Workflow 返回 JSON 后：
 6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Route**
+- REQUIRED: Intent text or `--script` flag parsed successfully.
+- BLOCKED if: no intent and no `--script` (E001).
+
+**GATE 2: Route → Context Assembly**
+- REQUIRED: Target script resolved unambiguously (single match or user-selected from candidates).
+- BLOCKED if: ambiguous routing without user resolution (E002).
+
+**GATE 3: Context → Dispatch**
+- REQUIRED: Args payload assembled with all required fields for target script.
+- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- BLOCKED if: script file not found (E003) or required args missing.
+
+**GATE 4: Dispatch → Ingest**
+- REQUIRED: Workflow execution completed (success or partial results available).
+- BLOCKED if: Workflow execution failed entirely (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 与 Ralph 集成

package/.agents/skills/maestro-tools-execute/SKILL.md

@@ -37,8 +37,37 @@ $ARGUMENTS — Tool name, keyword, or --category filter
 Empty arguments enters interactive mode: list all tools for user selection.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST ask_user before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded via `maestro load --type knowhow`).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via ask_user (execute as-is / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
 ### Step 1: Load Tool
 
 **By name**:

package/.agents/skills/maestro-tools-register/SKILL.md

@@ -37,8 +37,37 @@ $ARGUMENTS — Intent description
 ```
 </context>
 
+<invariants>
+1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords`, and `summary` in YAML frontmatter; missing fields → reject write
+2. **No duplicate names** — tool title MUST be unique within its category; duplicate detection → E002 warning with overwrite/optimize confirmation
+3. **Category required** — every tool MUST declare exactly one category from: coding, test, review, arch, debug; empty category → E003
+4. **Confirmation gate** — MUST ask_user before writing knowhow document and spec ref entry; NEVER persist without user confirmation
+5. **Promote is in-place** — promote mode MUST update existing knowhow frontmatter via `maestro wiki update`; NEVER recreate the document
+6. **Output boundary** — ALL file writes MUST target .workflow/knowhow/ (tool documents) and .workflow/specs/ (ref entries via maestro spec add) only. NEVER modify source code or files outside these paths
+7. **Description format** — first line after `### Title` MUST state "Use when ..." (usage timing); this is critical for ref entry summary visibility in spec-load
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Gather**
+- REQUIRED: Mode determined (extract/generate/optimize/promote) from argument parsing.
+- REQUIRED: For optimize/promote modes, target tool/document exists and is loadable.
+- BLOCKED if: empty args without user response to ask_user.
+
+**GATE 2: Gather → Write**
+- REQUIRED: Tool name, category, and usage timing confirmed.
+- REQUIRED: Steps extracted or generated (extract: ≥1 step, generate: user-confirmed scope).
+- REQUIRED: Inline vs ref mode decided based on step count.
+- REQUIRED: User confirmed via ask_user (title, category, keywords, summary, step count).
+- BLOCKED if: E001 (.workflow/specs/ not initialized), E003 (no category), user cancels.
+
+**GATE 3: Write → Verify**
+- REQUIRED: Knowhow document written with `tool: true` frontmatter (or updated in-place for promote).
+- REQUIRED: Spec ref entry registered (if user confirmed).
+- BLOCKED if: write failed or spec add returned error.
+
 ### Step 1: Intent Detection
 
 Parse $ARGUMENTS to determine mode:

package/.agents/skills/maestro-ui-codify/SKILL.md

@@ -35,8 +35,19 @@ Flags:
 - `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
 - `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
 - `--overwrite`: Allow overwriting existing package directory
+
+**Output boundary**: ALL file writes MUST target the `--output-dir` path (default: `.workflow/reference_style/`) for reference packages, and `.workflow/knowhow/` for knowledge assets (via `codify-to-knowhow`). NEVER modify the source directory being analyzed.
 </context>
 
+<invariants>
+1. **Source read-only** — the source path being analyzed MUST NOT be modified; extraction is purely read-only
+2. **Phase-sequential loading** — workflow files (ui-codify-extract, ui-codify-package, ui-codify-knowhow) MUST be read only when their phase starts; NEVER load all phases eagerly
+3. **User confirmation before knowhow** — Phase 3→4 gate MUST present ask_user before generating knowledge assets; NEVER auto-proceed to knowhow generation
+4. **Overwrite protection** — existing package directory MUST NOT be overwritten without `--overwrite` flag (E003)
+5. **Artifact completeness** — all 5 required artifacts MUST exist before reporting completion; NEVER skip artifact verification
+6. **Token-first extraction** — design-tokens.json MUST be generated before layout-templates.json; layout extraction depends on token foundation
+</invariants>
+
 <execution>
 ## 1. Load UI Specs
 

package/.agents/skills/maestro-universal-workflow/SKILL.md

@@ -35,6 +35,8 @@ Remaining         → intent
 **Library locations:**
 - Fixed scripts: `~/.maestro/workflows/swarm/wf-*.js`
 - Dynamic scripts: `~/.maestro/workflows/dynamic/uwf-*.js`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/workflows/dynamic/` (generated scripts) and `.workflow/scratch/{YYYYMMDD}-uwf-*/` (execution results). Fixed scripts at `~/.maestro/workflows/swarm/` are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -511,6 +513,36 @@ Findings: ${digest}
 12. **无反斜杠路径** — 字符串中路径用正斜杠（`\u`、`\a` 等会被解析为转义序列）
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Scan**
+- REQUIRED: Intent text or `--from`/`--resume` flag parsed.
+- BLOCKED if: no intent and no flags (E001).
+
+**GATE 2: Scan → Design/Execute**
+- REQUIRED: Library scan completed (both `swarm/` and `dynamic/` directories).
+- REQUIRED: User decision if matches found (reuse existing vs generate new).
+- BLOCKED if: scan fails to read script directories.
+
+**GATE 3: Design → Generate**
+- REQUIRED: Task decomposition completed with work_items, decision_points, data_flow.
+- REQUIRED: Phase orchestration and adversarial pattern selection determined by depth.
+- BLOCKED if: task cannot be decomposed (E002).
+
+**GATE 4: Generate → Execute**
+- REQUIRED: Script written to `~/.maestro/workflows/dynamic/uwf-{slug}.js`.
+- REQUIRED: `node --check` syntax validation passed.
+- REQUIRED: User confirmation via ask_user (unless resuming).
+- BLOCKED if: syntax validation fails after 2 retries (E003).
+
+**GATE 5: Execute → Persist**
+- REQUIRED: Workflow execution completed via `scriptPath` invocation.
+- BLOCKED if: Workflow execution failed (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 使用示例
@@ -571,3 +603,30 @@ universal-workflow 扫描时会同时检查 swarm/ 和 dynamic/ 目录，
 | E005 | 持久化失败 | 展示脚本内容，让用户手动保存 |
 
 </appendix>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent and no --from/--resume flag | Prompt user for intent text |
+| E002 | error | Task decomposition failed — cannot identify work_items | Require more specific intent description |
+| E003 | error | Generated script syntax error after 2 retries | Show script content + error for manual fix |
+| E004 | error | Workflow execution failed | Show error, offer --resume with runId |
+| E005 | error | Script persistence failed (filesystem write error) | Show script content for manual save |
+| W001 | warning | No matching scripts found in library scan | Proceed directly to S_DESIGN |
+| W002 | warning | Adversarial gate confidence < 50% | Flag low-confidence decision, suggest --depth deep |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and flags extracted (--name, --depth, --dry-run, --from, --resume)
+- [ ] Library scan completed across both swarm/ and dynamic/ directories
+- [ ] User decision captured if matching scripts found (reuse vs generate)
+- [ ] Task decomposition produced: work_items, decision_points, data_flow
+- [ ] Adversarial pattern selected per decision_point according to depth level
+- [ ] Blueprint presented to user with estimated agent count
+- [ ] Script generated as pure JavaScript with all 12 generation rules enforced
+- [ ] `node --check` syntax validation passed
+- [ ] User confirmation obtained before execution (unless --resume)
+- [ ] Workflow executed via scriptPath (not inline script string)
+- [ ] Script persisted to `~/.maestro/workflows/dynamic/uwf-{slug}.js`
+- [ ] Completion summary displayed with reuse/resume commands
+</success_criteria>

package/.agents/skills/maestro-update/SKILL.md

@@ -32,10 +32,38 @@ $ARGUMENTS — optional flags.
 - `update-v{TO}-setup.md` — post-migration setup for version {TO}
 
 **Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
+
+**Output boundary**: ALL file writes MUST target `.workflow/state.json` (version bump), `.workflow/state.json.backup-*` (backup), and `.workflow/` config files touched by version-specific setup. NEVER modify source code or `src/migrations/` files.
 </context>
 
+<invariants>
+1. **Backup before migration** — a timestamped backup of `.workflow/state.json` MUST be created before any schema migration runs; NEVER execute migration without backup
+2. **Idempotent** — running update when already on latest version MUST be a no-op (display "up to date"); NEVER re-apply migrations
+3. **Confirmation before execute** — migration diff MUST be displayed and user MUST confirm via ask_user before execution (unless `--force`); NEVER silently apply schema changes
+4. **Migration diff always visible** — even with `--force`, the migration diff MUST be displayed for audit visibility; NEVER skip diff display
+5. **Restore path on failure** — if migration fails, the backup restore command MUST be displayed; NEVER leave user without recovery instructions
+6. **Sequential migration** — all intermediate version steps MUST be applied in order by the schema registry; NEVER skip intermediate versions
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Detect → Check**
+- REQUIRED: Current version read from `.workflow/state.json`.
+- BLOCKED if: state.json missing or unreadable (E001).
+
+**GATE 2: Check → Execute**
+- REQUIRED: Dry-run migration check completed; target version identified.
+- REQUIRED: User confirmation via ask_user (unless `--force`).
+- BLOCKED if: already up to date (display message and exit) or user cancels.
+
+**GATE 3: Execute → Summary**
+- REQUIRED: Backup created at `.workflow/state.json.backup-v{current}-{timestamp}`.
+- REQUIRED: Schema migration completed successfully.
+- REQUIRED: Version-specific setup doc followed (if exists).
+- BLOCKED if: migration failed — display restore command and exit.
+
 ### Step 1: Detect Version
 
 ```
@@ -108,6 +136,16 @@ Next steps:
 
 </execution>
 
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/state.json` not found or unreadable | Run `/maestro-init` first |
+| E002 | error | Schema migration failed (npx tsx returned error) | Display backup restore command: `cp .workflow/state.json.backup-* .workflow/state.json` |
+| E003 | error | Version-specific setup doc failed to execute | Manual setup: read `~/.maestro/workflows/updates/update-v{target}-setup.md` |
+| W001 | warning | No version-specific setup doc found for target version | Proceed without setup; schema migration alone is sufficient |
+| W002 | warning | `--setup-only` but no setup script exists for current version | Display message and exit |
+</error_codes>
+
 <success_criteria>
 - [ ] Current version detected from state.json
 - [ ] Schema migrations run automatically (no manual intermediate steps)

package/.agents/skills/manage-codebase-rebuild/SKILL.md

@@ -46,13 +46,42 @@ $ARGUMENTS -- optional flags.
 - `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
 - `.workflow/codebase/doc-index.json` -- generated documentation index
 - `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `.workflow/project.md` (Tech Stack section only). NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Destructive with confirmation** — rebuild clears `.workflow/codebase/` entirely; MUST confirm with user unless `--force` is set
+2. **Commit confirmation** — git commit MUST be confirmed by user unless `--force` is set; `--skip-commit` bypasses commit entirely
+3. **Partial failure tolerance** — if 1-3 mapper agents fail, proceed with partial results (W001); only abort if all 4 fail (E002)
+4. **Focus scoping** — when `--focus <area>` is set, MUST only regenerate docs relevant to that scope; leave unrelated docs untouched
+5. **State update** — MUST update state.json with rebuild timestamp on completion
+6. **KG pipeline mandatory** — MUST run `maestro kg index` after doc regeneration; KG validation failure is non-fatal (W003)
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 
 **When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Confirmation → Mapping** (Pre-flight → Agent spawn)
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- REQUIRED: User confirmed rebuild (or `--force` set). W002 if existing docs found.
+- BLOCKED if user declines confirmation.
+
+**GATE 2: Mapping → KG Pipeline** (Agent results → Knowledge Graph)
+- REQUIRED: At least 1 of 4 mapper agents returned valid results.
+- REQUIRED: All output files written to `.workflow/codebase/`.
+- REQUIRED: doc-index.json generated and valid.
+- BLOCKED if all 4 mapper agents failed (E002).
+
+**GATE 3: KG Pipeline → Commit** (Knowledge Graph → Git)
+- REQUIRED: `maestro kg index` executed (W003 if validation fails — non-blocking).
+- REQUIRED: state.json updated with rebuild timestamp.
+- REQUIRED: If not `--skip-commit`: user confirmed git commit (or `--force` set).
+- BLOCKED if state.json update fails.
 </execution>
 
 <completion>