maestro-flow 0.5.46 → 0.5.48

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

@@ -34,8 +34,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/.agy/skills/spec-add/SKILL.md

@@ -43,9 +43,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 ask_question 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 ask_question (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, ask_question showing the formatted entry, target file path, and scope. Proceed only on user confirm.
 </execution>
 

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

@@ -56,8 +56,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/.agy/skills/spec-remove/SKILL.md

@@ -30,8 +30,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 ask_question 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 ask_question (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/.agy/skills/spec-setup/SKILL.md

@@ -25,9 +25,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 ask_question 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 ask_question (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), ask_question showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
 </execution>
 

package/.claude/agents/ralph-executor.md

@@ -1,6 +1,6 @@
 ---
 name: ralph-executor
-description: Single-step executor — ralph next + inline skill execution, multi-agent orchestration via SendMessage
+description: Single-step executor — ralph next + inline skill execution, unnamed nesting for multi-agent orchestration
 allowed-tools:
   - Read
   - Write
@@ -10,48 +10,42 @@ allowed-tools:
   - Grep
   - Skill
   - Agent
-  - SendMessage
 ---
 
 # Ralph Executor
 
 ## Role
 
-Single-step skill executor with multi-agent orchestration capability. Call `maestro ralph next` to load the skill prompt, execute it inline, return execution output via SendMessage. You are a sandboxed executor — arg resolution, context assembly, signal extraction, drift analysis, and session management are handled by the orchestrator.
+Single-step skill executor with multi-agent orchestration capability. Call `maestro ralph next` to load the skill prompt, execute it inline, return execution output as final text. You are a sandboxed executor — arg resolution, context assembly, signal extraction, drift analysis, and session management are handled by the orchestrator.
 
 ## Process
 
-**立即自启动**：你是 named mailbox teammate。收到含 `session_id` 和 `agent_name` 的 dispatch prompt 后，MUST 立即从 step 1 开始执行——禁止等待 mailbox 后续指令，禁止发送 idle notification。
+**立即自启动**：收到含 `session_id` 的 dispatch prompt 后，MUST 立即从 step 1 开始执行。
 
 1. Call `Bash("maestro ralph next --session {session_id}")` — **全量捕获 stdout，严禁截断管道**
    - Exit 0 → skill_prompt = stdout，继续执行
-   - Exit 1 → SendMessage 错误信息给 main，结束
-   - Exit 2 → SendMessage "所有 step 已完成" 给 main，结束
-   - Exit 3 → SendMessage "并发冲突" 给 main，结束
+   - Exit 1 → 返回错误信息，结束
+   - Exit 2 → 返回 "所有 step 已完成"，结束
+   - Exit 3 → 返回 "并发冲突"，结束
 2. Execute the skill prompt inline — follow all instructions faithfully
 3. Handle `<deferred_reading>` paths: Read files on demand during execution, do not batch-load upfront
-4. SendMessage({to: "main"}) 返回执行产物路径 + 摘要
+4. 返回执行产物路径 + 摘要作为最终输出文本（主流程通过 task-notification `<result>` 接收）
 
 ## Multi-Agent Orchestration
 
 当 skill prompt 需要多 agent 编排时（如 `maestro-execute` 的 wave 并行派发）：
 
-1. **派发 named worker**：调用 `Agent({name})` 派发 worker 为 named teammate，确保长时间任务存活：
-   ```
-   worker name 格式: {agent_name}-w{index}（如 exe-v2-001-w1, exe-v2-001-w2）
-   ```
-   > **必须传 name**：匿名 agent 执行完当前任务会 came to rest（死亡），后台任务完成通知无法唤醒。Named teammate 只会 idle，可被后台任务通知或 SendMessage 唤醒。
-2. **等待结果**：worker 通过 SendMessage 回传结果到 executor 的 mailbox
-3. **收集汇总**：接收所有 worker 的 SendMessage，汇总执行结果
-4. **回报主流程**：通过 `SendMessage({to: "main"})` 返回最终执行输出
+1. **派发 unnamed worker**：调用 `Agent()` 不传 name，子结果自动回流给本 executor（嵌套套娃模型）
+2. **等待结果**：子 Agent 的 task-notification 会自动回流到本 executor，可直接使用返回的 `<result>`
+3. **收集汇总**：汇总所有子 Agent 的执行结果
+4. **返回**：将最终执行输出作为文本返回（主流程通过 task-notification 接收）
 
 ### Worker Dispatch Template
 
 ```
 Agent({
-  name: "{agent_name}-w{index}",
   description: "执行子任务: {task_description}",
-  prompt: "你是 worker agent。执行以下任务：\n{task_content}\n\n完成后必须调用 SendMessage({to: \"{agent_name}\", summary: \"worker完成\", message: \"WORKER_RESULT: [执行结果摘要 + 产物路径]\"})。"
+  prompt: "执行以下任务：\n{task_content}\n\n返回执行结果摘要 + 产物路径。"
 })
 ```
 
@@ -62,12 +56,11 @@ Agent({
 | Field | Required | Description |
 |-------|----------|-------------|
 | `session_id` | Yes | ralph session ID |
-| `agent_name` | Yes | 本 agent 的 name，用于 sub-agent SendMessage 回传 |
 | execution context | No | 编排器注入的上下文（intent、boundary、goals、prior steps 等） |
 
 ## Output
 
-通过 `SendMessage({to: "main"})` 返回，格式：
+返回最终文本（主流程通过 task-notification `<result>` 接收），格式：
 
 ```
 EXECUTOR_OUTPUT:
@@ -78,14 +71,11 @@ EXECUTOR_OUTPUT:
 - error: <错误信息，仅 ERROR 时>
 ```
 
-失败时也必须 SendMessage，禁止静默崩溃。
-
 ## Constraints
 
-- 禁止无故空转——收到 session_id 即开始执行，不等待编排器的后续 mailbox 指令。等待 worker SendMessage 回传期间的 idle 是正常行为（平台自动触发 idle_notification，不可抑制）
+- 收到 session_id 即开始执行
 - Execute exactly one step per invocation
 - Do not call `maestro ralph complete` — completion is handled by the orchestrator
 - Do not read or modify `status.json` — session management is the orchestrator's responsibility
 - Do not skip execution steps or short-circuit — execute the full skill content
 - Do not insert/delete/reorder steps or evaluate decision nodes
-- 所有执行结果必须通过 SendMessage({to: "main"}) 回报，直接文本输出主流程看不到

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

@@ -37,6 +37,15 @@ Domain term lifecycle: discover/manual → register → active → (optional) de
 - `maestro domain deprecate <canonical> --successor <new>` — deprecate a term
 </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 AskUserQuestion before any glossary write; NEVER write without user confirmation
+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 (E002 if missing)
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/domain-add.md' completely.
 

package/.claude/commands/learn-decompose.md

@@ -28,8 +28,19 @@ $ARGUMENTS — target path/module and optional flags.
 
 **Storage read**: target files + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
 **Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-decompose-{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 files under analysis; all writes go to `.workflow/` only
+2. **Evidence-anchored findings** — every pattern MUST include at least one `file:line` anchor from source; unanchored patterns SHALL NOT be persisted
+3. **Dedup before persist** — MUST cross-reference against existing `learnings.md` and `coding-conventions.md` before writing; duplicate entries SHALL NOT be appended
+4. **Parallel agent isolation** — each dimension agent operates independently; NEVER share state between agents during analysis
+5. **Confirmation gate** — unless `-y` is set, MUST present all findings and target files via AskUserQuestion before any writes
+6. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
+</invariants>
+
 <state_machine>
 
 <states>
@@ -100,6 +111,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 <error_codes>
 | Code | Condition | Recovery |
 |------|-----------|----------|
+| E001 | No target path/module provided | Prompt user for target |
 | E002 | No source files in target | Check target has .ts/.js files |
 | W001 | One+ dimension agent failed | Proceed with available dimensions |
 | W002 | .workflow/specs/learnings.md missing or malformed | Treat all patterns as new; create file on persist |

package/.claude/commands/learn-follow.md

@@ -33,8 +33,46 @@ $ARGUMENTS — target and optional flags.
 
 **Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
 **Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.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 AskUserQuestion 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** (S_RESOLVE → S_CONTEXT)
+- REQUIRED: Target resolved to a readable source (file path, wiki entry, or search result).
+- BLOCKED if: target unresolvable after user prompt (E001/E002).
+
+**GATE 2: Reading → Extraction** (S_READ → S_EXTRACT)
+- 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** (S_EXTRACT → S_PERSIST)
+- 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** (S_PERSIST → END)
+- REQUIRED: Unless `-y`, AskUserQuestion 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.
+
+</execution>
+
 <state_machine>
 
 <states>
@@ -112,6 +150,9 @@ Write understanding map: Key Concepts, Patterns (table: name/location/convention
 <error_codes>
 | Code | Condition | Recovery |
 |------|-----------|----------|
+| E001 | No target path/wiki-id/topic provided | Prompt user for target |
+| E002 | Target path not found and wiki/grep search returned no results | Check path or broaden search terms |
+| W001 | Wiki forward/backlinks unavailable | Proceed without context web; note reduced coverage |
 | W002 | coding-conventions.md not found | All patterns marked "unknown status" |
 | W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
 </error_codes>

package/.claude/commands/learn-investigate.md

@@ -31,8 +31,20 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
 **Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.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 in S_FRAME, NEVER expand search scope without explicit user confirmation via S_ESCALATE
+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 AskUserQuestion; NEVER silently conclude as INCONCLUSIVE without user interaction
+7. **Confirmation gate** — unless `-y` is set, MUST present report.md path and spec-entries via AskUserQuestion before final writes
+</invariants>
+
 <state_machine>
 
 <states>
@@ -134,7 +146,9 @@ Append to .workflow/specs/learnings.md: confirmed → roles="implement", disprov
 <error_codes>
 | Code | Condition | Recovery |
 |------|-----------|----------|
+| E001 | No question text provided | Prompt user for investigation question |
 | E002 | --scope path not found | Check path |
+| W001 | Prior knowledge search returned no results | Proceed without prior context; note cold-start |
 | W002 | Very few evidence matches (<3) | Broaden search terms or expand scope |
 | W003 | All hypotheses inconclusive | Investigation marked INCONCLUSIVE |
 </error_codes>

package/.claude/commands/learn-second-opinion.md

@@ -34,8 +34,19 @@ $ARGUMENTS — target and optional mode flag.
 **Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
 
 **Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.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 of the 3 agents (Pragmatist/Purist/Strategist) MUST operate independently without shared state; NEVER pass one agent's findings to another
+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** — unless `-y` is set, MUST present findings and target files via AskUserQuestion before any writes
+</invariants>
+
 <state_machine>
 
 <states>
@@ -104,8 +115,11 @@ Interactive loop:
 <error_codes>
 | Code | Condition | Recovery |
 |------|-----------|----------|
+| E001 | No target provided | Prompt user for target (path, wiki ID, HEAD, staged, or phase) |
 | E002 | Unknown --mode value | Use: review, challenge, or consult |
+| E003 | Target resolution failed — path not found, wiki ID invalid, or no staged changes | Check target exists |
 | W001 | One review agent failed | Proceed with available perspectives |
+| W002 | Specs/wiki pre-load unavailable | Proceed without convention context; note reduced coverage |
 </error_codes>
 
 <success_criteria>

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

@@ -40,8 +40,19 @@ Multiple combinable. No flags + no description → interactive (scan + AskUserQu
 **CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
 
 **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/.claude/commands/maestro-analyze.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
+argument-hint: "[milestone|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
 allowed-tools:
   - Read
   - Write
@@ -27,17 +27,17 @@ Multi-dimensional analysis of a proposal, decision, or architecture choice via C
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.
+$ARGUMENTS -- milestone number for micro mode, topic text for macro/adhoc mode, no args for current milestone.
 
 **Dual-layer mode:**
 - **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
-- **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
+- **Micro mode** (numeric argument): Milestone-level deep analysis within an existing roadmap. Covers all phases under the milestone. Same analysis depth, broader scope. `analyze 1` = Milestone 1.
 
 **Disambiguation rule (mode selection):**
-- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as milestone number)
 - First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
-- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
-- Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
+- No positional arg → current milestone micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 milestone"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
 
@@ -52,9 +52,9 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 **Scope routing:**
 | Input | Mode | Scope |
 |-------|------|-------|
-| Pure digits (e.g. `1`, `42`) | micro | Phase-level deep analysis |
+| Pure digits (e.g. `1`, `42`) | micro | Milestone-level deep analysis |
 | Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
-| No positional arg + roadmap | micro | Milestone-wide |
+| No positional arg + roadmap | micro | Current milestone |
 | No positional arg + no roadmap | macro | Fallback |
 | `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
 
@@ -79,7 +79,7 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 **Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
 **Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
 **Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
-**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
+**Additional skip conditions**: input is already specific (explicit milestone number or unambiguous topic)
 **Exit condition**: all decision points settled → finalize session metadata
 </interview_protocol>
 
@@ -122,9 +122,9 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Phase/Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
-| Phase/Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {phase}` |
-| Phase/Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {milestone}` |
+| Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
 | Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
 | Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
 | Need more exploration | `/maestro-analyze {topic} -c` |
@@ -175,7 +175,7 @@ Both modes (full + quick):
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
-- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Artifact registered in state.json with correct scope/milestone
 - [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>

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

@@ -48,12 +48,23 @@ $ARGUMENTS — mode + optional flags.
 
 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>
+
 <state_machine>
 
 <states>

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

@@ -39,8 +39,19 @@ $ARGUMENTS — natural language 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/` (template JSON + index.json) and `.workflow/templates/design-drafts/` (intermediate drafts) only. NEVER modify source code or `.claude/commands/` files.
 </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 AskUserQuestion 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>
+
 <state_machine>
 
 <states>
@@ -141,7 +152,7 @@ Write `nodes.json`. Display resolved node list.
 |------|-----------|
 | Artifact boundary | Source outputs plan/spec/analysis/review |
 | Execution gate | Target contains `execute` |
-| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| Long-running | Target is maestro-plan, maestro-blueprint |
 | Post-testing | Source contains `test` or `auto-test` |
 | User-defined | type_hint == checkpoint |
 

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

@@ -30,10 +30,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, `.claude/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 AskUserQuestion 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 AskUserQuestion answered (for allow↔deny transitions with existing paths).
+- BLOCKED if: user declines mode switch.
+
 **Step 1: Parse subcommand**
 
 Extract from $ARGUMENTS: