maestro-flow 0.5.45 → 0.5.47

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):

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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