maestro-flow 0.5.46 → 0.5.47

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -22,10 +22,32 @@ Reads from:
 - `.workflow/scratch/*/index.json` — per-phase metadata and progress (resolved via state.json artifact registry)
 - `.workflow/scratch/*/.task/TASK-*.json` — individual task statuses (resolved via state.json artifact registry)
 - `.workflow/wiki-index.json` — unified wiki graph index (entry counts, health)
+
+**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>
 
+### 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: Dashboard sections rendered with available data.
+- REQUIRED: Next-step suggestion computed from state decision table.
+- BLOCKED: never — graceful degradation for missing sections.
+
 ### Step 1: Validate Project
 
 Verify `.workflow/` exists (E001) and `state.json` is present (E002).

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

@@ -28,10 +28,38 @@ $ARGUMENTS — subcommand and optional flags.
 - `--type <type>` — Filter: spec, knowhow, note, issue
 - `--fix` — Auto-fix issues during cleanup
 - `--json` — JSON output
+
+**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>
 Follow '~/.maestro/workflows/wiki-manage.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load** (Subcommand routing → Wiki data loading)
+- REQUIRED: Subcommand parsed and validated (health/search/cleanup/stats).
+- 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 → Report** (For cleanup --fix only)
+- REQUIRED: Preview of changes displayed to user.
+- REQUIRED: User confirmation before applying fixes.
+- BLOCKED if user declines fixes.
 </execution>
 
 <error_codes>

package/.codex/skills/odyssey-debug/SKILL.md

@@ -70,6 +70,8 @@ $ARGUMENTS
 4. Hypotheses ← S_DIAGNOSE | 5. Root Cause ← S_DIAGNOSE | 6. Fix & Confirmation ← S_FIX+S_CONFIRM
 7. Generalization ← S_GENERALIZE | 8. Discoveries ← S_DISCOVER | 9. Learnings ← S_RECORD
 
+**Output boundary**: ALL session artifacts MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-debug-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.
+
 **Knowledge Persistence categories (§9):**
 
 | Category | Content | Follow-up |
@@ -120,6 +122,48 @@ Base execution_discipline applies. Debug additions:
 Applies to: **S_ARCHAEOLOGY, S_EXPLORE, 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 → ARCHAEOLOGY**
+- REQUIRED: Issue parsed, SESSION_DIR created, session.json initialized with phase_goals[].
+- BLOCKED if: no issue and no session (E001).
+
+**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 AND delegate failed (partial results via W003 are acceptable).
+
+**GATE 3: EXPLORE → DIAGNOSE**
+- REQUIRED: explore.json written (or W006 skip logged), evidence phase=explore logged, G2 marked done.
+- BLOCKED if: exploration started but not completed.
+
+**GATE 4: DIAGNOSE → FIX**
+- REQUIRED: Root cause confirmed with evidence refs, session.json.root_cause written, G1 marked done.
+- BLOCKED if: hypotheses failed 3 times without escalation decision.
+
+**GATE 5: FIX → CONFIRM**
+- REQUIRED: Fix implemented with evidence phase=fix logged.
+- BLOCKED if: no fix attempted.
+
+**GATE 6: CONFIRM → GENERALIZE**
+- REQUIRED: Tests pass, CLI review completed, confirmation overall == confirmed, 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, G5 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -45,6 +45,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-improve-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
+**Output boundary**: ALL session artifacts 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 session artifacts outside these paths.
+
 **session.json — improve-specific fields:**
 ```json
 { "target": "", "dimensions": [], "baseline_metrics": {},
@@ -128,6 +130,53 @@ Base invariants apply. Additional: baseline metrics captured before any fix; eve
 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.
+- REQUIRED: Evidence phase=survey logged, understanding.md §2 updated, G1 marked done.
+- BLOCKED if: survey incomplete — both 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.
+
+**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, G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -51,6 +51,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": "",
@@ -131,6 +133,48 @@ id,title,description,task_type,criterion_refs,deps,wave,status,findings,evidence
 - Wave 2: Generalization agents (syntax-grep, semantic-scan, structural-match, historical-grep) -- parallel
 </csv_schema>
 
+<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.
+
+**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, G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -39,6 +39,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-review-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `explore.json` | `understanding.md` (sections 1-8)
 
+**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 },
@@ -111,6 +113,52 @@ id,title,description,task_type,dimension,deps,wave,status,findings,evidence,erro
 | 3 | Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) | 4 agents |
 </csv_schema>
 
+<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.
+
+**GATE 3: EXPLORE → REVIEW**
+- REQUIRED: explore.json written, evidence phase=explore logged, G2 marked done.
+- BLOCKED if: exploration started but not completed.
+
+**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, G5 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>