maestro-flow 0.5.45 → 0.5.47

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>

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

@@ -40,6 +40,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": [], "audit_result": null, "diverge_result": null,
@@ -117,6 +119,53 @@ id,title,description,task_type,dimension,deps,wave,status,findings,evidence,erro
 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, G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

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

@@ -36,6 +36,8 @@ $ARGUMENTS -- phase number and optional flags.
 
 **Session**: `.tests/auto-test/.csv-session/`
 **Output**: scenarios.csv, results.csv, discoveries.ndjson, report.json, state.json, reflection-log.md
+
+**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>
 
 <csv_schema>

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

@@ -84,6 +84,8 @@ When `--yes` or `-y`: Auto-confirm hypothesis selection, skip interactive sympto
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `understanding.md` (human-readable report)
+
+**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>
 
 <csv_schema>

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

@@ -32,6 +32,8 @@ $quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume e
 **Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-refactor-{slug}/`
+
+**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>
 
 <csv_schema>

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

@@ -95,6 +95,8 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - **test** → uat.md, .tests/ (UAT results, gaps, coverage)
 - Also reads: `.workflow/issues/issues.jsonl`, `.workflow/state.json`
 
+**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.
+
 ### Agent Registry
 
 | Agent | task_name | fork_turns | Responsibility |

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

@@ -74,6 +74,8 @@ When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validat
 
 **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) + `review.json` (structured review output)
+
+**Output boundary**: ALL file writes MUST target `.workflow/.csv-wave/{session-id}/`, `.workflow/state.json`, or `.workflow/issues/issues.jsonl` only. NEVER modify source code or files outside these paths. Review produces reports only — no source modifications.
 </context>
 
 <csv_schema>

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

@@ -24,10 +24,34 @@ $quality-sync "--since abc123 --dry-run"
 - `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
 - `--dry-run` -- Show what would be updated without writing
 
+**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>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Diff → Impact Trace**
+- REQUIRED: Git diff computed (or --full flag set for all files).
+- BLOCKED if no diff and no --full: nothing to sync (W001).
+
+**GATE 2: Impact Trace → Refresh**
+- REQUIRED: Affected components traced via doc-index.json.
+- BLOCKED if trace fails: cannot refresh docs without impact mapping.
+
+**GATE 3: Refresh → Completion**
+- REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
+- REQUIRED: If `--dry-run` is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
+- BLOCKED if missing: do not report completion without updated docs.
+
 ### Step 1: Validate
 
 Verify `.workflow/` directory exists — if missing, raise E001.

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

@@ -27,6 +27,8 @@ $ARGUMENTS -- phase number and optional flags.
 - `{target_dir}/.tests/test-results.json` -- pass/fail results
 - `{target_dir}/.tests/coverage-report.json` -- requirement coverage
 - `.tests/.csv-session/diagnosis.csv` + `diagnosis-results.csv`
+
+**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.
 </context>
 
 <csv_schema>

package/.codex/skills/security-audit/SKILL.md

@@ -25,10 +25,40 @@ $ARGUMENTS -- Parse tier and scope:
 | quick | Y | Y | -- | -- | -- | -- |
 | standard | Y | Y | Y | Y | -- | -- |
 | deep | Y | Y | Y | Y | Y | Y |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-security-audit-{tier}-{slug}/` or `.workflow/state.json` only. NEVER modify source code, configuration files, or dependencies. Audit is read-only analysis.
 </context>
 
+<invariants>
+1. **Audit is read-only** — NEVER modify source code, configuration, dependencies, or CI/CD files during audit. Security audit produces reports only.
+2. **Findings require file:line evidence** — every finding MUST reference a specific file:line location and include the vulnerable code pattern. No vague or category-only findings.
+3. **Severity NEVER downgraded without justification** — if a finding matches a known OWASP category, its severity follows OWASP guidance. Downgrading requires documented rationale (e.g., compensating control exists).
+4. **Tier coverage is mandatory** — all scan phases required by the selected tier MUST complete. NEVER skip a tier-required phase silently; failures are logged as W00x warnings.
+5. **False positive marking requires evidence** — marking a finding as false positive MUST include the compensating control or code path that prevents exploitation. NEVER dismiss findings without counter-evidence.
+6. **Secrets are never logged** — if secrets are discovered, report their location (file:line) and type but NEVER include the actual secret value in the report output.
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Recon → Scan**
+- REQUIRED: Tech stack detected and entry points identified.
+- REQUIRED: Auth/authz modules listed and data flow mapped.
+- BLOCKED if missing: cannot scan without entry points and data flow baseline.
+
+**GATE 2: Scan → Report** (tier-gated)
+- REQUIRED: OWASP Top 10 scan completed (all tiers).
+- REQUIRED: Dependency audit completed (all tiers).
+- REQUIRED: Secrets + CI/CD scan completed (standard/deep only).
+- REQUIRED: STRIDE + git history completed (deep only).
+- BLOCKED if tier-required scans incomplete: finish all tier-applicable phases before reporting.
+
+**GATE 3: Report → Completion**
+- REQUIRED: Severity matrix produced with file:line references and remediation.
+- REQUIRED: Artifact registered in state.json.
+- BLOCKED if missing: do not emit completion status without severity matrix.
+
 **Phase 1: Reconnaissance**
 
 1. Detect tech stack from package.json / go.mod / requirements.txt / Cargo.toml

package/.codex/skills/spec-add/SKILL.md

@@ -45,10 +45,38 @@ $ARGUMENTS — `<category> <title> <content>` where category selects the target
 Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
 
 Category is determined by the first positional argument.
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/` only. NEVER modify source code or files outside this path.
 </context>
 
+<invariants>
+1. **Idempotent append** — duplicate entry ID MUST be rejected (E003-level check on title + category match before write)
+2. **Category validation** — category MUST be one of: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation. Invalid category → E003
+3. **Confirmation gate** — MUST request_user_input before appending entry; NEVER write without user confirmation in interactive mode
+4. **Entry format invariance** — all entries MUST use `<spec-entry>` closed-tag format with id, keywords, and category attributes
+5. **Append-only** — MUST append to target file; NEVER overwrite or truncate existing spec content
+6. **Output boundary** — ALL file writes MUST target `.workflow/specs/` only. NEVER modify source code or files outside this path
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Validate**
+- REQUIRED: Category and content both parsed from arguments.
+- REQUIRED: Category is a valid value.
+- BLOCKED if: E001 (missing args), E003 (invalid category).
+
+**GATE 2: Validate → Format**
+- REQUIRED: `.workflow/specs/` directory exists.
+- REQUIRED: No duplicate entry with identical title + category already present in target file.
+- BLOCKED if: E002 (specs not initialized).
+
+**GATE 3: Format → Write**
+- REQUIRED: `<spec-entry>` block formatted with id, keywords, category attributes.
+- REQUIRED: User confirmation via request_user_input.
+- BLOCKED if: user declines confirmation — abort without writing.
+
 ### Step 1: Parse Input
 
 Extract category (first token), title (second token or quoted string), and content (remainder) from arguments.

package/.codex/skills/spec-load/SKILL.md

@@ -36,10 +36,36 @@ $spec-load "--category review"
 **--category loading**: Loads category's primary doc in full + matching entries from other files.
 
 **Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned.
+
+**Output boundary**: This command produces NO file writes. All output is conversation-context injection only.
 </context>
 
+<invariants>
+1. **Read-only** — NEVER modify, create, or delete any spec files during load. This command is purely a read operation
+2. **Output to context only** — loaded specs are injected into the conversation context; NEVER write loaded content to new files or modify existing files
+3. **Category primary doc** — when --category is specified, the primary category doc MUST be loaded in full before cross-file matching
+4. **Entry-level filtering** — --keyword filtering operates at `<spec-entry>` level via keywords attribute, NOT at file level; unmatched entries in a matching file are excluded
+5. **Graceful degradation** — if `.workflow/specs/` is missing but CLI search is available, fallback to CLI; only fail when both paths are exhausted
+6. **Output boundary** — this command produces NO file writes. All output is conversation-context injection only
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Discover**
+- REQUIRED: Arguments parsed — at least one of --category or --keyword provided, or empty args triggers full load.
+- BLOCKED if: invalid category value.
+
+**GATE 2: Discover → Load**
+- REQUIRED: At least one spec directory exists.
+- BLOCKED if: E001 — `.workflow/specs/` not initialized and no CLI fallback available.
+
+**GATE 3: Load → Display**
+- REQUIRED: Spec files read and entries parsed.
+- REQUIRED: Keyword filtering applied if --keyword was provided.
+- BLOCKED if: no readable spec files found.
+
 ### Step 1: Validate Specs Directory
 
 Verify `.workflow/specs/` exists (E001).

package/.codex/skills/spec-map/SKILL.md

@@ -53,6 +53,7 @@ $spec-map --continue "20260318-map-auth"
 
 **Output**: `.workflow/codebase/` (tech-stack.md, architecture.md, features.md, concerns.md)
 
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/` (output docs) and `.workflow/.csv-wave/{sessionId}/` (session state). NEVER modify source code or files outside these paths.
 </context>
 
 <csv_schema>

package/.codex/skills/spec-remove/SKILL.md

@@ -27,10 +27,38 @@ $ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
 **Flags:**
 - `--cascade` — When the target spec has a `ref` attribute linking to a knowhow document, also delete the referenced knowhow file. Without this flag, removal leaves an orphan knowhow file. Cascade checks the entry's `ref` attribute in the `<spec-entry>` tag.
 - `-y` — Skip confirmation prompt and proceed with removal immediately.
+
+**Output boundary**: File modifications MUST target ONLY the spec container file (.workflow/specs/*.md) and optionally the referenced knowhow file (.workflow/knowhow/*) when --cascade is used. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Confirmation required** — MUST request_user_input before deletion (unless -y flag); NEVER remove entries silently
+2. **Referential integrity** — before removing, check if other spec entries reference the target entry; warn user if references exist
+3. **Cascade explicit** — ref-type entries MUST NOT cascade-delete the linked knowhow file unless --cascade is explicitly passed; default leaves orphan knowhow intact
+4. **Atomic removal** — use `maestro wiki remove-entry` for atomic operation; NEVER manually edit spec files to remove entries
+5. **Index consistency** — wiki index MUST be auto-updated after removal; stale index entries are a hard failure
+6. **Output boundary** — file modifications MUST target ONLY the spec container file (.workflow/specs/*.md) and optionally the referenced knowhow file (.workflow/knowhow/*) when --cascade is used. NEVER modify source code or files outside these paths
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Lookup**
+- REQUIRED: Entry ID parsed from arguments.
+- BLOCKED if: E001 — no entry ID provided.
+
+**GATE 2: Lookup → Confirm**
+- REQUIRED: `.workflow/specs/` directory exists.
+- REQUIRED: Entry found in wiki index as a spec sub-node.
+- REQUIRED: Entry content loaded for user preview.
+- BLOCKED if: E002 (specs not initialized), E003 (entry not found), E004 (wrong type).
+
+**GATE 3: Confirm → Remove**
+- REQUIRED: User confirmed removal via request_user_input (unless -y flag).
+- REQUIRED: If --cascade and entry has ref attribute, user additionally confirmed knowhow file deletion.
+- BLOCKED if: user declines — abort without modification.
+
 ### Step 1: Parse Input
 
 Extract entry ID from arguments.