maestro-flow 0.5.46 → 0.5.48

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] [--concurrency N] [-c|--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
+description: Use when creating, revising, or verifying an execution plan for a milestone or task
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<milestone> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -63,27 +63,24 @@ All mean: **follow the cycle anyway**.
 </tdd_mode>
 
 <context>
-$ARGUMENTS — phase number/text and optional flags.
+$ARGUMENTS — milestone number/text and optional flags.
 
-**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)
+**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`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
+
+> **`--collab` removed**: multi-agent collaborative planning is now automatic — milestones spanning >3 modules auto-trigger a 2+1 agent model (2 parallel planners scoped to 2-3 modules each + 1 synthesis agent that merges, runs DAG/cycle/conflict analysis, and produces a unified plan.json).
 
 **Scope routing** (priority, per redesign §5.2):
 1. `--from analyze:ANL-xxx` → CONTEXT_DIR = ANL artifact path; scope=`standalone`
 2. `--from blueprint:BLP-xxx` → CONTEXT_DIR = BLP path; scope=`standalone`
 3. `--dir <path>` → CONTEXT_DIR = path; scope=`standalone`
-4. Numeric arg + roadmap → scope=`phase`; D-007 reverse-lookup milestone via `state.json.milestones[].phase_slugs`
+4. Numeric arg + roadmap → scope=`milestone`; resolve milestone from roadmap
 5. No args + roadmap → scope=`milestone` (plans all pending phases in current milestone)
 6. No args + no roadmap → search `state.json.artifacts[]` for latest `type=="analyze"` (DESC by created_at). Found → scope=`standalone`, CONTEXT_DIR = artifact.path. None → ERROR E001.
 7. Text arg + no upstream → scope=`adhoc/standalone`
 
-**D-007 milestone reverse lookup** (numeric scope only):
-```
-resolve_milestone(phase_number):
-  for ms in state.json.milestones[]:
-    if str(phase_number) in ms.phase_slugs: return ms.id
-  return state.json.current_milestone   # fallback
-```
-Write resolved milestone into PLN artifact registration and `plan.json.milestone`; NEVER read `current_milestone` directly for phase-scoped runs.
+**Milestone resolution** (numeric scope only):
+  target_milestone = specified milestone number
+  IF not found in state.json.milestones[]: ERROR
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/`
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
@@ -139,7 +136,7 @@ S_REGISTER    — 注册 PLN artifact、更新 index.json           PERSIST: sta
 
 <transitions>
 S_PARSE → S_RESUME     WHEN: --continue
-S_PARSE → S_CONTEXT    WHEN: phase/dir/--from resolved (D-007 reverse lookup for numeric)
+S_PARSE → S_CONTEXT    WHEN: milestone/dir/--from resolved
 S_PARSE → S_CONTEXT    WHEN: no args + no roadmap AND latest analyze artifact found in state.json (scope=standalone). Interactive mode: confirm the auto-discovered artifact with user ("Using analyze artifact ANL-xxx from {date}. Proceed?"). -y mode: auto-proceed with log.
 S_PARSE → ERROR        WHEN: no args + no roadmap + no analyze artifact
 
@@ -253,7 +250,7 @@ Collision detection against same-milestone plans.
 1. Register PLN artifact in state.json (scope, milestone, phase, depends_on)
 2. Update index.json with plan metadata
 3. If --gaps: link TASK files back to issues bidirectionally (task_refs[], task_plan_dir in issues.jsonl)
-4. Display: phase, task count, wave count, check status, confidence
+4. Display: milestone, task count, wave count, check status, confidence
 5. **Next-step suggestion** (suggest only, NEVER auto-execute): display recommended next command (e.g., `maestro-execute {phase}`). The user decides whether to proceed.
 
 </actions>
@@ -292,7 +289,7 @@ Collision detection against same-milestone plans.
 - [ ] Pressure pass completed on highest-complexity task
 - [ ] Collision detection against same-milestone plans (non-blocking)
 - [ ] Plan-checker passed (or minor issues acknowledged, max 3 iterations)
-- [ ] PLN artifact registered in state.json (numeric scope: milestone resolved via D-007 `phase_slugs` reverse lookup, NOT direct `current_milestone` read)
+- [ ] PLN artifact registered in state.json (numeric scope: milestone resolved directly from arg)
 - [ ] No-args fallback honored: latest analyze artifact auto-discovered when roadmap absent (§5.2 priority 6)
 - [ ] If --gaps: issues linked bidirectionally (task_refs[], task_plan_dir in issues.jsonl)
 </success_criteria>

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

@@ -9,6 +9,8 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 Wave-based template executor via `spawn_agents_on_csv`. Load template → bind variables → topological sort → group into barrier/non-barrier waves → spawn wave-by-wave → read results → report.
 
 Session: `.workflow/.maestro/MCP-{YYYYMMDD-HHmmss}/state.json`
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/MCP-*/` (session state) and `.workflow/.csv-wave/` (wave CSVs). Template files at `~/.maestro/templates/workflows/` are read-only during playback.
 </purpose>
 
 <invariants>

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

@@ -28,6 +28,7 @@ $maestro-quick "add dark mode toggle to settings page" --discuss --full
 
 **Output**: `.workflow/scratch/{slug}/` with plan.json, execution results, optional verification
 
+**Output boundary**: ALL metadata writes MUST target `.workflow/scratch/{slug}/`. Source code modifications are scoped to files identified in the plan. NEVER modify unrelated source files or `.workflow/state.json` structure beyond scratch task entries.
 </context>
 
 <invariants>
@@ -40,6 +41,22 @@ $maestro-quick "add dark mode toggle to settings page" --discuss --full
 
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Context**
+- REQUIRED: Task description provided (non-empty).
+- BLOCKED if: empty description (E001).
+
+**GATE 2: Analysis → Plan**
+- REQUIRED: Quick analysis completed with related files identified.
+- REQUIRED: Existing patterns found (≥1 similar implementation).
+- BLOCKED if: scratch directory creation failed (E002).
+
+**GATE 3: Execute → Report**
+- REQUIRED: All plan tasks attempted and statuses recorded.
+- REQUIRED: `plan.json` updated with task outcomes.
+- BLOCKED if: plan.json missing or no task statuses.
+
 ### Step 1: Parse Arguments
 
 Extract from arguments:

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

@@ -90,7 +90,7 @@ Remaining                        → intent (amend_mode 时为 change_request)
 7. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform codex --json --quiet` 预校验（project 覆盖 global，限定 `.codex/skills/`），命中即写绝对路径到 status.json；未命中标 `command_scope = "missing"`
 8. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成：解析 frontmatter + `<required_reading>` + `<deferred_reading>`，自动读取 required 文件全文并拼入 prompt；缺失 required → 退出码 1（E007），pause session。ralph build 阶段只通过 `maestro ralph skills --platform codex` 校验路径存在性，不读 SKILL.md 内容
 9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；通过 `create_goal` 绑定目标，`update_goal` 在收敛时释放
-10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+10. **planning_mode governs arg granularity** — `unified` → skill args 无 phase/milestone 占位符；`independent` → analyze/plan 用 `{milestone}`，execute/quality 用 `{phase}`
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 12. **Platform** — `session.platform = "codex"`；CLI 调用一律带 `--platform codex`
 13. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons. Especially invariants about ralph never executing steps and completion_confirmed by CLI.
@@ -426,8 +426,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
 | init | `maestro-init` | *(same)* | — | all |
 | analyze-macro | `maestro-analyze "{intent}"` | *(same)* | `post-analyze-scope` | all |
 | roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | — | all |
-| analyze | `maestro-analyze {phase}` | `maestro-analyze` | — | all |
-| plan | `maestro-plan {phase}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | — | all |
+| analyze | `maestro-analyze {milestone}` | `maestro-analyze` | — | all |
+| plan | `maestro-plan {milestone}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | — | all |
 | execute | `maestro-execute {phase}` | `maestro-execute` | `post-execute` | all |
 | business-test | `quality-auto-test {phase}` | `quality-auto-test` | `post-business-test` | full only |
 | review | `quality-review {phase}` | `quality-review` | `post-review` | all (quick: append `--tier quick`) |
@@ -471,9 +471,9 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
     - `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}"`
+    - **deferred chaining**（独立模式）：build 阶段前序 artifact 尚未产出，由 A_RESOLVE_ARGS（ralph-execute）运行时从 state.json 查找并注入：
+      - `plan` step（含 `{milestone}` 占位符）→ 查同 milestone 最新 completed analyze artifact，`--from analyze:{milestone_analyze_id}`，写 `source_artifact_ref`
+      - `execute` step（含 `{phase}` 占位符）→ 查同 phase+milestone 最新 completed plan artifact，`--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
@@ -875,9 +875,9 @@ Decomposition 产出后通过 Codex 内置工具管理目标（由 A_DECOMPOSE_T
 - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
 - [ ] auto_confirm=true 时 grill step args 追加 `-y`（Auto mode 代码代答，stage 不跳过）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
-- [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
+- [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(milestone)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路
-- [ ] plan step args 支持三路径：`{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}`，写入 step.source_artifact_ref
+- [ ] plan step args 支持三路径：`{milestone}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}`，写入 step.source_artifact_ref
 - [ ] roadmap step args 自动注入 `--from analyze:{analyze_macro_id}`（若存在）
 - [ ] artifact 过滤按 session.phase；unified 按 milestone
 - [ ] quality_mode 由 A_DETERMINE_QUALITY_MODE 决定，过滤 build steps
@@ -889,13 +889,13 @@ Decomposition 产出后通过 Codex 内置工具管理目标（由 A_DECOMPOSE_T
 - [ ] 每个 sub-goal 含 `completion_confirmed`（初始 false）
 - [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前
 - [ ] Unmet sub-goals 动态 grow steps[]（goal_ref tagged）；max retries → escalate
-- [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
+- [ ] planning_mode 显式决定；unified=无占位符, independent=analyze/plan 带 `{milestone}`、execute/quality 带 `{phase}`
 - [ ] Chain 必须以 `milestone-complete` 结尾
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
 - [ ] Ralph 不执行 step，只 evaluate；`Skill(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 查找注入）
+- [ ] Deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
+- [ ] Milestone-level plan step 运行时获得 `--from analyze:{milestone_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
 - [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
 - [ ] 每个 step 含 `completion_summary` + `completion_decisions` + `completion_caveats` + `completion_deferred`（初始 null）
 - [ ] `completion_summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（由 CLI `--summary` 参数传入）

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

@@ -147,22 +147,22 @@ S_FALLBACK:
 |-------|-----------------|--------|
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
-| maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-analyze | milestone or topic | `{milestone}` or `"{intent}"` |
+| maestro-plan | milestone, --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}` |
 
-**--from auto-injection (phase-level artifact chaining):**
+**--from auto-injection (artifact chaining):**
 
-Phase-level steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
+Steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
 
 ```
 Read state.json.artifacts（含 milestone_history 内归档 artifacts）
-→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+→ filter by milestone={session.milestone} (+ phase={session.phase} for execute-step lookups) + status=="completed"
 
-plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
-  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+plan step（含 {milestone} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
   2. 命中 → args 追加 --from analyze:{id}
   3. 写 step.source_artifact_ref = "analyze:{id}"
 
@@ -366,7 +366,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。Skill(ma
 - [ ] 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：milestone-level plan step 运行时从 state.json 查找同 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：`ralph_protocol_version < "2"` → 前置 `<goal_context>` block；`>= "2"` → skip（session_anchor 覆盖）
 - [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria

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

@@ -25,10 +25,41 @@ $maestro-tools-execute
 ```
 
 Empty arguments enters interactive mode: list all tools for user selection.
+
+**Output boundary**: File writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST request_user_input before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via request_user_input (execute / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
 ### Step 1: Load Tool
 
 **By name** (search all categories first, then filter):

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -46,10 +46,39 @@ tool: true
 ---
 Step content...
 ```
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` (tool documents) and `.workflow/specs/` (ref entries) only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords/tags`, and `summary` in YAML frontmatter; missing fields → reject write
+2. **No duplicate names** — tool title MUST be unique within its category; duplicate detection → E002 warning with overwrite/optimize confirmation
+3. **Category required** — every tool MUST declare exactly one category from: coding, test, review, arch, debug; empty category → E003
+4. **Confirmation gate** — MUST request_user_input before writing knowhow document and spec ref entry; NEVER persist without user confirmation
+5. **Promote is in-place** — promote mode MUST update existing knowhow frontmatter; NEVER recreate the document
+6. **Output boundary** — ALL file writes MUST target `.workflow/knowhow/` (tool documents) and `.workflow/specs/` (ref entries) only. NEVER modify source code or files outside these paths
+7. **Description format** — first line after `### Title` MUST state "Use when ..." (usage timing); this is critical for ref entry summary visibility
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Gather**
+- REQUIRED: Mode determined (extract/generate/optimize/promote) from argument parsing.
+- REQUIRED: For optimize/promote modes, target tool/document exists and is loadable.
+- BLOCKED if: empty args without user response to request_user_input.
+
+**GATE 2: Gather → Write**
+- REQUIRED: Tool name, category, and usage timing confirmed.
+- REQUIRED: Steps extracted or generated (extract: ≥1 step, generate: user-confirmed scope).
+- REQUIRED: User confirmed via request_user_input (title, category, keywords, summary, step count).
+- BLOCKED if: E001 (`.workflow/specs/` not initialized), E003 (no category), user cancels.
+
+**GATE 3: Write → Verify**
+- REQUIRED: Knowhow document written with `tool: true` frontmatter (or updated in-place for promote).
+- BLOCKED if: write failed or spec add returned error.
+
 ### Step 1: Intent Detection
 
 Parse $ARGUMENTS to determine mode:

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -61,6 +61,8 @@ $maestro-ui-codify "src/styles" --output-dir .workflow/packages --overwrite -y
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final)
 **Package Output**: `{output-dir}/{package-name}/` with design-tokens.json, layout-templates.json, animation-tokens.json, preview.html, preview.css, knowhow-manifest.json
+
+**Output boundary**: ALL file writes MUST target `.workflow/.csv-wave/{session-id}/` (wave state), `{output-dir}/{package-name}/` (reference package), `.workflow/knowhow/` (knowledge assets), and `.workflow/specs/` (spec entries). NEVER modify source code files in the scanned directory.
 </context>
 
 <csv_schema>

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

@@ -27,10 +27,38 @@ $ARGUMENTS — optional flags.
 - `--setup-only` -- Skip schema migration, run only the setup for current version
 
 **Version source:** `.workflow/state.json` → `version` field
+
+**Output boundary**: ALL file writes MUST target `.workflow/state.json` (version bump), `.workflow/state.json.backup-*` (backup), and `.workflow/` config files touched by version-specific setup. NEVER modify source code or `src/migrations/` files.
 </context>
 
+<invariants>
+1. **Backup before migration** — a timestamped backup of `.workflow/state.json` MUST be created before any schema migration runs; NEVER execute migration without backup
+2. **Idempotent** — running update when already on latest version MUST be a no-op (display "up to date"); NEVER re-apply migrations
+3. **Confirmation before execute** — migration diff MUST be displayed and user MUST confirm via request_user_input before execution (unless `--force`); NEVER silently apply schema changes
+4. **Migration diff always visible** — even with `--force`, the migration diff MUST be displayed for audit visibility; NEVER skip diff display
+5. **Restore path on failure** — if migration fails, the backup restore command MUST be displayed; NEVER leave user without recovery instructions
+6. **Sequential migration** — all intermediate version steps MUST be applied in order by the schema registry; NEVER skip intermediate versions
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Detect → Check**
+- REQUIRED: Current version read from `.workflow/state.json`.
+- BLOCKED if: state.json missing or unreadable (E001).
+
+**GATE 2: Check → Execute**
+- REQUIRED: Dry-run migration check completed; target version identified.
+- REQUIRED: User confirmation via request_user_input (unless `--force`).
+- BLOCKED if: already up to date (display message and exit) or user cancels.
+
+**GATE 3: Execute → Summary**
+- REQUIRED: Backup created at `.workflow/state.json.backup-v{current}-{timestamp}`.
+- REQUIRED: Schema migration completed successfully.
+- REQUIRED: Version-specific setup doc followed (if exists).
+- BLOCKED if: migration failed — display restore command and exit.
+
 ### Step 1: Detect Version
 
 ```
@@ -68,6 +96,16 @@ Display version change, backup path, next steps.
 
 </execution>
 
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/state.json` missing or unreadable | Run `$maestro-init` first |
+| E002 | error | Migration script execution failed | Display backup restore command |
+| E003 | error | Version-specific setup doc not found | Skip setup, display manual steps |
+| W001 | warning | Already up to date | No action needed |
+| W002 | warning | Setup doc unavailable for target version | Continue without setup |
+</error_codes>
+
 <success_criteria>
 - [ ] Version detected, schema migration run, setup doc followed
 - [ ] --setup-only, --dry-run, --force flags handled

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -74,6 +74,8 @@ When `--yes` or `-y`: Auto-confirm rebuild (implies --force), skip all prompts.
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
 **Target**: `.workflow/codebase/` (doc-index.json, tech-registry/, feature-maps/)
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `.workflow/project.md` (Tech Stack section only). NEVER modify source code or files outside these paths.
 </context>
 
 <csv_schema>

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -22,8 +22,19 @@ $manage-codebase-refresh "--since 3d --deep"
 **Flags**:
 - `--since <date>` -- Override change detection window (ISO date or relative like `3d`)
 - `--deep` -- Force deeper re-scan even for minor changes
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/` (doc files, doc-index.json) and `.workflow/state.json` (codebase_last_refreshed timestamp) only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Incremental only** — MUST NOT clear or rebuild .workflow/codebase/; for full rebuild use `$manage-codebase-rebuild`
+2. **Change-driven** — MUST only update doc entries affected by detected git changes; NEVER refresh unchanged docs
+3. **Baseline resolution** — MUST resolve change baseline via --since flag > state.json timestamp > 7-day fallback; NEVER scan entire history
+4. **Doc-index alignment** — doc-index.json timestamps MUST be updated for every refreshed entry
+5. **KG impact awareness** — if knowledge-graph.json exists, MUST run kg diff-wiki and log affected wiki entries as warnings
+6. **No-op safety** — if no changes detected (W001), MUST exit cleanly without modifying any files
+</invariants>
+
 <execution>
 
 ### Step 1: Validate Preconditions

package/.codex/skills/manage-drift-realign/SKILL.md

@@ -81,6 +81,8 @@ $manage-drift-realign --continue "20260624-drift-realign"
 **Core Output**: `tasks.csv` + `results.csv` + `discoveries.ndjson` + `context.md`
 **Report Output**: `.workflow/.drift-realign/drift-report-{date}.md` + `drift-log.jsonl`
 
+**Output boundary**: ALL file writes MUST target `.workflow/` metadata files (specs, codebase docs, roadmap.md, state.json, issues.jsonl) or `.workflow/.trash/drift-realign-{timestamp}/` (backups) or `.workflow/.drift-realign/` (session details). NEVER modify source code files.
+
 **State files read**:
 - `.workflow/state.json` — project state + artifact registry
 - `.workflow/roadmap.md` — milestone/phase roadmap

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

@@ -34,6 +34,8 @@ $ARGUMENTS — session-id, path, or empty for scan mode.
 - `--prune` — State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context
 - `--age N` — Graduation age threshold in days (default: 14). Used with `--prune`
 
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/`, `.workflow/specs/`, `.workflow/issues/`, `.workflow/wiki/`, `.workflow/harvest/`, or `.workflow/state.json` only. NEVER modify source code, source artifacts, or files outside these paths.
+
 **Source registry:**
 | Source | Scan Path | Key Files |
 |--------|-----------|-----------|
@@ -47,17 +49,37 @@ $ARGUMENTS — session-id, path, or empty for scan mode.
 | learning | `.workflow/specs/` | learnings.md |
 </context>
 
+<invariants>
+1. **Read-only until routing** — extraction and classification happen in-memory; no files written until Stage 6
+2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
+3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
+4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
+5. **Conflict pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category; set `confidence="low"` and log conflict note if semantic conflict detected
+6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
+7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9 (`--prune` mode).
 
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction/classification in-memory only
-2. **Dedup before write** — check harvest-log.jsonl + existing stores
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
-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
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Extraction** (Stages 1-3 → Stage 4)
+- REQUIRED: Source artifacts discovered and mode resolved (scan/session/path).
+- REQUIRED: User selected artifact(s) to harvest (or auto-selected via session/path mode, or `-y`).
+- BLOCKED if no harvestable artifacts found (W001) or invalid source (E004/E005).
+
+**GATE 2: Extraction → Routing** (Stage 4 → Stage 5-6)
+- REQUIRED: All files in selected artifacts loaded and parsed.
+- REQUIRED: Knowledge fragments extracted with category, confidence, and tags.
+- REQUIRED: Fragments filtered by `--min-confidence`.
+- BLOCKED if extraction produces zero fragments.
+
+**GATE 3: Routing → Write** (Stage 6 → Stage 7-8)
+- REQUIRED: Routing classification applied (auto or forced by `--to`).
+- REQUIRED: Dedup check passed against harvest-log.jsonl and existing stores.
+- REQUIRED: If `--dry-run`: preview displayed, no files written — GATE blocks further writes.
+- BLOCKED if dedup check fails or store paths unresolvable.
 
 **Routing rules:**
 - Universal design patterns → `coding` or `arch` category

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

@@ -29,10 +29,34 @@ $manage-issue "link ISS-20260318-001 --task TASK-003"
 ```
 
 **Subcommands**: `create`, `list`, `status`, `update`, `close`, `link`.
+
+**Output boundary**: ALL file writes MUST target `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`, or `.workflow/issues/` directory only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Schema compliance** — every issue record MUST conform to the canonical issue.json template schema
+2. **ID uniqueness** — issue IDs (ISS-XXXXXXXX-NNN) MUST be unique across issues.jsonl and issue-history.jsonl
+3. **Close moves to history** — `close` subcommand MUST move the record from issues.jsonl to issue-history.jsonl, NEVER delete without archiving
+4. **Bidirectional links** — `link` subcommand MUST create references in both the issue and the linked task
+5. **Confirmation on destructive ops** — `close` and bulk `update` MUST require user confirmation unless `-y` flag is set
+6. **Append-only audit** — NEVER overwrite existing issue records; updates MUST preserve all prior fields and add `updated_at` timestamp
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Execute** (Subcommand routing)
+- REQUIRED: Subcommand parsed and validated against valid set (create/list/status/update/close/link).
+- REQUIRED: `.workflow/issues/` directory exists (auto-create with empty issues.jsonl if missing).
+- BLOCKED if E_NO_SUBCOMMAND or E_INVALID_SUBCOMMAND.
+
+**GATE 2: Execute → Write** (For mutating subcommands: create/update/close/link)
+- REQUIRED: Target issue exists for update/close/link operations.
+- REQUIRED: User confirmation for close operations (unless -y).
+- REQUIRED: For link: both issue and task validated before any writes.
+- BLOCKED if target not found or confirmation denied.
+
 ### Step 1: Parse Subcommand
 
 Extract first token as subcommand. Valid: `create`, `list`, `status`, `update`, `close`, `link`.

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -72,6 +72,8 @@ When `--yes` or `-y`: Auto-confirm perspective selection, skip interactive valid
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + issues appended to `.workflow/issues/issues.jsonl`
+
+**Output boundary**: ALL file writes MUST target `.workflow/issues/issues.jsonl` or `.workflow/issues/discoveries/{SESSION_ID}/` only. NEVER modify source code or files outside these paths.
 </context>
 
 <csv_schema>

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

@@ -32,10 +32,36 @@ $manage-knowhow "prune --before 2026-01-01 --type tip --dry-run"
 - `--before <date>` / `--after <date>` — Date filters for prune
 - `--dry-run` — Preview prune without deleting (default for prune — use `--execute` to actually delete)
 - `--execute` — Required to actually perform prune deletions (prune defaults to dry-run)
+
+**Output boundary**: Workflow store writes MUST target `.workflow/knowhow/` only. System store writes MUST target `~/.claude/projects/*/memory/` only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **MEMORY.md protected** — NEVER delete MEMORY.md; only editable via `edit` subcommand
+2. **MEMORY.md line limit** — MUST warn (W003) when MEMORY.md exceeds 200 lines; content beyond 200 lines will be truncated at load
+3. **Confirmation on destructive ops** — `delete` and `prune` MUST require user confirmation unless `--confirm` flag is set
+4. **Store isolation** — `prune` operates on workflow store only; NEVER prune system memory files
+5. **Reference integrity** — `delete` MUST check for references from other entries before removing; warn if orphaned references would result
+6. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview destructive operations only
+7. **Index consistency** — after delete/prune, workflow index MUST be updated to reflect removals
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Execute** (Subcommand routing)
+- REQUIRED: Subcommand parsed from first token (list/search/view/edit/delete/prune).
+- REQUIRED: Both store paths resolved (workflow + system).
+- BLOCKED if E001 (no memory stores found) or invalid subcommand.
+
+**GATE 2: Execute → Mutate** (For destructive subcommands: delete/prune/edit)
+- REQUIRED: Target entry/file resolved and exists (E002 if not found).
+- REQUIRED: MEMORY.md protected from deletion (E004 — use `edit` instead).
+- REQUIRED: For `prune`: at least one filter provided (E003).
+- REQUIRED: User confirmation before delete/prune unless `--confirm` flag set.
+- BLOCKED if target unresolvable or confirmation denied.
+
 ### Step 1: Resolve Store Paths
 
 - **Workflow store**: `.workflow/knowhow/` (entries: `KNW-*.md`, `TIP-*.md`, `TPL-*.md`, `RCP-*.md`, `REF-*.md`, `DCS-*.md`, indexed in `.workflow/wiki-index.json`)

package/.codex/skills/manage-knowhow-capture/SKILL.md

@@ -33,10 +33,33 @@ $manage-knowhow-capture "decision Use PostgreSQL over MongoDB --status accepted"
 - `--code-paths <paths>` — Related source paths for asset/blueprint (comma-separated)
 - `--description <desc>` — One-line description for search results (falls back to content[:240])
 - `--category <cat>` — Spec category for agent discovery (coding, arch, test, debug, review, learning)
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` only. NEVER modify source code or files outside this path.
 </context>
 
+<invariants>
+1. **Description required** — every entry MUST have a `description` field in frontmatter (under 120 chars) for search indexing
+2. **Tags language match** — tags MUST match content language (Chinese content → Chinese tags, English → English)
+3. **ID uniqueness** — generated file names ({PREFIX}-{YYYYMMDD}-{slug}.md) MUST be unique; NEVER overwrite existing entries
+4. **Frontmatter completeness** — YAML frontmatter MUST include: title, description, type, category, created, tags, status
+5. **Type-specific validation** — each type MUST populate all its required fields before writing (template needs code block, recipe needs steps, etc.)
+6. **Idempotent naming** — same content captured twice MUST produce same slug, enabling dedup detection
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Type Detection → Content Collection** (Type routing → Content extraction)
+- REQUIRED: Type detected from first token or selected via request_user_input.
+- REQUIRED: Type maps to a valid prefix (KNW-/TPL-/RCP-/REF-/DCS-/TIP-/AST-/BLP-/DOC-/INS-).
+- BLOCKED if type unresolvable after interactive prompt.
+
+**GATE 2: Content Collection → Write** (Content extraction → File write)
+- REQUIRED: All type-specific required fields populated (e.g., template needs code block, recipe needs steps).
+- REQUIRED: Description generated or provided (under 120 chars).
+- BLOCKED if required fields missing after prompt.
+
 ### Step 1: Validate
 
 Verify `.workflow/` exists (E001). Create `.workflow/knowhow/` if missing.

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

@@ -44,6 +44,8 @@ $manage-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag
 **Storage**:
 - `.workflow/specs/learnings.md` — append-only store (shared with `quality-retrospective`)
 - Index auto-maintained by WikiIndexer (no manual index file needed)
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/learnings.md` only. NEVER modify source code or files outside this path. Bootstrap (creating `.workflow/specs/` directory and `learnings.md`) is the only exception.
 </context>
 
 <invariants>