maestro-flow 0.5.36 → 0.5.38

package/workflows/integration-test.md

@@ -30,6 +30,7 @@ If existing session at `${PHASE_DIR}/.tests/integration/state.json`: offer resum
 ### Step 1.3: Load Project Specs
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_content = maestro spec load --category test
 arch_content = maestro spec load --category arch
 ```

package/workflows/issue-discover.md

@@ -178,9 +178,9 @@ Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
 ### Step 9: Gather Codebase Context
 
 ```
-Per dimension:
-  1. Semantic search via {search_tool}(query="{dimension.description}")
-  2. Pattern search via rg for each dimension.search_patterns
+Per dimension (prefer maestro explore over rg):
+  1. maestro explore "{dimension.description}" per dimension, parallel
+  2. Fallback: Semantic search via {search_tool} + rg for dimension.search_patterns
   3. Collect matching files/snippets → {SESSION_ID}/{dimension.name}-context.md
 ```
 
@@ -189,7 +189,7 @@ Per dimension:
 ```
 Up to 3 rounds (exit early if no new gaps/findings):
   Round 1: Analyze context → identify issues + coverage gaps
-  Round 2: Refine patterns for gaps → search adjacent files → merge findings
+  Round 2: maestro explore for gap patterns → search adjacent files → merge findings
   Round 3: Final sweep on uncovered high-severity patterns + cross-module interactions
 
 Log per round → {SESSION_ID}/exploration-log.md:

package/workflows/issue-gaps-analyze.codex.md

@@ -58,7 +58,7 @@ id,title,description,iss_id,group_id,group_label,deps,context_from,wave,status,f
 **Wave 1 rows** — one per issue:
 
 ```csv
-"1","Explore: ISS-xxx {title}","Root cause exploration for ISS-xxx: {description}. Location: {location}. Severity: {severity}. Fix hint: {fix_direction}. Search keywords: {keywords from title+description+components}. TASK: grep keywords → read top matches → trace call chain → identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix. EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }. CONSTRAINTS: Evidence-only, use file reads to verify.","ISS-xxx","G1","src/auth","","","1","","","",""
+"1","Explore: ISS-xxx {title}","Root cause exploration for ISS-xxx: {description}. Location: {location}. Severity: {severity}. Fix hint: {fix_direction}. Search keywords: {keywords from title+description+components}. TASK: maestro explore keywords (preferred) or grep keywords → read top matches → trace call chain → identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix. EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }. CONSTRAINTS: Evidence-only, use file reads to verify.","ISS-xxx","G1","src/auth","","","1","","","",""
 ```
 
 **Wave 2 rows** — one per group:
@@ -94,6 +94,7 @@ Write `tasks.csv` to session folder.
 Filter `wave == 1 && status == pending`. Write `wave-1.csv`.
 
 ```javascript
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
@@ -121,6 +122,7 @@ Merge results into master `tasks.csv`, delete `wave-1.csv`.
 Filter `wave == 2 && status == pending`. Build `prev_context` from wave 1 findings of issues in same group. Write `wave-2.csv` with `prev_context` column.
 
 ```javascript
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-2.csv`,
   id_column: "id",

package/workflows/issue-gaps-analyze.md

@@ -68,10 +68,9 @@ For each group:
   Merge keywords from all issues in group: title, description, location, affected_components.
   Deduplicate keywords.
 
-  Standard depth: grep keywords in source files → top 20 paths, read 10 lines around
-    top 5 matches.
-  Deep depth: standard grep + semantic Agent search (error handling, data flow, deps),
-    merge results.
+  Standard depth: maestro explore per group (keywords as prompt), fallback grep; flag analysis as [LOW CONFIDENCE] (grep fallback, semantic depth lost).
+  Deep depth: maestro explore multi-prompt + semantic Agent search (error handling,
+    data flow, deps), merge results.
 
   Build GROUP_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
   Shared context benefits co-located issues — avoids redundant exploration.
@@ -82,7 +81,7 @@ For each group:
 ### Step 4: Run Analysis (per group, parallel across groups)
 
 ```
-Launch analysis for each group in parallel using Agent tool:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Launch analysis for each group in parallel using Agent tool:
 
   Agent({
     subagent_type: "general-purpose",
@@ -98,10 +97,10 @@ Launch analysis for each group in parallel using Agent tool:
 
 Alternatively, attempt CLI delegate first per group:
 
-  maestro delegate "<same prompt>" --role analyze --mode analysis
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: maestro delegate "<same prompt>" --role analyze --mode analysis
 
   If delegate fails (timeout, unavailable, parse error):
-    Fall back to Agent tool with same prompt.
+    Fall back to Agent tool with same prompt; set analysis confidence=low and flag as [LOW CONFIDENCE] (delegate failed).
     Record fallback in analysis metadata: { tool: "agent-fallback", reason: "<error>" }
 
 Validate response per issue: all required fields present.

package/workflows/issue-plan.md

@@ -47,7 +47,7 @@ Otherwise ANALYSIS_CONTEXT = "" (proceed without).
 ```
 Delegate planning prompt with issue details + ANALYSIS_CONTEXT:
 
-  maestro delegate "Generate step-by-step solution for {ISS-ID}: {ISSUE.title}
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: maestro delegate "Generate step-by-step solution for {ISS-ID}: {ISSUE.title}
   ISSUE: title, description, severity, location, fix_direction
   {ANALYSIS_CONTEXT}
   TASK: Break into atomic steps with action types (create|modify|delete|test)

package/workflows/knowhow.md

@@ -69,7 +69,13 @@ Full-text search across both stores. Rank: exact match > heading > content.
 
 ### Step 5-9: View, Edit, Delete, Prune, Integrity Check
 
-Same logic as before. Workflow entries managed via WikiWriter; system entries via direct file ops.
+MANDATORY: execute View/Edit/Delete/Prune/Integrity-Check logic per spec; REQUIRED produce: per-step result + final store-consistency report; BLOCKED if any step's produce missing.
+
+- **View**: Workflow `maestro wiki get <slug>`, System Read file; BLOCKED if entry not found.
+- **Edit**: System store only, direct file edit preserving frontmatter; BLOCKED if frontmatter schema invalid after edit.
+- **Delete**: Workflow `maestro wiki delete <slug>`, System mv to `.workflow/.trash/`; REQUIRED produce backup; BLOCKED if backup missing.
+- **Prune**: Scan `status=deprecated|superseded` entries, list candidates, delete after confirm; REQUIRED produce prune report; BLOCKED if delete without backup.
+- **Integrity Check**: Workflow verify `wiki-index.json` matches disk, System verify MEMORY.md links; REQUIRED produce report {missing[], stale[]}; BLOCKED if missing>0.
 
 ---
 

package/workflows/knowledge-audit.md

@@ -350,5 +350,5 @@ Next:
 4. **Double confirmation** — `--purge` 需 flag + 交互输入 artifact id 双重确认
 5. **Rescue before delete** — 删 artifact 前若 harvest-log 无记录，强制提示先跑 `/manage-harvest`
 6. **No dedup re-run** — audit 不做"是否重复"判断（harvest 负责），只做"是否矛盾/失效/老化"
-7. **Graceful degradation** — LLM detector 不可用时跳过 B/G 类语义场景，A/D/F 类正则+图算法仍可执行
+7. **Graceful degradation** — LLM detector 不可用时跳过 B/G 类语义场景，A/D/F 类正则+图算法仍可执行; Stage 8 报告加 partial_audit: true, skipped: [B,G] 并标 [LOW CONFIDENCE]
 8. **Idempotent** — 同一存储状态下重跑 `--dry-run` 必须输出一致的 finding 集

package/workflows/maestro-super.md

@@ -6,7 +6,7 @@ Super mode implies `-y` (all auto flags propagated) plus these additional behavi
 
 ## 1. Requirement Expansion
 
-On receiving user intent, autonomously expand incomplete requirements into a complete product scope. Delegate via role (`maestro delegate --role analyze --mode analysis`) for requirement completeness analysis and gap-filling. Accept requirements that add real user value; discard noise.
+On receiving user intent, autonomously expand incomplete requirements into a complete product scope. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Delegate via role (`maestro delegate --role analyze --mode analysis`) for requirement completeness analysis and gap-filling. Accept requirements that add real user value; discard noise.
 
 ## 2. Progressive Document Loading
 
@@ -14,7 +14,7 @@ Read execution documents (workflow maestro.md, chain steps) incrementally per-ph
 
 ## 3. Autonomous Decision-Making
 
-All design/architecture/scope decisions are made via Gemini delegate (`--mode analysis`). No AskUserQuestion calls. Decision criteria: mainstream industry standards, pragmatism, simplicity.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: All design/architecture/scope decisions are made via Gemini delegate (`--mode analysis`). No AskUserQuestion calls. Decision criteria: mainstream industry standards, pragmatism, simplicity.
 
 ## 4. Auto-Advance Milestones
 

package/workflows/maestro.md

@@ -1,7 +1,7 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Builds a `ralph_protocol_version: "1"` session: every executable step carries `skill,args,stage,scope,command_scope,command_path`; every cross-step gate is a `step.decision` node. All execution dispatched to unified executor (`maestro-ralph-execute`); the command body (`.claude/commands/maestro.md`) owns session build + dispatch. `--exec` is legacy input only — recorded to `legacy_options.exec_mode`, never changes execution. This brain is consumed for **classification only** (intent → task_type → chain); it does NOT prescribe execution semantics.
+Builds a `ralph_protocol_version: "2"` session: every executable step carries `skill,args,stage,scope,command_scope,command_path`; every cross-step gate is a `step.decision` node. All execution dispatched to unified executor (`maestro-ralph-execute`); the command body (`.claude/commands/maestro.md`) owns session build + dispatch. `--exec` is legacy input only — recorded to `legacy_options.exec_mode`, never changes execution. This brain is consumed for **classification only** (intent → task_type → chain); it does NOT prescribe execution semantics.
 
 **Prerequisites:**
 - None for initial invocation (can bootstrap)
@@ -217,7 +217,7 @@ If user chooses "Execute from step N": set `$START_STEP = N` (used in 3f to set
 
 ### 3e: Step-level command resolution (v1)
 
-> **Superseded by `ralph_protocol_version: "1"`.** The command body resolves `command_scope`/`command_path` per execution step via `maestro ralph skills --platform claude --json --quiet`; cross-step gates carry `step.decision`. Do NOT write a per-step `type` field (legacy skill/cli). `--exec` is recorded to `legacy_options.exec_mode` only — it never changes execution. FSM owns step ordering + decision evaluation (control-plane precedence, see command-body invariant 15).
+> **Superseded by `ralph_protocol_version: "2"`.** The command body resolves `command_scope`/`command_path` per execution step via `maestro ralph skills --platform claude --json --quiet`; cross-step gates carry `step.decision`. Do NOT write a per-step `type` field (legacy skill/cli). `--exec` is recorded to `legacy_options.exec_mode` only — it never changes execution. FSM owns step ordering + decision evaluation (control-plane precedence, see command-body invariant 15).
 
 ```
 If execMode is 'cli' or 'internal' → force that type for all steps ("cli" or "skill").
@@ -292,7 +292,7 @@ status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 Skill({ skill: "maestro-ralph-execute" })
 ```
 
-The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps in order. maestro sessions (source: "maestro") are `ralph_protocol_version: "1"`: execution steps load via `maestro ralph next`; any `step.decision` node hands off to `Skill("maestro-ralph")` for evaluation (same mechanism as ralph sessions). Decision nodes ARE supported in maestro sessions.
+The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps in order. maestro sessions (source: "maestro") are `ralph_protocol_version: "2"`: execution steps load via `maestro ralph next`; any `step.decision` node hands off to `Skill("maestro-ralph")` for evaluation (same mechanism as ralph sessions). Decision nodes ARE supported in maestro sessions.
 
 ---
 

package/workflows/map.md

@@ -19,7 +19,7 @@ Codebase scanning with parallel mapper agents.
 
 ## Step 2: Spawn Parallel Mapper Agents
 
-Spawn 4 parallel `workflow-codebase-mapper` agents, each writing to `.workflow/research/`:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn 4 parallel `workflow-codebase-mapper` agents, each writing to `.workflow/research/`:
 
 | Agent | Focus | Output | Content |
 |-------|-------|--------|---------|
@@ -41,7 +41,7 @@ Each agent spawned in parallel as `workflow-codebase-mapper` subagent with specs
 After all 4 agents complete:
 
 1. Verify all 4 documents exist with >10 lines each.
-2. If any missing/empty → log failure, re-spawn that agent (max 1 retry).
+2. If any missing/empty → log failure, re-spawn that agent (max 1 retry); after retry exhausted, flag SUMMARY as [LOW CONFIDENCE] (incomplete) and list missing docs.
 
 ---
 

package/workflows/milestone-audit.md

@@ -46,7 +46,7 @@ For each execute artifact, read `{path}/.task/TASK-*.json` and verify all tasks
 
 ## Step 5: Integration Check
 
-Spawn `workflow-integration-checker` agent:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-integration-checker` agent:
 
 ```
 Agent({

package/workflows/milestone-complete.md

@@ -55,7 +55,7 @@
         - Update `archive.json.pruned = { "at": now, "counts": { open_questions, constraints, insights, references }, "ref": "context-package.pruned.json" }`
       - Otherwise leave both files untouched and set `archive.json.pruned = { "at": now, "counts": {...zeros}, "ref": null }`
 
-   c. If the session dir lacks `archive.json` (legacy session prior to lifecycle convention), skip (a) and (b) silently — legacy sessions are not indexed.
+   c. If the session dir lacks `archive.json` (legacy session prior to lifecycle convention), skip (a) and (b); log W0xx "legacy session not indexed"; flag archive as [LOW CONFIDENCE] (lifecycle.indexed=false, legacy session).
 
 ---
 

package/workflows/plan.md

@@ -148,7 +148,7 @@ When `--tdd` is active:
 4b. **Load design reference** (if available)
    - If `${PHASE_DIR}/design-ref/MASTER.md` exists: load MASTER.md, design-tokens.json, animation-tokens.json (optional), layout-templates/layout-*.json
      - Every UI task must include in `read_first[]`: design-tokens.json, animation-tokens.json, relevant layout-*.json, MASTER.md
-   - Else if phase goal matches UI keywords (`landing|page|dashboard|frontend|UI|component|界面`): suggest running `maestro-impeccable --chain build` (non-blocking)
+   - Else if phase goal matches UI keywords (`landing|page|dashboard|frontend|UI|component|界面`): run `maestro-impeccable --chain build` (REQUIRED when design keywords matched)
 
 5. **Load upstream analysis** (if available)
    - If `${PHASE_DIR}/conclusions.json` exists with non-empty status: load as explorationContext (conclusions + explorations.json + perspectives.json)
@@ -166,13 +166,14 @@ When `--tdd` is active:
 
 6. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
    - Exploration angles (1-4 based on complexity): architecture, implementation, integration, risk
-   - Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
+   - MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
    - Output: `.process/exploration-{angle}.json`, `.process/explorations-manifest.json`, `.process/context-package.json`
 
 6b. **CLI supplementary context** (runs in parallel with step 6, skip if `--gaps` or no CLI tools enabled)
    ```
    IF no CLI tools enabled: skip
 
+   MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
    Bash({
      command: 'maestro delegate "PURPOSE: Gather implementation context for planning phase
    TASK: Identify existing patterns for similar features | Map dependency graph of target modules | Find potential conflict points with other recent changes
@@ -319,7 +320,7 @@ Bidirectional linking (main flow, post-planner): update matching issues in `.wor
 
 ### Steps
 
-1. **Spawn workflow-plan-checker agent**
+1. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: **Spawn workflow-plan-checker agent**
    - Input: plan.json + all .task/TASK-*.json + index.json (success_criteria)
    - Check dimensions: requirements coverage, feasibility, dependency correctness (no circular deps), convergence criteria quality (grep-verifiable, no subjective language), read_first completeness, action concreteness (no vague references), wave structure (no conflicting files), completeness (no orphan tasks), UI-observable coverage (when plan touches UI: each delivery wave has ≥1 `[UI-observable]` criterion)
 
@@ -335,7 +336,7 @@ Bidirectional linking (main flow, post-planner): update matching issues in `.wor
 
 4. **Plan Readiness Gate** (blocks P4.5)
 
-   Block if: requirements_coverage < 40% | task missing read_first/convergence.criteria | no pressure pass | circular deps. If blocked → AskUserQuestion: 修订计划 or 忽略风险并继续 (record residual_risks). Add confidence section to plan.json.
+   Block if: requirements_coverage < 40% | task missing read_first/convergence.criteria | no pressure pass | circular deps. If blocked → AskUserQuestion: 修订计划 or 忽略风险并继续 (record residual_risks). Add confidence section to plan.json with `evidence_source: plan-checker findings (round N)`.
 
 5. **Update index.json**
    - Set `index.json.plan` = `{ task_ids, task_count, complexity, waves, executor_assignments: {}, confidence: overall_score }`
@@ -412,9 +413,9 @@ Bidirectional linking (main flow, post-planner): update matching issues in `.wor
 | E005: Plan directory not found (--check) | Check path, use --dir |
 | Phase directory not found | Abort with message: "Phase {phase} not found. Run /workflow:init first." |
 | No context.md | Warn, proceed with exploration only |
-| Exploration agent fails | Log error, continue with available explorations |
+| Exploration agent fails | Log error, continue with available explorations; flag plan as [LOW CONFIDENCE] (partial explorations) |
 | Planner produces invalid JSON | Retry once, then abort with error details |
-| Plan-checker exceeds 3 rounds | Accept plan with warnings, note in index.json |
+| Plan-checker exceeds 3 rounds | Accept plan with warnings, note in index.json; flag plan as [LOW CONFIDENCE] (checker unresolved) |
 | User cancels clarification | Proceed with available context |
 
 ---

package/workflows/quick.md

@@ -215,7 +215,7 @@ Passed inline to planner agent in Step 5.
 
 **Spawn workflow-planner in quick mode:**
 
-Spawn `workflow-planner` agent with:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-planner` agent with:
 
 - **Context**: mode (`quick` or `quick-full`), directory, description, state.json, CLAUDE.md, specs, context.md (if discuss mode)
 - **Constraints**: single plan with 1-3 atomic tasks, no research phase. Full mode: ~40% context usage + require files/action/convergence.criteria/implementation per task. Default: ~30% context usage.
@@ -243,7 +243,7 @@ Skip entirely if NOT $FULL_MODE.
 Spawning plan checker...
 ```
 
-Spawn `workflow-plan-checker` agent to verify plan.json and TASK-*.json:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-plan-checker` agent to verify plan.json and TASK-*.json:
 
 - **Check dimensions**: requirement coverage, task completeness (files/action/convergence.criteria/implementation), scope sanity (1-3 tasks), context compliance (if discuss mode).
 - **Return**: `## VERIFICATION PASSED` or `## ISSUES FOUND` with structured issue list.
@@ -263,15 +263,17 @@ If iteration_count < 2:
 
 If iteration_count >= 2:
 - Display: "Max iterations reached. {N} issues remain."
-- Offer: 1) Force proceed, 2) Abort
+- Offer: 1) Force proceed, 2) Abort; if Force proceed, flag plan as [LOW CONFIDENCE] (remaining issues)
 
 ---
 
+**GATE Step 6→7**: REQUIRED plan.json verified by plan-checker BEFORE execution; BLOCKED if plan.json not verified
+
 ### Step 7: Spawn Executor
 
 **Spawn workflow-executor:**
 
-Spawn `workflow-executor` agent:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-executor` agent:
 
 - **Read**: plan.json, TASK-*.json, state.json, CLAUDE.md
 - **Constraints**: execute all tasks, atomic commits per task, write summaries to `${QUICK_DIR}/.summaries/TASK-{NNN}-summary.md`
@@ -296,13 +298,13 @@ Skip entirely if NOT $FULL_MODE.
 Spawning verifier...
 ```
 
-Spawn `workflow-verifier` agent: check plan objectives against actual codebase using plan.json and summaries. Write result to `${QUICK_DIR}/verification.json`.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-verifier` agent: check plan objectives against actual codebase using plan.json and summaries. Write result to `${QUICK_DIR}/verification.json`.
 
 Read verification result:
 | Status | Action |
 |--------|--------|
 | passed | Store "Verified", continue |
-| gaps_found | Display gaps, offer: 1) Re-run executor, 2) Accept as-is |
+| gaps_found | Display gaps, offer: 1) Re-run executor, 2) Accept as-is; if Accept as-is, flag execution as [LOW CONFIDENCE] (gaps unresolved) |
 
 ---
 

package/workflows/ralph-amend-goal.md

@@ -0,0 +1,177 @@
+# Ralph Goal Amendment Flow
+
+`A_AMEND_GOAL` 详细流程。加载方式：`maestro-ralph.md` S_AMEND_GOAL via `<deferred_reading>`。
+
+触发：`/maestro-ralph --amend [change_request]`
+GUARD: running ralph session 存在
+
+---
+
+## Phase 1 — 快照
+
+1. 定位最新 running ralph session
+2. Read: `task_decomposition` WHERE `status != "superseded"`, `boundary_contract`, completed steps `completion_summary`
+3. Display:
+   ```
+   📍 Session: {session_id}
+   进度: {completed}/{total} steps
+   目标:
+   {for g in active_goals:}
+     [{status_icon}] {g.id}: {g.goal} — done_when: {g.done_when}
+   {end for}
+   边界: in_scope={count}, out_of_scope={count}
+   修改历史: {goal_changelog.length} 次
+   ```
+
+## Phase 2 — 解析
+
+| Condition | 行为 |
+|-----------|------|
+| `change_request` 非空 | 直接使用 |
+| `change_request` 为空 | AskUserQuestion（4 选项 + 自由输入追加） |
+
+AskUserQuestion options:
+
+| label | description |
+|-------|-------------|
+| 修改现有目标 | 调整子目标范围或完成条件 |
+| 新增目标 | 追加新子目标 |
+| 移除目标 | 取消未完成子目标 |
+| 调整边界 | 修改 in_scope / out_of_scope / constraints |
+
+## Phase 3 — Mini Grill
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Delegate (run_in_background, STOP, wait):
+
+```
+maestro delegate "PURPOSE: 评估目标变更影响
+TASK:
+  1. 对比 current_goals 与 change_request，识别冲突/缺口
+  2. 判定已完成 steps 在新目标下是否有效（基于 completion_summary + completion_decisions）
+  3. 判定 pending steps 是否需重建/跳过
+  4. 评估 risk_level
+CONTEXT:
+  intent             = {session.intent}
+  current_goals      = {task_decomposition where status != superseded}
+  completed_steps    = [{index, skill, stage, completion_summary, completion_decisions}]
+  pending_steps      = [{index, skill, stage, goal_ref}]
+  boundary_contract  = {boundary_contract}
+  change_request     = {change_request}
+EXPECTED:
+  ---IMPACT---
+  CHANGE_TYPE=modify|add|remove|boundary
+  AFFECTED_GOALS=[{id, action: modify|supersede|keep, new_goal?, new_done_when?}]
+  INVALIDATED_STEPS=[{index, reason}]
+  NEW_GAPS=[{goal_id, description, suggested_stages: [analyze|plan|execute|...]}]
+  BOUNDARY_CHANGES={in_scope_add:[], out_of_scope_add:[], constraints_add:[]}
+  RISK_LEVEL=low|medium|high
+  RISK_REASON=...
+  ---END---
+CONSTRAINTS:
+  - 只评估不修改
+  - high: 已完成工作与新目标直接冲突
+  - medium: 部分 steps 需跳过/重建，已完成工作可保留
+  - low: 纯增量，已有工作不受影响"
+--role analyze --mode analysis
+```
+
+**GATE Phase 3→4**: REQUIRED impact_assessment complete; BLOCKED if delegate output missing
+
+## Phase 4 — 确认
+
+Display: 影响摘要（risk_level, affected, invalidated, new_gaps）。AskUserQuestion:
+
+| label | description |
+|-------|-------------|
+| 应用并继续 | 归档旧目标 → 写入新目标 → 重建链路 → handoff |
+| 仅改目标 | 更新目标，保留链路不变 |
+| 取消 | 无修改 |
+
+GUARD: `RISK_LEVEL == high` → auto_confirm 无效
+
+## Phase 5 — 应用
+
+### 5.1 Changelog entry
+
+Append to `session.goal_changelog[]`：
+
+```json
+{
+  "id": "CHG-{NNN}",
+  "timestamp": "{ISO}",
+  "change_type": "{CHANGE_TYPE}",
+  "reason": "{change_request}",
+  "impact_assessment": { "risk_level": "...", "invalidated_steps": [...], "new_steps_inserted": 0, "evidence_source": "delegate impact assessment output" },
+  "before": { "goals": [{"id":"...","goal":"...","done_when":"..."}] },
+  "after":  { "goals": [{"id":"...","goal":"...","done_when":"..."}] }
+}
+```
+
+`NNN` = `(goal_changelog.length + 1).toString().padStart(3, '0')`
+
+**GATE 5.1→5.2**: REQUIRED goal_changelog written; BLOCKED if changelog entry missing
+
+### 5.2 归档
+
+对 AFFECTED_GOALS 中 `action ∈ {modify, supersede}` 的条目：
+- Set `status: "superseded"`, `superseded_by: "CHG-{NNN}"`, `superseded_at: now`
+- GUARD: `status == "done"` 的目标不可 supersede（skip + warn）
+
+### 5.3 写入新目标
+
+| action | 处理 |
+|--------|------|
+| `modify` | 新条目 `id: "{original_id}v{version}"`, `origin: "CHG-{NNN}"`, `status: "pending"` |
+| `add` | 新条目 `id: "G{next_num}"`, `origin: "CHG-{NNN}"`, `status: "pending"` |
+| `remove` | 仅 supersede，不新增 |
+| `keep` | 不变 |
+
+### 5.4 重建链路
+
+GUARD: 用户选"应用并继续"
+
+1. INVALIDATED_STEPS 中 pending step → set `status: "skipped"`
+2. NEW_GAPS → 按 `suggested_stages` 插入 steps + decision nodes
+   - 按 A_BUILD_STEPS 规则构建（goal_ref + command_path 解析 + command_scope 校验）
+   - 插入位置：当前 active step 之后、`post-goal-audit` 之前
+3. 原链路有 `post-goal-audit` → 保留
+4. 原链路无 `post-goal-audit` AND `task_decomposition` 存在 → 在 `milestone-complete` 前插入
+5. Reindex all steps
+
+### 5.5 Boundary
+
+`BOUNDARY_CHANGES` 非空时：
+- `in_scope_add` → append to `boundary_contract.in_scope`
+- `out_of_scope_add` → append to `boundary_contract.out_of_scope`
+- `constraints_add` → append to `boundary_contract.constraints`
+
+### 5.6 Persist + Handoff
+
+1. Write status.json
+2. Display:
+   ```
+   ◆ Goal amendment: {CHG-NNN}
+   {change_type} — {reason}
+   Risk: {RISK_LEVEL} | Superseded: {n} | Added: {n} | Skipped steps: {n} | Inserted steps: {n}
+   ```
+3. Handoff → maestro-ralph-execute（平台适配：Claude 用 `Skill()`，Codex 用 `$` 直调）
+
+---
+
+## Anchor 呈现规则
+
+Goals Overview 输出格式（CLI `buildSessionAnchor` 自动生成）：
+
+```
+**Goals Overview**:
+- [✓] G1: 实现搜索 API — done_when: 测试通过
+- [superseded] G2: 前端搜索页 → 被 CHG-001 替换
+- [○] G2v2: 前端搜索页+迁移兼容 — done_when: 新旧数据均可检索 (via CHG-001)
+- [○] G3: 旧数据迁移脚本 — done_when: 全量测试通过 (via CHG-001)
+- Course corrections: 1 applied
+```
+
+规则：
+- `superseded` 目标 → 单行标注，不展开细节
+- 新目标 → 标注 `(via CHG-xxx)`
+- re-grounding / goal-audit → 仅取 `status != "superseded"`

package/workflows/refactor.md

@@ -79,6 +79,8 @@ Run full test suite. Record final state in reflection-log.md.
 
 ### Step 7: Complete
 
+Glob plan.json AND .summaries/ MUST exist before marking completed; BLOCKED if missing.
+
 Update index.json: `status="completed"`.
 
 Present: tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings. If regressions: list affected tests, suggest quality-debug.

package/workflows/retrospective.md

@@ -135,7 +135,7 @@ delta = { vs_phase, tasks_completed, gaps_found, issues_opened, rework_iteration
 
 ## Stage 4: multi_lens_analysis
 
-Spawn one Agent per active lens **in parallel** (`run_in_background: false`). Each returns JSON.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn one Agent per active lens **in parallel** (`run_in_background: false`). Each returns JSON.
 
 ### Lens registry
 
@@ -233,10 +233,12 @@ Return ONLY a single JSON object, no prose, matching this schema:
 
 ### Spawn pattern
 
-Spawn all lenses in parallel. Collect into `lens_results`. If any fails, log W001, proceed with successful lenses.
+Spawn all lenses in parallel. Collect into `lens_results`. If any fails, log W001, proceed with successful lenses; flag retrospective as [LOW CONFIDENCE] (partial lenses).
 
 ---
 
+**GATE Stage 4→5**: REQUIRED lens analyses complete BEFORE synthesis; BLOCKED if lens_results missing
+
 ## Stage 5: synthesize
 
 ### Generate insight IDs
@@ -253,6 +255,8 @@ Sections: Header (tweetable, metadata) → Metrics table → Delta table (if --c
 
 Write both to `{artifact_dir}/`.
 
+Glob `{artifact_dir}/retrospective.json` AND `retrospective.md` MUST exist before Stage 8 complete; BLOCKED if missing.
+
 ---
 
 ## Stage 6: route_outputs
@@ -307,7 +311,7 @@ Invoke manage-learn tip with:
 insight.routed_id = "TIP-{captured_id}"
 ```
 
-Fallback: if skill ID cannot be captured, write tip file directly per `workflows/knowhow.md` Part B Step 3 and update `wiki-index.json` per Step 4.
+Fallback: if skill ID cannot be captured, write tip file directly per `workflows/knowhow.md` Part B Step 3 and update `wiki-index.json` per Step 4; flag tip as [LOW CONFIDENCE] (skill not captured).
 
 #### Target: issue
 

package/workflows/review.md

@@ -161,7 +161,7 @@ Each finding: { id: "{PREFIX}-{NNN}", dimension, severity, title, file, line, sn
 ### Standard Level — Parallel Agent Review
 
 ```
-Per dimension → spawn workflow-reviewer agent (all parallel):
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Per dimension → spawn workflow-reviewer agent (all parallel):
   Context: dimension, phase_name, phase_goal, review_files, success_criteria,
            tech_stack, specs_content, verification_gaps
   Instructions:
@@ -172,7 +172,7 @@ Per dimension → spawn workflow-reviewer agent (all parallel):
     - Top 20 findings by severity, each with file:line evidence
 ```
 
-Launch ALL dimension agents in a single message. Collect dimension_results (JSON findings array). Log W001 on agent failure, continue with partial results.
+Launch ALL dimension agents in a single message. Collect dimension_results (JSON findings array). Log W001 on agent failure, continue with partial results; flag review as [LOW CONFIDENCE] (partial results).
 
 ### Deep Level — Enhanced Agent Review
 
@@ -234,6 +234,7 @@ IF cli_targets.length == 0: skip to Step 7
 # Build concise review prompt from findings
 finding_summary = cli_targets.map(f => "${f.id}: [${f.severity}] ${f.file}:${f.line} — ${f.title}").join("\n")
 
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
 Bash({
   command: 'maestro delegate "PURPOSE: Cross-verify code review findings and identify missed issues
 TASK: For each finding, verify severity is accurate | Check for false positives | Identify any critical issues missed by initial review in the same files
@@ -286,7 +287,7 @@ deep_dive_targets:
 ```
 Iterate up to max_iterations (deep=3, standard=1) over unresolved targets:
 
-  Per target → spawn workflow-reviewer agent:
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Per target → spawn workflow-reviewer agent:
     Context: original finding JSON, previous analysis (if iteration > 1)
     Tasks: read affected file, find callers/imports, check test coverage
     Analyze: root cause, impact radius, remediation (with code example), risk if unfixed
@@ -369,6 +370,7 @@ Write ${PHASE_DIR}/review.json:
 
 ```
 Update index.json.updated_at = now()
+Glob review.json MUST exist before Step 10 complete; BLOCKED if missing.
 Set index.json.review = { level, verdict, reviewed_at, severity_distribution,
                           findings_count, issues_created count }
 ```
@@ -433,7 +435,7 @@ Next steps:
 | No changed files | Abort: "No changed files detected in this phase." |
 | Reviewer agent fails | Log W001, continue with available dimension results |
 | All agents fail | Abort: "Review could not complete — all dimension agents failed." |
-| Deep-dive agent fails | Log finding as unresolved, skip enrichment |
+| Deep-dive agent fails | Log finding as unresolved, skip enrichment; flag finding as [LOW CONFIDENCE] (enrichment skipped) |
 
 ---
 

package/workflows/roadmap-common.md

@@ -47,7 +47,7 @@ Read project artifacts to understand what has already been built:
 ## Codebase Exploration (conditional)
 
 - Detect if project has source files
-- If yes: spawn `cli-explore-agent` for context discovery
+- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: If yes: spawn `cli-explore-agent` for context discovery
   - If `project_context.already_shipped` exists: include as "feature audit" directive — agent should verify which shipped features are present in code and identify integration points for new work
 - Output: relevant files, patterns, tech stack, feature_audit
 
@@ -55,7 +55,7 @@ Read project artifacts to understand what has already been built:
 
 ## External Research — API & Technology Details (Optional)
 
-Spawn `workflow-external-researcher` agent when requirement mentions specific technologies, APIs, or external services.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-external-researcher` agent when requirement mentions specific technologies, APIs, or external services.
 
 **Trigger**: Technology keywords detected in requirement or codebase exploration found external dependencies. Auto-trigger in auto mode (`-y`). Skip if requirement is purely organizational/conceptual.
 
@@ -66,7 +66,7 @@ If topics found → spawn `workflow-external-researcher` agent for API research:
 - Focus on details affecting phase decomposition and dependency ordering
 - Output → `apiResearchContext` (in-memory)
 
-If no topics or research fails → `apiResearchContext = null`, continue.
+If no topics or research fails → `apiResearchContext = null`, continue; flag roadmap as [LOW CONFIDENCE] (no external research).
 
 ---