maestro-flow 0.5.45 → 0.5.47

package/.claude/commands/quality-auto-test.md

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

package/.claude/commands/quality-debug.md

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

package/.claude/commands/quality-refactor.md

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

package/.claude/commands/quality-retrospective.md

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

package/.claude/commands/quality-review.md

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

package/.claude/commands/quality-sync.md

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

package/.claude/commands/quality-test.md

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

package/.claude/commands/security-audit.md

@@ -32,8 +32,19 @@ $ARGUMENTS — Parse tier and scope:
 | quick | ✓ | ✓ | — | — | — | — |
 | standard | ✓ | ✓ | ✓ | ✓ | — | — |
 | deep | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**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)

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

@@ -44,9 +44,36 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 ```
 </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, ui. Invalid category → E003
+3. **Scope isolation** — writes target ONLY the scope-resolved directory; project scope NEVER writes to global (~/.maestro/specs/), global scope NEVER writes to project (.workflow/specs/)
+4. **Confirmation gate** — MUST AskUserQuestion before appending entry (unless -y flag); NEVER write without user confirmation in interactive mode
+5. **Entry format invariance** — all entries MUST use `<spec-entry>` closed-tag format with id, keywords, and category attributes
+6. **Output boundary** — ALL file writes MUST target the scope-resolved specs directory (.workflow/specs/, ~/.maestro/specs/, .workflow/collab/specs/, or .workflow/collab/{uid}/specs/) and optionally .workflow/knowhow/ for --ref mode. NEVER modify source code or files outside these paths
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/specs-add.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Validate**
+- REQUIRED: Category and content both parsed from arguments.
+- REQUIRED: Category is a valid value (coding, arch, quality, debug, test, review, learning, ui).
+- REQUIRED: Scope resolved to a valid directory path.
+- BLOCKED if: E001 (missing args), E003 (invalid category), E004 (invalid scope), E005 (personal scope without uid).
+
+**GATE 2: Validate → Format**
+- REQUIRED: Specs directory exists for the resolved scope.
+- 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 AskUserQuestion (unless -y flag).
+- BLOCKED if: user declines confirmation — abort without writing.
+
 **Confirmation gate**: Unless -y flag is passed, after formatting the `<spec-entry>` block but before appending to the target file, AskUserQuestion showing the formatted entry, target file path, and scope. Proceed only on user confirm.
 </execution>
 

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

@@ -57,8 +57,33 @@ When loading entries with `ref` attribute, only the summary is shown with a load
 Use the load command to read the full referenced document.
 </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. **Scope layering** — global scope MUST merge both ~/.maestro/specs/ and .workflow/specs/; project scope loads .workflow/specs/ only; team adds .workflow/collab/specs/; personal adds .workflow/collab/{uid}/specs/
+4. **Category primary doc** — when --category is specified, the primary category doc MUST be loaded in full before cross-file matching
+5. **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
+6. **Output boundary** — this command produces NO file writes. All output is conversation-context injection only
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/specs-load.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Discover**
+- REQUIRED: Arguments parsed — at least one of --category or --keyword is provided, or empty args triggers full load.
+- REQUIRED: Scope resolved (default: global+project merged).
+- BLOCKED if: invalid scope value or invalid category value.
+
+**GATE 2: Discover → Load**
+- REQUIRED: At least one spec directory exists in the resolved scope chain.
+- BLOCKED if: E001 — .workflow/specs/ not initialized AND no global specs available. Warn and abort.
+
+**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 in any scope layer.
 </execution>
 
 <error_codes>

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

@@ -31,8 +31,34 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 - `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
 </context>
 
+<invariants>
+1. **Confirmation required** — MUST AskUserQuestion 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>
 Follow '~/.maestro/workflows/specs-remove.md' completely.
+
+### 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 AskUserQuestion (unless -y flag).
+- REQUIRED: If --cascade and entry has ref attribute, user additionally confirmed knowhow file deletion.
+- BLOCKED if: user declines — abort without modification.
 </execution>
 
 <error_codes>

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)