maestro-flow 0.5.46 → 0.5.47

package/.claude/commands/maestro-swarm-workflow.md

@@ -43,6 +43,8 @@ Remaining        → intent
 | `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
 | `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
 | `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -196,6 +198,29 @@ Workflow 返回 JSON 后：
 6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Route**
+- REQUIRED: Intent text or `--script` flag parsed successfully.
+- BLOCKED if: no intent and no `--script` (E001).
+
+**GATE 2: Route → Context Assembly**
+- REQUIRED: Target script resolved unambiguously (single match or user-selected from candidates).
+- BLOCKED if: ambiguous routing without user resolution (E002).
+
+**GATE 3: Context → Dispatch**
+- REQUIRED: Args payload assembled with all required fields for target script.
+- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- BLOCKED if: script file not found (E003) or required args missing.
+
+**GATE 4: Dispatch → Ingest**
+- REQUIRED: Workflow execution completed (success or partial results available).
+- BLOCKED if: Workflow execution failed entirely (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 与 Ralph 集成

package/.claude/commands/maestro-tools-execute.md

@@ -35,8 +35,37 @@ $ARGUMENTS — Tool name, keyword, or --category filter
 Empty arguments enters interactive mode: list all tools for user selection.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST AskUserQuestion 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 via `maestro load --type knowhow`).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via AskUserQuestion (execute as-is / 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**:

package/.claude/commands/maestro-tools-register.md

@@ -35,8 +35,37 @@ $ARGUMENTS — Intent description
 ```
 </context>
 
+<invariants>
+1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords`, 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 AskUserQuestion 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 via `maestro wiki update`; NEVER recreate the document
+6. **Output boundary** — ALL file writes MUST target .workflow/knowhow/ (tool documents) and .workflow/specs/ (ref entries via maestro spec add) 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 in spec-load
+</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 AskUserQuestion.
+
+**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: Inline vs ref mode decided based on step count.
+- REQUIRED: User confirmed via AskUserQuestion (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).
+- REQUIRED: Spec ref entry registered (if user confirmed).
+- BLOCKED if: write failed or spec add returned error.
+
 ### Step 1: Intent Detection
 
 Parse $ARGUMENTS to determine mode:

package/.claude/commands/maestro-ui-codify.md

@@ -33,8 +33,19 @@ Flags:
 - `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
 - `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
 - `--overwrite`: Allow overwriting existing package directory
+
+**Output boundary**: ALL file writes MUST target the `--output-dir` path (default: `.workflow/reference_style/`) for reference packages, and `.workflow/knowhow/` for knowledge assets (via `codify-to-knowhow`). NEVER modify the source directory being analyzed.
 </context>
 
+<invariants>
+1. **Source read-only** — the source path being analyzed MUST NOT be modified; extraction is purely read-only
+2. **Phase-sequential loading** — workflow files (ui-codify-extract, ui-codify-package, ui-codify-knowhow) MUST be read only when their phase starts; NEVER load all phases eagerly
+3. **User confirmation before knowhow** — Phase 3→4 gate MUST present AskUserQuestion before generating knowledge assets; NEVER auto-proceed to knowhow generation
+4. **Overwrite protection** — existing package directory MUST NOT be overwritten without `--overwrite` flag (E003)
+5. **Artifact completeness** — all 5 required artifacts MUST exist before reporting completion; NEVER skip artifact verification
+6. **Token-first extraction** — design-tokens.json MUST be generated before layout-templates.json; layout extraction depends on token foundation
+</invariants>
+
 <execution>
 ## 1. Load UI Specs
 

package/.claude/commands/maestro-universal-workflow.md

@@ -33,6 +33,8 @@ Remaining         → intent
 **Library locations:**
 - Fixed scripts: `~/.maestro/workflows/swarm/wf-*.js`
 - Dynamic scripts: `~/.maestro/workflows/dynamic/uwf-*.js`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/workflows/dynamic/` (generated scripts) and `.workflow/scratch/{YYYYMMDD}-uwf-*/` (execution results). Fixed scripts at `~/.maestro/workflows/swarm/` are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -509,6 +511,36 @@ Findings: ${digest}
 12. **无反斜杠路径** — 字符串中路径用正斜杠（`\u`、`\a` 等会被解析为转义序列）
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Scan**
+- REQUIRED: Intent text or `--from`/`--resume` flag parsed.
+- BLOCKED if: no intent and no flags (E001).
+
+**GATE 2: Scan → Design/Execute**
+- REQUIRED: Library scan completed (both `swarm/` and `dynamic/` directories).
+- REQUIRED: User decision if matches found (reuse existing vs generate new).
+- BLOCKED if: scan fails to read script directories.
+
+**GATE 3: Design → Generate**
+- REQUIRED: Task decomposition completed with work_items, decision_points, data_flow.
+- REQUIRED: Phase orchestration and adversarial pattern selection determined by depth.
+- BLOCKED if: task cannot be decomposed (E002).
+
+**GATE 4: Generate → Execute**
+- REQUIRED: Script written to `~/.maestro/workflows/dynamic/uwf-{slug}.js`.
+- REQUIRED: `node --check` syntax validation passed.
+- REQUIRED: User confirmation via AskUserQuestion (unless resuming).
+- BLOCKED if: syntax validation fails after 2 retries (E003).
+
+**GATE 5: Execute → Persist**
+- REQUIRED: Workflow execution completed via `scriptPath` invocation.
+- BLOCKED if: Workflow execution failed (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 使用示例
@@ -569,3 +601,30 @@ universal-workflow 扫描时会同时检查 swarm/ 和 dynamic/ 目录，
 | E005 | 持久化失败 | 展示脚本内容，让用户手动保存 |
 
 </appendix>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent and no --from/--resume flag | Prompt user for intent text |
+| E002 | error | Task decomposition failed — cannot identify work_items | Require more specific intent description |
+| E003 | error | Generated script syntax error after 2 retries | Show script content + error for manual fix |
+| E004 | error | Workflow execution failed | Show error, offer --resume with runId |
+| E005 | error | Script persistence failed (filesystem write error) | Show script content for manual save |
+| W001 | warning | No matching scripts found in library scan | Proceed directly to S_DESIGN |
+| W002 | warning | Adversarial gate confidence < 50% | Flag low-confidence decision, suggest --depth deep |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and flags extracted (--name, --depth, --dry-run, --from, --resume)
+- [ ] Library scan completed across both swarm/ and dynamic/ directories
+- [ ] User decision captured if matching scripts found (reuse vs generate)
+- [ ] Task decomposition produced: work_items, decision_points, data_flow
+- [ ] Adversarial pattern selected per decision_point according to depth level
+- [ ] Blueprint presented to user with estimated agent count
+- [ ] Script generated as pure JavaScript with all 12 generation rules enforced
+- [ ] `node --check` syntax validation passed
+- [ ] User confirmation obtained before execution (unless --resume)
+- [ ] Workflow executed via scriptPath (not inline script string)
+- [ ] Script persisted to `~/.maestro/workflows/dynamic/uwf-{slug}.js`
+- [ ] Completion summary displayed with reuse/resume commands
+</success_criteria>

package/.claude/commands/maestro-update.md

@@ -30,10 +30,38 @@ $ARGUMENTS — optional flags.
 - `update-v{TO}-setup.md` — post-migration setup for version {TO}
 
 **Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
+
+**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 AskUserQuestion 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 AskUserQuestion (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
 
 ```
@@ -106,6 +134,16 @@ Next steps:
 
 </execution>
 
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/state.json` not found or unreadable | Run `/maestro-init` first |
+| E002 | error | Schema migration failed (npx tsx returned error) | Display backup restore command: `cp .workflow/state.json.backup-* .workflow/state.json` |
+| E003 | error | Version-specific setup doc failed to execute | Manual setup: read `~/.maestro/workflows/updates/update-v{target}-setup.md` |
+| W001 | warning | No version-specific setup doc found for target version | Proceed without setup; schema migration alone is sufficient |
+| W002 | warning | `--setup-only` but no setup script exists for current version | Display message and exit |
+</error_codes>
+
 <success_criteria>
 - [ ] Current version detected from state.json
 - [ ] Schema migrations run automatically (no manual intermediate steps)

package/.claude/commands/manage-codebase-rebuild.md

@@ -44,13 +44,42 @@ $ARGUMENTS -- optional flags.
 - `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
 - `.workflow/codebase/doc-index.json` -- generated documentation index
 - `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+
+**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>
 
+<invariants>
+1. **Destructive with confirmation** — rebuild clears `.workflow/codebase/` entirely; MUST confirm with user unless `--force` is set
+2. **Commit confirmation** — git commit MUST be confirmed by user unless `--force` is set; `--skip-commit` bypasses commit entirely
+3. **Partial failure tolerance** — if 1-3 mapper agents fail, proceed with partial results (W001); only abort if all 4 fail (E002)
+4. **Focus scoping** — when `--focus <area>` is set, MUST only regenerate docs relevant to that scope; leave unrelated docs untouched
+5. **State update** — MUST update state.json with rebuild timestamp on completion
+6. **KG pipeline mandatory** — MUST run `maestro kg index` after doc regeneration; KG validation failure is non-fatal (W003)
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 
 **When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Confirmation → Mapping** (Pre-flight → Agent spawn)
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- REQUIRED: User confirmed rebuild (or `--force` set). W002 if existing docs found.
+- BLOCKED if user declines confirmation.
+
+**GATE 2: Mapping → KG Pipeline** (Agent results → Knowledge Graph)
+- REQUIRED: At least 1 of 4 mapper agents returned valid results.
+- REQUIRED: All output files written to `.workflow/codebase/`.
+- REQUIRED: doc-index.json generated and valid.
+- BLOCKED if all 4 mapper agents failed (E002).
+
+**GATE 3: KG Pipeline → Commit** (Knowledge Graph → Git)
+- REQUIRED: `maestro kg index` executed (W003 if validation fails — non-blocking).
+- REQUIRED: state.json updated with rebuild timestamp.
+- REQUIRED: If not `--skip-commit`: user confirmed git commit (or `--force` set).
+- BLOCKED if state.json update fails.
 </execution>
 
 <completion>

package/.claude/commands/manage-drift-realign.md

@@ -58,8 +58,20 @@ Arguments: $ARGUMENTS
 - `.workflow/project.md`
 
 使用 `maestro timeline` CLI 构建统一的 git+session 时间线。
+
+**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.
 </context>
 
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；当文档说 X 但代码做 Y 时，文档漂移，NEVER 反向修改代码来匹配文档
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Never modify source code** — drift-realign only updates `.workflow/` metadata; source code files are read-only
+4. **Mutual exclusion** — `--report` 与 `--auto-archive` 互斥；同时传入 MUST trigger E006
+5. **Auto-depth escalation** — `drift_window` > 180 天 MUST auto-upgrade to `--depth deep` with W002 warning
+6. **Audit trail** — every triage decision MUST be logged in `drift-log.jsonl` with finding ID, action, and timestamp
+7. **Rebuild trigger** — codebase scope 的 3+ P0 finding MUST auto-trigger `/quality-sync --full` after triage
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
 

package/.claude/commands/manage-harvest.md

@@ -37,17 +37,41 @@ Arguments: $ARGUMENTS
 - `-y` / `--yes` — Skip confirmation prompts for all write operations (artifact selection, routing decisions, store writes). Useful for CI or batch harvesting.
 
 Additional flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+
+**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.
 </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 in order.
 
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction and classification happen in-memory.
-2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
-3. **Never modify source artifacts** — harvest is purely extractive.
-4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
-5. **Conflict pre-check on spec routing** — when routing to spec (Stage 6b), 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.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 

package/.claude/commands/manage-issue-discover.md

@@ -45,8 +45,19 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 ### Pre-load specs
 1. **Debug specs**: Run `maestro load --type spec --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
 2. Optional — proceed without if unavailable.
+
+**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>
 
+<invariants>
+1. **Read-only analysis** — discovery agents MUST NOT modify source code; only `.workflow/issues/` is writable
+2. **Source tagging** — MUST set `source: "discover"` on every issues.jsonl row so concurrent writers (e.g. `manage-harvest`) can be distinguished and deduplicated
+3. **Dedup before write** — MUST check existing issues.jsonl for duplicates before appending new findings
+4. **Session traceability** — every discovery run MUST produce a session directory under `.workflow/issues/discoveries/` with full agent outputs
+5. **Schema compliance** — every issue row MUST conform to the canonical issue.json template schema
+6. **Idempotent re-run** — repeated execution with same scope and prompt MUST NOT create duplicate issues
+</invariants>
+
 <execution>
 Determine mode from $ARGUMENTS:
 - No arguments or empty → interactive selection via AskUserQuestion
@@ -54,6 +65,23 @@ Determine mode from $ARGUMENTS:
 - First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
 
 Follow '~/.maestro/workflows/issue-discover.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Mode Selection → Analysis** (Steps 1-2 → Steps 3-8)
+- REQUIRED: Mode correctly determined from arguments (multi-perspective or by-prompt).
+- REQUIRED: `.workflow/issues/` directory exists (auto-create if missing).
+- BLOCKED if E_NO_PROJECT (`.workflow/` missing) or E_EMPTY_PROMPT (by-prompt without text).
+
+**GATE 2: Analysis → Issue Creation** (Steps 8-9 → Steps 10-11)
+- REQUIRED: All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt).
+- REQUIRED: Findings deduplicated against existing issues.jsonl.
+- BLOCKED if E_DISCOVERY_FAILED (all agents returned no results).
+
+**GATE 3: Issue Creation → Completion** (Steps 11-12)
+- REQUIRED: Issues appended to issues.jsonl with correct schema and `source: "discover"`.
+- REQUIRED: Discovery session directory created with full agent outputs.
+- BLOCKED if schema validation fails on any issue record.
 </execution>
 
 <error_codes>

package/.claude/commands/manage-issue.md

@@ -37,12 +37,35 @@ $ARGUMENTS -- subcommand + options. Parse first token as subcommand.
 **State files:**
 - `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
 - `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+
+**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>
 Parse subcommand from first token of $ARGUMENTS.
 Follow '~/.maestro/workflows/issue.md' completely.
 
+### 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: Issue data validated against issue.json template schema.
+- REQUIRED: For `close`: resolution text provided.
+- REQUIRED: For `link`: target task ID resolved and exists.
+- BLOCKED if schema validation fails or target references unresolvable.
 </execution>
 
 <completion>

package/.claude/commands/manage-kg-extractors.md

@@ -38,6 +38,8 @@ $ARGUMENTS -- optional flags.
 
 **Output:** `.workflow/kg/extractors.yaml` — declarative rules for PluginEngine.
 
+**Output boundary**: ALL file writes MUST target `.workflow/kg/extractors.yaml` only. NEVER modify source code or files outside this path. `--scan-only` MUST NOT write any files.
+
 **Rule format:**
 ```yaml
 version: 1
@@ -66,6 +68,16 @@ plugins:
 
 <execution>
 
+<invariants>
+1. **Read-only source code** — agents MUST only read source files for pattern discovery; NEVER modify source code
+2. **Scan-only safety** — `--scan-only` MUST stop after Phase 2 summary; NEVER write extractors.yaml
+3. **Append preservation** — `--append` MUST preserve existing rules in extractors.yaml; default (overwrite) MUST warn (W003) if file exists
+4. **Min-count threshold** — patterns with fewer occurrences than `--min-count` MUST be excluded unless explicitly overridden
+5. **User confirmation** — each pattern group MUST be confirmed/edited/skipped by user before writing (Phase 3, Step 2)
+6. **Schema compliance** — generated extractors.yaml MUST conform to version 1 PluginEngine schema with required fields (id, languages, mode, rules)
+7. **Validation mandatory** — MUST run `maestro kg index` after writing to verify new symbols are extractable
+</invariants>
+
 ### Phase 1: Discover patterns
 
 Spawn **3 parallel agents** to scan the codebase:
@@ -78,7 +90,21 @@ Spawn **3 parallel agents** to scan the codebase:
 
 Each agent returns: `[{pattern_type, regex_evidence, file_count, sample_matches: [{file, line, code}]}]`
 
-**Gate:** If all 3 agents return empty results → E002 (abort). If at least 1 agent succeeds, proceed with partial results (log W001 for failed agents).
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Generation** (Phase 1 → Phase 2)
+- REQUIRED: At least 1 of 3 agents returned valid pattern results.
+- BLOCKED if all 3 agents return empty results (E002).
+
+**GATE 2: Generation → Write** (Phase 2 → Phase 3)
+- REQUIRED: At least 1 pattern meets `--min-count` threshold.
+- REQUIRED: User confirmed pattern groups via AskUserQuestion.
+- BLOCKED if `--scan-only` is set — stop after summary.
+
+**GATE 3: Write → Validation** (Phase 3 → KG Index)
+- REQUIRED: extractors.yaml written with valid schema.
+- REQUIRED: `maestro kg index` executed to verify extraction.
+- BLOCKED if schema validation fails on generated YAML.
 
 ### Phase 2: Generate rules
 

package/.claude/commands/manage-knowhow-capture.md

@@ -44,11 +44,35 @@ $ARGUMENTS — type token + description + optional flags.
 | No args | — | — | AskUserQuestion (10 options) |
 
 **Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
+
+**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>
 Follow '~/.maestro/workflows/knowhow.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Type Detection → Content Collection** (Type routing → Content extraction)
+- REQUIRED: Type detected from first token or selected via AskUserQuestion.
+- 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` field generated or provided (under 120 chars).
+- REQUIRED: Tags generated in correct language matching content.
+- BLOCKED if required fields missing after user prompt (E002/E003).
+
 **Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
 
 **Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.

package/.claude/commands/manage-knowhow.md

@@ -24,6 +24,8 @@ Arguments: $ARGUMENTS
 
 Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
 
+**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.
+
 **Subcommands:**
 - `list` — List entries from both stores (default if no arguments)
 - `search <query>` — Full-text search across both stores
@@ -44,8 +46,32 @@ Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
 
 <execution>
 Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+
+### 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.
 </execution>
 
+<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>
+
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|

package/.claude/commands/manage-knowledge-audit.md

@@ -35,8 +35,21 @@ Arguments: $ARGUMENTS
 **互斥规则：** `--interactive`、`--mark`、`--delete`、`--purge` 四选一，同时传入多个 → E006。
 
 Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/`, `.workflow/knowhow/`, `.workflow/.trash/knowledge-audit-{timestamp}/`, `.workflow/issues/`, or audit report files (`audit-report-*.md`, `audit-log.jsonl`). NEVER modify source code files.
 </context>
 
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；spec/knowhow 声明 MUST 与代码实际行为一致；每个 finding 的 evidence MUST 包含代码引用（文件:行号）
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Deprecate over delete** — 文本存储首选 `status="deprecated"` 保留历史；NEVER 物理删除 spec/knowhow 文件
+4. **Purge 仅 artifact** — `--purge` MUST NOT 作用于 spec/knowhow scope (E004)
+5. **Rescue before delete** — 未 harvest 的 artifact 删除前 MUST 强制提示先跑 `/manage-harvest` (W002)
+6. **Conflict marker sync** — deprecate/delete 执行时如果目标条目有 conflict-marker，MUST 同步调用 `maestro spec conflict clear` 清除标记
+7. **Mutual exclusion** — `--interactive`/`--mark`/`--delete`/`--purge` 四选一；同时传入多个 MUST trigger E006
+8. **Dry-run safety** — `--dry-run` MUST NOT write any files; `--purge` 与 `--dry-run` 互斥 (E003)
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.