maestro-flow 0.5.42 → 0.5.43

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: maestro-milestone-audit
 description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[milestone, e.g., 'M1']"
-allowed-tools: spawn_agents_on_csv, Read, Write, Bash, Glob, Grep
+argument-hint: "[milestone, e.g., 'M1'] [-y]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -28,9 +28,9 @@ $maestro-milestone-audit "M1"
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,scope,check_targets,deps,wave,status,findings,gaps_found,severity,error
-"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1","pending","","","",""
-"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1","pending","","","",""
+id,title,description,scope,check_targets,deps,wave,status,audit_verdict,findings,gaps_found,severity,error
+"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1","pending","","","","",""
+"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1","pending","","","","",""
 ```
 
 **Columns**:
@@ -45,6 +45,7 @@ id,title,description,scope,check_targets,deps,wave,status,findings,gaps_found,se
 | `deps` | Input | Dependencies (empty — all wave 1) |
 | `wave` | Computed | Wave number (always 1 — single parallel wave) |
 | `status` | Lifecycle | `pending` (initial) → `completed`/`failed` (set by merge step from worker's `result_status`) |
+| `audit_verdict` | Lifecycle | `pass` / `warning` / `fail` — audit check outcome per dimension (merged from worker output) |
 | `findings` | Lifecycle | Detailed findings per dimension (max 500 chars; merged) |
 | `gaps_found` | Lifecycle | Semicolon-separated list of integration gaps (merged) |
 | `severity` | Lifecycle | `critical` / `warning` / `info` per gap (merged) |
@@ -90,7 +91,14 @@ For each phase: check for completed analyze (optional), plan (required), execute
 
 Verify all adhoc-scoped artifacts completed. For each execute artifact, verify all tasks in plan dir completed.
 
-### Step 5: Integration Check via CSV Wave
+### Step 5: Confirmation Gate
+
+Unless `-y` flag is set, display audit scope summary and ask user via `request_user_input`:
+- Show: milestone name, phase count, artifact count, integration dimensions to check
+- Options: "Proceed with audit" / "Cancel"
+- If cancelled → END
+
+### Step 6: Integration Check via CSV Wave
 
 1. Create session folder: `.workflow/.csv-wave/{dateStr}-audit-{milestone}/`
 2. Build `tasks.csv` from csv_schema — populate `scope` and `check_targets` columns using phase artifacts discovered in Step 2
@@ -162,12 +170,16 @@ CONSTRAINTS:
   - Do NOT call spawn_agents_on_csv (no recursion).
 ```
 5. Parse `gaps_found` from all workers — aggregate into `.workflow/milestones/{milestone}/audit-report.md`
-6. Any worker with `audit_verdict == fail` and `severity == critical` → milestone verdict = FAIL
+6. Verdict determination:
+   - Any worker with `result_status == "failed"` (worker error, no verdict produced) → milestone verdict = **INCOMPLETE** (audit cannot pass with missing dimensions; re-run required)
+   - Any worker with `audit_verdict == "fail"` and `severity == "critical"` → milestone verdict = **FAIL**
+   - All workers completed with `audit_verdict` in `["pass", "warning"]` → milestone verdict = **PASS**
 
-### Step 6: Verdict
+### Step 7: Verdict
 
-**PASS**: All phases have completed EXC artifacts, no critical integration gaps, all adhoc completed.
+**PASS**: All phases have completed EXC artifacts, no critical integration gaps, all adhoc completed, all integration workers completed successfully.
 **FAIL**: Missing EXC artifacts or critical integration gaps found.
+**INCOMPLETE**: One or more integration check workers failed (result_status="failed") — audit cannot produce a reliable verdict. Fix worker errors and re-run.
 
 Display structured audit report.
 

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -38,8 +38,8 @@ Read `.workflow/state.json` for `current_milestone`, `artifacts[]`, `milestones[
 
 Validate audit report at `.workflow/milestones/{milestone}/audit-report.md`:
 - Parse for `## Verdict` section (or `**Verdict:**` inline)
-- PASS condition: verdict line contains the word `PASS` (case-insensitive)
-- Any other verdict (FAIL, PARTIAL, missing section) → E002 unless `--force`
+- PASS condition: verdict line matches strict pattern `^PASS$` (case-insensitive, trimmed) — rejects partial matches like "PASS_WITH_WARNINGS", "BYPASS", or "COMPASS"
+- Any other verdict (FAIL, INCOMPLETE, PARTIAL, missing section) → E002 unless `--force`
 
 Verify all milestone artifacts completed (E003 unless `--force`).
 
@@ -91,7 +91,7 @@ Learning content here.
 
 1. **High-frequency patterns**: Scan all `<spec-entry category="learning">` entries for keyword overlap. Trigger threshold: **>=2 entries sharing the same keyword**. For each triggered keyword, ask: "Keyword '{keyword}' appears in {N} learning entries. Promote to formal coding convention?"
 2. **Convention drift**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`. Trigger threshold: **any deviation found** (technique used but not documented, or documented convention not followed). Ask: "Convention '{convention}' was bypassed during this milestone. Update conventions?"
-3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link new knowledge. Trigger threshold: **always runs** (no user confirmation needed).
+3. **Wiki island check**: Suggest `wiki-connect --fix` to link new knowledge. Ask user via `request_user_input`: "Run wiki-connect to link new knowledge entries?" with options: "Yes, link now" / "No, skip". Only run if user confirms (or `-y` is set).
 
 If `-y`: auto-accept all promotions without asking.
 If not `-y`: ask user for confirmation via `request_user_input`:

package/.codex/skills/maestro-milestone-release/SKILL.md

@@ -34,7 +34,23 @@ $ARGUMENTS — optional explicit version and flags.
 Follow '~/.maestro/workflows/milestone-release.md' completely.
 
 **Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
-Bump manifest → Commit → Tag → Push
+**Confirmation gate** → Bump manifest → Commit → Tag → Push
+
+**Default behavior**: Without explicit `--no-dry-run` or user confirmation, the skill runs in dry-run mode (preview only). This prevents accidental commits, tags, and pushes.
+
+**Confirmation gate** (before any git write operations):
+Unless `-y` flag is set, display a summary and ask user via `request_user_input`:
+```
+Release preview:
+  Version:   v{previous} → v{new}
+  Milestone: {name}
+  Changelog: {N} entries
+  Actions:   commit + tag{" + push" unless --no-push}
+```
+Options: "Confirm release" / "Dry-run only (preview)" / "Cancel"
+- "Confirm release" → proceed with commit, tag, push
+- "Dry-run only" → display report without writing
+- "Cancel" → abort
 
 **Report:**
 ```
@@ -64,6 +80,7 @@ Changelog: {N} entries
 
 <success_criteria>
 - [ ] Preconditions validated
+- [ ] Confirmation gate passed (user confirmed or `-y` set) before any git write operations
 - [ ] Target version computed and greater than previous
 - [ ] Version manifest(s) updated
 - [ ] CHANGELOG.md entry with milestone summary + grouped changes

package/.codex/skills/maestro-next/SKILL.md

@@ -3,6 +3,7 @@ name: maestro-next
 description: "Single-command recommendation — pick the best next skill from the pool and execute it in-context"
 argument-hint: "\"<intent>\" [-y] [--dry-run] [--top N] [--list]"
 allowed-tools: Read, Bash, Glob, Grep, request_user_input
+invocation-note: "$skill {args}" in output is a suggest-only display format — the user or parent orchestrator decides whether to execute
 ---
 
 <purpose>
@@ -42,7 +43,7 @@ $ARGUMENTS — 意图文本 + 可选 flags。
 1. **不创建 session / 不写 status.json / 不调用 create_goal/update_plan** — 单次原子调用，产出由目标 skill 自行管理
 2. **管线编排器不在候选池** — `maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer` 永远不会被推荐
 3. **Skill 发现限定 codex 平台** — 通过 `maestro ralph skills --platform codex --json --quiet` 解析 `command_scope` + `command_path`（project 覆盖 global，限定 `.codex/skills/`）；未命中即 E003
-4. **空 intent 或 "continue/next/go/继续/下一步/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
+4. **空 intent 或 "continue/next/go/继续/下一步/接下来"** → 直接采用 lifecycle_position 推断的自然下一步（无需 clarification，不进入 S_PARSE 的 clarify 回合）
 5. **字面命中路由表优先** — lifecycle 仅作加分；命中失败时 lifecycle 上升为决定性信号
 6. **In-context invocation** — top pick 以 `$skill-name {args}` 形式在协调器上下文直接调用，**禁止** spawn_agent / spawn_agents_on_csv / shell_exec 包装
 7. **参数传递** — 默认 intent 原文作为第一个 arg；用户可在 S_CONFIRM 修改；`-y` 仅当用户传入时透传到 skill args
@@ -60,7 +61,7 @@ S_LIST      — `--list` 模式：分组展示候选池                     PERS
 S_PRESENT   — 显示 top pick + 备选 + 推荐理由 + 执行参数        PERSIST: —
 S_CONFIRM   — request_user_input 选择/修改参数（auto_mode 跳过） PERSIST: —
 S_EXECUTE   — 在协调器上下文以 `$skill {args}` 直调              PERSIST: —
-S_FALLBACK  — intent 空且 clarification 失败                    PERSIST: —
+S_FALLBACK  — 候选池全部 missing（E003）                        PERSIST: —
 </states>
 
 <transitions>
@@ -69,8 +70,7 @@ S_PARSE:
   → S_LIST       WHEN: --list flag
   → S_STATE      WHEN: intent text present
   → S_STATE      WHEN: keyword "continue"/"next"/"go"/"继续"/"下一步"/"接下来"
-  → S_PARSE      WHEN: no intent (max 1 clarify round)    DO: request_user_input
-  → S_FALLBACK   WHEN: clarification empty
+  → S_STATE      WHEN: empty intent (treat as lifecycle next step — no clarification)
 
 S_STATE:
   → S_RANK       DO: A_INFER_LIFECYCLE
@@ -99,7 +99,7 @@ S_EXECUTE:
   → END          DO: A_INVOKE_SKILL → 输出 "✓ executed $<skill>"
 
 S_FALLBACK:
-  → END          DO: raise E001
+  → END          DO: raise E003
 
 </transitions>
 
@@ -167,7 +167,7 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 
 | Intent 模式 | top pick |
 |------------|---------|
-| 空 / "continue" / "next" / "go" / "继续" / "下一步" / "接下来" | lifecycle 自然下一步 |
+| 空 / "continue" / "next" / "go" / "继续" / "下一步" / "接下来" | lifecycle 自然下一步（空 intent 直接进入 S_STATE，不做 clarification） |
 | "status" / "状态" / "现在到哪了" | `manage-status` |
 | 字面命中路由表 | 路由表优先（lifecycle 仅加分） |
 | 无任何匹配 | lifecycle 下一步 + raise W002 |
@@ -234,14 +234,15 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 
 ### A_INVOKE_SKILL
 
-在协调器上下文以 `$skill-name {args}` 直接调用（**NO spawn_agent, NO shell_exec 包装**）：
+在协调器上下文以 `$skill-name {args}` 形式输出推荐调用（suggest-only display — 由用户或父编排器决定是否执行）：
 
 1. 解析最终 args：
    - 默认：`{intent}`（原文，去除已识别的关键词如 "continue"）
    - 用户改过：使用用户输入
    - `-y` 透传：附加 `-y`（仅当用户传入且目标 skill 支持）
-2. 在响应中直接写出调用指令，例如：`$maestro-analyze "优化登录流程"`
-3. 读取目标 skill 产出后输出 `✓ executed $<skill-name>`
+2. 在响应中输出建议调用指令，例如：`$maestro-analyze "优化登录流程"`
+   - `$skill {args}` 是建议格式，非自动执行；用户确认后由协调器上下文执行
+3. 执行后输出 `✓ executed $<skill-name>`
 4. 不修改任何 `.workflow/` 文件；不创建 session；不触发后续 chain
 
 </actions>
@@ -278,7 +279,7 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | intent 空且 clarification 后仍空 | 提供意图描述或使用 `--list` 浏览 |
+| E001 | error | (reserved — empty intent now falls through to lifecycle next step) | — |
 | E002 | error | codex skill 池为空（`maestro ralph skills --platform codex` 无结果） | 检查 `.codex/skills/` 与 `~/.codex/skills/` |
 | E003 | error | 选定命令在 codex 平台未命中（`command_scope == "missing"`） | 列出 codex 可用 skill 让用户重选 |
 | W001 | warning | top1 与 top2 得分差距 < 阈值 | 强制展示前 3 让用户裁决 |

package/.codex/skills/maestro-overlay/SKILL.md

@@ -2,16 +2,16 @@
 name: maestro-overlay
 description: Create or edit command overlays from natural language
 argument-hint: "<intent> | --list | --remove <name>"
-allowed-tools: Read, Write, Bash, Glob, Grep
+allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
 4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
 
 ```
-Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
-(or --list /      (read command        (apply_patch    (shell_exec +
-  --remove)         XML sections)       to overlays/)    banner)
+Parse Intent  →  Identify Targets  →  Draft JSON  →  Preview+Confirm  →  Install + Report
+(or --list /      (read command        (apply_patch    (request_user_      (shell_exec +
+  --remove)         XML sections)       to overlays/)    input preview)      banner)
 ```
 
 **Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
@@ -46,7 +46,7 @@ $maestro-overlay "--remove cli-verify-after-execute"
 3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
 4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
 5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
-6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
+6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions. After clarification, always show a preview of the overlay (target commands, injection section, mode, content summary) and request user confirmation via `request_user_input` before writing or installing. Never proceed with best-guess writes without confirmation.
 </invariants>
 
 <execution>
@@ -57,7 +57,7 @@ $maestro-overlay "--remove cli-verify-after-execute"
 - `--list` → run `maestro overlay list`, then stop
 - `--remove <name>` → run `maestro overlay remove <name>`, then stop
 
-**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
+**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions via `request_user_input`.
 
 ### Step 2: Identify Targets and Injection Points
 
@@ -92,6 +92,16 @@ Build slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `
 
 **Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
 
+### Step 3.5: Preview and Confirm
+
+Before writing or installing, show the user a preview via `request_user_input`:
+- Target command(s) and injection section(s)
+- Patch mode (append/prepend/replace/new-section)
+- Content summary (first few lines of injected markdown)
+- Overlay file path
+
+Options: Confirm (proceed to install), Edit (revise content), Cancel (abort).
+
 ### Step 4: Install via CLI and Report
 
 Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).

package/.codex/skills/maestro-player/SKILL.md

@@ -103,14 +103,20 @@ S_LOAD:
 
 S_INIT:
   → END          WHEN: --dry-run                        DO: display wave plan with [BARRIER] markers
-  → S_WAVE_LOOP  DO: A_INIT_SESSION
+  → S_CONFIRM    DO: A_INIT_SESSION
+
+S_CONFIRM:
+  → S_WAVE_LOOP  WHEN: -y OR --yes OR --continue OR --skip-questions OR user confirms
+  → END          WHEN: user cancels
+  GUARD: display wave plan (template, session, context, waves with [BARRIER] markers), request_user_input to confirm execution. Do NOT write state.json or spawn agents before confirmation.
 
 S_WAVE_LOOP:
-  → S_WAVE_LOOP  WHEN: wave completed, more pending     DO: A_EXECUTE_WAVE → advance
+  → S_WAVE_LOOP  WHEN: 1+ completed in wave, more pending   DO: A_EXECUTE_WAVE → advance (propagate incomplete marker if partial failures)
   → S_COMPLETE   WHEN: all steps completed
-  → END          WHEN: checkpoint pause                 DO: set status=paused
-  → END          WHEN: wave failed                      DO: mark remaining skipped, set status=aborted
-  GUARD: checkpoint nodes → handle inline (no spawn), save snapshot, optional user pause
+  → END          WHEN: checkpoint pause                      DO: set status=paused
+  → S_WAVE_LOOP  WHEN: all failed in wave, retry available   DO: retry same wave (retry_count++, max 1 retry per wave)
+  → END          WHEN: all failed in wave, retry exhausted   DO: set status=aborted, record retry_count and evidence_incomplete
+  GUARD: checkpoint nodes → handle inline (no spawn), save snapshot, optional user pause. Partial failures (1+ completed, some failed) → continue with incomplete marker, do NOT mark failed rows as completed.
 
 S_COMPLETE:
   → END          DO: display per-wave results, set status=completed

package/.codex/skills/maestro-quick/SKILL.md

@@ -100,14 +100,14 @@ Update plan.json task statuses as completed.
 
 ### Step 9: Commit and Report
 
-Commit all changes: `git add -A && git commit -m "quick: {slug} - {short description}"`. Update `.workflow/state.json` scratch task entry (if state.json exists).
+Stage only files modified during this skill execution (tracked via task summaries). Display the file list for user confirmation before committing (skip confirmation if `-y`). Commit: `git add <file1> <file2> ... && git commit -m "quick: {slug} - {short description}"`. NEVER use `git add -A` — it may stage unrelated changes. Update `.workflow/state.json` scratch task entry (if state.json exists).
 
 Display report: task description, scratch path, status (completed/completed-with-gaps), tasks completed/total, files modified count. If `--full`: include verification result (PASS/GAPS).
 
 </execution>
 
 ### Artifact Verification
-Before reporting completion, verify: plan.json exists AND .summaries/TASK-*-summary.md exists for each task. Task summaries MUST include concrete evidence of completion. If missing: DO NOT report completion.
+Before reporting completion, verify: `{scratchDir}/plan.json` exists AND `{scratchDir}/plan.json` contains task statuses marked completed. Task status entries MUST include concrete evidence of completion (files_modified, verification results). If missing: DO NOT report completion.
 
 <error_codes>
 

package/.codex/skills/maestro-ralph/SKILL.md

@@ -8,21 +8,29 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Closed-loop decision engine for the maestro workflow lifecycle.
 Reads project state → infers position → builds adaptive chain → delegates execution.
 
+### Notation
+
+`Skill(name)` / `Skill(name, args)` = 加载 `~/.codex/skills/{name}/SKILL.md` 或 `.codex/skills/{name}/SKILL.md`（project 覆盖 global），args 填入目标 SKILL.md `<context>` 块的输入参数位。这是 skill 间的内部调用，**不是 CLI 命令**。严禁翻译为 `Bash("maestro {name} {args}")`——CLI 不接受裸 intent。
+
+合法 CLI 子命令仅限结构化操作：`maestro ralph next`、`maestro ralph complete`、`maestro ralph skills`、`maestro delegate`、`maestro explore` 等。
+
 ### Session
 
-`.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源（schema 见 `<appendix>`）。session_id 格式：`ralph-{YYYYMMDD-HHmmss}`（本 skill 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（`$maestro` coordinator 创建，静态链）。两类都由 `$maestro-ralph-execute` 推进。session-id 省略时取最新 `status=="running"`。
+`.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源（schema 见 `<appendix>`）。session_id 格式：`ralph-{YYYYMMDD-HHmmss}`（本 skill 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（`Skill(maestro)` coordinator 创建，静态链）。两类都由 `Skill(maestro-ralph-execute)` 推进。session-id 省略时：continue/execute 取最新 `status=="running"`；status 取最新 session（by created_at，不限 status）。
 
 ### Entry points
 
-- **`$maestro-ralph "intent"`** — 新建 session：infer → decompose → build → emit /goal prompt（如有 decomposition）→ dispatch ralph-execute
-- **`$maestro-ralph continue [session-id]`** — 恢复执行；省略=最新 running（首选直接 `$maestro-ralph-execute [session-id]`）
-- **`$maestro-ralph status [session-id]`** — 显示进度；省略=最新 ralph session
+- **`Skill(maestro-ralph, "intent")`** — 新建 session：infer → decompose → build → create_goal（如有 decomposition）→ dispatch ralph-execute
+- **`Skill(maestro-ralph, "continue [session-id]")`** — 用户入口：恢复执行，路由到 S_DISPATCH → `Skill(maestro-ralph-execute)`。省略 session-id 时取最新 `status=="running"` session
+- **`Skill(maestro-ralph, "status [session-id]")`** — 显示进度。省略 session-id 时取最新 session（by created_at，不限 status）
 
-> 推进规则：**step 推进由 `$maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `$maestro-ralph` 直调 handoff，无需用户手动切换。
+> **continue vs ralph-execute**：用户说"继续"时走 `Skill(maestro-ralph, "continue")`（用户入口，经 S_DISPATCH handoff）；内部 step 推进链和 decision 回调走 `Skill(maestro-ralph-execute)`（内部 handoff，跳过 ralph 路由层）。两者最终都由 ralph-execute 执行 step。
 
-> **CLI vs Skill 边界**：`maestro` 作为 CLI 二进制只有结构化子命令（`ralph`、`delegate`、`explore` 等），不接受裸 intent。`Bash("maestro \"some intent\"")` 会报错退出。创建 session 和路由 intent 必须通过 `$maestro-ralph` 或 `$maestro` skill 调用。CLI 层仅用于 step 加载（`ralph next`）和完成标记（`ralph complete`）。
+> 推进规则：**step 推进由 `Skill(maestro-ralph-execute)` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `Skill(maestro-ralph)` 直调 handoff，无需用户手动切换。
 
-Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
+> **CLI vs Skill 边界**：`maestro` 作为 CLI 二进制只有结构化子命令（`ralph`、`delegate`、`explore` 等），不接受裸 intent。`Bash("maestro \"some intent\"")` 会报错退出。创建 session 和路由 intent 必须通过 `Skill(maestro-ralph)` 或 `Skill(maestro)` skill 调用。CLI 层仅用于 step 加载（`ralph next`）和完成标记（`ralph complete`）。
+
+Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，通过 `create_goal` 注册目标。
 
 Step kinds:
 - **执行 step**: ralph-execute 调 `Bash("maestro ralph next")` 加载 SKILL.md + required_reading 全文，按 stdout 内联执行
@@ -33,18 +41,18 @@ Key difference from maestro coordinator:
 - ralph: living chain → decision nodes re-evaluate → chain grows/shrinks dynamically
 
 Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`
-Mutual invocation with `$maestro-ralph-execute` forms a self-perpetuating work loop.
+Mutual invocation with `Skill(maestro-ralph-execute)` forms a self-perpetuating work loop.
 
 ### Execution Flow
 
 ```
- $maestro-ralph "intent" ─▶ ralph        infer → decompose → build chain
+ Skill(maestro-ralph, "intent") ─▶ ralph        infer → decompose → build chain
                               │           resolves command_path per step
                               │           writes status.json
-                              │           emits /goal prompt
+                              │           calls create_goal
                               ▼
                        ralph-execute  ◀─┐ 执行 step → `maestro ralph next` + inline + `ralph complete`
-                              │         │ decision step → $maestro-ralph
+                              │         │ decision step → Skill(maestro-ralph)
                               └─────────┘ CLI writes step.completion_confirmed
                        loop until all completion_confirmed | paused
 ```
@@ -74,20 +82,20 @@ Remaining                        → intent (amend_mode 时为 change_request)
 
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
-2. **Handoff via `$maestro-ralph-execute` 直调** — 创建 session 后始终自动 handoff；decision 评估后始终 handoff
+2. **Handoff via `Skill(maestro-ralph-execute)` 直调** — 创建 session 后始终自动 handoff；decision 评估后始终 handoff
 3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
 4. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（详见 invariant 8）
 5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
 6. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
 7. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform codex --json --quiet` 预校验（project 覆盖 global，限定 `.codex/skills/`），命中即写绝对路径到 status.json；未命中标 `command_scope = "missing"`
 8. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成：解析 frontmatter + `<required_reading>` + `<deferred_reading>`，自动读取 required 文件全文并拼入 prompt；缺失 required → 退出码 1（E007），pause session。ralph build 阶段只通过 `maestro ralph skills --platform codex` 校验路径存在性，不读 SKILL.md 内容
-9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 输出提示词后继续 handoff，用户可在执行过程中随时输入 `/goal`
+9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；通过 `create_goal` 绑定目标，`update_goal` 在收敛时释放
 10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 12. **Platform** — `session.platform = "codex"`；CLI 调用一律带 `--platform codex`
 13. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons. Especially invariants about ralph never executing steps and completion_confirmed by CLI.
 14. **Delegate fallback must be marked** — when A_DELEGATE_EVALUATE verdict parse fails and falls back to "fix", MUST record `parse_failed: true, confidence_score: 0` in decisions.ndjson. Subsequent steps inherit LOW CONFIDENCE flag.
-15. **CLI ≠ Skill** — `maestro` CLI binary 只提供结构化子命令（`ralph next|complete|skills|check|session`、`delegate`、`explore`、`search` 等），**不接受裸 intent**。Session 创建、intent 路由、decision 评估均为 skill 层操作：`$maestro-ralph "intent"` 或 `$maestro "intent"`。**严禁** `Bash("maestro \"intent text\"")` — CLI 会报错退出。
+15. **CLI ≠ Skill** — `maestro` CLI binary 只提供结构化子命令（`ralph next|complete|skills|check|session`、`delegate`、`explore`、`search` 等），**不接受裸 intent**。Session 创建、intent 路由、decision 评估均为 skill 层操作：`Skill(maestro-ralph, "intent")` 或 `Skill(maestro, "intent")`。**严禁** `Bash("maestro \"intent text\"")` — CLI 会报错退出。
 </invariants>
 
 <state_machine>
@@ -170,7 +178,7 @@ S_CONFIRM:
   → END             WHEN: user selects "Cancel"
 
 S_DISPATCH:
-  → END             DO: $maestro-ralph-execute
+  → END             DO: Skill(maestro-ralph-execute)
 
 S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取自该字段)
   → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test)
@@ -220,7 +228,7 @@ S_FALLBACK:
 
 ### A_SHOW_STATUS
 
-1. 若 `target_session_id` 提供 → 直接加载 `.workflow/.maestro/{target_session_id}/status.json`；否则取最新 ralph session（by created_at）
+1. 若 `target_session_id` 提供 → 直接加载 `.workflow/.maestro/{target_session_id}/status.json`；否则取最新 session（by created_at，不限 status）
 2. Display: Session, Status, Position, Progress, Current step
 3. List steps: [✓] completion_confirmed, [▸] current, [ ] pending, [◆] decision（`step.decision` 非空）；执行 step 附 `command_scope`(global/project) + `command_path`
 4. If `task_decomposition` present (absent → skip):
@@ -395,7 +403,16 @@ narrow → derive defaults from intent + codebase, skip questions.
 
 **5. Persist** (additive): `boundary_contract`, `execution_criteria`, `task_decomposition`。每个 sub-goal 含 `status: "pending"` + `completion_confirmed: false`。
 
-**6. Stage** the Goal Prompt (Appendix) for A_CREATE_SESSION to emit.
+**6. Register goal** via `create_goal`:
+```
+create_goal({
+  objective: "Ralph {intent} — converge {N} sub-goals within boundary",
+  success_criteria: task_decomposition.map(g => `${g.id}: ${g.done_when}`),
+  constraints: [...execution_criteria,
+    "通过 Skill(maestro-ralph-execute) 推进 step，禁止绕过直接执行 steps[*].skill",
+    "禁止修改 boundary_contract.out_of_scope"]
+})
+```
 
 ### A_BUILD_STEPS
 
@@ -466,7 +483,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
 1. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 + 列出缺失 skill
 2. Write `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json` (Appendix: Session Schema)；含 `platform: "codex"`, `cli_tool: "codex"`
 3. Display chain overview：每步显示 `{index}. {skill} [{type}] [{command_scope}]`
-4. If `task_decomposition` present: display **Goal Prompt block** (Appendix)，不阻塞流程，继续 handoff
+4. If `task_decomposition` present: call `create_goal`（由 A_DECOMPOSE_TASKS 已注册）+ `update_plan`，继续 handoff
 
 ### A_DELEGATE_EVALUATE
 
@@ -663,7 +680,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
    Intent: {session.intent}
    Drift:  {drift_description}
    建议回归: {corrective_action}
-   选项：1) $maestro-ralph continue 忽略漂移继续  2) 手动修正后 continue  3) $maestro-ralph status 查看后决定
+   选项：1) Skill(maestro-ralph, "continue") 忽略漂移继续  2) 手动修正后 continue  3) Skill(maestro-ralph, "status") 查看后决定
    ```
 3. GUARD: auto_confirm 对本动作无效——漂移熔断不可自动跳过
 
@@ -671,7 +688,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 
 1. Set session status = "paused", write status.json
 2. Display: ◆ 已达最大重试次数，debug 已执行。请人工介入。
-3. Display: $maestro-ralph continue 恢复
+3. Display: Skill(maestro-ralph, "continue") 恢复
 
 ### A_AMEND_GOAL
 
@@ -683,7 +700,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 | 2. 解析 | `change_request` 非空 → 直接用；为空 → request_user_input（修改/新增/移除/调整边界） | `change_type` + `change_request` |
 | 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
 | 4. 确认 | request_user_input：应用并继续 / 仅改目标 / 取消 | 用户选择 |
-| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff $maestro-ralph-execute |
+| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff Skill(maestro-ralph-execute) |
 
 GUARD: `RISK_LEVEL == high` → request_user_input 不跳过（auto_confirm 无效）
 GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
@@ -827,17 +844,13 @@ maestro-execute {target_phase}                       [goal_ref: G{n}]
 decision:post-goal-audit {retry+1}
 ```
 
-### Goal Prompt Template
-
-链路概览后逐字显示（仅当 decomposition 已产出）：
+### Goal Management (Codex Built-in)
 
-```
-📋 任务分解完成。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
-
-/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 $maestro-ralph-execute 推进 step；decision 节点由其自动 handoff 回 ralph 评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
-```
+Decomposition 产出后通过 Codex 内置工具管理目标（由 A_DECOMPOSE_TASKS 步骤 6 调用）：
 
-`/goal` 由用户输入；ralph 输出提示词后继续 handoff，不阻塞。
+- `create_goal` — 注册目标 + success_criteria + constraints
+- `update_plan` — 同步 steps[] 进度到 Codex plan 视图
+- `update_goal` — 收敛时释放（A_APPLY_GOAL_DONE / session completed）；abort/pause 时保持（支持 `Skill(maestro-ralph, "continue")` 恢复）
 
 ### Error Codes
 
@@ -879,7 +892,7 @@ decision:post-goal-audit {retry+1}
 - [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
 - [ ] Chain 必须以 `milestone-complete` 结尾
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
-- [ ] Ralph 不执行 step，只 evaluate；`$maestro-ralph-execute` 直调 handoff
+- [ ] Ralph 不执行 step，只 evaluate；`Skill(maestro-ralph-execute)` 直调 handoff
 - [ ] session.platform = "codex"；所有 CLI 调用携带 `--platform codex`
 - [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
 - [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）