maestro-flow 0.5.34 → 0.5.36

package/.claude/commands/domain-add.md

@@ -0,0 +1,69 @@
+---
+name: domain-add
+description: Register a domain term into project glossary
+argument-hint: "<canonical> \"<definition>\""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are automatically injected into agent context via hooks (domain-compact for all prompts, domain-expanded on keyword match).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/domain-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<canonical> "<definition>"`
+
+**Examples:**
+```bash
+/domain-add auth-token "Short-lived credential for API authentication"
+/domain-add event-bus "Central pub-sub message broker for cross-module communication"
+/domain-add 会话上下文 "Runtime state container for active workflow session"
+```
+
+Domain term lifecycle: discover/manual → register → active → (optional) deprecated → removed.
+
+**Related commands:**
+- `maestro domain list` — list all registered terms
+- `maestro domain discover` — scan codebase for term candidates
+- `maestro domain show <canonical>` — show term details
+- `maestro domain deprecate <canonical> --successor <new>` — deprecate a term
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/domain-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Canonical name and definition are both required | parse_input |
+| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first | validate |
+| E003 | fatal | Term already registered with same canonical name | duplicate_check |
+| E004 | warning | Near-match found — confirm merge or create new | duplicate_check |
+</error_codes>
+
+<success_criteria>
+- [ ] Canonical name and definition parsed and validated
+- [ ] No duplicate term in glossary (or user confirmed near-match)
+- [ ] Aliases and keywords auto-extracted from definition
+- [ ] Term written to glossary.yaml with tier and relationships
+- [ ] Confirmation displayed with term details and verify command
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify term added | `maestro domain show <canonical>` |
+| Add more terms | `/domain-add <canonical> "<definition>"` |
+| Discover candidates | `maestro domain discover` |
+| List all terms | `maestro domain list` |
+</completion>

package/.claude/commands/maestro-amend.md

@@ -12,8 +12,6 @@ allowed-tools:
 ---
 <purpose>
 Signal-driven overlay generator — collect workflow deficiency signals from multiple sources, diagnose which commands need amendment, batch-generate targeted overlays. All amendments use overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
-
-Differs from `/maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
 </purpose>
 
 <required_reading>

package/.claude/commands/maestro-analyze.md

@@ -23,6 +23,7 @@ Multi-dimensional analysis of a proposal, decision, or architecture choice via C
 <deferred_reading>
 - [state.json](~/.maestro/templates/state.json) — read when registering artifact
 - [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
 </deferred_reading>
 
 <context>
@@ -94,6 +95,12 @@ Every decision MUST trace to independently gathered evidence. Manual Read/Grep i
 
 Decisions without CLI/agent-sourced evidence MUST be flagged as LOW CONFIDENCE.
 
+### Boundary Grill (Step 5 → Step 6)
+
+After discussion rounds, BEFORE synthesis: run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+Input: discussion.md decisions + exploration-codebase.json. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
+IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
+
 ### Standard Mode Gates
 
 Gates 1-4 are defined in `analyze.md`. NEVER skip gates. NEVER substitute manual Read/Grep for agent/CLI exploration.
@@ -193,6 +200,8 @@ Full mode:
 - [ ] Confidence tracking initialized (Step 4.6) and re-scored each round (Step 5.8)
 - [ ] Readiness gate checked before synthesis (Step 5.10)
 - [ ] Pressure pass completed ≥ 1 time before Step 6
+- [ ] Boundary grill executed between Phase 4 and Phase 5 (skip if no conflicts detected)
+- [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
 - [ ] Confidence summary with factor decomposition written to analysis.md
 
 Gaps mode:

package/.claude/commands/maestro-brainstorm.md

@@ -25,6 +25,7 @@ Pipeline: grill (optional) → **brainstorm** → roadmap / analyze / blueprint.
 - [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
 - [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
 - [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in cross-role review)
 </deferred_reading>
 
 <context>
@@ -88,8 +89,14 @@ These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until
 - REQUIRED: Per-feature files `{role}/analysis-F-*.md` written for each feature in §10.
 - BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
 
-**GATE 3: Cross-Role Review → Completion** (Step 4.5 → Report)
+**GATE 2.5: Cross-Role Review → Boundary Grill** (Step 4.5 → Step 4.6)
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role-reviewer output.
+Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
+IF conflicts → results to `guidance-specification.md` §12.5 + feed into GATE 3. NON-BLOCKING.
+
+**GATE 3: Cross-Role Review → Completion** (Step 4.5/4.6 → Report)
 - REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
+- REQUIRED: Boundary grill completed (if conflicts detected, results logged).
 - REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
 - REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
 - BLOCKED if missing: complete review synthesis before reporting.
@@ -191,6 +198,8 @@ Status verdicts:
 - [ ] `ui-designer/analysis.md` references DESIGN.md visual constraints when ui-designer is selected
 - [ ] Each `{role}/analysis.md` §2 Decisions table has ≥ 1 row per feature
 - [ ] Cross-role review (Step 4.5) executed; reviewer compares §2 Decision Digests; output includes `patch_targets[]` for every finding
+- [ ] Boundary grill executed after cross-role review (skip if no conflicts detected)
+- [ ] Boundary grill results written to guidance-specification.md §12.5 (if conflicts found)
 - [ ] If findings exist: each accepted resolution applied via Edit (annotate / strikeout / append) AND logged in `guidance-specification.md` §12 "Cross-Role Resolutions"
 - [ ] If zero findings: final report explicitly states "No cross-role issues detected"; guidance §12 unchanged
 - [ ] Heading-drift patch failures surfaced in final report (if any)

package/.claude/commands/maestro-collab.md

@@ -73,7 +73,12 @@ S_COLLECT:
   GUARD: 1+ succeeded → continue with partial results (W001)
 
 S_CROSS_VERIFY:
-  → S_SYNTHESIZE    DO: A_CLASSIFY_FINDINGS
+  → S_BOUNDARY_GRILL  DO: A_CLASSIFY_FINDINGS
+
+S_BOUNDARY_GRILL:
+  → S_SYNTHESIZE    WHEN: no boundary conflicts detected     DO: —
+  → S_SYNTHESIZE    WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking
 
 S_SYNTHESIZE:
   → S_REGISTER      DO: A_GENERATE_OUTPUTS
@@ -134,6 +139,12 @@ Read all per-tool outputs. For each finding:
 consensus_level = consensus_count / total_findings * 100.
 If consensus_level < 40%: W003.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+Input: classified CONFLICT findings + per-tool outputs. Check upstream scope if `--from` used.
+IF conflicts → tag with resolution, feed into A_GENERATE_OUTPUTS. No conflicts → pass through.
+
 ### A_GENERATE_OUTPUTS
 
 Resolve conflicts via evidence-weighted voting:
@@ -160,6 +171,8 @@ Write 3 files:
 <success_criteria>
 - [ ] All delegates launched in parallel via Bash(run_in_background: true), STOP after launch
 - [ ] Cross-verification: consensus/conflict/unique classification with consensus_level
+- [ ] Boundary grill executed on CONFLICT items (skip if no boundary conflicts detected)
+- [ ] Boundary grill results written to collab-report.md § Boundary Grill Results (if conflicts found)
 - [ ] 3 output files produced (collab-report.md, context.md, conclusions.json)
 - [ ] CLB artifact registered in state.json
 - [ ] Partial degradation: continued if 1+ tools succeeded

package/.claude/commands/maestro-next.md

@@ -92,9 +92,9 @@ S_FALLBACK:
 读 project state 推断 `lifecycle_position`（核心信号）：
 
 ```bash
-cat .workflow/state.json 2>$null              # phase / milestone / artifacts
-ls -la .workflow/scratch/ 2>$null | head -10  # 最近 artifact (mtime DESC)
-ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
+cat .workflow/state.json 2>/dev/null              # phase / milestone / artifacts
+ls -la .workflow/scratch/ 2>/dev/null | head -10  # 最近 artifact (mtime DESC)
+ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 ```
 
 **项目状态 → lifecycle_position → 自然下一步：**
@@ -110,7 +110,8 @@ ls -la .workflow/.maestro/ 2>$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}` |
 
@@ -133,6 +134,16 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
 | Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
 | Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
+| **前置条件不满足** | **禁止** | 候选命令的前置条件未满足时，直接从候选池移除（如 `maestro-milestone-*` 在 `current_milestone=null` 时移除） |
+
+**前置条件检查（评分前执行，不满足则移除候选）：**
+
+| 命令 | 前置条件 |
+|------|---------|
+| `maestro-milestone-audit` | `current_milestone` 存在且非 null |
+| `maestro-milestone-complete` | `current_milestone` 存在且非 null |
+| `maestro-milestone-release` | `current_milestone` 存在且非 null |
+| `maestro-merge` | 存在活跃的 fork 分支 |
 
 **特殊意图处理：**
 

package/.claude/commands/maestro-overlay.md

@@ -21,7 +21,10 @@ Turn natural-language instructions into command overlays — JSON patch files th
 </required_reading>
 
 <context>
-**Overlay model** — an overlay is a JSON file with a `name`, one or more `targets` (command names without `.md`), and a list of `patches`. Each patch targets an XML section (`execution`, `required_reading`, `context`, `success_criteria`, etc.), a mode (`append`, `prepend`, `replace`, `new-section`), and `content`. On apply, the patcher wraps the content in hashed HTML-comment markers so re-apply is idempotent and removal is surgical.
+**Overlay model**:
+- JSON file: `name`, `targets[]` (command names), `patches[]`
+- Patch: `section` (XML tag), `mode` (append/prepend/replace/new-section), `content`
+- Apply: hashed HTML-comment markers (idempotent, surgical removal)
 
 **Where overlays live**
 - User overlays: `~/.maestro/overlays/*.json` — created by this skill
@@ -139,8 +142,6 @@ Run:
 maestro overlay add ~/.maestro/overlays/<slug>.json
 ```
 
-This validates the overlay, copies it into place (idempotent), and applies it across all known install scopes. On validation failure, fix the JSON and re-run.
-
 ### 5. Report
 
 Show the user:

package/.claude/commands/maestro-plan.md

@@ -25,6 +25,7 @@ Produces plan.json + TASK files; registers PLN artifact in state.json.
 - [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
 - [task.json](~/.maestro/templates/task.json) — read when generating task files
 - [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
 </deferred_reading>
 
 <context>
@@ -50,7 +51,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 
 **Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
 
-**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
+**`--from analyze:*` / `blueprint:*`**: scope=standalone → skip adhoc milestone auto-creation.
 
 ### Role Knowledge
 `maestro search --category arch` → select relevant → `maestro wiki load`
@@ -84,11 +85,19 @@ Follow '~/.maestro/workflows/plan.md' completely.
 - REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
 - BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.
 
+**GATE P3.5 → P4: Boundary Grill → Plan Check**
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+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.
+
 **GATE P4 → P5: Plan Check → User Confirmation**
 - REQUIRED: Plan-checker passed (or minor issues acknowledged).
+- REQUIRED: Boundary grill completed (conflicts resolved or accepted as risks).
 - REQUIRED: Confidence scored with 5-dimension factor model.
 - REQUIRED: Pressure pass completed on highest-complexity task.
-- BLOCKED if: plan-checker found critical issues — fix plan before presenting to user.
+- REQUIRED: If plan touches UI (检出 `dashboard/` 或 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`), each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical-slice delivery, not backend-only).
+- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage — fix plan before presenting to user.
 
 **GATE P5 → Completion: User Confirmation → Done**
 - REQUIRED: User confirmation captured (execute/modify/cancel).
@@ -150,8 +159,6 @@ For each created TASK-{NNN}.json that has issue_id:
   Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
 ```
 
-This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
-
 ### Mode: Revise / Check
 
 Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
@@ -213,7 +220,11 @@ Status verdicts:
 - [ ] .task/TASK-*.json files created for each task
 - [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
 - [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] UI plans: each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical slice; verified at runtime by ralph frontend-verify gate)
 - [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Boundary grill executed in P3.5 (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 in P4 with 5-dimension factor model
 - [ ] Plan readiness gate checked before P4.5 collision detection
 - [ ] Pressure pass completed on highest-complexity task

package/.claude/commands/maestro-ralph-execute.md

@@ -134,19 +134,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
 
@@ -162,13 +187,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 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
 
@@ -244,5 +280,10 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] --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>