maestro-flow 0.5.46 → 0.5.48

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

@@ -60,8 +60,20 @@ Arguments: $ARGUMENTS
 - `.workflow/project.md`
 
 使用 `maestro timeline` CLI 构建统一的 git+session 时间线。
+
+**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.
 </context>
 
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；当文档说 X 但代码做 Y 时，文档漂移，NEVER 反向修改代码来匹配文档
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Never modify source code** — drift-realign only updates `.workflow/` metadata; source code files are read-only
+4. **Mutual exclusion** — `--report` 与 `--auto-archive` 互斥；同时传入 MUST trigger E006
+5. **Auto-depth escalation** — `drift_window` > 180 天 MUST auto-upgrade to `--depth deep` with W002 warning
+6. **Audit trail** — every triage decision MUST be logged in `drift-log.jsonl` with finding ID, action, and timestamp
+7. **Rebuild trigger** — codebase scope 的 3+ P0 finding MUST auto-trigger `/quality-sync --full` after triage
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
 

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

@@ -39,17 +39,41 @@ Arguments: $ARGUMENTS
 - `-y` / `--yes` — Skip confirmation prompts for all write operations (artifact selection, routing decisions, store writes). Useful for CI or batch harvesting.
 
 Additional flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+
+**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.
 </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 in order.
 
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction and classification happen in-memory.
-2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
-3. **Never modify source artifacts** — harvest is purely extractive.
-4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
-5. **Conflict pre-check on spec routing** — when routing to spec (Stage 6b), 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.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 

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

@@ -39,12 +39,35 @@ $ARGUMENTS -- subcommand + options. Parse first token as subcommand.
 **State files:**
 - `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
 - `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+
+**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>
 Parse subcommand from first token of $ARGUMENTS.
 Follow '~/.maestro/workflows/issue.md' completely.
 
+### 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: Issue data validated against issue.json template schema.
+- REQUIRED: For `close`: resolution text provided.
+- REQUIRED: For `link`: target task ID resolved and exists.
+- BLOCKED if schema validation fails or target references unresolvable.
 </execution>
 
 <completion>

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

@@ -47,8 +47,19 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 ### Pre-load specs
 1. **Debug specs**: Run `maestro load --type spec --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
 2. Optional — proceed without if unavailable.
+
+**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>
 
+<invariants>
+1. **Read-only analysis** — discovery agents MUST NOT modify source code; only `.workflow/issues/` is writable
+2. **Source tagging** — MUST set `source: "discover"` on every issues.jsonl row so concurrent writers (e.g. `manage-harvest`) can be distinguished and deduplicated
+3. **Dedup before write** — MUST check existing issues.jsonl for duplicates before appending new findings
+4. **Session traceability** — every discovery run MUST produce a session directory under `.workflow/issues/discoveries/` with full agent outputs
+5. **Schema compliance** — every issue row MUST conform to the canonical issue.json template schema
+6. **Idempotent re-run** — repeated execution with same scope and prompt MUST NOT create duplicate issues
+</invariants>
+
 <execution>
 Determine mode from $ARGUMENTS:
 - No arguments or empty → interactive selection via ask_user
@@ -56,6 +67,23 @@ Determine mode from $ARGUMENTS:
 - First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
 
 Follow '~/.maestro/workflows/issue-discover.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Mode Selection → Analysis** (Steps 1-2 → Steps 3-8)
+- REQUIRED: Mode correctly determined from arguments (multi-perspective or by-prompt).
+- REQUIRED: `.workflow/issues/` directory exists (auto-create if missing).
+- BLOCKED if E_NO_PROJECT (`.workflow/` missing) or E_EMPTY_PROMPT (by-prompt without text).
+
+**GATE 2: Analysis → Issue Creation** (Steps 8-9 → Steps 10-11)
+- REQUIRED: All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt).
+- REQUIRED: Findings deduplicated against existing issues.jsonl.
+- BLOCKED if E_DISCOVERY_FAILED (all agents returned no results).
+
+**GATE 3: Issue Creation → Completion** (Steps 11-12)
+- REQUIRED: Issues appended to issues.jsonl with correct schema and `source: "discover"`.
+- REQUIRED: Discovery session directory created with full agent outputs.
+- BLOCKED if schema validation fails on any issue record.
 </execution>
 
 <error_codes>

package/.agents/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_user.
+- 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/.agents/skills/manage-knowhow/SKILL.md

@@ -26,6 +26,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
@@ -46,8 +48,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/.agents/skills/manage-knowhow-capture/SKILL.md

@@ -46,11 +46,35 @@ $ARGUMENTS — type token + description + optional flags.
 | No args | — | — | ask_user (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_user.
+- 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/.agents/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/.agents/skills/manage-status/SKILL.md

@@ -26,12 +26,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/.agents/skills/manage-wiki/SKILL.md

@@ -45,13 +45,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/.agents/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/.agents/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/.agents/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/.agents/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>