maestro-flow 0.5.46 → 0.5.47

package/.claude/commands/spec-setup.md

@@ -26,9 +26,39 @@ $ARGUMENTS (no arguments expected)
 - Project must contain source files to scan  # (see code: E002)
 </context>
 
+<invariants>
+1. **Non-destructive** — NEVER overwrite existing spec files; if a file already exists, skip it and report as already-initialized
+2. **Idempotent** — safe to re-run on an initialized project; re-running MUST NOT duplicate entries or corrupt existing content
+3. **Confirmation gate** — MUST AskUserQuestion showing all files to be created before writing; NEVER write without user confirmation
+4. **Output boundary** — ALL file writes MUST target .workflow/specs/ (spec files) and .workflow/knowhow/ (recipe knowhow) only. NEVER modify source code, .workflow/state.json, or files outside these paths
+5. **Core files mandatory** — coding-conventions.md, architecture-constraints.md, and learnings.md MUST always be created (unless they already exist)
+6. **Signal-driven optionals** — optional spec files (quality-rules.md, test-conventions.md, ui-conventions.md) MUST only be created when corresponding framework/tool signals are detected in the codebase; NEVER create optional files without evidence
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/specs-setup.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Precondition → Scan**
+- REQUIRED: .workflow/ directory exists.
+- REQUIRED: Project contains source files to scan.
+- BLOCKED if: E001 (.workflow/ not initialized), E002 (no source files).
+
+**GATE 2: Scan → Plan**
+- REQUIRED: Codebase scan completed — framework, language, and tooling signals collected.
+- REQUIRED: Core spec file list determined (always 3: coding-conventions, architecture-constraints, learnings).
+- REQUIRED: Optional spec files determined by detected signals only.
+
+**GATE 3: Plan → Write**
+- REQUIRED: User confirmed the full list of files to create via AskUserQuestion (showing core specs, optional specs, recipe knowhow, and detected signals).
+- BLOCKED if: user declines — abort without writing.
+
+**GATE 4: Write → Report**
+- REQUIRED: All confirmed files written to .workflow/specs/ and .workflow/knowhow/.
+- REQUIRED: Existing files skipped (not overwritten).
+- REQUIRED: .proposed.md files created when slug collision detected (W003).
+
 **Confirmation gate**: After scanning codebase and determining which files/directories will be created (core specs, optional specs, recipe knowhow), AskUserQuestion showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
 </execution>
 

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -57,6 +57,8 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 
 **Upstream**: `maestro-ui-codify`, `learn-decompose`, or any skill that generates a manifest
 **Downstream**: `maestro search --category coding`, `maestro load --type spec --keyword <slug>`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` (knowhow assets) and `.workflow/specs/` (spec entries) only. NEVER modify source code, manifest files, or files outside these paths.
 </context>
 
 <manifest_schema>

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

@@ -22,10 +22,36 @@ $ARGUMENTS — `<canonical> <definition>` where canonical is a kebab-case term n
 **Prerequisites**: `.workflow/domain/` must exist (run `maestro domain init` if missing).
 
 **Domain term lifecycle**: discover/manual → register → active → (optional) deprecated → removed
+
+**Output boundary**: ALL file writes MUST target `.workflow/domain/glossary.yaml` only. NEVER modify source code or files outside this path.
 </context>
 
+<invariants>
+1. **Single-term atomic operation** — each invocation registers exactly ONE term; NEVER batch-write multiple terms in a single execution
+2. **Glossary append-only** — existing terms in `glossary.yaml` SHALL NOT be modified or removed; only new entries are appended
+3. **Duplicate guard** — MUST check for exact canonical name match AND near-matches before writing; NEVER create duplicate entries
+4. **Confirmation mandatory** — MUST present term details (canonical, definition, aliases, tier, path) via `request_user_input` before any glossary write; NEVER write without user confirmation (unless `--yes`)
+5. **Schema compliance** — every term entry MUST include canonical name, definition, tier, and at least one alias/keyword; incomplete entries SHALL NOT be persisted
+6. **Domain directory prerequisite** — `.workflow/domain/` MUST exist before writing; NEVER auto-create the directory without user confirmation (E002 if missing)
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Validate**
+- REQUIRED: Canonical name and definition both parsed and non-empty.
+- BLOCKED if: either missing (E001).
+
+**GATE 2: Validate → Dedup Check**
+- REQUIRED: `.workflow/domain/glossary.yaml` exists and is readable.
+- BLOCKED if: domain directory not initialized (E002).
+
+**GATE 3: Dedup → Register**
+- REQUIRED: No exact duplicate found (E003). Near-matches resolved via user confirmation.
+- REQUIRED: User confirmed term details (canonical, definition, aliases, tier) via `request_user_input` (unless `--yes`).
+- BLOCKED if: user declines confirmation.
+
 ### Step 1: Parse Input
 
 Extract canonical (first token, kebab-case) and definition (remainder) from arguments.

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

@@ -11,8 +11,36 @@ Scan codebase for potential domain terms not yet in `.workflow/domain/glossary.y
 `--auto`: auto-register candidates with confidence ≥ 0.8 without prompting.
 </purpose>
 
+<context>
+$ARGUMENTS — optional `--auto` flag.
+
+**Output boundary**: ALL file writes MUST target `.workflow/domain/glossary.yaml` only (via `maestro domain add`). NEVER modify source code or files outside this path.
+</context>
+
+<invariants>
+1. **Read-only scan** — NEVER modify source code files during codebase scan; only glossary.yaml is written (via `maestro domain add`)
+2. **Dedup against existing** — MUST filter all candidates against current glossary before presenting; NEVER show already-registered terms
+3. **Confidence threshold for auto** — `--auto` MUST only register candidates with confidence ≥ 0.8; candidates below threshold MUST be skipped or presented for manual review
+4. **User confirmation required** — without `--auto`, MUST present candidates and obtain user selection before any registration; NEVER auto-register in interactive mode
+5. **Atomic registration** — each accepted candidate MUST be registered via individual `maestro domain add` call; NEVER batch-write directly to glossary.yaml
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Scan → Filter**
+- REQUIRED: Codebase scan completed with at least 1 candidate found.
+- BLOCKED if: no candidates found — report "No new domain terms detected" and exit.
+
+**GATE 2: Filter → Present**
+- REQUIRED: All candidates deduplicated against existing glossary.yaml entries.
+- BLOCKED if: glossary.yaml not found (E001) — prompt user to run `maestro domain init`.
+
+**GATE 3: Present → Register**
+- REQUIRED: User selection obtained (unless `--auto` with confidence ≥ 0.8).
+- BLOCKED if: user selects "skip" — exit without registration.
+
 ### Step 1: Scan Codebase
 
 Run `maestro domain discover` to scan TypeScript interfaces, types, enums, const patterns, API routes, and README headings.
@@ -41,3 +69,21 @@ Register? (all | select by number | skip)
 For each confirmed candidate, run `maestro domain add "<canonical>" "<definition>"`.
 
 </execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/domain/glossary.yaml` not found | Run `maestro domain init` first |
+| E002 | error | Codebase scan failed (no TypeScript/source files found) | Check project structure |
+| W001 | warning | No new candidates after dedup filtering | All potential terms already registered |
+| W002 | warning | `--auto` skipped low-confidence candidates | Review skipped candidates manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Codebase scanned for domain term candidates
+- [ ] Existing glossary terms filtered out (no duplicates presented)
+- [ ] Candidates ranked by confidence score
+- [ ] User selection obtained (interactive) or confidence threshold applied (--auto)
+- [ ] Selected candidates registered via `maestro domain add`
+- [ ] Summary displayed with registration count
+</success_criteria>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -9,6 +9,8 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 Wave-based template executor via `spawn_agents_on_csv`. Load template → bind variables → topological sort → group into barrier/non-barrier waves → spawn wave-by-wave → read results → report.
 
 Session: `.workflow/.maestro/MCP-{YYYYMMDD-HHmmss}/state.json`
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/MCP-*/` (session state) and `.workflow/.csv-wave/` (wave CSVs). Template files at `~/.maestro/templates/workflows/` are read-only during playback.
 </purpose>
 
 <invariants>

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

@@ -28,6 +28,7 @@ $maestro-quick "add dark mode toggle to settings page" --discuss --full
 
 **Output**: `.workflow/scratch/{slug}/` with plan.json, execution results, optional verification
 
+**Output boundary**: ALL metadata writes MUST target `.workflow/scratch/{slug}/`. Source code modifications are scoped to files identified in the plan. NEVER modify unrelated source files or `.workflow/state.json` structure beyond scratch task entries.
 </context>
 
 <invariants>
@@ -40,6 +41,22 @@ $maestro-quick "add dark mode toggle to settings page" --discuss --full
 
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Context**
+- REQUIRED: Task description provided (non-empty).
+- BLOCKED if: empty description (E001).
+
+**GATE 2: Analysis → Plan**
+- REQUIRED: Quick analysis completed with related files identified.
+- REQUIRED: Existing patterns found (≥1 similar implementation).
+- BLOCKED if: scratch directory creation failed (E002).
+
+**GATE 3: Execute → Report**
+- REQUIRED: All plan tasks attempted and statuses recorded.
+- REQUIRED: `plan.json` updated with task outcomes.
+- BLOCKED if: plan.json missing or no task statuses.
+
 ### Step 1: Parse Arguments
 
 Extract from arguments:

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

@@ -25,10 +25,41 @@ $maestro-tools-execute
 ```
 
 Empty arguments enters interactive mode: list all tools for user selection.
+
+**Output boundary**: File writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST request_user_input before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via request_user_input (execute / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
 ### Step 1: Load Tool
 
 **By name** (search all categories first, then filter):