maestro-flow 0.5.34 → 0.5.36

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

@@ -9,8 +9,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Task companion command — pairs with any task to provide knowledge context loading,
 structured companion document recording, insight capture, and skill routing.
 
-Does not create sessions or modify workflow state. Pure side-car utility.
-
 Four modes:
 - **before** — Pre-task: load spec + knowhow index + codebase index, create companion doc
 - **note** — Mid-task: append a structured entry to the active companion doc

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-fork/SKILL.md

@@ -12,8 +12,6 @@ the worktree. Since `.workflow/` is gitignored, this command explicitly copies p
 and milestone scratch artifacts into the worktree.
 
 Also supports `--sync` mode to pull latest main into an active worktree.
-
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
 </purpose>
 
 <required_reading>

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

@@ -7,7 +7,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 <purpose>
 Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time — challenging vague terminology against existing code, probing edge cases with concrete scenarios, and verifying assumptions with code evidence. Produces a verified context package (grill-report.md + terminology.md + context-package.json) for downstream brainstorm/analyze/roadmap consumption.
 
-Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; brainstorm generates and elaborates.
 
 Codex specifics:
 - **No agent spawning** — codebase exploration runs directly via Glob/Grep/Read in coordinator context.
@@ -110,8 +109,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-next/SKILL.md

@@ -19,10 +19,6 @@ Codex specifics:
 - **Skill pool discovery via CLI** — `maestro ralph skills --platform codex --json --quiet`（project `.codex/skills/` 覆盖 global `~/.codex/skills/`）
 - **No session, no status.json, no goal** — 不调 `create_goal` / `update_plan`，由目标 skill 自行管理产出
 
-与 `$maestro` / `$maestro-ralph` 区别：
-- 不创建 session、不构建 chain、不写 status.json
-- 始终只推 1 个 top pick，最多列 2-3 个备选
-- 适用场景：意图清晰且单步即可完成；或需要定向推荐时
 </purpose>
 
 <context>
@@ -132,7 +128,8 @@ ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
 | 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |
-| 测试全绿 | milestone-audit | `maestro-milestone-audit` |
+| 测试全绿 + current_milestone 存在 | milestone-audit | `maestro-milestone-audit` |
+| 测试全绿 + current_milestone=null (standalone) | review-done | 回退到 `quality-review` 或 `manage-status`（无 milestone 上下文时不推荐 milestone 命令） |
 | 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
 | 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
 
@@ -155,6 +152,16 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
 | Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
 | Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
+| **前置条件不满足** | **禁止** | 候选 skill 的前置条件未满足时，直接从候选池移除（如 `maestro-milestone-*` 在 `current_milestone=null` 时移除） |
+
+**前置条件检查（评分前执行，不满足则移除候选）：**
+
+| Skill | 前置条件 |
+|-------|---------|
+| `maestro-milestone-audit` | `current_milestone` 存在且非 null |
+| `maestro-milestone-complete` | `current_milestone` 存在且非 null |
+| `maestro-milestone-release` | `current_milestone` 存在且非 null |
+| `maestro-merge` | 存在活跃的 fork 分支 |
 
 **特殊意图处理：**
 

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>
@@ -145,8 +153,13 @@ S_WAVE_1 → S_WAVE_2    DO: spawn parallel explorations, merge results, build p
 
 S_WAVE_2 → S_CHECK     DO: spawn planning agent, merge results
 
-S_CHECK → S_CONFIRM    WHEN: plan passes or max 3 iterations    DO: A_PLAN_CHECK
-S_CHECK → S_WAVE_2     WHEN: plan fails check, iterations < 3   DO: feed checker feedback back
+S_CHECK → S_BOUNDARY_GRILL  WHEN: plan passes or max 3 iterations    DO: A_PLAN_CHECK
+S_CHECK → S_WAVE_2         WHEN: plan fails check, iterations < 3   DO: feed checker feedback back
+
+S_BOUNDARY_GRILL:
+  → S_CONFIRM    WHEN: no boundary conflicts detected     DO: —
+  → S_CONFIRM    WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_CONFIRM → S_REGISTER WHEN: -y OR user confirms
 S_CONFIRM → S_CSV_GEN  WHEN: user wants to modify
@@ -197,10 +210,32 @@ 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.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after plan-checker pass.
+Input: plan.json tasks + convergence criteria + upstream context. Scope guard: "only plan scope; do not re-analyze or re-scope".
+IF conflicts → results to plan.json `boundary_grill` section + affected TASK files. DEC conflicts add `boundary_warning` to confidence.
+Non-blocking: warnings, not hard stops.
+
 ### A_PLAN_CHECK
 Run plan-checker: coverage, dependency validity, criteria quality, pressure pass on highest-complexity task.
 Confidence: 5-dimension factor model + readiness gate.
@@ -240,6 +275,9 @@ Collision detection against same-milestone plans.
 - [ ] .task/TASK-*.json with read_first[] (file being modified + source of truth files)
 - [ ] Every task has convergence.criteria[] with grep-verifiable conditions (no subjective language)
 - [ ] Every task action and implementation contain concrete values (no "align X with Y")
+- [ ] Boundary grill executed after plan-checker pass (skip if no conflicts detected)
+- [ ] Boundary grill results written to plan.json `boundary_grill` section (if conflicts found)
+- [ ] DEC conflicts reflected in confidence `boundary_warning` factor
 - [ ] Plan confidence scored with 5-dimension factor model
 - [ ] Readiness gate checked before collision detection
 - [ ] Pressure pass completed on highest-complexity task

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

@@ -294,7 +294,8 @@ resolve_milestone(phase_number):
 |-----------|----------|
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
-| uat.md: all passed | `milestone-audit` |
+| uat.md: all passed + `session.milestone` 存在 | `milestone-audit` |
+| uat.md: all passed + `session.milestone=null` (standalone) | 标记 session completed（无 milestone 可审计） |
 | uat.md: has failures | `test-failed` |
 
 ### A_DETERMINE_QUALITY_MODE
@@ -376,7 +377,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 
 ### A_BUILD_STEPS
 
-Generate steps from `session.lifecycle_position` to `milestone-complete`.
+Generate steps from `session.lifecycle_position` to `milestone-complete`（`session.milestone` 存在时）或最后一个质量门（standalone 时）。
 
 | Stage | Skill (independent) | Skill (unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
@@ -408,7 +409,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
-6. **终点硬约束**：chain 以 `milestone-complete` 结尾
+6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
@@ -426,6 +427,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 +765,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

@@ -11,8 +11,6 @@ Generate a milestone/phase roadmap using `spawn_agents_on_csv` with 2-wave analy
 Wave 1: parallel analysis (scope, risk, dependency). Wave 2: assembly -> roadmap.md with Milestone > Phase hierarchy.
 
 Additional: `--revise` (modify existing roadmap), `--review` (read-only health check).
-
-For formal specification documents (Product Brief, PRD, Architecture, Epics), use `maestro-blueprint` instead.
 </purpose>
 
 <context>
@@ -29,6 +27,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 +179,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 +233,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-wiki/SKILL.md

@@ -7,8 +7,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 
 <purpose>
 Unified wiki graph management. Health monitoring, interactive search, orphan cleanup, and graph statistics. Day-to-day operations to keep the knowledge graph healthy.
-
-Complements `wiki-connect` (link discovery) and `wiki-digest` (synthesis) with operational tooling.
 </purpose>
 
 <required_reading>

package/.codex/skills/odyssey-debug/SKILL.md

@@ -8,8 +8,6 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 <purpose>
 Closed-loop deep debugging: archaeology (what changed) → explore (call chains, error gaps) → diagnose (hypothesis-driven) → fix & confirm → generalize (举一反三) → discover siblings → persist learnings.
 
-Unlike `quality-debug` (fast fix), this treats every bug as a learning signal — digs into git history before hypotheses, confirms fixes with CLI review, scans for siblings of the root cause.
-
 Core philosophy:
 - **Archaeology before hypothesis** — look at what changed before guessing why
 - **Fix one, find many** — a single bug reveals a class of bugs

package/.codex/skills/odyssey-improve/SKILL.md

@@ -9,12 +9,6 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 Deep codebase improvement: survey (dependency + complexity baseline) -> audit (6 dimensions) ->
 diagnose (root cause analysis) -> fix -> verify -> generalize -> discover -> record.
 
-Unlike `$quality-review` (single pass), this is a persistent session with evidence trails,
-baseline metrics, iterative improvement, and codebase-wide generalization. `--skip-fix` for audit-only.
-
-Focuses on **program runtime quality** — performance, security, architecture, reliability,
-observability, maintainability. Combines static analysis with runtime-aware reasoning.
-
 Core philosophy:
 - **Measure before improving** — baseline first, then optimize
 - **Root cause over symptom** — trace each issue to its origin

package/.codex/skills/odyssey-review-test-fix/SKILL.md

@@ -9,9 +9,6 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 Deep code review with generalization: archaeology → explore → multi-dimensional review →
 fix all findings → confirm → generalize (举一反三) → discover → persist.
 
-Unlike `quality-review` (pipeline gate verdict), this reviews AND fixes: exhaustive documentation,
-targeted fixes, codebase-wide generalization, decision journal. `--skip-fix` for review-only.
-
 **三句哲学约束（穷尽迭代）:**
 1. **零遗留** — 每个 finding 必须是 action item（修复 / issue / 决策），不允许只报告不处理
 2. **穷尽迭代** — 按 severity 从高到低逐轮修复，直到 0 remaining actionable findings 才退出 fix loop

package/.codex/skills/odyssey-ui/SKILL.md

@@ -9,9 +9,6 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 Deep UI polish cycle: survey (design tokens + pattern inventory) -> audit (6 dimensions) ->
 diverge (creative exploration) -> fix -> verify -> generalize -> discover -> record.
 
-Unlike `$maestro-impeccable` (single command), this is a persistent session with evidence trails,
-decision journal, iterative improvement, and codebase-wide generalization. `--skip-fix` for audit-only.
-
 Core philosophy:
 - **Every pixel tells a story** — subtle details create the experience
 - **Diverge before converge** — explore creatively, then implement methodically

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

@@ -413,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>

package/.codex/skills/spec-setup/SKILL.md

@@ -9,8 +9,6 @@ allowed-tools: Read, Write, Bash, Glob, Grep
 Initialize project specs by scanning the codebase and generating spec files in `.workflow/specs/`.
 Core files (coding, arch, learning) always created. Optional files created only when relevant signals detected.
 
-Triggered automatically by `maestro-init` for **existing projects** (source files detected). Greenfield projects skip this — specs are populated progressively by analyze, plan, and execute stages.
-
 ```bash
 $spec-setup
 ```

package/.codex/skills/team-coordinate/SKILL.md

@@ -7,9 +7,6 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 
 <purpose>
 Wave-based multi-role coordination via `spawn_agents_on_csv`. Dynamic role generation + linear wave execution with per-wave evaluation gates.
-
-**Core difference from other team skills**: Roles are NOT predefined — they are dynamically generated from task analysis at runtime. Each role's behavioral instructions are encoded directly into the CSV `description` column, eliminating the need for role-spec files.
-
 **Core workflow**: Analyze Task → Generate Dynamic Roles → Build CSV → Wave-by-Wave Execution with Evaluation → Aggregate Results
 
 ```

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -1,7 +1,5 @@
 # Team Lifecycle v4 — Agent Instruction
 
-This instruction is loaded by team-worker agents when spawned with roles: `analyst`, `writer`, `planner`, `executor`, `tester`, `reviewer`.
-
 ---
 
 ## Role-Based Execution

package/README.md

@@ -36,7 +36,7 @@ Maestro-Flow is built on two interconnected systems that reinforce each other:
           ┌──────────────┴──────────────┐  ┌──────────────────┴───────────────┐
           │   Workflow Orchestration     │  │      Knowledge System            │
           │                             │  │                                  │
-          │  Intent Router              │  │  Knowledge Graph (SQLite)        │
+          │  Intent Router              │  │  MaestroGraph (SQLite)            │
           │    └─ 40+ chain types       │  │    └─ Code + Knowledge unified   │
           │  Ralph Decision Engine      │  │  Spec Injection (Hooks)          │
           │    └─ 11-state FSM          │  │    └─ Auto-inject into prompts   │
@@ -67,6 +67,8 @@ maestro install
 
 **Prerequisites**: Node.js ≥ 18, Claude Code CLI. Optional: Codex CLI, Gemini CLI for multi-agent workflows.
 
+`maestro install` provides an interactive component selector — choose which assets (commands, hooks, MCP, agents) to install. Use `maestro workspace link` to share knowledge (specs, knowhow, domain) across multiple projects.
+
 ---
 
 ## Quick Start
@@ -95,6 +97,18 @@ Ralph automatically determines where you are (brainstorm → plan → execute
 | `/maestro-quick` | Quick fixes, small features (analyze → plan → execute) |
 | `/maestro-*` | Step-by-step: brainstorm, blueprint, analyze, plan, execute, verify |
 
+### Odyssey — Long-Running Iterative Cycles
+
+Odyssey commands run extended, self-correcting loops that combine archaeology, diagnosis, fix, verification, and knowledge persistence until acceptance criteria are met:
+
+| Command | Focus |
+|---------|-------|
+| `odyssey-debug` | Debug cycle — archaeology, diagnosis, fix, confirmation, generalization |
+| `odyssey-planex` | Requirement-driven cycle — plan, execute, strict verify, fix loop |
+| `odyssey-improve` | Codebase improvement — multi-dimensional audit, targeted fix, verify |
+| `odyssey-review-test-fix` | Deep review + fix — multi-dimensional review, targeted fix, generalization |
+| `odyssey-ui` | UI optimization — visual survey, audit, divergent exploration, fix |
+
 ---
 
 ## Workflow Orchestration
@@ -159,9 +173,9 @@ These patterns compose: a team coordinator can delegate subtasks to different LL
 
 ## Knowledge System
 
-### Knowledge Graph
+### Knowledge Graph (MaestroGraph)
 
-A SQLite-backed unified graph that stores both **code structure** (functions, classes, call chains via tree-sitter extraction) and **project knowledge** (specs, knowhow, domain terms, issues) in one queryable structure.
+**MaestroGraph** is the unified code index engine that replaces the former CodeGraph dependency. Built on `web-tree-sitter` for AST-level extraction, it stores both **code structure** (functions, classes, call chains) and **project knowledge** (specs, knowhow, domain terms, issues) in a single SQLite-backed graph with dual FTS5 indexes.
 
 ```bash
 maestro kg search <symbol>        # Find nodes
@@ -187,6 +201,10 @@ Agent executes task
 
 Four learning tools feed this cycle: `learn-retro` (retrospective), `learn-follow` (pattern study), `learn-decompose` (architecture breakdown), `learn-investigate` (deep dive).
 
+### Domain Knowledge
+
+A semantic glossary layer that defines **what things mean** in your project. Domain terms (`maestro domain`) standardize terminology, map concept relationships, and serve as a MaestroGraph knowledge source — bridging the gap between code-level symbols and business-level concepts.
+
 ### Wiki & Search
 
 WikiIndexer walks the `.workflow/` directory, parses frontmatter, builds backlink graphs, and creates a **BM25 inverted index** for full-text search across all project knowledge — specs, knowhow, issues, and KG nodes as virtual entries.
@@ -225,7 +243,7 @@ Built with React 19, Zustand, Tailwind CSS 4, Framer Motion, Hono, WebSocket.
 
 | Metric | Count |
 |--------|-------|
-| Source files (TypeScript) | 446 |
+| Source files (TypeScript) | 454 |
 | Lines of code | ~111,000 |
 | Slash commands | 64 |
 | Workflow definitions | 115 |
@@ -233,7 +251,7 @@ Built with React 19, Zustand, Tailwind CSS 4, Framer Motion, Hono, WebSocket.
 | Agent definitions | 23 |
 | CLI commands | 32 |
 | Templates | 92 |
-| Guides (bilingual) | 66 |
+| Guides (bilingual) | 67 |
 
 ### Tech Stack
 
@@ -277,6 +295,7 @@ maestro/
 
 **Getting Started**
 - **[Quick Start Guide](guide/quick-start-guide.en.md)** — Install, first workflow, key concepts
+- **[Install Guide](guide/install-guide.md)** — Step-by-step installation, component selection, workspace setup
 - **[Maestro Ralph Guide](guide/maestro-ralph-guide.en.md)** — Adaptive lifecycle engine, decision nodes, quality modes
 
 **Workflow**
@@ -288,6 +307,9 @@ maestro/
 
 **Knowledge**
 - **[Knowledge Management Guide](guide/knowledge-management-guide.en.md)** — KG, specs, knowhow, wiki
+- **[Search System Guide](guide/search-system-guide.md)** — Unified BM25F search, MaestroGraph integration, type filtering
+- **[MaestroGraph Plan](guide/plan-maestrograph.md)** — Unified KG engine design, CodeGraph replacement, tree-sitter integration
+- **[Domain Knowledge Plan](guide/plan-domain-knowledge.md)** — Semantic glossary, term relationships, concept layer
 - **[Spec System Guide](guide/spec-system-guide.en.md)** — Spec entries, keyword loading, validation hooks
 - **[Hooks Guide](guide/hooks-guide.en.md)** — 17 hooks, spec injection, context budget
 - **[Learning Tools Guide](guide/learn-tools-guide.en.md)** — Retro, follow, decompose, investigate
@@ -296,6 +318,7 @@ maestro/
 - **[Delegate Async Guide](guide/delegate-async-guide.en.md)** — Multi-CLI delegation, message injection, chaining
 - **[Overlay Guide](guide/overlay-guide.en.md)** — Non-invasive command extensions
 - **[Worktree Guide](guide/worktree-guide.en.md)** — Milestone-level parallel development
+- **[Workspace Guide](guide/workspace-guide.md)** — Cross-workspace knowledge sharing, link/unlink
 - **[MCP Tools Reference](guide/mcp-tools-guide.en.md)** — All 9 MCP endpoint tools
 - **[Collab Guide](guide/team-lite-guide.en.md)** — 2-8 person team collaboration