maestro-flow-one 0.2.15 → 0.2.17

package/claude/maestro-flow/SKILL.md

@@ -138,6 +138,55 @@ If chain selected: -> Step 4
 
 ---
 
+## Step 3.5: Task Decomposition (broad lifecycle intents)
+
+Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — reference that spec; do not duplicate.
+
+```
+Classify intent breadth:
+  broad   = 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp
+  narrow  = single file/function/bug, "fix X", "add Y to Z"
+  other   = medium
+
+Skip decomposition (-> Step 4 directly) WHEN:
+  narrow intent  OR  single-command chain  OR  chain ∈ {status, init, quick}
+
+Else (broad MUST clarify even if auto_confirm; medium clarify unless auto_confirm):
+  AskUserQuestion ≤3 rounds (options pre-filled from intent + quick Glob/Grep of target module):
+    1. Scope        -> in_scope / out_of_scope
+    2. Constraints  -> constraints + execution_criteria (compat/API/perf/test bar)
+    3. Done         -> definition_of_done
+
+  Derive:
+    execution_criteria  = 3-6 imperative rules every step obeys
+    task_decomposition  = outcome sub-goals; each:
+      { id:"G1", goal, boundary, done_when, evidence, lifecycle:[...], status:"pending" }
+      RULE: done_when objectively verifiable, mapped to a ralph evidence artifact
+            (verification.json | review.json | uat.md | <test path>)
+
+  Write {session_dir}/goal-checklist.md (template below) with ALL_GOALS_DONE sentinel.
+  Stage additive block + goal_checklist_path for Step 4.
+  Emit the /goal bind prompt:
+    📋 任务分解完成。复制下面一行设定目标(推荐)：
+    /goal 当 {session_dir}/goal-checklist.md 子目标全 [x] 且含 ALL_GOALS_DONE 时达成；
+          否则按执行准则继续推进且不越边界契约
+```
+
+**goal-checklist.md template:**
+```markdown
+# Flow Goal Checklist — {session_id}
+> Intent: {intent}
+## 执行准则 / Execution Criteria
+- {criterion}
+## 边界契约 / Boundary Contract
+- In scope / Out of scope / Constraints / Definition of Done
+## 子目标 / Sub-goals
+- [ ] G1: {goal} — done when: {done_when} (evidence: {evidence})
+<!-- executor flips [ ]→[x] when evidence confirms; appends ALL_GOALS_DONE when all [x] -->
+```
+
+---
+
 ## Step 4: Build Session
 
 ### 4.1: Create session from template
@@ -147,8 +196,21 @@ session_id = "flow-{YYYYMMDD-HHmmss}"
 session_dir = .workflow/.maestro/{session_id}/
 
 Build steps[] from selected chain template.
+
+If Step 3.5 produced a decomposition:
+  - Add additive block to status.json (OPTIONAL keys; absent = old behavior;
+    never remove/rename existing fields — status JSON is schema-additive + step-dynamic):
+      boundary_contract, execution_criteria, task_decomposition, goal_checklist_path
+  - Each step gains optional "goal_ref": null
+  - Append a decision step
+      { "cmd":"decision:post-goal-audit", "type":"decision",
+        "decision":"post-goal-audit", "retry_count":0, "max_retries":2 }
+    as the FINAL node — after the last evidence-producing step (verify/review/test),
+    before a milestone-complete/close-out step if the chain ends with one
+    (audit needs evidence artifacts to exist)
+
 Write status.json.
-Display chain steps, confirm (or auto if -y).
+Display chain steps (+ Sub-goals: {n} if decomposed), confirm (or auto if -y).
 ```
 
 Fall through to Phase 2.

package/claude/maestro-flow/chains/templates.json

@@ -25,6 +25,12 @@
       "evaluates": "state.json",
       "verdict_prompt": "检查是否有下一个 milestone",
       "structural": true
+    },
+    "post-goal-audit": {
+      "evaluates": "goal-checklist.md + per-subgoal evidence (verification.json|review.json|uat.md|test path)",
+      "verdict_prompt": "审计子目标: 逐个对照 done_when 判定 met/unmet, 输出 STATUS(all_met|has_unmet) 与 UNMET=[{id,gap,target_phase}]",
+      "fix_loop": ["maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-goal-audit"],
+      "goal_gate": true
     }
   },
   "templates": {

package/claude/maestro-flow/executor.md

@@ -72,7 +72,13 @@ artifact_dir = .workflow/scratch/{artifact.path}/
 Fallback: glob .workflow/scratch/*-P{phase}-*/ sorted by date DESC
 ```
 
-#### 3.3: Structural vs Quality-gate
+#### 3.3: Route by decision class
+
+```
+decision_type == "post-milestone"   -> Structural (evaluate directly)
+decision_type == "post-goal-audit"  -> Goal-gate (audit sub-goals, grow steps)
+otherwise                            -> Quality-gate (delegate analyzer)
+```
 
 **Structural decisions (post-milestone)** -- evaluate directly:
 
@@ -90,6 +96,42 @@ post-milestone:
     -> proceed (mark done, continue)
 ```
 
+**Goal-gate decision (post-goal-audit)** -- shares contract with maestro-ralph `A_GOAL_AUDIT_EVALUATE`:
+
+```
+Read session.task_decomposition + session.goal_checklist_path
+For each sub-goal status != "done": resolve its evidence artifact under {artifact_dir}
+
+Bash({
+  command: `maestro delegate "PURPOSE: 审计子目标达成, 决定是否补充执行步骤
+TASK: 逐个读取未完成子目标 evidence | 对照 done_when 判定 met/unmet | 给出 unmet 差距与 target_phase
+MODE: analysis
+CONTEXT: @{goal_checklist_path} @{evidence files} | 执行准则: {execution_criteria} | 边界: {boundary_contract}
+EXPECTED: ---VERDICT--- STATUS: all_met | has_unmet / UNMET: [{id,gap,target_phase}] ---END---
+CONSTRAINTS: 只评估不修改 | 严格按 done_when | 不越 boundary_contract" --role analyze --mode analysis`,
+  run_in_background: true
+})
+STOP -- wait for callback.
+
+On callback:
+  For each met sub-goal -> set task_decomposition[i].status="done" + flip [ ]→[x] in goal-checklist.md
+  STATUS == all_met:
+    Append line `ALL_GOALS_DONE` to goal-checklist.md
+    Mark decision completed, write status.json
+    -> Step 3.8 (continue; satisfies user /goal Stop hook)
+  STATUS == has_unmet:
+    For each unmet sub-goal G{n} (grouped by target_phase), insert before this decision node:
+      maestro-plan {target_phase} --gaps "G{n}: {gap}"   [internal] [goal_ref: G{n}]
+      maestro-execute {target_phase}                      [external] [goal_ref: G{n}]
+      maestro-verify {target_phase}                       [internal] [goal_ref: G{n}]
+    Re-append: decision:post-goal-audit {retry+1}          [decision]
+    Reindex steps, increment retry_count, write status.json
+    Display: Decision: post-goal-audit -> {k} unmet, +{N} steps inserted (G{ids})
+    -> Step 3.8 (continue)
+  GUARD: retry_count >= max_retries AND still unmet ->
+    insert quality-debug "{unmet gaps}" [internal]; set session.status="paused"; End.
+```
+
 **Quality-gate decisions** -- delegate to external analyzer:
 
 Result file mapping:

package/codex/maestro-flow/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: maestro-flow
-description: Unified workflow command collection — intent routing, minimal closed-loop chain selection, wave-based CSV execution. All 49 maestro commands in one skill.
+description: Unified workflow command collection — intent routing, minimal closed-loop chain selection, sequential direct step execution. All 49 maestro commands in one skill.
 argument-hint: "\"intent\" [-y] [--chain <name>] [--cmd <name> <args>] | list | status | continue | execute"
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>
-Single-entry skill packaging all 49 Maestro workflow commands.
+Single-entry skill packaging all 49 Maestro workflow commands (Codex variant).
 
 Two execution modes:
-1. **Router** (default): Analyze intent -> match chain template -> create session -> wave execution
+1. **Router** (default): Analyze intent -> decompose (broad intents) -> match chain -> create session -> sequential step execution
 2. **Direct** (`--cmd <name> <args>`): Load and execute a specific command inline
 
-Execution uses `spawn_agents_on_csv` for wave-based parallel/sequential step dispatch.
-Commands loaded via `maestro-flow resolve` CLI for path resolution.
+Execution invokes each step DIRECTLY in coordinator context (no agent spawning).
+Step lifecycle managed by `maestro-flow next/done` CLI. Commands loaded via `maestro-flow resolve`.
+Goal tracking via built-in `create_goal` / `update_plan` / `update_goal`.
 
 Session path: `.workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
@@ -24,7 +25,7 @@ $ARGUMENTS -- intent text, flags, or special keywords.
 **Skill directory structure** (relative to this SKILL.md):
 ```
 maestro-flow/
-  SKILL.md              <- this file (router + wave executor)
+  SKILL.md              <- this file (router + sequential executor)
   commands/
     lifecycle/          <- 17 commands: init, analyze, plan, execute, verify, ...
     quality/            <- 7 commands: debug, review, test, auto-test, ...
@@ -45,13 +46,13 @@ maestro-flow/
 </context>
 
 <invariants>
-1. **ALL steps via spawn_agents_on_csv** -- coordinator NEVER executes skill logic directly
-2. **Coordinator = prompt assembler** -- classify -> enrich args -> build CSV -> spawn -> read results -> next wave
-3. **Decision nodes handled by coordinator** -- delegate-evaluate for quality gates, direct for structural
-4. **Barrier = solo wave** -- analyze, plan, execute, brainstorm, roadmap always run alone
-5. **Non-barriers can parallel** -- consecutive non-barrier, non-decision steps grouped into one wave
-6. **Wave-by-wave** -- never start wave N+1 before wave N results are read
-7. **Decision nodes NEVER appear in CSV** -- processed by coordinator between waves
+1. **Steps invoked DIRECTLY in-context** -- coordinator runs `$maestro-flow --cmd <skill> <args>` itself, sequentially. NO spawn_agents_on_csv, NO wave, NO CSV.
+2. **Coordinator owns the loop** -- classify -> decompose -> build -> for each step: resolve args -> invoke -> read result -> persist -> next.
+3. **Decision nodes evaluate, never execute** -- quality-gate via `maestro delegate --role analyze`; goal-gate audits sub-goals; structural evaluated directly.
+4. **Goal is tool-created** -- broad intents call `create_goal` with sub-goal success criteria; `update_goal` on convergence.
+5. **task_decomposition drives DYNAMIC step growth** -- sub-goals are the convergence spec; `steps[]` is a living array. `post-goal-audit` re-checks the checklist and inserts scoped steps for unmet sub-goals.
+6. **Status JSON: schema-additive + step-dynamic** -- decomposition fields OPTIONAL (absent -> old behavior); `steps[]` grown at runtime; `goal_ref` traces dynamically-added steps. Never remove/rename existing fields.
+7. **Sequential execution** -- one step at a time in index order; each step's result read before the next starts.
 </invariants>
 
 <execution>
@@ -65,22 +66,12 @@ Parse $ARGUMENTS:
     -> Step 1a: Direct Command Execution
     -> End.
 
-  list
-    -> Bash: maestro-flow list
-    -> End.
-
-  status [session-id]
-    -> Bash: maestro-flow status [session-id]
-    -> End.
-
-  chains
-    -> Bash: maestro-flow chains
-    -> End.
+  list      -> Bash: maestro-flow list. End.
+  status [session-id] -> Bash: maestro-flow status [session-id]. End.
+  chains    -> Bash: maestro-flow chains. End.
 
   execute | continue
-    -> Find latest running flow session
-    -> If not found: "No running flow session." End.
-    -> Phase 2 (Wave Execution Loop)
+    -> Phase 2 (Sequential Execution Loop)
 
   --chain <name> [-y] <remaining>
     -> Force chain selection (skip intent analysis), go to Step 4
@@ -94,20 +85,14 @@ Parse $ARGUMENTS:
 
 ### Step 1a: Direct Command Execution (--cmd)
 
-Entry point for delegate sessions and single-command execution.
+Entry point for single-command execution.
 
 ```
-1. Bash: maestro-flow resolve <name>
-   -> Returns absolute path to command .md file
-
+1. Bash: maestro-flow resolve <name>   -> absolute path to command .md
 2. If NOT_FOUND -> Error. End.
-
 3. Read() the command .md file
-
 4. Set $ARGUMENTS = <remaining-args>
-
 5. Follow the command's <execution> section completely
-
 End.
 ```
 
@@ -124,15 +109,62 @@ If not: state_summary = "Project not initialized"
 ## Step 3: Intent Analysis & Chain Matching
 
 ```
-Bash: maestro-flow suggest "{intent}"
--> Parse output for suggested chains
-
-Display top 3 chain options to user
+Bash: maestro-flow suggest "{intent}"  -> parse suggested chains
+Display top 3 chain options
 AskUserQuestion: select chain / single command / Cancel
 
 If auto_confirm: pick highest scoring chain
 If single command: --cmd -> Step 1a
-If chain selected: -> Step 4
+If chain selected: -> Step 3.5
+```
+
+---
+
+## Step 3.5: Task Decomposition (broad lifecycle intents)
+
+Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — reference that spec; do not duplicate.
+
+```
+Classify intent breadth:
+  broad   = 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp
+  narrow  = single file/function/bug, "fix X", "add Y to Z"
+  other   = medium
+
+Skip decomposition (-> Step 4 directly) WHEN:
+  narrow intent  OR  single-command chain  OR  chain ∈ {status, init, quick}
+
+Else (broad MUST clarify even if auto_confirm; medium clarify unless auto_confirm):
+  AskUserQuestion ≤3 rounds (options pre-filled from intent + quick Glob/Grep of target module):
+    1. Scope        -> in_scope / out_of_scope
+    2. Constraints  -> constraints + execution_criteria (compat/API/perf/test bar)
+    3. Done         -> definition_of_done
+
+  Derive:
+    execution_criteria  = 3-6 imperative rules every step obeys
+    task_decomposition  = outcome sub-goals; each:
+      { id:"G1", goal, boundary, done_when, evidence, lifecycle:[...], status:"pending" }
+      RULE: done_when objectively verifiable, mapped to a ralph evidence artifact
+            (verification.json | review.json | uat.md | <test path>)
+
+  Write {session_dir}/goal-checklist.md (template below) with ALL_GOALS_DONE sentinel.
+  Register goal via built-in tool:
+    create_goal({ objective: "Flow {chain}: {intent} — converge {N} sub-goals within boundary",
+      success_criteria: task_decomposition.map(g => `${g.id}: ${g.done_when}`),
+      constraints: [...execution_criteria, "stay within boundary_contract"] })
+  Stage additive block + goal_checklist_path for Step 4.
+```
+
+**goal-checklist.md template:**
+```markdown
+# Flow Goal Checklist — {session_id}
+> Intent: {intent}
+## 执行准则 / Execution Criteria
+- {criterion}
+## 边界契约 / Boundary Contract
+- In scope / Out of scope / Constraints / Definition of Done
+## 子目标 / Sub-goals
+- [ ] G1: {goal} — done when: {done_when} (evidence: {evidence})
+<!-- executor flips [ ]→[x] when evidence confirms; appends ALL_GOALS_DONE when all [x] -->
 ```
 
 ---
@@ -142,11 +174,9 @@ If chain selected: -> Step 4
 ### 4.1: Load template & build steps
 
 ```
-Bash: maestro-flow chain {template_name}
--> Parse step list
-
-Build session steps[] from template.
-Decision steps get extra fields: decision, retry_count, max_retries
+Bash: maestro-flow chain {template_name}  -> parse step list
+Build session steps[] from template. Each step type ∈ {internal, external, decision}.
+Decision steps get extra fields: decision, retry_count, max_retries.
 ```
 
 ### 4.2: Create session
@@ -157,25 +187,31 @@ session_dir = .workflow/.maestro/{session_id}/
 
 Write {session_dir}/status.json:
 {
-  "session_id": "{session_id}",
-  "source": "flow",
+  "session_id": "{session_id}", "source": "flow",
   "created_at": "{ISO}", "updated_at": "{ISO}",
-  "intent": "{intent}",
-  "status": "running",
-  "chain_name": "{template_name}",
-  "task_type": "{category}",
-  "phase": {phase},
-  "milestone": "{current_milestone}",
-  "auto_mode": {auto_confirm},
-  "quality_mode": "standard",
-  "passed_gates": [],
-  "context": {
-    "scratch_dir": null, "plan_dir": null, "analysis_dir": null
-  },
-  "steps": [...],
-  "waves": [],
-  "current_step": 0
+  "intent": "{intent}", "status": "running",
+  "chain_name": "{template_name}", "task_type": "{category}",
+  "phase": {phase}, "milestone": "{current_milestone}",
+  "auto_mode": {auto_confirm}, "quality_mode": "standard", "passed_gates": [],
+  "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null },
+  "steps": [ { ..., "goal_ref": null } ],
+  "waves": [], "current_step": 0,
+
+  "_comment": "↓ OPTIONAL additive block — present only if Step 3.5 ran; absent = flat-chain behavior",
+  "boundary_contract": {}, "execution_criteria": [], "task_decomposition": [], "goal_checklist_path": ""
 }
+
+If Step 3.5 produced a decomposition:
+  - Fill the additive block (never remove/rename existing fields)
+  - Append a decision step
+      { "cmd":"decision:post-goal-audit", "type":"decision",
+        "decision":"post-goal-audit", "retry_count":0, "max_retries":2 }
+    as the FINAL node — after the last evidence-producing step (verify/review/test),
+    before a milestone-complete/close-out step if the chain ends with one
+  - update_plan({ plan: steps.map(s => ({ step: s.cmd, status: "pending" })) })
+Else:
+  - create_goal({ objective: "Flow {chain}: {N} steps" })
+  - update_plan({ plan: steps.map(s => ({ step: s.cmd, status: "pending" })) })
 ```
 
 ### 4.3: Display + confirm
@@ -185,13 +221,13 @@ Write {session_dir}/status.json:
   MAESTRO FLOW SESSION
 ============================================================
   Session:  {session_id}
-  Chain:    {chain_name} ({total} steps)
+  Chain:    {chain_name} ({total} steps)   Sub-goals: {n if decomposed}
   Phase:    {phase}
 
-  [ ] 0. maestro-plan {phase}                [barrier]
-  [ ] 1. maestro-execute {phase}             [barrier]
+  [ ] 0. maestro-plan {phase}
+  [ ] 1. maestro-execute {phase}
   [ ] 2. maestro-verify {phase}
-  [ ] 3. * post-verify                       [decision]
+  [ ] 3. > post-goal-audit                   [decision]
   ...
 ============================================================
 
@@ -203,27 +239,46 @@ Fall through to Phase 2.
 
 ---
 
-## Phase 2: Wave Execution Loop
+## Phase 2: Sequential Execution Loop
 
-### 2.1: Load session + find next step
+Core loop: `maestro-flow next` -> route by type -> execute directly -> `maestro-flow done` -> self-invoke.
 
-Read status.json. Find first pending step.
+### 2.1: Load next step
 
-- If decision node -> Step 2.2 (Decision Evaluation)
-- If non-decision -> Step 2.3 (Wave Execution)
-- If no pending -> Phase 3 (Completion)
+```
+Bash: maestro-flow next [session-id]
+Parse:
+  "NO_SESSION"       -> "No running flow session." End.
+  "SESSION_COMPLETE" -> Phase 3.
+  Else:
+    STEP / TYPE / SKILL / ARGS
+    DECISION / RETRY        (decision only)
+    PATH                    (internal/external only)
+    ---COMMAND--- + content (internal/external only)
 
-### 2.2: Decision Evaluation
+Display banner: [{idx}/{total}] {SKILL} [{TYPE}]  Args: {ARGS}
 
-**Route by decision type:**
-- Quality-gate decisions (post-verify, post-business-test, post-review, post-test) -> delegate analysis
-- Structural decisions (post-milestone) -> direct evaluation
+Route:
+  TYPE == "decision"  -> Step 2.2
+  TYPE == "internal"  -> Step 2.3 (direct)
+  TYPE == "external"  -> Step 2.4 (direct)
+```
 
-#### 2.2a: Delegate quality-gate assessment
+### 2.2: Decision Evaluation
 
 ```
-Read decision metadata: { decision, retry_count, max_retries }
+Route by decision class:
+  decision == "post-milestone"   -> Structural (2.2d)
+  decision == "post-goal-audit"  -> Goal-gate (2.2g)
+  otherwise                       -> Quality-gate (2.2a)
+```
+
+Resolve `artifact_dir`: read state.json, filter artifacts by session.milestone+phase, latest;
+fallback glob `.workflow/scratch/*-P{phase}-*/`.
 
+#### 2.2a: Quality-gate delegate assessment
+
+```
 Result file mapping:
   post-verify         -> {artifact_dir}/verification.json
   post-business-test  -> {artifact_dir}/business-test-results.json
@@ -232,7 +287,7 @@ Result file mapping:
 
 Bash({
   command: `maestro delegate "PURPOSE: evaluate ${decision} quality gate
-TASK: read result files | analyze pass/fail | assess severity | recommend next step
+TASK: read result files | analyze pass/fail | assess severity | recommend
 MODE: analysis
 CONTEXT: @${result_files}
 EXPECTED:
@@ -246,211 +301,126 @@ CONSTRAINTS: evaluate only | retry ${retry_count}/${max_retries}" --role analyze
   run_in_background: true
 })
 STOP -- wait for callback.
-```
-
-#### 2.2b: Parse verdict & apply
-
-```
-On callback: maestro delegate output <exec_id>
-Extract STATUS / REASON / GAP_SUMMARY / CONFIDENCE
-If parse fails -> fallback: STATUS = "fix"
 
-Verdict actions:
-  proceed   -> add gate to passed_gates[], mark decision completed, continue
-  fix       -> clear passed_gates[], insert fix-loop steps, continue
-  escalate  -> session status = "paused". End.
+On callback: maestro delegate output <exec_id> -> extract STATUS/REASON/GAP_SUMMARY/CONFIDENCE
+If parse fails -> fallback STATUS = "fix"
 
-Interactive (non-auto): AskUserQuestion before applying
-Auto (-y): follow verdict directly
+Verdict:
+  proceed   -> add gate to passed_gates[], mark decision completed
+  fix       -> clear passed_gates[], insert fix-loop (2.2c)
+  escalate  -> session.status = "paused". End.
+Interactive (non-auto): AskUserQuestion before applying. Auto (-y): follow directly.
 ```
 
 #### 2.2c: Fix-loop templates
 
-When verdict == "fix", insert fix-loop after current position:
-
-**post-verify:**  quality-debug -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify {retry+1}
-**post-review:**  quality-debug -> maestro-plan --gaps -> maestro-execute -> quality-review -> decision:post-review {retry+1}
-**post-test:**    quality-debug -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify -> quality-test -> decision:post-test {retry+1}
-**post-business-test:** quality-debug -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify -> quality-auto-test -> decision:post-business-test {retry+1}
+When verdict == "fix", insert after current position, reindex:
 
-Insert, reindex, write status.json, continue to 2.3.
+- **post-verify:** quality-debug -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify {retry+1}
+- **post-review:** quality-debug -> maestro-plan --gaps -> maestro-execute -> quality-review -> decision:post-review {retry+1}
+- **post-test:** quality-debug --from-uat -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify {0} -> quality-test -> decision:post-test {retry+1}
+- **post-business-test:** quality-debug --from-business-test -> maestro-plan --gaps -> maestro-execute -> maestro-verify -> decision:post-verify {0} -> quality-auto-test -> decision:post-business-test {retry+1}
 
-#### 2.2d: Structural decisions
+#### 2.2d: Structural (post-milestone)
 
-**post-milestone:**
 ```
-Read .workflow/state.json -> check next milestone
-If found: update session, insert lifecycle steps for next milestone
-If none: proceed, session completes naturally
+Read state.json -> next milestone (pending/active)?
+If found: update session (milestone, phase, reset passed_gates), insert lifecycle steps, reindex
+If none: proceed (session completes naturally)
 ```
 
-#### 2.2e: Finalize decision
+#### 2.2g: Goal-gate (post-goal-audit)
 
-```
-Mark decision step "completed"
-Write status.json
+Shares contract with maestro-ralph `A_GOAL_AUDIT_EVALUATE`.
 
-STOP behavior:
-  auto_mode == true  -> no STOP, continue to 2.3
-  auto_mode == false -> STOP. Display: "Use $maestro-flow execute to continue"
 ```
+Read session.task_decomposition + goal_checklist_path
+For each sub-goal status != "done": resolve its evidence artifact under {artifact_dir}
 
-### 2.3: Build and Execute Wave
-
-**Loop while pending non-decision steps exist:**
-
-#### 1. buildNextWave
+Bash({
+  command: `maestro delegate "PURPOSE: 审计子目标达成, 决定是否补充执行步骤
+TASK: 逐个读取未完成子目标 evidence | 对照 done_when 判定 met/unmet | 给出 unmet 差距与 target_phase
+MODE: analysis
+CONTEXT: @{goal_checklist_path} @{evidence files} | 执行准则: {execution_criteria} | 边界: {boundary_contract}
+EXPECTED: ---VERDICT--- STATUS: all_met | has_unmet / UNMET: [{id,gap,target_phase}] ---END---
+CONSTRAINTS: 只评估不修改 | 严格按 done_when | 不越 boundary_contract" --role analyze --mode analysis`,
+  run_in_background: true
+})
+STOP -- wait for callback.
 
+On callback:
+  For each met sub-goal -> task_decomposition[i].status="done" + flip [ ]→[x] in goal-checklist.md
+  STATUS == all_met:
+    Append `ALL_GOALS_DONE` to goal-checklist.md
+    Set all task_decomposition[*].status="done"; update_goal({ status:"complete" })
+    Mark decision completed, write status.json -> 2.2e
+  STATUS == has_unmet:
+    For each unmet G{n} (grouped by target_phase), insert before this decision node:
+      maestro-plan {target_phase} --gaps "G{n}: {gap}"   [internal] [goal_ref: G{n}]
+      maestro-execute {target_phase}                      [external] [goal_ref: G{n}]
+      maestro-verify {target_phase}                       [internal] [goal_ref: G{n}]
+    Re-append: decision:post-goal-audit {retry+1}          [decision]
+    Reindex, increment retry_count, write status.json + update_plan -> 2.2e
+  GUARD: retry_count >= max_retries AND still unmet ->
+    insert quality-debug "{unmet gaps}" [internal]; session.status="paused"; End.
 ```
-Scan pending steps from current position:
-  - Barrier step (analyze, plan, execute, brainstorm, roadmap)
-    -> solo wave (single row CSV)
-  - Non-barrier step
-    -> collect consecutive non-barrier, non-decision steps (multi-row CSV)
-  - Stop at first decision node
-```
-
-**Barrier list:**
-
-| Command | Barrier |
-|---------|---------|
-| maestro-analyze | yes |
-| maestro-plan | yes |
-| maestro-execute | yes |
-| maestro-brainstorm | yes |
-| maestro-roadmap | yes |
-| All others | no |
 
-#### 2. buildSkillCall(step, session)
-
-Assemble fully-resolved command for CSV:
+#### 2.2e: Finalize decision
 
-**Placeholder resolution:**
 ```
-{phase}        -> session.phase
-{intent}       -> session.intent
-{scratch_dir}  -> session.context.scratch_dir or latest artifact path
-{plan_dir}     -> session.context.plan_dir
-{analysis_dir} -> session.context.analysis_dir
+Mark decision step "completed"; write status.json
+Bash: maestro-flow done  -> Skill({ skill: "maestro-flow", args: "execute" })  End.
+(auto_mode == false on quality-gate: STOP first, display "Use $maestro-flow execute to continue")
 ```
 
-**Per-skill enrichment:**
-
-| Skill | Enrichment |
-|-------|-----------|
-| maestro-brainstorm | args empty -> `"{intent}"` |
-| maestro-roadmap | args empty -> `"{intent}"` |
-| maestro-analyze | args empty -> `{phase}` |
-| maestro-plan | resolve latest analyze artifact -> `--dir .workflow/scratch/{path}` |
-| maestro-execute | resolve latest plan artifact -> `--dir .workflow/scratch/{path}` |
-| quality-debug | append gap_summary context |
-| quality-* / maestro-verify / milestone-* | args empty -> `{phase}` or empty |
-
-**Auto flag propagation (if auto_mode == true):**
-
-| Skill | Flag |
-|-------|------|
-| maestro-init | -y |
-| maestro-analyze | -y |
-| maestro-brainstorm | -y |
-| maestro-roadmap | -y |
-| maestro-plan | -y |
-| maestro-execute | -y |
-| quality-auto-test | -y |
-| quality-test | -y --auto-fix |
-| maestro-milestone-complete | -y |
-
-Result: `$maestro-flow --cmd <skill-name> <enriched-args> [auto-flag]`
-
-#### 3. Write wave CSV
+### 2.3: Internal Execution (direct)
 
 ```
-Write {sessionDir}/wave-{N}.csv:
-
-id,skill_call,topic
-"0","$maestro-flow --cmd maestro-plan 1 -y","Flow step 0/8: plan phase 1"
-"1","$maestro-flow --cmd maestro-execute 1 -y","Flow step 1/8: execute phase 1"
+Command content already in context (after ---COMMAND--- from `maestro-flow next`).
+Set $ARGUMENTS = ARGS. Apply auto-flag if session.auto_mode (table below).
+Follow the command's <execution> section completely (respect its required/deferred reading).
+On success -> 2.5. On failure -> 2.6.
 ```
 
-Rules:
-- `skill_call`: `$maestro-flow --cmd <skill> <args>` (routes through this skill's --cmd)
-- `topic`: human-readable step description
-- Non-barrier + non-decision -> multi-row (parallel)
-- Barrier -> single-row (solo)
-- Decision nodes NEVER appear in CSV
-
-#### 4. Spawn
+### 2.4: External Execution (direct)
 
 ```
-spawn_agents_on_csv({
-  csv_path: "{sessionDir}/wave-{N}.csv",
-  id_column: "id",
-  instruction: WAVE_INSTRUCTION,
-  max_workers: <wave_size>,
-  max_runtime_seconds: 3600,
-  output_csv_path: "{sessionDir}/wave-{N}-results.csv",
-  output_schema: RESULT_SCHEMA
-})
+External steps run in coordinator context too (no spawn). Append -y.
+Invoke directly: follow `$maestro-flow --cmd {SKILL} {ARGS} -y` — i.e., resolve the
+command .md (already provided after ---COMMAND---) and follow its <execution> completely.
+On success -> 2.5. On failure -> 2.6.
 ```
 
-**Sub-Agent Instruction:**
-```
-You are a CSV job sub-agent in a maestro-flow pipeline.
+**Auto flag propagation (session.auto_mode == true):**
 
-Execute the skill call: {skill_call}
-Task: {topic}
+| Skill | Flag |
+|-------|------|
+| maestro-init / maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-plan / maestro-execute / quality-auto-test / maestro-milestone-complete | -y |
+| quality-test | -y --auto-fix |
+| (all others) | (none) |
 
-Rules:
-- Do NOT modify .workflow/.maestro/ status files
-- The skill has its own session management
-- Execute the command completely
+### 2.5: Mark Done & Advance
 
-Report result:
-{"status":"completed|failed","skill_call":"{skill_call}","summary":"one-line result","artifacts":"artifact paths","error":"failure reason"}
 ```
+Bash: maestro-flow done [session-id]
+Parse:
+  "COMPLETED: {idx} {skill}" / "NEXT: ..." -> Skill({ skill: "maestro-flow", args: "execute" }) End.
+  "SESSION_COMPLETE" -> Phase 3.
 
-**Result Schema:** `{ status, skill_call, summary, artifacts, error }` -- all string
-
-#### 5. Read results & update
-
-```
-Read wave-{N}-results.csv
-For each result row:
-  Match to step by id
-  If status == "completed":
-    step.status = "completed"
-    step.completed_at = now
-  If status == "failed":
-    step.status = "failed"
-    step.error = result.error
+Context propagation (after a context-producing skill): read its artifacts, update
+session.context (analyze->analysis_dir, plan->plan_dir, execute->scratch_dir,
+brainstorm->brainstorm_dir, roadmap->spec_session_id); write status.json.
 ```
 
-#### 6. Barrier context update
-
-After barrier wave completes, read outputs and update session context:
-
-| Barrier | Read | Update |
-|---------|------|--------|
-| maestro-analyze | context.md, state.json | context.analysis_dir |
-| maestro-plan | plan.json | context.plan_dir |
-| maestro-execute | results | context.scratch_dir |
-| maestro-brainstorm | .brainstorming/ | context.brainstorm_dir |
-| maestro-roadmap | specs/ | context.spec_session_id |
-
-#### 7. Persist & continue
+### 2.6: Handle Failure
 
 ```
-Write status.json
-Record wave in session.waves[]
-
-Failure check:
-  -y: retry once, then skip and continue
-  non-y: mark remaining skipped, pause, STOP
-
-Next step check:
-  Decision node -> loop to 2.2
-  More external steps -> loop to 2.3 step 1
-  No pending -> Phase 3
+Bash: maestro-flow step {session_id} {idx} failed
+Auto mode:
+  not retried -> step ... pending -> Skill({ skill:"maestro-flow", args:"execute" })  (retry once)
+  retried     -> step ... skipped -> Skill({ skill:"maestro-flow", args:"execute" })  (continue)
+Interactive: AskUserQuestion retry / skip / abort
+  abort -> session.status = "paused". End.
 ```
 
 ---
@@ -458,45 +428,28 @@ Next step check:
 ## Phase 3: Completion
 
 ```
-session.status = "completed"
-Write status.json
+session.status = "completed"; write status.json
+update_plan: all steps -> "completed"
+update_goal({ status: "complete" })   (idempotent if released by 2.2g)
 
 Display:
 ============================================================
   FLOW COMPLETE
 ============================================================
   Session:  {session_id}
-  Chain:    {chain_name}
-  Phase:    {phase}
-  Waves:    {wave_count} executed
-  Steps:    {completed}/{total} ({skipped} skipped)
-
-  [+] 0. maestro-plan 1            [W1]
-  [+] 1. maestro-execute 1         [W2]
-  [+] 2. maestro-verify 1          [W3]
-  [+] 3. * post-verify -> proceed  [decision]
-  [~] 4. quality-auto-test 1       [skipped]
-  [+] 5. quality-review 1          [W4]
+  Chain:    {chain_name}   Steps: {completed}/{total} ({skipped} skipped)
+  Sub-goals: {done}/{total}
+
+  [+] 0. maestro-plan 1
+  [+] 1. maestro-execute 1
+  [+] 2. maestro-verify 1
+  [+] 3. > post-goal-audit -> all_met  [decision]
   ...
 ============================================================
 ```
 
 </execution>
 
-<csv_schema>
-### wave-{N}.csv
-
-```csv
-id,skill_call,topic
-"0","$maestro-flow --cmd maestro-verify 1","Flow step 2/8: verify phase 1"
-"1","$maestro-flow --cmd quality-review 1","Flow step 3/8: review phase 1"
-```
-
-### Result Schema
-
-`{ status, skill_call, summary, artifacts, error }` -- all string
-</csv_schema>
-
 <error_codes>
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
@@ -504,20 +457,21 @@ id,skill_call,topic
 | E002 | error | Command not found for --cmd | maestro-flow list |
 | E003 | error | No matching chain template | maestro-flow chains |
 | E004 | error | Delegate verdict parse failed | Fallback: treat as "fix" |
-| E005 | error | Wave timeout | Mark step failed, pause |
-| W001 | warning | Multiple chains match equally | Show top 3 |
+| E005 | error | Step execution failed | auto: retry once then skip; interactive: ask |
 </error_codes>
 
 <success_criteria>
 - [ ] --cmd resolves via maestro-flow CLI, executes command inline
 - [ ] list/status/chains/suggest route to maestro-flow CLI
-- [ ] Intent analysis -> chain matching -> session creation
-- [ ] Wave execution via spawn_agents_on_csv with CSV skill_call format
-- [ ] Barrier steps solo wave, non-barriers parallel
-- [ ] Decision nodes evaluated between waves (never in CSV)
-- [ ] Quality-gate decisions delegate-evaluated, structural evaluated directly
-- [ ] Fix-loop insertion + reindex on "fix" verdict
-- [ ] passed_gates tracking, retry_count enforcement
-- [ ] Context propagation after barrier waves
+- [ ] Intent analysis -> decomposition (broad) -> chain matching -> session creation
+- [ ] Broad intents decomposed (≤3 boundary questions); goal registered via create_goal
+- [ ] status.json schema-additive (decomposition fields optional) + step-dynamic (steps[] grows)
+- [ ] post-goal-audit appended as final node; unmet sub-goals grow steps[] (goal_ref tagged)
+- [ ] Steps invoked DIRECTLY in-context — NO spawn_agents_on_csv, NO wave/CSV
+- [ ] Sequential execution; status.json + update_plan persisted after every step/decision
+- [ ] Quality-gate delegate-evaluated; goal-gate audits sub-goals; structural direct
+- [ ] Fix-loop / goal-fix insertion + reindex; passed_gates + retry_count enforced
+- [ ] Context propagation after context-producing skills
+- [ ] update_goal released on convergence (2.2g / Phase 3); held while paused
 - [ ] Auto mode: skip confirmation, auto-follow verdicts, retry+skip on failure
 </success_criteria>

package/codex/maestro-flow/chains/templates.json

@@ -25,6 +25,12 @@
       "evaluates": "state.json",
       "verdict_prompt": "检查是否有下一个 milestone",
       "structural": true
+    },
+    "post-goal-audit": {
+      "evaluates": "goal-checklist.md + per-subgoal evidence (verification.json|review.json|uat.md|test path)",
+      "verdict_prompt": "审计子目标: 逐个对照 done_when 判定 met/unmet, 输出 STATUS(all_met|has_unmet) 与 UNMET=[{id,gap,target_phase}]",
+      "fix_loop": ["maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-goal-audit"],
+      "goal_gate": true
     }
   },
   "templates": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"