maestro-flow 0.5.33 → 0.5.35

package/.claude/skills/maestro-help/phases/03-workflow-guide.md

@@ -123,18 +123,45 @@ const taskPatterns = [
 4. `/quality-auto-test [phase] --re-run` — 重跑失败场景
 ```
 
+**Odyssey 长周期循环** (深度自主):
+
+```markdown
+## Odyssey 长周期循环
+
+适用于需要深度考古、多轮诊断/修复/验证、知识泛化和持久化的复杂任务。
+每个 odyssey 命令都是自含闭环，自主循环直到完成。
+
+### 调试类
+1. `/odyssey-debug "问题描述"` — 考古→诊断→修复→确认→泛化→知识持久化
+
+### 代码改进
+1. `/odyssey-improve "改进目标"` — 多维审计→深度诊断→定向修复→验证→泛化
+
+### 审查修复
+1. `/odyssey-review-test-fix "审查范围"` — 考古→探索→多维审查→修复→泛化
+
+### 需求迭代
+1. `/odyssey-planex "需求描述"` — 计划→执行→严格验证→修复循环（直到验收通过）
+
+### UI 优化
+1. `/odyssey-ui "优化目标"` — 视觉调研→多维审计→发散探索→修复→验证
+```
+
 #### Step 4.3: 工作流全景图
 
 对需要全景视角的用户，展示 Mermaid 图：
 
 ```
-上游起源: brainstorm(发散) | blueprint(收敛) → 可选
+上游起源: brainstorm(发散) | blueprint(收敛) | grill(压力测试) → 可选
 理解层:   analyze "topic"(宏观) → scope_verdict 路由
 编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
 执行层:   plan → execute → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
-全自动: /maestro -y → (自动路由)
+全自动:   /maestro -y → (自动路由)
+Odyssey:  odyssey-debug / odyssey-improve / odyssey-planex / odyssey-ui → (自主循环)
+并行加速: swarm-workflow / universal-workflow → (多 agent 并发)
+智能导航: /maestro-next → (检测状态推荐下一步)
 ```
 
 #### Step 4.4: 关键概念说明
@@ -156,6 +183,11 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 - **Spec**: 项目约束规则（coding/arch/debug/test），自动注入到工作流
 - **Wiki**: 知识图谱，存储详细技术文档
 - **Ralph**: 自适应决策引擎，动态调整执行链
+- **Odyssey**: 长周期自主循环命令族（debug/improve/planex/ui/review-test-fix），自含考古→诊断→修复→泛化→知识持久化
+- **Swarm Workflow**: 将任务路由到固定 Workflow 脚本进行多 agent 并发执行
+- **Universal Workflow**: 动态生成对抗性 Workflow 脚本，支持复用和持久化
+- **Grill**: 在 brainstorm 之前的压力测试，用代码库现实检验想法/需求
+- **Next**: 智能导航，检测工作流状态并推荐最优下一步命令
 ```
 
 ### Mode 5: Beginner Onboarding
@@ -180,6 +212,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 | 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
 | 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
 | 9 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 10 | `/maestro-next` | 智能导航 | 不确定下一步时，自动检测状态推荐 |
 ```
 
 #### Step 5.2: 快速入门路径

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

@@ -293,7 +293,7 @@ Read `.workflow/state.json` and route by condition:
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
      "auto_mode": false,
      "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null,
-       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null },
+       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null, "grill_id": null },
      "steps": [{
        "index": 0, "type": "skill|decision",
        "skill": "", "args": "",
@@ -328,12 +328,27 @@ Read `.workflow/state.json` and route by condition:
 
 Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechanism**.
 
-1. **buildSkillCall**: replace placeholders `{phase}`/`{plan_dir}`/`{analysis_dir}`/`{brainstorm_dir}`/`{spec_session_id}`; append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map)
+1. **buildSkillCall**: replace placeholders + append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map):
+
+   | Placeholder | Source |
+   |-------------|--------|
+   | `{phase}` | session.phase |
+   | `{plan_dir}` | session.context.plan_dir |
+   | `{analysis_dir}` | session.context.analysis_dir |
+   | `{brainstorm_dir}` | session.context.brainstorm_dir |
+   | `{spec_session_id}` | session.context.spec_session_id |
+   | `{GRL}` | session.context.grill_id |
+   | `{ANL}` | session.analyze_macro_id |
+   | `{BLP}` | session.blueprint_id |
+   | `{intent}` | session.intent |
+
+   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `$skill {resolved_args}` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: capture summary; mark step `status="done"`. **Barrier-context update** (when step is a context-producing skill):
    | Skill | Read | Context Updates |
    |-------|------|-----------------|
+   | maestro-grill | grill-report.md, state.json | grill_id |
    | maestro-analyze | context.md, state.json | analysis_dir, gaps, phase |
    | maestro-plan | plan.json, .task/TASK-*.json | plan_dir, task_count |
    | maestro-brainstorm | .brainstorming/ | brainstorm_dir, features |

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -23,14 +23,22 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents per wave (default: 6)
+- `--concurrency N`: Max concurrent agents per wave (default: 6)
+- `-c, --continue`: Resume existing session
 - `--continue`: Resume existing session
 - `-q, --quick`: Skip exploration + scoring, Wave 3 only
 - `--gaps [ISS-ID]`: Issue root cause analysis. If ISS-ID: single issue. If omitted: all open/registered from issues.jsonl.
-- `--from <source>`: Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Resolves to context-package.json for upstream context inheritance.
+- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, analyze:ID, blueprint:BLP-xxx, @file, or path). Resolves to context-package.json via state.json artifact lookup for typed references, or direct path for @file/path.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, context-package.json (all modes), analysis.md + conclusions.json (full mode AND quick mode; quick writes minimal conclusions.json with `scope_verdict` + `implementation_scope[]` only)
+
+### Pre-load (runs unconditionally, including -y auto mode)
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. **Role Knowledge**: `maestro search --category debug` → select relevant → `maestro wiki load`
+5. All optional — proceed without if unavailable (log warning)
 </context>
 
 <interview_protocol>
@@ -310,8 +318,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions] [--review-only]"
+argument-hint: "[topic] [-y|--yes] [--concurrency N] [-c|--continue] [--count N] [--skip-questions] [--review-only]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -15,14 +15,31 @@ Wave 3 compares Decision Digests from each role's `analysis.md` §2 and patches
 <context>
 $ARGUMENTS — topic text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 6), `--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md)
+**Flags**: `-y` (auto), `--concurrency N` (default 6), `-c`/`--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md), `--from <source>` (load upstream context package)
+
+**--from resolution** (upstream context loading):
+```
+--from grill:ID     → state.json.artifacts[type=grill, id=ID].context_package → load context-package.json
+--from blueprint:ID → state.json.artifacts[type=blueprint, id=ID].context_package → load
+--from @file        → load file directly as context-package.json
+--from path/        → load path/context-package.json
+```
+When loaded, pre-seed guidance-specification.md with:
+- `constraints[status=locked]` → §4 locked decisions (skip in interview)
+- `domain.terminology[]` → §2 Concepts & Terminology (seed)
+- `non_goals[]` → §3 Non-Goals (seed)
+- `open_questions[]` → interview priority topics
+- `insights[]` → W2 role analysis context
+
+When `--from` is absent, auto-discover from state.json: latest `type=grill` artifact in same milestone → load its `context_package` if available. No match → proceed without upstream context.
 
 **9 valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
-### Pre-load specs
+### Pre-load
 1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
 2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
-3. Both optional — proceed without if unavailable.
+3. **Project context**: Read `.workflow/project.md` (if exists) → Validated requirements (already shipped) as constraints, Active requirements as current scope. Read `state.json.accumulated_context` → deferred items as brainstorming seeds, key_decisions as locked constraints.
+4. All optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
 
@@ -432,8 +449,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] context.md aggregates session results with next-step routing
 - [ ] Session sealed via finish-work (auto mode only)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Use when a confirmed plan is ready for implementation
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -75,8 +75,8 @@ $maestro-execute --continue "20260318-execute-P3-phase3"
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents within each wave (default: 5)
-- `--continue`: Resume existing session
+- `--concurrency N`: Max concurrent agents within each wave (default: 5)
+- `-c, --continue`: Resume existing session
 
 **Inner flags** (passed inside quotes):
 - `--auto-commit`: Atomic git commit after each task completion
@@ -335,6 +335,28 @@ After each wave: if blocked tasks exist, prompt user to continue or stop (AUTO_Y
 
 Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with error "Dependency {dep_id} blocked/failed".
 
+### Phase 2.5: Verification Gate
+
+**Objective**: Cross-validate execution results against convergence criteria using external model perspective.
+
+1. **Collect verification targets**: For each completed task, read `.summaries/TASK-{NNN}-summary.md` + convergence criteria from `.task/TASK-{NNN}.json`
+2. **Delegate verification**: Run `maestro delegate` with accumulated evidence:
+   ```
+   maestro delegate "PURPOSE: 验证执行结果是否满足 convergence criteria
+   TASK: 逐项检查 | 对照 criteria | 标注 pass/fail | 汇总 gaps
+   CONTEXT: @.summaries/ @.task/
+   EXPECTED: verification.json { tasks: [{ id, criteria_met: bool, gaps: [] }], overall_pass: bool }
+   CONSTRAINTS: 只验证不修改" --role analyze --mode analysis
+   ```
+3. **Write verification.json** to plan directory with per-task pass/fail and gap list
+4. **Gate decision**:
+   - `overall_pass == true` → proceed to Phase 3
+   - Critical gaps (task criteria all failed) → log warning, mark affected tasks as `needs_retry`
+   - Non-critical gaps → record as `concerns` in verification.json, proceed
+5. **Register VRF artifact**: `{ id: "VRF-{next}", type: "verify", scope, path: verification.json, depends_on: "EXC-{id}" }`
+
+Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
+
 ### Phase 3: Results Aggregation
 
 **Objective**: Update all state files and generate execution report.

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

@@ -110,8 +110,17 @@ Resume routing:
 - [ ] `context-package.json` generated with schema "context-package/1.0"
 - [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
 - [ ] Session sealed via finish-work
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
 description: Use when creating, revising, or verifying an execution plan for a phase or task
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -65,7 +65,7 @@ All mean: **follow the cycle anyway**.
 <context>
 $ARGUMENTS — phase number/text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 4), `--continue` (resume), `--dir <path>`, `--from <source>` (load upstream context directly: analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, path), `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
+**Flags**: `-y` (auto), `--concurrency N` (default 4), `-c`/`--continue` (resume), `--dir <path>`, `--from <source>` (load upstream context directly: analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, path), `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
 
 **Scope routing** (priority, per redesign §5.2):
 1. `--from analyze:ANL-xxx` → CONTEXT_DIR = ANL artifact path; scope=`standalone`
@@ -89,6 +89,14 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
 **Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+
+**D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
+```
+milestone_id = "ADH-{YYYYMMDD}-{slug}"
+state.json.milestones.push({ id: milestone_id, name: "{intent slug}", type: "adhoc", status: "active", phase_slugs: [] })
+state.json.current_milestone = milestone_id
+```
+**Exception**: `--from analyze:ANL-xxx` or `--from blueprint:BLP-xxx` → skip adhoc creation (upstream artifact provides milestone context or is intentionally milestone-free).
 </context>
 
 <csv_schema>
@@ -197,7 +205,22 @@ Each explores one angle: architecture (module boundaries, deps), patterns (simil
 Consumes all exploration findings + context.md + specs. Produces:
 - `plan.json`: summary, approach, task_ids, waves (with phase labels), confidence section
 - `.task/TASK-*.json`: each with read_first[], convergence.criteria[] (grep-verifiable), concrete action/implementation
-- Deep Work Rules: every task has read_first with file being modified + source of truth files
+
+**Deep Work Rules** (MANDATORY for every task):
+1. `read_first[]`: MUST contain the file being modified + source-of-truth files (tests, interfaces, schemas)
+2. `convergence.criteria[]`: MUST be grep-verifiable (e.g., `"src/auth.ts contains export function verifyToken("`) — no subjective language ("well-structured", "properly implemented")
+3. `action`: concrete implementation verb (create/modify/delete/refactor) + target path
+4. `implementation[]`: ordered steps with file:change pairs — each step < 60 min
+- Anti-pattern: `"Implement the feature"` (vague). Correct: `"Create src/auth.ts with verifyToken() and generateToken() functions using jsonwebtoken"`
+- Anti-pattern: `read_first: []` (empty). Every file change requires reading the target first.
+
+**Anti-splitting Rules**:
+1. One feature = one task (don't split "create auth module" into "create file" + "add exports")
+2. Group trivial changes (< 5 min each) into a single task
+3. `depends_on` only for genuine data/API dependencies, not arbitrary sequencing
+4. Task count guards: simple scope → 1-2 tasks, medium → 2-4, complex → 4-8
+
+**UI-observable criteria**: If plan touches UI paths (components/, pages/, styles/) or frontend keywords, at least 1 convergence criterion per delivery wave MUST be UI-observable (e.g., `"page renders without console errors"`, `"button click triggers API call"`).
 
 Verifies plan.json and every .task/*.json exists on disk before reporting completed; else report blocked.
 

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

@@ -426,6 +426,9 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
     - `analyze_macro_id` 存在且当前 step 是 `roadmap` → args 改为 `--from analyze:{analyze_macro_id}`
     - `analyze_macro_id` 存在且 `scope_verdict ∈ {medium, small}` 且当前 step 是 `plan` → args 改为 `--from analyze:{analyze_macro_id}`
     - `blueprint_id` 存在 → 当前 step 是 `plan` → args 改为 `--from blueprint:{blueprint_id}`（优先级低于 phase 数字参数）
+    - **phase-level deferred chaining**（独立模式，step 含 `{phase}` 占位符）：build 阶段前序 artifact 尚未产出，由 A_RESOLVE_ARGS（ralph-execute）运行时从 state.json 查找同 phase+milestone 最新 completed artifact 注入：
+      - `plan` step → `--from analyze:{phase_analyze_id}`，写 `source_artifact_ref`
+      - `execute` step → `--dir {plan_path}`（现有逻辑），写 `source_artifact_ref = "plan:{id}"`
     - 写入 `step.source_artifact_ref` 以便审计
 13. **D-007 Milestone-ref 标注**：每个含 `{phase}` 占位符的 step → `step.milestone_id = session.milestone`（由 A_RESOLVE_PHASE 反查得出），禁止读 `current_milestone`
 14. **动态插入步骤**（A_APPLY_*）同样应用规则 7-13
@@ -761,5 +764,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
 - [ ] Ralph 不执行 step，只 evaluate；`$maestro-ralph-execute` 直调 handoff
 - [ ] session.platform = "codex"；所有 CLI 调用携带 `--platform codex`
+- [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
+- [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
+- [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
 
 </appendix>

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

@@ -128,19 +128,44 @@ S_FALLBACK:
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-execute | phase or --dir | see --from auto-injection below |
 | quality-debug | gap context | Read previous step's error/gap |
 | quality-* | phase | `{phase}` |
 
-**Artifact dir resolution for --dir:**
+**--from auto-injection (phase-level artifact chaining):**
+
+Phase-level steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
+
 ```
-Read state.json → filter artifacts by milestone + phase
-plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
-execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+Read state.json.artifacts（含 milestone_history 内归档 artifacts）
+→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+
+plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+  2. 命中 → args 追加 --from analyze:{id}
+  3. 写 step.source_artifact_ref = "analyze:{id}"
+
+execute step（含 {phase} 占位符，args 无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="plan" artifact → id = PLN-xxx, path = scratch/...
+  2. 命中 → args 追加 --dir .workflow/scratch/{path}
+  3. 写 step.source_artifact_ref = "plan:{id}"
 ```
 
-Write enriched args back to status.json.
+兜底：查询无结果 → 不注入，由命令自身 discovery 逻辑处理。已有 `--from` 或 `--dir` 的 step 不覆盖。
+
+**Goal context injection:**
+
+当 step.goal_ref 非空且 session.task_decomposition 存在时：
+```
+goal = session.task_decomposition.find(g => g.id == step.goal_ref)
+if goal:
+  goal_snippet = { id: goal.id, goal: goal.goal, done_when: goal.done_when,
+                   boundary: goal.boundary, evidence: goal.evidence }
+  → 传递给 A_EXEC_STEP 用于 inline execution 前注入（见 step 2 goal context pre-injection）
+```
+
+Write enriched args + source_artifact_ref back to status.json.
 
 ### A_EXEC_DECISION
 
@@ -156,13 +181,24 @@ Write enriched args back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-3. **Complete**:
+2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+   ```
+   <goal_context>
+   Sub-goal: {goal.id} — {goal.goal}
+   Done when: {goal.done_when}
+   Boundary: {goal.boundary}
+   Evidence target: {goal.evidence}
+   Execution criteria: {session.execution_criteria joined by '; '}
+   </goal_context>
+   ```
+   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
+3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+4. **Complete**:
    - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
    - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
    - `Bash("maestro ralph retry N")`
    - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
-4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `$maestro-ralph-execute` 直调自调用。
 
@@ -240,5 +276,10 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
 - [ ] 只处理 session.platform == "codex" 的会话
+- [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
+- [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
+- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
+- [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
 
 </appendix>

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

@@ -29,6 +29,11 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-roadmap-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
+
+### Pre-load (runs unconditionally, including -y auto mode)
+1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge for dependency and scope analysis
+3. All optional — proceed without if unavailable (log warning)
 </context>
 
 <interview_protocol>
@@ -176,7 +181,22 @@ Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depen
 3. Generate context.md (summary + analysis findings + roadmap stats)
 4. Write .workflow/roadmap.md with Milestone > Phase hierarchy
 5. Update state.json milestones + current_milestone
-6. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
+6. **Generate context-package.json** (schema `context-package/1.0`):
+   ```jsonc
+   {
+     "$schema": "context-package/1.0",
+     "source": { "type": "roadmap", "artifact_id": "RDM-{id}", "session_path": "...", "generated_at": "..." },
+     "requirements": [],       // from milestone phase goals → { id, title, acceptance }
+     "constraints": [],         // from scope decisions → locked items
+     "domain": {},              // inherit from upstream --from context-package if loaded
+     "non_goals": [],           // deferred scope items
+     "insights": [],            // from risk analysis and dependency findings
+     "open_questions": [],      // unresolved scope areas
+     "references": [{ "type": "roadmap", "path": "roadmap.md" }]
+   }
+   ```
+   Register `context_package` path in RDM artifact entry so downstream `--from roadmap:ID` can resolve.
+7. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
 
 </actions>
 
@@ -215,5 +235,14 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] context.md generated
 - [ ] Uncertainty assessed, strategy selected, milestones with phases + success criteria
 - [ ] Artifact registered in state.json with milestone entries
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
+
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
 </output>

package/.codex/skills/manage-harvest/SKILL.md

@@ -57,6 +57,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 4. **Never modify source artifacts** — purely extractive
 5. **Confidence filtering** — below threshold logged but not routed
 6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `title`, `description`, `keywords`, `date`, `source="harvest"` attributes
+7. **Conflict pre-check on spec routing** — when routing to spec, compare new entry against existing specs with same keywords/category. If semantic conflict detected, set `confidence="low"` on the new entry and log conflict note. Use `maestro spec conflict mark` if contradiction is clear
 
 **Routing rules:**
 - Universal design patterns → `coding` or `arch` category
@@ -66,7 +67,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 - Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `$spec-add "<category> <content>"`
 - Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
 
-**Next steps:** `$manage-wiki health`, `maestro search --type note`, `$wiki-connect --fix`, `$wiki-digest`, `$manage-issue list --source harvest`
+**Next steps:** `$manage-wiki health`, `maestro search --type note`, `$wiki-connect --fix`, `$wiki-digest`, `$manage-issue list --source harvest`, `$manage-knowledge-audit --scope spec` (when specs extracted, check for conflicts)
 
 **Prune mode** (`--prune`): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from `artifacts[]` → `artifact_archive[]`, prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
 </execution>

package/.codex/skills/quality-review/SKILL.md

@@ -197,7 +197,7 @@ Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
 If `--dimensions` flag provided, override with explicit list.
 
-6. **Specs loading**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools (unless `--skip-specs`)
+6. **Specs loading**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools (unless `--skip-specs`). Also run `maestro spec conflict list` to load existing conflict markers (review should prioritize verifying contested entries against code)
 7. **CSV generation**: One row per dimension + one aggregation row
 
 **Wave computation**: Simple 2-wave -- all dimension tasks = wave 1, aggregation = wave 2.
@@ -352,11 +352,13 @@ Generate `context.md`:
 | standard | critical + high |
 | deep | critical + high + medium |
 
+**Spec conflict check**: If any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark <file> <line> --note "<evidence>"` on the spec entry. Code is the single source of truth. Log spec conflicts in review.json as `spec_conflicts[]`.
+
 **Phase index update**: Update `{artifact_dir}/index.json` with review status.
 
 **Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
 
-Display summary.
+Display summary. If spec conflicts detected, suggest: `maestro spec conflict list` → `$manage-knowledge-audit --scope spec`.
 
 ### Shared Discovery Board Protocol
 
@@ -411,4 +413,13 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"s
 - [ ] Issues auto-created for qualifying severity findings
 - [ ] Phase index.json updated with review status
 - [ ] discoveries.ndjson append-only throughout
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
+
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>