maestro-flow 0.5.37 → 0.5.39

package/workflows/init.md

@@ -37,7 +37,7 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
      - Target users / stakeholders
      - Success criteria
 
-   Decision gate: When enough context for project.md, ask "Ready to create project.md?"
+   Decision gate: When ≥3 research dimensions gathered, ask "Ready to create project.md?"
    - "Create project.md" → proceed
    - "Keep exploring" → continue questioning
 
@@ -67,9 +67,9 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
 
    If `--auto`: use template defaults (all the above on).
 
-3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
+3. **Research** (conditional, triggered when `config.workflow.research == true`) -- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep when triggered: Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
 
-4. **Synthesize** -- Spawn `workflow-research-synthesizer` agent:
+4. **Synthesize** -- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-research-synthesizer` agent:
    - Input: all `.workflow/research/` documents
    - Output: `.workflow/research/SUMMARY.md` with consolidated findings
 
@@ -103,10 +103,10 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
 
 If `.workflow/specs/` does not exist:
 
-1. Run `Bash("maestro spec init")` — creates empty seed files (skeleton only, no codebase scan)
+1. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Run `Bash("maestro spec init")` — creates empty seed files (skeleton only, no codebase scan)
 
 2. If project has existing source files (package.json, tsconfig.json, pyproject.toml, go.mod, etc.):
-   - Auto-trigger `Skill({ skill: "spec-setup" })` — scan codebase and populate specs with detected conventions
+   - MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: auto-trigger `Skill({ skill: "spec-setup" })` — scan codebase and populate specs with detected conventions
    - Note: Specs are further enriched by analyze, plan, and execute stages via `maestro spec add`
 
 3. If greenfield project (no source files):
@@ -117,8 +117,8 @@ If `.workflow/specs/` does not exist:
 
 If `.workflow/domain/` does not exist:
 
-1. Run `Bash("maestro domain init")` — creates `.workflow/domain/glossary.yaml` with empty terms array
-2. If brownfield project (has source files): run `maestro domain discover --auto` to scan codebase for initial term candidates, present top 5 for confirmation
+1. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Run `Bash("maestro domain init")` — creates `.workflow/domain/glossary.yaml` with empty terms array
+2. If brownfield project (has source files): MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: run `maestro domain discover --auto` to scan codebase for initial term candidates, present top 5 for confirmation
 3. If greenfield project: skip discovery (no codebase to scan); domain terms will be populated by grill/brainstorm sessions via finish-work extraction
 
 

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-gaps-analyze.codex.md

@@ -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,7 +68,7 @@ For each group:
   Merge keywords from all issues in group: title, description, location, affected_components.
   Deduplicate keywords.
 
-  Standard depth: maestro explore per group (keywords as prompt), fallback grep.
+  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.
 
@@ -81,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",
@@ -97,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/odyssey-base.md

@@ -0,0 +1,258 @@
+# Odyssey 共享基座
+
+所有 Odyssey 命令（debug, improve, planex, review-test-fix, ui）共享此基座。
+
+<execution_discipline>
+**四条铁律：**
+
+1. **Phase auto-commit** — 每个阶段完成后自动 `git commit`，无需用户确认
+   - 代码变更 + understanding.md → `git add` → `git commit -m "{command}({slug}): {phase} — {摘要}"`
+   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
+
+2. **Confident edits only, but must attempt** — 有把握才改代码；仅在真正需要人类判断时记录 decision
+   - Confident → edit + commit
+   - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`，不动代码
+   - ⚠️ **Decision gate** — 仅以下情形算 decision：跨模块架构权衡需人类方向 | 业务语义歧义修复可能改变意图 | 需引入新依赖或 breaking API
+   - ❌ "不确定怎么修"、"范围太大"、"历史遗留" 不是合法 decision 理由
+
+3. **多 CLI 辅助** — `maestro delegate` 多角度交叉验证
+   - 不同阶段用不同 `--role`（analyze / review / explore）
+   - 所有 delegate 调用 `run_in_background: true`，等回调继续
+
+4. **禁止以上下文消耗为由中断** — harness 自动 context compression；以"上下文不足"或"已执行 N 阶段"为由中断属纪律违反，必须完整走到 S_RECORD → END
+
+**Zero-residual:** 每个发现必须有 action（fix / issue / decision）。"仅报告"和"历史遗留跳过"均禁止。
+</execution_discipline>
+
+<shared_schemas>
+
+### session.json 标准字段（所有命令共有）
+
+```json
+{
+  "session_id": "{type}-odyssey-{YYYYMMDD-HHmmss}",
+  "current_state": "S_INTAKE",
+  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
+  "phase_goals": [], "phase_goals_all_done": false,
+  "self_iteration_log": [],
+  "cross_phase_loops": 0, "max_loops": 5,
+  "created_at": "", "updated_at": ""
+}
+```
+
+各命令在此基础上添加特有字段（如 `issue`, `target`, `requirement` 等）。
+
+### evidence.ndjson 基础 schema（每行共有字段）
+
+```json
+{"ts":"","phase":"","type":"","source":"","content":"","note":""}
+```
+
+各命令定义 phase-specific 扩展字段（如 `hypothesis`, `severity`, `dimension` 等）。
+
+### generalization_stats schema
+
+```json
+{
+  "patterns_extracted": 0, "total_hits": 0,
+  "cross_layer_confirmed": 0, "regression_risks": 0,
+  "by_layer": {"syntax": 0, "semantic": 0, "structural": 0},
+  "deepening_triggered": false
+}
+```
+
+</shared_schemas>
+
+<anti_stall>
+**防停滞机制**
+
+### session.json 新增字段
+
+```json
+{
+  "progress_metrics": {
+    "phase_stats": {},
+    "stale_count": 0,
+    "last_productive_phase": "",
+    "convergence_trend": "unknown"
+  },
+  "directions_tried": []
+}
+```
+
+### Progress Tracking
+
+每个分析阶段结束时：
+1. 统计 `new_findings`（去重后新发现）和 `repeated`（与已有 evidence 重复）
+2. 写入 `progress_metrics.phase_stats[state_name]`
+3. `new == 0` → `stale_count++`，`convergence_trend = "stalling"`
+4. `new > 0` → `stale_count = 0`，更新 `last_productive_phase`
+5. 连续 2 阶段 new 递减 → `convergence_trend = "diminishing"`
+
+### Direction Diversity
+
+```json
+{
+  "phase": "S_DIAGNOSE", "round": 1,
+  "strategy_type": "scope_widen|perspective_shift|tool_switch|structural_pivot",
+  "strategy_desc": "扩展搜索到 utils/", "result": "2 new findings"
+}
+```
+
+**去重规则:** 自迭代前检查同 phase 历史 → 新策略必须在 `strategy_type` 或 `strategy_desc` 上不同 → 4 种 type 均已尝试 → 强制升级 stale_count
+
+### Stall Escalation Ladder
+
+| stale_count | 策略 |
+|-------------|------|
+| 0 | 正常推进 |
+| 1 | **换视角** — 不同 CLI 工具、反向追踪、手动阅读。方向必须与 directions_tried 不同 |
+| 2 | **结构性转向** — 重定义搜索维度、换分析框架、拆解子问题。不是参数调优 |
+| 3 | **人工升级** — AskUserQuestion / `-y` 自动 INCONCLUSIVE 并推进 |
+
+### /loop Heartbeat（可选，`--heartbeat` 启用）
+
+建议用户 `/loop 270s`。每阶段更新 `session.json.updated_at`。超 15 分钟未更新 → 告警 + stale_count。连续 2 次无更新 → 建议 `-c` resume。
+</anti_stall>
+
+<self_iteration>
+**Quality Gate（进度感知版）**
+
+| 维度 | sufficient | insufficient |
+|------|-----------|-------------|
+| Coverage | 已知相关文件/模块均已分析 | 遗漏 grep/git log 可发现的目标 |
+| Depth | ≥80% 发现有 file:line 级证据 | 多数仅泛泛描述 |
+| Actionability | 每条结论有具体后续动作 | 仅"建议关注"类无操作结论 |
+
+**进度感知迭代（替代固定 3 轮）:**
+- phase complete → evaluate 3 dims + check `progress_metrics`
+- any insufficient AND `stale_count < 3` → re-enter，expansion strategy 必须经 directions_tried 去重
+- 按 Stall Escalation Ladder 选择策略类型
+
+**Expansion strategies:**
+- `scope_widen`: 更多目录、git log 深度 ×2、额外 delegate 角度
+- `perspective_shift`: 不同 CLI 工具、反向追踪、手动阅读
+- `tool_switch`: 切换到未使用的分析工具
+- `structural_pivot`: 重定义问题框架、拆解子问题
+
+**Exit:** all sufficient → advance | `stale_count >= 3` → log gaps, advance
+
+**Log:** `evidence.ndjson {"phase":"self-iteration"}` + `session.json.self_iteration_log[]` + `directions_tried[]`
+</self_iteration>
+
+<shared_actions>
+
+### A_GENERALIZE
+
+3 层 pattern extraction → 4-agent 并发 scan → cross-layer dedup → iterative deepening。
+
+**Pattern 来源:** 由各命令指定（root cause / audit findings / implementation patterns 等）。
+
+**3 层提取:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex → Grep | `eval(`, missing `await`, inline styles |
+| Semantic | Agent 理解反模式 → scan | 未处理异步错误、缺少校验 |
+| Structural | 文件/模块结构相似性 | 同类导入结构、缺少 override |
+
+Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template, confidence}]`
+
+**4-agent 并发 scan（单条消息）:**
+
+| Agent | Strategy | Scope |
+|-------|----------|-------|
+| Syntax grep | Grep regex | Full project |
+| Semantic scan | 反模式检查 | Related modules |
+| Structural match | 结构相似文件 | Full project |
+| Historical grep | `git log -S` | Git history |
+
+**Cross-layer dedup:** 多层命中 → boost | 单层 → `needs_review` | 历史已修 → `regression_risk`
+
+**Iterative deepening:** module ≥3 hits → 定向深扫（max 1 round）
+
+**Persist:** understanding.md 泛化 section + `session.json.generalization_stats`（schema 见 shared_schemas）
+
+📌 Auto-commit: `"...({slug}): GENERALIZE — 泛化扫描完成"`
+
+### A_DISCOVER
+
+1. **Triage** 每个 hit ±10 行上下文 → 分类 `bug` / `risk` / `safe`
+2. **Route:**
+   - bug + 可直接修 → **立即修复** → back to S_FIX
+   - bug + 需跨模块决策 → 创建 issue（含 fix 建议 + 影响分析）
+   - risk → 评估能否直接加 guard；能 → 修
+   - safe → skip
+   Normal: AskUserQuestion | `-y`: auto-fix 可修的，其余 create issue
+3. **Cross-phase loops:** `cross_phase_loops++`。`loops >= max_loops` → 必须逐项记录原因（禁止笼统"历史遗留"）
+4. Append evidence + update understanding.md
+
+📌 Auto-commit: `"...({slug}): DISCOVER — 发现分类完成"`
+
+### A_RECORD
+
+1. Finalize understanding.md 最后一节 — learnings 按各命令指定的分类表结构化
+   - **两步模式:** 执行中写产出文件（临时）→ 完成后用户通过 next_step_routing 沉淀永久知识
+2. Mark record goal done。Pending decisions: Normal → AskUserQuestion | `-y` → skip (show deferred count)
+3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`。未完成: Normal → AskUserQuestion | `-y` → auto accept
+4. `current_state = "COMPLETED"`，emit completion summary（格式由各命令定义）
+
+📌 Auto-commit: `"...({slug}): RECORD — 会话总结与知识沉淀"`
+
+</shared_actions>
+
+<shared_appendix>
+
+### Goal Prompt 机制
+
+**⚠️ 时机守卫：仅 INTAKE 完成后显示一次。RECORD 完成时禁止重显。**
+
+```
+📋 {Command} Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
+
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+{command-specific convergence rules}
+遇到 phase=decision 的 pending 必须 AskUserQuestion，不得自行 resolve。
+```
+
+输出后继续执行不阻塞。
+
+### `-y` 通用规则
+
+- Decision pending → best-effort continue, record `deferred`
+- 3-strike escalation → auto INCONCLUSIVE
+- Discovery routing → auto create issue
+- Record pending → skip, show deferred count
+- Record goal audit → auto accept
+
+`deferred` items 在 completion summary 显示为"待决策"；可通过 `-c` 恢复。各命令在自身文件中列出特有 decision points。
+
+### Phase Goal Lifecycle
+
+`pending → done (confirmed=true)` | `pending → skipped (confirmed=true)` | `pending → failed (confirmed=false)`
+
+`phase_goals_all_done = true` 仅当 ALL goals 有 `completion_confirmed == true`。
+
+### Pre-load（可选，缺失不阻塞）
+
+| 层级 | 命令 |
+|------|------|
+| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` |
+| Wiki search | `maestro search "<keywords>" --json`（top 5） |
+| Specs | `maestro load --type spec --category <cat>` |
+| Role knowledge | `maestro search --category <cat>` → `maestro load --type knowhow --id <id>` |
+| Prior sessions | `Glob(".workflow/scratch/*-{type}-odyssey-*")` |
+
+### Common Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E003 | error | Resume but no session found | Start new |
+| E004 | error | Delegate failed | Retry or proceed without |
+| W003 | warning | Generalization 0 hits | Skip discovery |
+| W004 | warning | Delegate parse failed | Use raw output |
+
+</shared_appendix>

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) |
 
 ---