maestro-flow 0.5.46 → 0.5.48

package/.agy/skills/manage-kg-extractors/SKILL.md

@@ -40,6 +40,8 @@ $ARGUMENTS -- optional flags.
 
 **Output:** `.workflow/kg/extractors.yaml` — declarative rules for PluginEngine.
 
+**Output boundary**: ALL file writes MUST target `.workflow/kg/extractors.yaml` only. NEVER modify source code or files outside this path. `--scan-only` MUST NOT write any files.
+
 **Rule format:**
 ```yaml
 version: 1
@@ -68,6 +70,16 @@ plugins:
 
 <execution>
 
+<invariants>
+1. **Read-only source code** — agents MUST only read source files for pattern discovery; NEVER modify source code
+2. **Scan-only safety** — `--scan-only` MUST stop after Phase 2 summary; NEVER write extractors.yaml
+3. **Append preservation** — `--append` MUST preserve existing rules in extractors.yaml; default (overwrite) MUST warn (W003) if file exists
+4. **Min-count threshold** — patterns with fewer occurrences than `--min-count` MUST be excluded unless explicitly overridden
+5. **User confirmation** — each pattern group MUST be confirmed/edited/skipped by user before writing (Phase 3, Step 2)
+6. **Schema compliance** — generated extractors.yaml MUST conform to version 1 PluginEngine schema with required fields (id, languages, mode, rules)
+7. **Validation mandatory** — MUST run `maestro kg index` after writing to verify new symbols are extractable
+</invariants>
+
 ### Phase 1: Discover patterns
 
 Spawn **3 parallel agents** to scan the codebase:
@@ -80,7 +92,21 @@ Spawn **3 parallel agents** to scan the codebase:
 
 Each agent returns: `[{pattern_type, regex_evidence, file_count, sample_matches: [{file, line, code}]}]`
 
-**Gate:** If all 3 agents return empty results → E002 (abort). If at least 1 agent succeeds, proceed with partial results (log W001 for failed agents).
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Generation** (Phase 1 → Phase 2)
+- REQUIRED: At least 1 of 3 agents returned valid pattern results.
+- BLOCKED if all 3 agents return empty results (E002).
+
+**GATE 2: Generation → Write** (Phase 2 → Phase 3)
+- REQUIRED: At least 1 pattern meets `--min-count` threshold.
+- REQUIRED: User confirmed pattern groups via ask_question.
+- BLOCKED if `--scan-only` is set — stop after summary.
+
+**GATE 3: Write → Validation** (Phase 3 → KG Index)
+- REQUIRED: extractors.yaml written with valid schema.
+- REQUIRED: `maestro kg index` executed to verify extraction.
+- BLOCKED if schema validation fails on generated YAML.
 
 ### Phase 2: Generate rules
 

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

@@ -23,6 +23,8 @@ Arguments: $ARGUMENTS
 
 Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
 
+**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.
+
 **Subcommands:**
 - `list` — List entries from both stores (default if no arguments)
 - `search <query>` — Full-text search across both stores
@@ -43,8 +45,32 @@ Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
 
 <execution>
 Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+
+### 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.
 </execution>
 
+<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>
+
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|

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

@@ -43,11 +43,35 @@ $ARGUMENTS — type token + description + optional flags.
 | No args | — | — | ask_question (10 options) |
 
 **Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
+
+**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>
 Follow '~/.maestro/workflows/knowhow.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Type Detection → Content Collection** (Type routing → Content extraction)
+- REQUIRED: Type detected from first token or selected via ask_question.
+- 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` field generated or provided (under 120 chars).
+- REQUIRED: Tags generated in correct language matching content.
+- BLOCKED if required fields missing after user prompt (E002/E003).
+
 **Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
 
 **Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.

package/.agy/skills/manage-knowledge-audit/SKILL.md

@@ -37,8 +37,21 @@ Arguments: $ARGUMENTS
 **互斥规则：** `--interactive`、`--mark`、`--delete`、`--purge` 四选一，同时传入多个 → E006。
 
 Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/`, `.workflow/knowhow/`, `.workflow/.trash/knowledge-audit-{timestamp}/`, `.workflow/issues/`, or audit report files (`audit-report-*.md`, `audit-log.jsonl`). NEVER modify source code files.
 </context>
 
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；spec/knowhow 声明 MUST 与代码实际行为一致；每个 finding 的 evidence MUST 包含代码引用（文件:行号）
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Deprecate over delete** — 文本存储首选 `status="deprecated"` 保留历史；NEVER 物理删除 spec/knowhow 文件
+4. **Purge 仅 artifact** — `--purge` MUST NOT 作用于 spec/knowhow scope (E004)
+5. **Rescue before delete** — 未 harvest 的 artifact 删除前 MUST 强制提示先跑 `/manage-harvest` (W002)
+6. **Conflict marker sync** — deprecate/delete 执行时如果目标条目有 conflict-marker，MUST 同步调用 `maestro spec conflict clear` 清除标记
+7. **Mutual exclusion** — `--interactive`/`--mark`/`--delete`/`--purge` 四选一；同时传入多个 MUST trigger E006
+8. **Dry-run safety** — `--dry-run` MUST NOT write any files; `--purge` 与 `--dry-run` 互斥 (E003)
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 

package/.agy/skills/manage-status/SKILL.md

@@ -23,12 +23,34 @@ $ARGUMENTS (no arguments required)
 - `.workflow/roadmap.md` -- milestone and phase structure
 - `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
 - `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
+
+**Output boundary**: Read-only command. MUST NOT write any files. All output is displayed to the user via text.
 </context>
 
+<invariants>
+1. **Read-only** — MUST NOT write or modify any files; this is a pure display command
+2. **Graceful degradation** — missing roadmap.md, plan.json, or task files MUST NOT cause failure; display available data and note missing sections
+3. **State accuracy** — progress percentages MUST be calculated from actual task statuses, NEVER estimated or inferred
+4. **Wiki health optional** — wiki health score display MUST degrade gracefully if wiki is unavailable
+5. **Complete dashboard** — MUST include: milestone progress, phase status, task counts, active work, and next-step suggestions
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/status.md' completely.
 
 Next-step decision table defined in workflow status.md Step 5.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Load → Render** (State loading → Dashboard display)
+- REQUIRED: `.workflow/` exists and `state.json` is readable (E001/E002 if not).
+- REQUIRED: Project state loaded with milestone and artifact registry.
+- BLOCKED if state.json missing or corrupt (E002).
+
+**GATE 2: Render → Route** (Dashboard → Next-step suggestions)
+- REQUIRED: Per-phase progress calculated from actual task statuses.
+- REQUIRED: Dashboard rendered with progress bars and status table.
+- BLOCKED if state parsing fails entirely.
 </execution>
 
 <error_codes>

package/.agy/skills/manage-wiki/SKILL.md

@@ -42,13 +42,41 @@ $ARGUMENTS — subcommand and optional flags.
 - `--format brief|full` — (digest) Output format
 - `--recent N` — (digest) Scope to N most recent entries
 - `--create-issues` — (digest) Create issues for identified knowledge gaps
+
+**Output boundary**: File writes MUST target `.workflow/wiki/`, `.workflow/knowhow/`, or `.workflow/issues/issues.jsonl` (when `--create-issues`) only. NEVER modify source code or files outside these paths. `--dry-run` overrides `--fix` — no writes when both are set.
 </context>
 
+<invariants>
+1. **Dry-run precedence** — `--dry-run` MUST override `--fix` when both are passed; preview only, no writes
+2. **Read-only by default** — without `--fix` or `--create-issues`, all subcommands MUST be read-only
+3. **Confirmation on fixes** — `--fix` MUST show preview of changes before applying; auto-apply only when explicitly set
+4. **Graph integrity** — `connect` MUST NOT create circular link chains; validate graph acyclicity for parent-child relationships
+5. **Threshold enforcement** — `--min-similarity` MUST be respected; NEVER suggest connections below the threshold
+6. **Subcommand isolation** — each subcommand routes to its own workflow file; NEVER cross-execute subcommand logic
+</invariants>
+
 <execution>
 **Subcommand routing:**
 - `health|search|cleanup|stats` → Follow `~/.maestro/workflows/wiki-manage.md` completely.
 - `connect` → Follow `~/.maestro/workflows/wiki-connect.md` completely (Stages 1-6).
 - `digest` → Follow `~/.maestro/workflows/wiki-digest.md` completely (Stages 1-8).
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load** (Subcommand routing → Wiki data loading)
+- REQUIRED: Subcommand parsed and validated (health/search/cleanup/stats/connect/digest).
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- BLOCKED if E003 (invalid subcommand) or E001.
+
+**GATE 2: Load → Execute** (Wiki data → Subcommand execution)
+- REQUIRED: Wiki data loaded via `maestro wiki` CLI.
+- REQUIRED: At least one wiki entry exists (E002 if none).
+- BLOCKED if wiki data loading fails entirely.
+
+**GATE 3: Execute → Write** (For mutating operations: cleanup --fix, connect --fix, digest --create-issues)
+- REQUIRED: Preview of changes shown to user.
+- REQUIRED: `--dry-run` NOT set (overrides `--fix`).
+- BLOCKED if preview generation fails or user declines.
 </execution>
 
 <error_codes>

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

@@ -52,6 +52,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-improve-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
+**Output boundary**: ALL file writes MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-improve-odyssey-{slug}/`) or `.workflow/state.json` only. Source code modifications during S_FIX are in-scope but MUST be committed per action. NEVER write artifacts outside these paths.
+
 **session.json — improve-specific fields:**
 ```json
 { "target": "", "dimensions": [], "baseline_metrics": {},
@@ -105,6 +107,54 @@ All invariants (evidence append-only, session-as-state, phase goal tracking, aut
 Applies to: **S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
+<execution>
+Follow base execution discipline completely. Actions defined in state_machine below.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: INTAKE → SURVEY**
+- REQUIRED: Target resolved, SESSION_DIR created, session.json initialized with baseline_metrics.
+- REQUIRED: phase_goals[] derived from flags.
+- BLOCKED if: no target specified (E001) or target path not found (E002).
+
+**GATE 2: SURVEY → AUDIT**
+- REQUIRED: Current state survey completed — dependency audit, complexity scan, test coverage map, error handling scan.
+- REQUIRED: Evidence phase=survey logged, understanding.md §2 updated, G1 marked done.
+- BLOCKED if: survey incomplete — all 4 scan types must be attempted.
+
+**GATE 3: AUDIT → DIAGNOSE**
+- REQUIRED: All dimension agents completed (or --dimensions subset), findings merged with severity classification.
+- REQUIRED: audit_result written to session.json, understanding.md §3 with severity matrix, G2 marked done.
+- BLOCKED if: zero dimensions reviewed (W002 partial is allowed, zero is not).
+
+**GATE 4: DIAGNOSE → FIX**
+- REQUIRED: Root causes identified for all critical/high findings with evidence.
+- REQUIRED: diagnoses[] written, understanding.md §4 updated, G3 marked done.
+- BLOCKED if: hypotheses failed 3 times without escalation decision (A_ESCALATE_DIAGNOSIS).
+
+**GATE 5: FIX → VERIFY**
+- REQUIRED: ALL findings within fix_threshold fixed by severity tier (critical → high → medium → low).
+- REQUIRED: Per-fix evidence phase=fix logged.
+- BLOCKED if: tier incomplete — each tier must be fully addressed before advancing.
+
+**GATE 6: VERIFY → GENERALIZE**
+- REQUIRED: Tests pass, metrics re-captured, before/after comparison logged.
+- REQUIRED: confirmation written, understanding.md §5 updated, G4 marked done.
+- BLOCKED if: needs_rework → route back to S_FIX.
+
+**GATE 7: GENERALIZE → DISCOVER**
+- REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
+- REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G5 marked done.
+- BLOCKED if: any layer not attempted (thoroughness floor violation).
+
+**GATE 8: DISCOVER → RECORD**
+- REQUIRED: All hits triaged with per-item classification and reason.
+- REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged.
+- REQUIRED: G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

package/.agy/skills/odyssey-planex/SKILL.md

@@ -57,6 +57,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-planex-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
+**Output boundary**: ALL session artifacts MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-planex-odyssey-{slug}/`) or `.workflow/state.json` only. Source code modifications during S_EXECUTE and S_FIX are in-scope but MUST be committed per action. NEVER write session artifacts outside these paths.
+
 **session.json — planex-specific fields:**
 ```json
 { "requirement": "",
@@ -108,6 +110,50 @@ Base execution_discipline #1-5.
 Applies to: **S_PLAN, S_VERIFY, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
+<execution>
+Follow base execution discipline completely. Actions defined in state_machine below.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: INTAKE → PLAN**
+- REQUIRED: Requirement parsed, >=1 acceptance criterion defined with verify_method assigned.
+- REQUIRED: session.json initialized, understanding.md §1 written, G1 marked done.
+- BLOCKED if: no requirement provided (E001) or zero criteria derived (W001).
+
+**GATE 2: PLAN → EXECUTE**
+- REQUIRED: Plan tasks decomposed with criteria_refs mapping each task to acceptance criteria.
+- REQUIRED: session.json.plan populated, understanding.md §2 updated, G2 marked done.
+- BLOCKED if: plan has zero tasks or unmapped criteria.
+
+**GATE 3: EXECUTE → VERIFY**
+- REQUIRED: All plan tasks executed (or marked blocked after 3 retries per deviation rule).
+- REQUIRED: execution_config confirmed, per-task evidence logged, understanding.md §3 updated, G3 marked done.
+- BLOCKED if: tasks still pending execution.
+
+**GATE 4: VERIFY → FIX / GENERALIZE**
+- REQUIRED: Every acceptance criterion verified by its assigned method (test/grep/cli-review/manual).
+- REQUIRED: Per-criterion evidence logged with pass/fail status and iteration count.
+- BLOCKED if: verification incomplete — all criteria must be checked before routing decision.
+- Route: all passed → GENERALIZE (or RECORD if skip_generalize). Some failed + iteration < max → FIX.
+
+**GATE 5: FIX → VERIFY**
+- REQUIRED: current_iteration incremented, targeted fixes applied for each failed criterion.
+- REQUIRED: Fix evidence logged, understanding.md §5 updated.
+- BLOCKED if: no fix attempted for failing criteria.
+
+**GATE 6: GENERALIZE → DISCOVER**
+- REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
+- REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G5 marked done.
+- BLOCKED if: any layer not attempted (thoroughness floor violation).
+
+**GATE 7: DISCOVER → RECORD**
+- REQUIRED: All hits triaged with per-item classification and reason.
+- REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged.
+- REQUIRED: G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -45,6 +45,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-review-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `explore.json` | `understanding.md`
 
+**Output boundary**: ALL session artifacts MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-review-odyssey-{slug}/`) or `.workflow/state.json` only. Source code modifications during S_FIX are in-scope but MUST be committed per action. NEVER write session artifacts outside these paths.
+
 **session.json — review-specific fields:**
 ```json
 { "target": "", "dimensions": [], "review_result": {"remaining_actionable": 0},
@@ -90,6 +92,54 @@ All invariants defined in base.
 Applies to: **S_ARCHAEOLOGY, S_EXPLORE, S_REVIEW, S_FIX, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
+<execution>
+Follow base execution discipline completely. Actions defined in state_machine below.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: INTAKE → ARCHAEOLOGY**
+- REQUIRED: Target resolved to file list, SESSION_DIR created, session.json initialized.
+- REQUIRED: phase_goals[] derived from flags, understanding.md §1 written.
+- BLOCKED if: no target specified (E001) or target path not found (E002).
+
+**GATE 2: ARCHAEOLOGY → EXPLORE**
+- REQUIRED: Git history analysis completed (timeline + blame agents), evidence phase=archaeology logged.
+- REQUIRED: understanding.md §2 updated.
+- BLOCKED if: both archaeology agents failed AND delegate failed (partial results via W003 are acceptable).
+
+**GATE 3: EXPLORE → REVIEW**
+- REQUIRED: explore.json written with call_chains/recent_changes/error_gaps/similar_patterns (or W006 skip logged).
+- REQUIRED: Evidence phase=explore logged, understanding.md §3 updated, G2 marked done.
+- BLOCKED if: exploration started but not completed (W006 skip is acceptable, incomplete is not).
+
+**GATE 4: REVIEW → FIX**
+- REQUIRED: All dimension agents completed, findings merged with severity classification.
+- REQUIRED: review_result written to session.json, understanding.md §4 with severity matrix, G1 marked done.
+- BLOCKED if: zero dimensions reviewed (W002 partial is allowed, zero is not).
+
+**GATE 5: FIX → CONFIRM**
+- REQUIRED: Current severity tier fully addressed — all findings in tier fixed or individually classified.
+- REQUIRED: Per-fix evidence phase=fix logged, auto-commit per tier.
+- BLOCKED if: tier incomplete — no partial tier advancement.
+
+**GATE 6: CONFIRM → GENERALIZE**
+- REQUIRED: Tests pass, remaining_actionable == 0, new findings == 0.
+- REQUIRED: confirmation written, understanding.md §5 updated, G3 marked done.
+- BLOCKED if: needs_rework → route back to S_FIX.
+
+**GATE 7: GENERALIZE → DISCOVER**
+- REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
+- REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G4 marked done.
+- BLOCKED if: any layer not attempted (thoroughness floor violation).
+
+**GATE 8: DISCOVER → RECORD**
+- REQUIRED: All hits triaged with per-item classification and reason.
+- REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged.
+- REQUIRED: G5 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -41,6 +41,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
+**Output boundary**: ALL session artifacts MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`) or `.workflow/state.json` only. Source code modifications during S_FIX are in-scope but MUST be committed per action. NEVER write session artifacts outside these paths.
+
 **session.json — ui-specific fields:**
 ```json
 { "target": "", "dimensions": [],
@@ -89,6 +91,54 @@ $ARGUMENTS
 Applies to: **S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
+<execution>
+Follow base execution discipline completely. Actions defined in state_machine below.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: INTAKE → SURVEY**
+- REQUIRED: Target resolved, SESSION_DIR created, session.json initialized.
+- REQUIRED: phase_goals[] derived from flags, understanding.md §1 written.
+- BLOCKED if: no target specified (E001) or target path not found (E002).
+
+**GATE 2: SURVEY → AUDIT**
+- REQUIRED: Design system inventory + current state analysis completed.
+- REQUIRED: Evidence phase=survey logged, understanding.md §2 updated, G1 marked done.
+- BLOCKED if: survey incomplete — token scan and styling analysis must both be attempted.
+
+**GATE 3: AUDIT → DIVERGE**
+- REQUIRED: All 6 dimension agents completed (or --dimensions subset), findings merged with severity classification.
+- REQUIRED: audit_result written to session.json, understanding.md §3 with severity matrix, G2 marked done.
+- BLOCKED if: zero dimensions reviewed (W002 partial is allowed, zero is not).
+
+**GATE 4: DIVERGE → FIX**
+- REQUIRED: Both parallel agents (Polish + Delight) completed, ideas consolidated with audit findings.
+- REQUIRED: diverge_result written, understanding.md §4 updated, G3 marked done.
+- BLOCKED if: divergent exploration not attempted.
+
+**GATE 5: FIX → VERIFY**
+- REQUIRED: ALL findings/ideas within fix_threshold fixed by priority tier.
+- REQUIRED: Per-fix evidence phase=fix logged.
+- BLOCKED if: tier incomplete — each tier must be fully addressed before advancing.
+
+**GATE 6: VERIFY → GENERALIZE**
+- REQUIRED: Tests pass (lint, unit, visual regression), delegate verification completed.
+- REQUIRED: confirmation written, understanding.md §5 updated, G4 marked done.
+- BLOCKED if: needs_rework → route back to S_FIX.
+
+**GATE 7: GENERALIZE → DISCOVER**
+- REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
+- REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G5 marked done.
+- BLOCKED if: any layer not attempted (thoroughness floor violation).
+
+**GATE 8: DISCOVER → RECORD**
+- REQUIRED: All hits triaged with per-item classification and reason.
+- REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged.
+- REQUIRED: G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

package/.agy/skills/quality-auto-test/SKILL.md

@@ -51,8 +51,20 @@ Flags, artifact context resolution, and output formats defined in workflow auto-
    - Browse: `maestro search --category test`
    - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
 4. All are optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-auto-test-P{N}-{slug}/` or `.workflow/state.json` only. Source code modifications are limited to test files generated by this command. NEVER modify existing production source code.
 </context>
 
+<invariants>
+1. **Test code isolation** — generated tests MUST be written to test directories following existing project conventions. NEVER modify production source code to make tests pass.
+2. **RED-GREEN integrity** — tests MUST be written to fail first (RED), then verified to pass against implementation (GREEN). NEVER write tests that pass trivially or assert nothing.
+3. **Layer ordering is strict** — L0→L3 execution is sequential and fail-fast. NEVER skip a layer or run L2 before L1 passes.
+4. **Existing tests are sacred** — NEVER modify, delete, or overwrite existing test files. New tests are additive only.
+5. **Convergence requires evidence** — pass rate and confidence score MUST be computed from actual execution results. NEVER infer or estimate pass rates without running tests.
+6. **Iteration has bounds** — outer iteration MUST NOT exceed `--max-iter` (default 5). Inner test_defect fix MUST NOT exceed 3 attempts per scenario before escalating.
+7. **Traceability is mandatory for spec source** — when route=spec, every test scenario MUST trace back to a REQ-*.md requirement. Untraceable tests are flagged.
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/auto-test.md' completely.
 
@@ -135,7 +147,7 @@ Append to state.json.artifacts[]:
 | E003 | error | No test framework detected | Install test framework or configure test runner |
 | W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
 | W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
-| W003 | warning | Degraded spec mode (no full spec package) | Consider running maestro-roadmap --mode full |
+| W003 | warning | Degraded spec mode (no full spec package) | Consider running /maestro-blueprint |
 </error_codes>
 
 <success_criteria>

package/.agy/skills/quality-debug/SKILL.md

@@ -50,8 +50,19 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - Role knowledge: `maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
 
 **Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
+
+**Output boundary**: ALL file writes MUST target `DEBUG_DIR` or `.workflow/state.json` only. NEVER modify source code, test files, or other artifacts outside these paths during investigation.
 </context>
 
+<invariants>
+1. **Investigation is read-only on source** — debug MUST NOT modify source code, test files, or execution artifacts. Diagnosis produces understanding.md, evidence.ndjson, and reports only.
+2. **Root cause requires reproduction** — NEVER declare a root cause confirmed without evidence (code trace, log entry, or reproduction steps). Hypothesis without evidence stays "suspected".
+3. **Evidence is append-only** — evidence.ndjson entries MUST only be appended, NEVER modified or deleted. Each entry is an immutable observation.
+4. **Confidence is multi-factor** — root cause confidence MUST use the multi-factor scoring model (Step 7.0). NEVER use bare high/medium/low without dimensional breakdown.
+5. **Prior investigations are consulted** — when related debug artifacts exist, check understanding.md for prior root causes. NEVER re-investigate an already-confirmed root cause without new symptoms.
+6. **Fix direction is not fix execution** — debug produces `fix_direction` and `affected_files` but NEVER applies fixes. Fix execution belongs to plan→execute cycle.
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/debug.md' completely.
 

package/.agy/skills/quality-refactor/SKILL.md

@@ -38,8 +38,19 @@ If not provided, prompt user for scope.
    - Browse: `maestro search --category coding`
    - Identify task-relevant entries, then load: `maestro load --type knowhow --id <id1> [id2...]`
 4. All are optional — proceed without if unavailable.
+
+**Output boundary**: Refactoring modifies source files within the declared scope only. Ancillary outputs (reflection-log.md) MUST target `.workflow/scratch/{YYYYMMDD}-refactor-{slug}/`. NEVER modify files outside the confirmed scope without re-confirmation.
 </context>
 
+<invariants>
+1. **Plan before change** — NEVER apply refactoring changes without a confirmed plan. Every modification traces to a plan item.
+2. **Behavioral equivalence** — refactoring MUST preserve existing behavior. All tests MUST pass after each individual change, not just at the end.
+3. **Scope is locked after confirmation** — once the user confirms the refactoring plan, do NOT expand scope to include additional files or changes without re-confirmation.
+4. **Incremental verification** — each discrete refactoring step MUST be verified (tests run) before proceeding to the next. NEVER batch multiple unrelated changes into a single verification.
+5. **No feature creep** — refactoring MUST NOT add new functionality, change APIs, or alter public interfaces. If a beneficial API change is discovered, log it as a recommendation, do NOT apply it.
+6. **Rollback safety** — if any test fails after a refactoring step, revert that specific change before attempting alternatives. NEVER proceed with failing tests.
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/refactor.md' completely.
 

package/.agy/skills/quality-retrospective/SKILL.md

@@ -40,8 +40,19 @@ Arguments: $ARGUMENTS
 - `--lens <name>` — Restrict to specific lens (technical|process|quality|decision); default: all four
 
 Modes (scan/single/range/all) and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+
+**Output boundary**: ALL file writes MUST target the phase's retrospective directory (`.workflow/scratch/{YYYYMMDD}-retrospective-P{N}/`), `.workflow/state.json`, `.workflow/issues.jsonl`, or `.workflow/specs/` (append-only). NEVER modify source code, verification.json, review.json, plan.json, or other existing artifacts.
 </context>
 
+<invariants>
+1. **Source artifacts are read-only** — NEVER modify verification.json, review.json, plan.json, or any execution artifact. Retrospective reads these for analysis only.
+2. **Stable insight IDs** — `INS-{8hex}` MUST be deterministic from `hash(phase_num + lens + title)`. Re-runs MUST NOT create duplicate insights.
+3. **Routing requires confirmation** — unless `-y` flag is set, every external write (issues.jsonl, spec entry, knowhow capture) MUST be confirmed by user before execution.
+4. **Lens independence** — each lens agent (technical/process/quality/decision) operates independently. One lens's findings MUST NOT suppress or override another's.
+5. **Append-only for specs** — learnings.md entries are appended as `<spec-entry>` blocks. NEVER overwrite or restructure existing entries.
+6. **Archive before overwrite** — if retrospective.json already exists for a phase, the existing file MUST be archived before writing a new version.
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
 

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

@@ -56,8 +56,19 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - Role knowledge: `maestro search --category review` → select relevant → `maestro load --type knowhow --id`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
+
+**Output boundary**: ALL file writes MUST target `REVIEW_DIR` or `.workflow/state.json` only. NEVER modify source code, execution artifacts, or files outside these paths.
 </context>
 
+<invariants>
+1. **Review is read-only on source** — NEVER modify source code, test files, or execution artifacts. Review produces reports only.
+2. **Findings require evidence** — every finding MUST reference file:line and include a code snippet or concrete description. No vague or unanchored findings.
+3. **Verdict is data-driven** — NEVER change verdict severity to accommodate user preference without new evidence. Verdicts flow from findings, not negotiation.
+4. **Dimension independence** — each review dimension produces findings independently. One dimension's results MUST NOT suppress or override another's.
+5. **Prior review delta** — when a prior review.json exists for the same phase, findings MUST be compared. Do NOT re-report already-resolved findings as new.
+6. **Spec conflict integrity** — if code contradicts a spec entry, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/review.md' completely.
 

package/.agy/skills/quality-sync/SKILL.md

@@ -27,8 +27,18 @@ $ARGUMENTS -- optional flags:
 - `--full` -- Complete resync of all tracked files (ignores git diff, rebuilds all docs)
 - `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
 - `--dry-run` -- Show what would be updated without writing changes
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `doc-index.json` only. NEVER modify source code or files outside `.workflow/`. `--dry-run` MUST suppress all writes.
 </context>
 
+<invariants>
+1. **Source code is read-only** — sync reads source files to generate documentation. NEVER modify source code, test files, or any non-documentation files.
+2. **Dry-run is side-effect-free** — when `--dry-run` is set, NO file writes occur. Report only what would change.
+3. **Impact trace before refresh** — NEVER regenerate a doc file without first tracing which source changes affect it via doc-index.json. Untargeted full-refresh requires explicit `--full` flag.
+4. **Idempotent sync** — running sync twice with the same diff MUST produce identical results. State.json timestamp prevents redundant re-runs.
+5. **Incremental by default** — without `--full`, only changed components are refreshed. NEVER silently expand to a full rebuild.
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/sync.md' completely.
 

package/.agy/skills/quality-test/SKILL.md

@@ -26,8 +26,20 @@ UAT-style conversational testing for a completed phase. Interactive scenario wal
 Phase or task: $ARGUMENTS (optional)
 
 Flags, artifact context resolution, and output directory format defined in workflow test.md.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-test-P{N}-{slug}/`, `.workflow/state.json`, or `.workflow/issues.jsonl` only. NEVER modify source code or execution artifacts outside these paths. `--frontend-verify` additionally writes `e2e-results.json` to the same scratch directory.
 </context>
 
+<invariants>
+1. **UAT is observational** — test execution observes behavior and records results. NEVER modify source code during testing. Source fixes belong to debug→plan→execute cycle.
+2. **Severity is inferred, not asked** — severity MUST be inferred from user's natural language description of issues. NEVER explicitly ask the user to assign severity levels.
+3. **One scenario at a time** — tests MUST be presented individually for user verification. NEVER batch-present multiple scenarios or assume outcomes.
+4. **Evidence before verdict** — UAT confidence MUST be scored with the 4-dimension factor model from actual test results. NEVER emit a verdict without running the readiness gate.
+5. **Existing UAT is resumable** — when uat.md exists for the target phase, offer resume. NEVER silently overwrite prior test progress.
+6. **Frontend-verify is deterministic** — `--frontend-verify` mode uses browser assertions with concrete pass/fail per criterion. NEVER treat "no response" or timeout as pass.
+7. **Auto-fix has bounds** — `--auto-fix` gap-fix loop MUST NOT exceed 2 iterations. Persistent failures escalate to debug, not infinite retry.
+</invariants>
+
 <execution>
 **Mode select:** `--frontend-verify` → 走下方 **Frontend Verify Mode**（确定性浏览器 smoke，**不是**对话式 UAT）；否则 Follow '~/.maestro/workflows/test.md' completely.