maestro-flow 0.5.46 → 0.5.48

package/.codex/skills/domain-list/SKILL.md

@@ -9,6 +9,19 @@ allowed-tools: Read, Bash, Glob, Grep
 List all registered domain terms from `.workflow/domain/glossary.yaml`. Shows canonical name, definition, tier, aliases, and status.
 </purpose>
 
+<context>
+$ARGUMENTS — optional `--tier core|extended|peripheral` filter.
+
+**Output boundary**: Read-only command — NEVER write any files. Display output to console only.
+</context>
+
+<invariants>
+1. **Strictly read-only** — NEVER modify `glossary.yaml` or any other file; display-only operation
+2. **Complete listing** — MUST show all registered terms (filtered by --tier if specified); NEVER silently omit entries
+3. **Tier grouping** — MUST group terms by tier (core → extended → peripheral → deprecated); NEVER display flat unsorted list
+4. **Graceful absence** — if glossary.yaml does not exist, report "No domain glossary" with init command; NEVER create or auto-initialize
+</invariants>
+
 <execution>
 
 ### Step 1: Load Glossary
@@ -36,3 +49,19 @@ Apply optional `--tier` filter. Display terms grouped by tier (core → extended
 ```
 
 </execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/domain/glossary.yaml` not found | Run `maestro domain init` first |
+| E002 | error | glossary.yaml parse error (invalid YAML) | Check file syntax |
+| W001 | warning | No terms match --tier filter | Show "No terms in tier: {tier}" |
+</error_codes>
+
+<success_criteria>
+- [ ] Glossary loaded and parsed successfully
+- [ ] Terms grouped by tier (core → extended → peripheral → deprecated)
+- [ ] Optional --tier filter applied correctly
+- [ ] Each term displayed with canonical name, definition, aliases, keywords
+- [ ] Total count shown
+</success_criteria>

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

@@ -33,6 +33,8 @@ $ARGUMENTS — target path/module and optional flags.
 - `--save-wiki`: Create wiki note entries per dimension group
 
 **Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/.csv-wave/{session-id}/`, `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`, and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths.
 </context>
 
 <invariants>

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

@@ -25,10 +25,44 @@ $ARGUMENTS — target and optional flags.
 - `--save-wiki` — Create wiki note with reading notes
 
 **Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-follow-{slug}-{date}.md` and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only traversal** — NEVER modify source code or wiki entries under analysis; all writes go to `.workflow/` only
+2. **Forcing questions mandatory** — each section MUST have all 4 forcing questions applied; NEVER skip questions even for trivial sections
+3. **Anchor requirement** — every extracted pattern MUST include a `file:line` anchor; unanchored patterns SHALL NOT be persisted to learnings.md
+4. **Convention cross-ref** — MUST check every finding against `coding-conventions.md` and mark status (documented/candidate); NEVER persist without status tag
+5. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
+6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via `request_user_input` before any writes
+7. **Depth contract** — `--depth shallow` MUST NOT descend into function bodies; `--depth deep` MUST cover every branch and sub-expression
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Resolve → Context Building**
+- REQUIRED: Target resolved to a readable source (file path, wiki entry, or search result).
+- BLOCKED if: target unresolvable after user prompt (E001).
+
+**GATE 2: Reading → Extraction**
+- REQUIRED: All sections traversed with 4 forcing questions applied per section.
+- REQUIRED: Depth contract honored — shallow stays at top-level, deep covers every branch.
+- BLOCKED if: any section skipped without forcing questions.
+
+**GATE 3: Extraction → Persistence**
+- REQUIRED: All extracted patterns have file:line anchors.
+- REQUIRED: Convention cross-ref completed against coding-conventions.md (or marked "unknown status" if W002).
+- BLOCKED if: unanchored patterns remain in extraction results.
+
+**GATE 4: Persistence → Completion**
+- REQUIRED: Unless `-y`, `request_user_input` showing files to write and spec-entries to append — user must confirm.
+- REQUIRED: KNW-follow-{slug}-{date}.md written with understanding map.
+- REQUIRED: learnings.md appended (not overwritten) with new spec-entry blocks.
+- BLOCKED if: user declines confirmation — offer to adjust findings before retry.
+
 ### Stage 1: Resolve Target + Load Context Web
 - File: verify exists, parse imports for dependency files
 - Wiki ID: fetch + load forward/backlinks

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

@@ -20,10 +20,43 @@ $ARGUMENTS — question text and optional flags.
 - `--no-persist` — Skip writing to learnings.md (report.md still written locally)
 
 **Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-investigate-{slug}/` and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only investigation** — NEVER modify source code files; all writes go to `.workflow/` only
+2. **Evidence append-only** — `evidence.ndjson` MUST be appended line-by-line; NEVER overwrite or truncate existing evidence entries
+3. **Scope lock** — once `--scope` is resolved, NEVER expand search scope without explicit user confirmation via escalation
+4. **Hypothesis cap** — MUST NOT generate more than `--max-hypotheses` (default 3) before triggering escalation; NEVER silently exceed the cap
+5. **Structured evidence format** — every evidence entry MUST include `{ts, type, source, relevance, content, note}`; incomplete entries SHALL NOT be appended
+6. **3-strike escalation** — after all hypotheses fail, MUST escalate to user via `request_user_input`; NEVER silently conclude as INCONCLUSIVE without user interaction
+7. **Confirmation gate** — unless `--no-persist` is set, MUST present report.md path and spec-entries via `request_user_input` before final writes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Frame → Evidence Collection**
+- REQUIRED: Question parsed, slug generated, investigation directory created.
+- REQUIRED: Prior knowledge search completed (maestro search + learnings.md + debug-notes).
+- BLOCKED if: no question provided (E001) or scope path not found (E002).
+
+**GATE 2: Evidence → Hypothesis Formation**
+- REQUIRED: At least 3 evidence items collected in evidence.ndjson.
+- BLOCKED if: fewer than 3 evidence matches (W002 — broaden search before proceeding).
+
+**GATE 3: Hypothesis Testing → Report**
+- REQUIRED: All hypotheses tested (up to max-hypotheses) with results recorded.
+- REQUIRED: If all failed, 3-strike escalation triggered via `request_user_input`.
+- BLOCKED if: hypotheses remain untested.
+
+**GATE 4: Report → Completion**
+- REQUIRED: report.md written with answer, evidence trail, hypothesis results.
+- REQUIRED: Unless `--no-persist`, user confirmation obtained before learnings append.
+- BLOCKED if: user declines — offer to adjust findings before retry.
+
 ### Stage 1: Frame the Question
 - Parse question, generate slug, create investigation directory
 - Load debug specs: `maestro load --type spec --category debug` for known issues and patterns

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

@@ -21,10 +21,43 @@ $ARGUMENTS — lens selection and scope flags.
 **Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
 
 **Output**: `.workflow/knowhow/KNW-retro-{date}.md` + `KNW-retro-{date}.json`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-retro-{date}.md`, `.workflow/knowhow/KNW-retro-{date}.json`, and `.workflow/specs/learnings.md` only. NEVER modify source code, git history, or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only analysis** — NEVER modify source code, git history, or wiki entries; all writes go to `.workflow/` only
+2. **Git data integrity** — git commands MUST be read-only (`git log`, `git diff --stat`); NEVER run `git commit`, `git reset`, or any write-mode git operation
+3. **Confirmation before agents** — MUST prompt user via `request_user_input` before spawning decision evaluation agents; NEVER auto-spawn without confirmation
+4. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
+5. **Confirmation before persist** — MUST prompt user via `request_user_input` before appending insights to learnings.md
+6. **Lens contract** — MUST execute exactly the selected lens(es); `--lens git` SHALL NOT trigger decision evaluation and vice versa
+7. **Prior retro preservation** — existing `KNW-retro-*.json` files MUST NOT be modified; only new files created for current retro
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Lens Execution**
+- REQUIRED: Lens selection parsed (git/decision/all).
+- REQUIRED: Git repo validated if git lens selected (E001).
+- BLOCKED if: not inside git repo for git lens, or no commits in window (E002).
+
+**GATE 2: Git Lens → Decision Lens**
+- REQUIRED: Git metrics computed (commits, LOC, sessions, hotspots).
+- BLOCKED if: git data gathering failed entirely — skip git lens, continue with decision lens only.
+
+**GATE 3: Decision Collection → Decision Evaluation**
+- REQUIRED: Decisions collected from wiki/specs/git/phase.
+- REQUIRED: User confirmation obtained via `request_user_input` before spawning evaluation agents.
+- BLOCKED if: no decisions found (E003) or user declines agent spawn.
+
+**GATE 4: Report → Persist**
+- REQUIRED: Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json.
+- REQUIRED: User confirmation obtained via `request_user_input` before learnings append.
+- BLOCKED if: user declines — display summary only, skip persistence.
+
 ### Phase 1: Parse + Select Lenses
 
 ### Phase 2: Git Lens (skip if --lens decision)

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -29,10 +29,40 @@ $ARGUMENTS — target and optional flags.
 - `--mode consult` — Interactive Q&A session
 
 **Output**: `.workflow/knowhow/KNW-opinion-{slug}-{date}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-opinion-{slug}-{date}.md` and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only analysis** — NEVER modify source code, wiki entries, or plan files under review; all writes go to `.workflow/` only
+2. **Agent independence** — in review mode, each persona agent (Pragmatist/Purist/Strategist) MUST operate independently without shared state; NEVER pass one agent's findings to another during wave 1
+3. **Evidence-backed verdicts** — every finding MUST include a `location` reference (file:line or section); ungrounded opinions SHALL NOT appear in the report
+4. **Mode contract** — MUST execute exactly the mode specified (review/challenge/consult); NEVER mix mode behaviors within a single execution
+5. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
+6. **Confirmation gate** — MUST present findings and target files via `request_user_input` before any writes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Resolve → Execute**
+- REQUIRED: Target resolved to concrete content (file, wiki entry, git diff, or phase plan).
+- BLOCKED if: target unresolvable (E001) or unknown mode (E002).
+
+**GATE 2: Execute → Synthesize**
+- REQUIRED: Mode-specific analysis completed (review: ≥2 of 3 personas completed; challenge: adversarial agent completed; consult: Q&A session ended).
+- BLOCKED if: all persona agents failed in review mode — skip to degraded synthesis with LOW CONFIDENCE flag.
+
+**GATE 3: Synthesize → Persist**
+- REQUIRED: Synthesis produced with agreements, disagreements, verdict, and top 3 recommendations.
+- BLOCKED if: synthesis agent failed — use raw persona outputs as fallback.
+
+**GATE 4: Persist → Completion**
+- REQUIRED: `request_user_input` confirmation before writing learnings.
+- REQUIRED: KNW-opinion-{slug}-{date}.md written.
+- BLOCKED if: user declines — offer to adjust findings before retry.
+
 ### Phase 1: Resolve Target + Load Context
 Resolve target to content. Load specs, `maestro search`, prior lessons for context brief.
 

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

@@ -349,6 +349,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
    | Placeholder | Source |
    |-------------|--------|
    | `{phase}` | session.phase |
+   | `{milestone}` | session.milestone |
    | `{plan_dir}` | session.context.plan_dir |
    | `{analysis_dir}` | session.context.analysis_dir |
    | `{brainstorm_dir}` | session.context.brainstorm_dir |
@@ -358,7 +359,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
    | `{BLP}` | session.blueprint_id |
    | `{intent}` | session.intent |
 
-   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
+   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{milestone}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `Skill(skill_name, resolved_args)` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: mark step `status="done"`. **Structured completion**: `Bash("maestro ralph complete {idx} --status DONE --summary \"...\" [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`（`--summary` MUST，动词开头 ≤100 字）。**Barrier-context update** (when step is a context-producing skill):
@@ -424,9 +425,9 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `init` | `maestro-init` |
 | `blueprint` | `maestro-blueprint "{intent}"` |
 | `analyze_macro` | `maestro-analyze "{intent}"` |
-| `analyze` | `maestro-analyze {phase}` |
+| `analyze` | `maestro-analyze {milestone}` |
 | `ui_design` | `maestro-impeccable build "{phase}"` |
-| `plan` | `maestro-plan {phase}` |
+| `plan` | `maestro-plan {milestone}` |
 | `plan_from_analyze` | `maestro-plan --from analyze:{analyze_macro_id}` |
 | `plan_from_blueprint` | `maestro-plan --from blueprint:{blueprint_id}` |
 | `execute` | `maestro-execute {phase}` |
@@ -482,7 +483,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `deploy` | quality-review → maestro-milestone-release |
 | `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review → manage-harvest --auto |
-| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {milestone} → [B] maestro-plan {milestone}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto (**auto_mode: grill 透传 `-y`，Auto mode 代码代答**) |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
@@ -542,7 +543,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 - [ ] Intent classified and chain resolved
 - [ ] Chain catalog 覆盖 blueprint / analyze_macro / plan_from_analyze / plan_from_blueprint / blueprint-driven / analyze-macro-driven 等新拓扑路径
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查；写入 step
-- [ ] plan step args 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
+- [ ] plan step args 支持 `{milestone}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
 - [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
 - [ ] Goal registered via built-in `create_goal`; status.json decomposition fields additive-only
 - [ ] status.json 唯一真源；无 markdown 清单

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

@@ -41,8 +41,19 @@ Multiple combinable. No flags + no description → interactive (scan + request_u
 | `both` | Both paths checked; overlay targets whichever exists |
 
 **Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. NEVER modify `.claude/commands/*.md` directly — overlay installation is handled by `maestro overlay add`.
 </context>
 
+<invariants>
+1. **Non-invasive only** — amendments MUST use the overlay system (`~/.maestro/overlays/*.json`); direct edits to `.claude/commands/*.md` are NEVER permitted
+2. **Idempotent patches** — re-running the same amendment MUST produce identical overlay JSON; overlay markers prevent duplicate injection
+3. **Pristine source reads** — signal diagnosis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals), not installed copies
+4. **Code bugs excluded** — signals classified as code bugs MUST be routed to `$maestro-quick` or `$maestro-plan --gaps`, NEVER patched via overlay
+5. **User confirmation before install** — overlay JSON MUST be previewed and confirmed by the user before `maestro overlay add` runs (unless `-y`)
+6. **Section existence verified** — target section MUST be confirmed to exist in the pristine source before drafting a patch; missing sections trigger `new-section` mode
+</invariants>
+
 <state_machine>
 
 <states>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] [--from <source>] \"<milestone|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -13,11 +13,11 @@ Wave 1 (CLI exploration, parallel) -> Wave 2 (6-dimension scoring, parallel) ->
 
 **Dual-layer scope (D-003)**:
 - **Macro layer** (text argument, e.g. `analyze "auth refactor"`): broad impact exploration. Produces `scope_verdict ∈ {small, medium, large}` to drive downstream routing (roadmap vs plan).
-- **Phase layer** (numeric argument, e.g. `analyze 1`): phase-scoped deep analysis under `current_milestone`. Milestone resolved via D-007 `phase_slugs` reverse lookup, NEVER direct `current_milestone` read.
+- **Milestone layer** (numeric argument, e.g. `analyze 1`): milestone-level deep analysis covering all phases under the milestone. `analyze 1` = Milestone 1.
 </purpose>
 
 <context>
-$ARGUMENTS -- phase number, topic text, and optional flags.
+$ARGUMENTS -- milestone number, topic text, and optional flags.
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
@@ -94,7 +94,7 @@ Available exploration dimensions: architecture, implementation, performance, sec
 6. **Gaps mode pipeline**: --gaps follows: Load issues from issues.jsonl -> Classify & group by location/component -> CSV gen (W1: 1 explore row per issue, W2: 1 synthesis per group) -> Execute waves -> Write issue.analysis record per issue -> Append history `{ action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }` -> Output context.md for plan --gaps
 7. **Graceful degradation**: Missing exploration reduces scoring quality; missing scoring reduces synthesis quality
 8. **Tri-output**: context.md + context-package.json always. analysis.md (full only) + conclusions.json (full + quick — quick writes minimal with `scope_verdict` + `implementation_scope[]`). Gaps mode writes to issues.jsonl + context.md + context-package.json
-9. **D-007 milestone resolution**: numeric scope MUST reverse-lookup `state.json.milestones[].phase_slugs`. NEVER read `current_milestone` directly for phase-scoped artifact registration.
+9. **Milestone resolution**: numeric scope directly specifies the milestone number. Resolve from `state.json.milestones[]` by ID.
 10. **scope_verdict mandatory** (D-003): macro/adhoc/standalone scopes MUST produce `scope_verdict ∈ {small, medium, large}` in conclusions.json. Drives downstream chain (roadmap vs plan).
 11. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons.
 12. **Evidence required on decisions** — every decision in context.md MUST cite evidence from Wave 1 exploration findings or Wave 2 scores. Decisions citing only orchestrator's manual file reading are flagged LOW CONFIDENCE. **Degradation exception**: when invariant 7 activates and evidence is incomplete, decisions MAY proceed but MUST inherit LOW CONFIDENCE flag per invariant 13 — this is not a violation of the MUST, it is the defined degraded behavior.
@@ -119,24 +119,19 @@ S_PARSE:
   -> S_CONTEXT    WHEN: scope resolved (milestone/phase/macro/adhoc/standalone/gaps)
   -> ERROR(E001)  WHEN: no args and no roadmap
 
-  **Scope routing** (text → macro layer, numeric → phase layer per D-003):
+  **Scope routing** (text → macro layer, numeric → milestone layer per D-003):
   | Condition | Scope | Layer | Slug |
   |-----------|-------|-------|------|
   | --gaps flag | gaps | — | ISS-ID slugified or "issue-gaps" |
-  | Empty subject + milestone + roadmap | milestone | phase | milestone name slugified |
+  | Empty subject + milestone + roadmap | milestone | milestone | milestone name slugified |
   | Empty subject, no roadmap | ERROR E001 | — | -- |
-  | Numeric + milestone + roadmap | phase | phase | phase slug from roadmap |
+  | Numeric + roadmap | milestone | milestone | milestone name slugified |
   | Text subject + milestone | macro | macro | subject slugified (max 40) |
   | Text subject, no milestone | macro | macro | subject slugified (max 40) |
 
-  **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 (standalone)
-  ```
-  Write resolved milestone into `session.milestone` and artifact registration; NEVER use `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
 
 S_CONTEXT:
   -> S_CSV_GEN    DO: load project.md, roadmap.md, state.json, prior artifacts, specs, upstream context-package (if --from)
@@ -252,7 +247,7 @@ Filter `wave==3 AND status=="pending"` -> build prev_context from wave 2 scores
 | `medium` | 1-2 subsystems, parallel-safe |
 | `small` | Single file or few files, directly executable |
 
-Write to `conclusions.json.scope_verdict` (all modes that produce conclusions); mirror into `context.md` and `context-package.json.source.scope_verdict`. Phase-scoped runs may omit (default null).
+Write to `conclusions.json.scope_verdict` (all modes that produce conclusions); mirror into `context.md` and `context-package.json.source.scope_verdict`. Milestone-scoped runs may omit (default null).
 
 Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specific (skip prior decided areas).
 
@@ -286,7 +281,7 @@ Non-blocking: conflicts produce warnings, pipeline continues.
    | Scope | Condition | Suggested |
    |-------|-----------|-----------|
    | Phase/Milestone | Go + UI work needed | `$maestro-impeccable build {target}` |
-   | Phase/Milestone | Go + ready to plan | `$maestro-plan` or `$maestro-plan {phase}` |
+   | Phase/Milestone | Go + ready to plan | `$maestro-plan` or `$maestro-plan {milestone}` |
    | Phase/Milestone | No-Go | `$maestro-brainstorm {topic}` |
    | Macro/Adhoc/Standalone | `scope_verdict == "large"` | `$maestro-roadmap --from analyze:{ANL_ID}` |
    | Macro/Adhoc/Standalone | `scope_verdict == "medium"` | `$maestro-plan --from analyze:{ANL_ID}` |
@@ -341,7 +336,7 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] context.md produced (all modes); analysis.md (full mode); conclusions.json (full mode AND quick mode with at minimum `scope_verdict` + `implementation_scope[]`)
 - [ ] context-package.json produced (all modes) with constraints, requirements, insights, open_questions
 - [ ] `scope_verdict ∈ {small, medium, large}` written into conclusions.json + context.md (macro/adhoc/standalone scopes)
-- [ ] D-007 milestone reverse lookup applied for numeric scope; `session.milestone` populated via `phase_slugs`, never via direct `current_milestone` read
+- [ ] Milestone resolved directly from numeric arg; `session.milestone` populated from state.json.milestones[]
 - [ ] context.md contains all decisions classified as Locked/Free/Deferred
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Confidence scored per dimension with factor-based model (full mode)

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

@@ -61,12 +61,23 @@ $maestro-companion "route what should I do next"
 
 Auto-detection: if `--type` not provided, infer from `--task` description keywords.
 
+**Output boundary**: ALL file writes MUST target `.workflow/.scratchpad/` (companion docs + `.companion-active` pointer) only. Promotion writes (spec/knowhow) are delegated to `spec-add` / `manage-knowhow-capture` skills. NEVER modify source code, `.workflow/state.json`, or files outside `.workflow/.scratchpad/`.
+
 **Companion document:**
 - Path: `.workflow/.scratchpad/companion-{YYYYMMDD-HHmmss}.md`
 - Active doc tracking: `.workflow/.scratchpad/.companion-active` (stores path of current companion doc)
 - Format: YAML frontmatter (rich metadata) + typed sections + timestamped entries
 </context>
 
+<invariants>
+1. **No session creation** — companion NEVER creates workflow sessions, NEVER writes to state.json
+2. **Side-car only** — companion MUST NOT modify source code or execute implementation tasks; it is strictly a knowledge loading + recording utility
+3. **One active doc** — only one `.companion-active` pointer SHALL exist at a time; creating a new companion doc MUST clear any stale pointer
+4. **Append-only entries** — note mode MUST append entries; NEVER overwrite or reorder existing entries
+5. **Promotion via delegation** — spec/knowhow promotion MUST route through `spec-add` / `manage-knowhow-capture` skills; companion NEVER writes directly to `.workflow/specs/` or `.workflow/knowhow/`
+6. **Type-template integrity** — context template sections MUST match the resolved `task_type`; NEVER mix templates from different types
+</invariants>
+
 <execution>
 
 ## S_BEFORE — Knowledge Loading + Companion Doc Creation

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

@@ -58,8 +58,19 @@ $ARGUMENTS — natural language workflow description, or flags.
 1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
 2. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Informs executor argument defaults and context injection.
 3. Optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/templates/workflows/` (final templates) and `.workflow/templates/design-drafts/` (in-progress drafts). NEVER modify source code, `.claude/commands/`, or `.codex/skills/`.
 </context>
 
+<invariants>
+1. **Max 20 nodes** — workflow templates MUST NOT exceed 20 nodes; larger workflows MUST be split into sub-workflows
+2. **Acyclic DAG** — generated template MUST be a directed acyclic graph; cycles MUST be detected and rejected before persistence
+3. **No orphan nodes** — every node MUST be reachable from at least one edge; unreachable nodes MUST be flagged
+4. **Confirmation before write** — template JSON MUST be shown to user via request_user_input before writing to `~/.maestro/templates/workflows/`; cancellation saves draft only
+5. **Draft preservation** — abandoning at any confirmation gate MUST save current progress to design-drafts directory; NEVER discard user's partial work
+6. **Deferred reading only** — node-catalog and template-schema MUST be read at their designated phases (P2, P5), NEVER loaded eagerly at startup
+</invariants>
+
 <execution>
 
 ### Phase 0: Resume / Edit (conditional)

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

@@ -33,10 +33,35 @@ $ARGUMENTS -- Parse subcommand and optional path argument.
 
 **Enforcement:** The `workflow-guard` hook (PreToolUse on Write/Edit) reads this config
 and blocks operations targeting files outside boundaries. Requires hooks level >= `full`.
+
+**Output boundary**: ALL file writes MUST target `.workflow/config.json` (guard section) only. NEVER modify hook files, `.codex/settings.json`, or source code.
 </context>
 
+<invariants>
+1. **Config-only mutation** — guard MUST only modify the `guard` section of `.workflow/config.json`; NEVER touch other config sections or files
+2. **Non-destructive** — `off` MUST preserve existing paths and mode; NEVER clear the path list when disabling
+3. **Mode switch confirmation** — switching between allow/deny mode MUST require request_user_input confirmation when existing paths will be cleared
+4. **Hook dependency** — guard MUST warn when enabled but `workflow-guard` hook is not active (hooks level < full)
+5. **Path normalization** — all paths MUST use forward slashes with trailing slash for directories; NEVER store raw backslash paths
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Config Read**
+- REQUIRED: Subcommand parsed (on/off/status/allow/deny) or defaulted to `status`.
+- BLOCKED if: invalid subcommand provided.
+
+**GATE 2: Config Read → Execute**
+- REQUIRED: `.workflow/config.json` read successfully or initialized with empty guard section.
+- BLOCKED if: file unreadable and cannot be created (E001).
+
+**GATE 3: Execute → Confirm**
+- REQUIRED: Config mutation applied (for on/off/allow/deny) or status displayed (for status).
+- REQUIRED: Mode-switch request_user_input answered (for allow↔deny transitions with existing paths).
+- BLOCKED if: user declines mode switch.
+
 **Step 1: Parse subcommand**
 
 Extract from $ARGUMENTS:

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

@@ -36,6 +36,8 @@ $ARGUMENTS 匹配关键词 → 路由到对应模式：
 | "cli", "终端", "terminal" | 7 | CLI Reference |
 | 其他自由文本 | 1 | Fuzzy Search |
 
+**Output boundary**: This skill is read-only — it MUST NOT write any files. All output is displayed directly to the user via text response.
+
 ## Data Source
 
 读取同目录下的 `catalog.json` 作为唯一数据源：

package/.codex/skills/maestro-help/catalog.json

@@ -7,19 +7,19 @@
   "commands": [
     {"name": "maestro", "command": "/maestro", "category": "core", "description": "智能协调器 — 根据意图和项目状态自动选择最优命令链", "source": "../../commands/maestro.md"},
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
-    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — Milestone > Phase 分解，下游以 milestone 为入口", "source": "../../commands/maestro-roadmap.md"},
     {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "头脑风暴 — 发散探索，多角色创意，上游起源命令", "source": "../../commands/maestro-brainstorm.md"},
     {"name": "maestro-blueprint", "command": "/maestro-blueprint", "category": "core", "description": "正式规格文档化 — 7-phase 收敛规格链，上游起源命令，产出 .workflow/blueprint/", "source": "../../commands/maestro-blueprint.md"},
     {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
     {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
-{"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
+{"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
     {"name": "maestro-overlay", "command": "/maestro-overlay", "category": "core", "description": "Overlay 管理 — 创建、查看、删除命令补丁", "source": "../../commands/maestro-overlay.md"},
     {"name": "maestro-amend", "command": "/maestro-amend", "category": "core", "description": "修正补丁 — 从工作流信号自动生成 overlay", "source": "../../commands/maestro-amend.md"},
     {"name": "maestro-fork", "command": "/maestro-fork", "category": "worktree", "description": "Worktree 分叉 — 基于 milestone 创建隔离开发环境", "source": "../../commands/maestro-fork.md"},
     {"name": "maestro-merge", "command": "/maestro-merge", "category": "worktree", "description": "Worktree 合并 — 同步变更回主线", "source": "../../commands/maestro-merge.md"},
     {"name": "maestro-collab", "command": "/maestro-collab", "category": "team", "description": "人类团队协作 — .workflow/collab/ 目录管理", "source": "../../commands/maestro-collab.md"},
-    {"name": "maestro-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查 Phase 完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
+    {"name": "maestro-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查里程碑完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
     {"name": "maestro-milestone-complete", "command": "/maestro-milestone-complete", "category": "milestone", "description": "里程碑完成 — 归档里程碑并推进下一个", "source": "../../commands/maestro-milestone-complete.md"},
     {"name": "maestro-milestone-release", "command": "/maestro-milestone-release", "category": "milestone", "description": "里程碑发布 — 生成发布说明和变更日志", "source": "../../commands/maestro-milestone-release.md"},
     {"name": "maestro-composer", "command": "/maestro-composer", "category": "core", "description": "编排器 — compose + play 工作流组合执行", "source": "../../commands/maestro-composer.md"},
@@ -157,17 +157,17 @@
   ],
   "workflows": {
     "topology": {
-      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "hierarchy": "Roadmap > Milestone > Phase | Plan > Task > Wave",
       "layers": {
         "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
-        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(milestone 数字参数)",
         "orchestration": "roadmap (可选，消费上游 context)",
         "execution": ["plan", "execute", "verify"]
       }
     },
     "paths": {
-      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → quality-review",
-      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → quality-review",
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute → quality-review",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute → quality-review",
       "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → quality-review",
       "D_small_fix": "plan → execute → quality-review",
       "E_spec_only": "blueprint → (供人阅读)",

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

@@ -25,6 +25,7 @@ $maestro-init "--from brainstorm:20260318-brainstorm-auth"
 
 **Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
 
+**Output boundary**: ALL file writes MUST target `.workflow/` (project files, state, config, specs). NEVER modify existing source code or files outside `.workflow/`.
 </context>
 
 <invariants>
@@ -37,6 +38,21 @@ $maestro-init "--from brainstorm:20260318-brainstorm-auth"
 
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Detect**
+- REQUIRED: Arguments parsed; flags extracted.
+- BLOCKED if: `-y` set but no document reference provided (E001).
+
+**GATE 2: Detect → Gather**
+- REQUIRED: Project state classified (empty/code/existing).
+- BLOCKED if: existing `.workflow/` detected (E002).
+
+**GATE 3: Gather → Write**
+- REQUIRED: All project information gathered (interactive or extracted).
+- REQUIRED: Templates read from `~/.maestro/templates/`.
+- BLOCKED if: templates unreadable.
+
 ### Step 1: Parse Arguments
 
 Extract flags from arguments:

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

@@ -34,6 +34,8 @@ $ARGUMENTS — learning intent text, or flags.
 | `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
 
 **Session state:** `.workflow/knowhow/.maestro-learn/{session_id}/status.json`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/.maestro-learn/{session_id}/` (session state) and delegate to learn-* commands for knowledge writes. NEVER modify source code or files outside `.workflow/`.
 </context>
 
 <execution>

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

@@ -123,8 +123,8 @@ ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 | 无 `.workflow/` + 有源码 | init | `maestro-init` |
 | 有 state.json，无 roadmap，无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
 | 有 macro analyze artifact，无 roadmap | roadmap | `maestro-roadmap` |
-| 有 roadmap，未启动 phase | analyze | `maestro-analyze {phase}` |
-| 最新 artifact = analyze | plan | `maestro-plan {phase}` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {milestone}` |
+| 最新 artifact = analyze | plan | `maestro-plan {milestone}` |
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
 | 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |

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

@@ -38,6 +38,7 @@ $maestro-overlay "--remove cli-verify-after-execute"
 - Shared docs: `~/.maestro/overlays/docs/*.md`
 - Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
 
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs). NEVER modify `.claude/commands/*.md` or `.codex/skills/` directly — overlay application is handled by `maestro overlay add`.
 </context>
 
 <invariants>