maestro-flow 0.5.37 → 0.5.39

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

package/workflows/roadmap.md

@@ -1,6 +1,6 @@
 # Workflow: Roadmap (Light Mode)
 
-Lightweight requirements-to-roadmap path. Shared logic: `@roadmap-common.md`.
+Lightweight requirements-to-roadmap path. Shared logic: `@~/.maestro/workflows/roadmap-common.md`.
 
 ---
 
@@ -27,9 +27,9 @@ Parse flags from `$ARGUMENTS`:
    - `--from`: enrich from context-package (`requirements`, `constraints[locked]`, `domain`, `non_goals`, `insights`, `open_questions`)
    - `project_context`: cross-reference `already_shipped`, promote `deferred` items, apply `locked_decisions`
 
-2. **Codebase Exploration** — follow roadmap-common.md
+2. **Codebase Exploration** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md Codebase Exploration logic; REQUIRED produce: codebase context summary; BLOCKED if missing
 
-3. **External Research** — follow roadmap-common.md
+3. **External Research** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md External Research logic; REQUIRED produce: apiResearchContext (or [LOW CONFIDENCE] if none)
 
    `apiResearchContext` is passed into:
    - Step 3 (Decomposition): technology complexity informs phase sizing and ordering
@@ -43,7 +43,7 @@ Parse flags from `$ARGUMENTS`:
 
 ## Step 3: Decomposition
 
-Spawn `cli-roadmap-plan-agent` (include `apiResearchContext` if set). Apply **Minimum-Phase Principle** from roadmap-common.md.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `cli-roadmap-plan-agent` (include `apiResearchContext` if set). Apply **Minimum-Phase Principle** from ~/.maestro/workflows/roadmap-common.md.
 
 ---
 
@@ -58,10 +58,13 @@ Spawn `cli-roadmap-plan-agent` (include `apiResearchContext` if set). Apply **Mi
 
 ## Step 5: Write Outputs
 
-Follow roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state.json update, scratch directory).
+MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state.json update, scratch directory); REQUIRED produce: .workflow/roadmap.md; BLOCKED if missing
 
 ---
 
+**GATE Step 5→6**: REQUIRED roadmap.md written BEFORE handoff.
+Glob .workflow/roadmap.md MUST exist before Step 6 handoff; BLOCKED if missing.
+
 ## Step 6: Handoff
 
 Display summary and next steps: `maestro-blueprint` | `maestro-plan 1` | `maestro-brainstorm 1` | `manage-status`

package/workflows/spec-generate.md

@@ -2,7 +2,7 @@
 
 Specification document chain producing a complete specification package (Product Brief, PRD, Architecture, Epics, Roadmap) through 7 sequential phases with multi-CLI analysis and interactive refinement. Pure documentation — no code generation.
 
-**Shared logic**: `@roadmap-common.md` (worktree guard, context loading, codebase exploration, external research, minimum-phase principle, roadmap write logic)
+**Shared logic**: `@~/.maestro/workflows/roadmap-common.md` (worktree guard, context loading, codebase exploration, external research, minimum-phase principle, roadmap write logic)
 
 ## Pipeline Position
 
@@ -70,7 +70,7 @@ Load specification and template documents:
 | Quality gates | Per-phase quality criteria and scoring | P0 - must read |
 | Templates | product-brief, requirements-prd, architecture-doc, epics-template | Read on-demand per phase |
 
-**Load project specs and history**: Follow roadmap-common.md "Load Project Context".
+**Load project specs and history**: MANDATORY: execute ~/.maestro/workflows/roadmap-common.md "Load Project Context"; REQUIRED produce: specs+history loaded.
 
 Additional full-mode rules:
 - Features in `already_shipped` are EXCLUDED from spec generation scope
@@ -109,15 +109,15 @@ Session ID: SPEC-{slug}-{YYYY-MM-DD}
 Output dir: .workflow/.spec/{session_id}/
 ```
 
-**Step 2.3: Seed Analysis via CLI**
+**Step 2.3: Seed Analysis via CLI** (MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep)
 - Spawn CLI analysis to extract: problem_statement, target_users, domain, constraints, dimensions (3-5)
 - Assess complexity: simple (1-2 components) / moderate (3-5) / complex (6+)
 - For context-package input: enrich with feature decomposition data
 
-**Step 2.4: Codebase Exploration** — follow roadmap-common.md
+**Step 2.4: Codebase Exploration** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md Codebase Exploration logic; REQUIRED produce: discovery-context.json (codebase context)
 - Output: `discovery-context.json` with relevant_files, patterns, tech_stack
 
-**Step 2.5: External Research** — follow roadmap-common.md
+**Step 2.5: External Research** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md External Research logic; REQUIRED produce: apiResearchContext (or [LOW CONFIDENCE] if none)
 
 `apiResearchContext` is passed into:
 - Step 4 (Product Brief): technology feasibility assessment
@@ -166,7 +166,7 @@ Generate product brief through multi-perspective CLI analysis.
 - Read discovery-context.json (if codebase detected)
 - For context-package input: read context-package.json domain and requirements sections
 
-**Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)**
+**Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)** (MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep)
 
 | Perspective | Role | Focus |
 |-------------|------|-------|
@@ -191,6 +191,8 @@ Generate product brief through multi-perspective CLI analysis.
 
 **Output**: `product-brief.md`, `glossary.json`
 
+**GATE P2→P3**: REQUIRED product-brief.md written; BLOCKED if missing
+
 ### Step 5: Requirements / PRD (Phase 3)
 
 Generate detailed PRD with functional/non-functional requirements.
@@ -216,11 +218,13 @@ Generate detailed PRD with functional/non-functional requirements.
 
 **Output**: `requirements/` directory (index + individual files)
 
+**GATE P3→P4**: REQUIRED requirements/_index.md with MoSCoW table; BLOCKED if missing
+
 ### Step 6: Architecture (Phase 4)
 
 Generate architecture decisions, component design, and technology selections.
 
-**Step 6.1: Architecture Analysis via CLI (role: review)**
+**Step 6.1: Architecture Analysis via CLI (role: review)** (MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep)
 - System architecture style with justification
 - Core components and responsibilities
 - Component interaction diagram (Mermaid graph TD)
@@ -340,7 +344,7 @@ Convert Epics into an interactive roadmap with user confirmation.
 - Read individual `EPIC-NNN-{slug}.md` for Stories and acceptance criteria
 - Read `architecture/_index.md` for technical constraints (ADR decisions)
 
-Apply **Minimum-Phase Principle** from roadmap-common.md for Epic→Phase mapping:
+Apply **Minimum-Phase Principle** from ~/.maestro/workflows/roadmap-common.md for Epic→Phase mapping:
 - Default: ALL Epics → 1 Phase (wave DAG orders tasks by Epic dependencies)
 - Only split if hard dependency conditions are all met
 - MVP-tagged Epics → Milestone 1, Post-MVP → Milestone 2+
@@ -350,7 +354,7 @@ Apply **Minimum-Phase Principle** from roadmap-common.md for Epic→Phase mappin
 - ADR decisions → phase technical constraints
 
 **Step 11.2: Generate Draft Roadmap**
-Follow roadmap-common.md **Roadmap Template** format. For full mode, populate from product-brief.md vision and Epic→Stories acceptance criteria.
+MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **Roadmap Template** format. For full mode, populate from product-brief.md vision and Epic→Stories acceptance criteria; REQUIRED produce: roadmap section.
 
 **Step 11.3: Interactive Refinement (max 3 rounds)**
 - Present roadmap overview: phase count, milestone structure, dependency graph
@@ -364,9 +368,9 @@ Follow roadmap-common.md **Roadmap Template** format. For full mode, populate fr
 
 **Step 11.4: Write Outputs**
 - Write `roadmap.md` to spec directory: `{spec_dir}/roadmap.md`
-- Write `.workflow/roadmap.md` — follow roadmap-common.md **Overwrite vs Edit Rules**
+- MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **Overwrite vs Edit Rules**; REQUIRED produce: .workflow/roadmap.md; BLOCKED if missing
 - Update `spec-config.json`: add Phase 7 completion
-- Update `state.json` — follow roadmap-common.md **state.json Update Rules**
+- MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **state.json Update Rules**; REQUIRED produce: state.json updated
 
 **Step 11.5: Handoff Options (AskUserQuestion)**
 
@@ -380,6 +384,7 @@ Follow roadmap-common.md **Roadmap Template** format. For full mode, populate fr
 ### Step 12: Final Report
 
 ```
+Glob product-brief.md AND requirements/ AND architecture/ AND epics/ MUST exist before final report; BLOCKED if missing.
 == spec-generate complete ==
 Session: SPEC-{slug}-{date} | Quality: {score}% ({gate}) | Phases: {completed_count}/7
 Output: .workflow/.spec/{session_id}/
@@ -457,14 +462,14 @@ Init detects existing `.workflow/roadmap.md` and skips roadmap creation.
 | Phase | Error | Blocking? | Action |
 |-------|-------|-----------|--------|
 | Phase 1 | Empty input | Yes | Error and exit |
-| Phase 1 | CLI analysis fails | No | Basic parsing fallback |
+| Phase 1 | CLI analysis fails | No | Basic parsing fallback; flag seed analysis as [LOW CONFIDENCE] (basic parsing) |
 | Phase 1.5 | Gap analysis fails | No | Skip to basic prompts |
-| Phase 2 | Single CLI fails | No | Continue with available |
-| Phase 3 | Gemini fails | No | Codex fallback |
-| Phase 4 | Review fails | No | Skip review |
+| Phase 2 | Single CLI fails | No | Continue with available; flag product-brief as [LOW CONFIDENCE] (N-1 perspectives) |
+| Phase 3 | Gemini fails | No | Codex fallback; flag requirements as [LOW CONFIDENCE] (fallback tool) |
+| Phase 4 | Review fails | No | Skip review; flag architecture/ as [LOW CONFIDENCE] (review skipped) |
 | Phase 5 | Story generation fails | No | Generate epics only |
-| Phase 6 | Validation fails | No | Partial report |
+| Phase 6 | Validation fails | No | Partial report; flag readiness-report as [LOW CONFIDENCE] (validation incomplete) |
 | Phase 6.5 | Max iterations (2) | No | Force handoff |
-| Step 2.5 | External research fails | No | apiResearchContext = null, continue |
+| Step 2.5 | External research fails | No | apiResearchContext = null, continue; flag Phase 2-5 outputs as [LOW CONFIDENCE] (no external research) |
 
-CLI Fallback Chain: Role-based resolution → degraded mode (local only)
+CLI Fallback Chain: Role-based resolution → degraded mode (local only); flag all affected outputs as [LOW CONFIDENCE] (degraded local-only mode)

package/workflows/specs-load.md

@@ -59,7 +59,7 @@ Extract `--scope`, `--uid`, `--category <category>` and remaining text (keyword
 maestro spec load --scope <scope> [--uid <uid>] [--category <category>] [--keyword <word>]
 ```
 
-If `maestro spec load` CLI is unavailable, read files directly from the resolved directory.
+If `maestro spec load` CLI is unavailable, read files directly from the resolved directory; flag loaded specs as [LOW CONFIDENCE] (CLI unavailable, direct file read).
 
 ### Step 3: Keyword Filter (optional)
 

package/workflows/specs-setup.md

@@ -285,6 +285,8 @@ source: spec-setup
 
 ### Step 7: Summary
 
+Glob created spec/recipe files MUST exist before Step 7 summary; BLOCKED if missing.
+
 Display list of all created files grouped by destination:
 
 ```

package/workflows/sync.md

@@ -36,8 +36,8 @@ No files changed → emit W001, exit
 Read .workflow/codebase/doc-index.json
 Extract: components[], features[], requirements[], architecture_decisions[]
 
-If missing: prompt → (a) run /manage-codebase-rebuild then re-run (recommended)
-             or    → (b) DEGRADED_MODE: git-diff-only, skip Steps 3-5
+If missing: prompt → (a) MUST run /manage-codebase-rebuild then re-run
+             or    → (b) DEGRADED_MODE: git-diff-only, skip Steps 3-5; flag sync as [LOW CONFIDENCE] (git-diff-only, Steps 3-5 skipped)
 ```
 
 ### Step 4: Impact Chain Traversal
@@ -50,6 +50,8 @@ Traverse impact chain: file → components (via code_locations match)
 Aggregate deduplicated: { files, components, features, requirements }
 ```
 
+GATE Step 4→5: impact_chain non-empty BEFORE update index; BLOCKED if impact_chain empty (no affected components/features/requirements identified)
+
 ### Step 5: Update Doc Index (skip if --dry-run)
 
 ```

package/workflows/test-gen.md

@@ -12,7 +12,7 @@ Tests expose bugs -- fixing is for quality-debug or maestro-execute.
 specs_content = maestro spec load --category test
 ```
 
-Follow project test conventions in Step 4 (Generate Test Plan) and Step 5 (Write Tests).
+Apply project test conventions (from Step 0 specs) when generating the plan (Step 4) and writing tests (Step 5); REQUIRED: tests conform to loaded spec conventions.
 
 ---
 

package/workflows/test.md

@@ -275,7 +275,7 @@ issues == 0 → Step 13. issues > 0 → Step 11.
 ### Step 11: Auto-Diagnose
 
 1. **Cluster gaps** by component/area (same file/module → one cluster, same flow → one cluster)
-2. **Spawn one debug agent per cluster** (parallel, `run_in_background: false`): pre-filled symptoms, `goal: find_root_cause`. Include `issue_id` refs.
+2. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: **Spawn one debug agent per cluster** (parallel, `run_in_background: false`): pre-filled symptoms, `goal: find_root_cause`. Include `issue_id` refs.
 3. **Collect results**, update uat.md gaps:
 ```yaml
 - test: {N}

package/workflows/ui-codify-extract.md

@@ -350,6 +350,7 @@ Task(subagent_type="ui-design-agent",
 ```bash
 # Agents run in parallel and write separate output files
 # Each agent generates its own JSON directly
+Glob ${temp_dir}/style-extraction/style-1/design-tokens.json, ${temp_dir}/animation-extraction/animation-tokens.json, ${temp_dir}/layout-extraction/layout-templates.json MUST exist before Phase 2 complete; BLOCKED if missing
 echo "[Phase 2] Parallel agent analysis complete"
 ```
 

package/workflows/ui-codify-knowhow.md

@@ -203,7 +203,7 @@ echo "  knowhow-manifest.json written to ${package_dir}"
 通过 Skill tool 调用 codify-to-knowhow：
 
 ```javascript
-Skill("codify-to-knowhow", args="${package_dir}")
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Skill("codify-to-knowhow", args="${package_dir}")
 ```
 
 等待 codify-to-knowhow 完成。它将：

package/workflows/ui-codify-package.md

@@ -50,7 +50,7 @@ echo "[Phase 3] Token files prepared"
 **Agent Task**:
 
 ```javascript
-Agent(ui-design-agent): `
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): `
   [PREVIEW_SHOWCASE_GENERATION]
   Generate interactive multi-component showcase panel for reference package
 

package/workflows/ui-codify.md

@@ -130,7 +130,7 @@ echo "  Output: $package_dir"
 
 ## Phase 2: Parallel Agent Extraction (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-extract.md` then execute.
+MANDATORY: execute ui-codify-extract.md steps; REQUIRED produce: design-tokens.json, animation-tokens.json, layout-templates.json; BLOCKED if missing.
 
 Variables available to Phase 2:
 - `source_path` — absolute path to source directory
@@ -147,7 +147,7 @@ Phase 2 writes:
 
 ## Phase 3: Reference Package Generation (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-package.md` then execute.
+MANDATORY: execute ui-codify-package.md steps; REQUIRED produce: preview.html, preview.css, token files copied to package_dir; BLOCKED if missing.
 
 Variables available to Phase 3:
 - `temp_dir` — temporary workspace with extraction results
@@ -167,7 +167,7 @@ Phase 3 writes:
 
 ## Phase 4: Knowledge Asset Generation (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-knowhow.md` then execute.
+MANDATORY: execute ui-codify-knowhow.md steps; REQUIRED produce: knowhow-manifest.json, knowhow files, spec entries; BLOCKED if missing.
 
 Variables available to Phase 4:
 - `package_dir` — package directory with all token files
@@ -189,15 +189,17 @@ Phase 4 writes:
 | 1 | E001: Missing source path | Report usage, exit |
 | 1 | E002: Source not found | Report path, exit |
 | 1 | E003: Package exists | Suggest --overwrite, exit |
-| 2 | Agent failure | Report which agent failed, continue with partial results |
+| 2 | Agent failure | Report which agent failed, continue with partial results; flag partial results as [LOW CONFIDENCE] (agent failure) |
 | 2 | No files discovered | Report empty discovery, exit |
 | 3 | Token copy failed | Report missing file, exit |
-| 3 | Preview generation failed | Report error, continue (preview is non-critical) |
-| 4 | Manifest build failed | Report error, package still usable without knowhow |
-| 4 | codify-to-knowhow failed | Report error, manifest remains for manual retry |
+| 3 | Preview generation failed | Report error, continue (preview is non-critical); flag preview.html/css as [LOW CONFIDENCE] (preview generation failed) |
+| 4 | Manifest build failed | Report error, package still usable without knowhow; flag knowhow assets as [LOW CONFIDENCE] (manifest build failed) |
+| 4 | codify-to-knowhow failed | Report error, manifest remains for manual retry; flag knowhow/spec entries as [LOW CONFIDENCE] (codify-to-knowhow failed) |
 
 ## Completion Message
 
+Glob all listed output files MUST exist before completion message; BLOCKED if missing.
+
 ```
 UI Design System Codified!