maestro-flow 0.5.42 → 0.5.44

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

@@ -1,7 +1,7 @@
 ---
 name: manage-drift-realign
 description: Detect and realign .workflow/ artifact drift against code reality after refactoring
-argument-hint: "--scope <roadmap|spec|codebase|state|issue|knowhow|project|all> [--since YYYY-MM-DD|commit|HEAD~N] [--depth shallow|deep] [--dry-run] [--report] [--auto-archive] [--interactive]"
+argument-hint: "[--scope <roadmap|spec|codebase|state|issue|knowhow|project|all>] [--since YYYY-MM-DD|commit|HEAD~N] [--depth shallow|deep] [--dry-run] [--report] [--auto-archive] [--interactive]"
 allowed-tools:
   - read_file
   - write_file
@@ -45,7 +45,10 @@ Arguments: $ARGUMENTS
 
 **`--interactive`：** 逐项交互分诊（默认）。
 
-**互斥规则：** `--report` 覆盖 `--interactive`；`--auto-archive` 覆盖 `--interactive`。
+**互斥规则：**
+- `--report` 覆盖 `--interactive`
+- `--auto-archive` 覆盖 `--interactive`
+- `--report` 与 `--auto-archive` 互斥（同时传入 → E006）
 
 **状态文件读取：**
 - `.workflow/state.json`
@@ -129,6 +132,7 @@ Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
 | E003 | error | git 不可用（非 git 仓库） | 初始化 git |
 | E004 | error | `--since` 无法解析 | 检查日期格式或 commit ref |
 | E005 | error | 备份失败 | 检查磁盘空间 |
+| E006 | error | `--report` 与 `--auto-archive` 同时传入 | 二选一：`--report` 仅生成报告，`--auto-archive` 执行归档 |
 | W001 | warning | session 历史不可用（wiki 未索引） | 运行 `maestro wiki rebuild` |
 | W002 | warning | `drift_window` > 180 天 | 建议使用 `--depth deep` |
 | W003 | warning | 部分 scanner agent 失败 | 以部分覆盖继续 |

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

@@ -35,7 +35,10 @@ Arguments: $ARGUMENTS
 - `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
 - `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
 
-Flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+**Flags:**
+- `-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.
 </context>
 
 <execution>

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

@@ -5,6 +5,7 @@ argument-hint: "[multi-perspective | by-prompt <prompt>] [-y] [--scope <glob>] [
 allowed-tools:
   - read_file
   - write_file
+  - edit_file
   - shell
   - find_files
   - search

package/.agents/skills/manage-kg-extractors/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: manage-kg-extractors
 description: Analyze codebase patterns and generate .workflow/kg/extractors.yaml for custom symbol extraction
-argument-hint: "[--scan-only] [--append] [--language <lang>]"
+argument-hint: "[--scan-only] [--append] [--language <lang>] [--min-count <n>]"
 allowed-tools:
   - read_file
   - write_file
@@ -26,6 +26,7 @@ $ARGUMENTS -- optional flags.
 - `--scan-only` — Only report detected patterns, don't write extractors.yaml
 - `--append` — Append new rules to existing extractors.yaml (default: overwrite)
 - `--language <lang>` — Limit analysis to specific language (python, typescript, java, etc.)
+- `--min-count <n>` — Minimum occurrences to include a pattern (default: 3). Use `--min-count 1` to include rare patterns.
 
 **Analysis targets (per language):**
 
@@ -79,6 +80,8 @@ 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 2: Generate rules
 
 For each discovered pattern with ≥3 occurrences:
@@ -114,6 +117,7 @@ If `--scan-only`: stop after Phase 2 summary.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | .workflow/ not initialized | Run maestro-init first |
+| E002 | error | All 3 Phase 1 agents failed — zero patterns discovered | Check codebase language detection; retry with `--language` |
 | W001 | warning | No patterns detected for language | Try broader scan or different language |
 | W002 | warning | Pattern has < 3 occurrences | Skipped by default, include with --min-count 1 |
 | W003 | warning | Existing extractors.yaml will be overwritten | Use --append to preserve |

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

@@ -9,6 +9,7 @@ allowed-tools:
   - shell
   - find_files
   - search
+  - web_fetch
   - ask_user
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->

package/.agents/skills/manage-knowledge-audit/SKILL.md

@@ -34,6 +34,8 @@ Arguments: $ARGUMENTS
 
 **删除策略**默认 `--interactive`（三态面板逐项决策）；非交互模式 `--mark`（仅打标）/ `--delete`（软删到 `.trash/`）/ `--purge`（物理擦除，仅 artifact 且需双重确认）。
 
+**互斥规则：** `--interactive`、`--mark`、`--delete`、`--purge` 四选一，同时传入多个 → E006。
+
 Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
 </context>
 
@@ -113,6 +115,7 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | E003 | error | `--purge` 与 `--dry-run` 同用 | 二选一 |
 | E004 | error | `--purge` 作用于非 artifact 范围 | purge 仅支持 artifact scope |
 | E005 | error | 备份失败（`.trash/` 写入异常） | 检查磁盘空间与权限，重试 |
+| E006 | error | `--interactive`/`--mark`/`--delete`/`--purge` 同时传入多个 | 四选一，默认 `--interactive` |
 | W001 | warning | 检出冲突但用户选择 keep | 记入 report，不阻断 |
 | W002 | warning | 待删 artifact 无 harvest-log 记录 | 提示先跑 manage-harvest |
 | W003 | warning | 循环 supersedes 链 | 自动断环或交互选保留节点 |

package/.agents/skills/manage-wiki/SKILL.md

@@ -38,6 +38,7 @@ $ARGUMENTS — subcommand and optional flags.
 **Flags:**
 - `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
 - `--fix` — Auto-fix issues found during cleanup/connect (remove broken links, apply connections)
+- `--dry-run` — Preview mode, no writes. **Overrides `--fix`**: when both are passed, `--dry-run` takes precedence (preview only, no fixes applied).
 - `--json` — Output in JSON format
 - `--min-similarity N` — (connect) Minimum similarity threshold for link candidates
 - `--max N` — (connect) Maximum number of suggestions

package/.agents/skills/odyssey-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-debug
 description: Long-running debug cycle — archaeology, diagnosis, fix, confirmation, generalization, discovery, and knowledge persistence
-argument-hint: "<issue> [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<issue> [--template <name>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - read_file
   - write_file
@@ -239,6 +239,7 @@ All sibling bugs fixed or issued — no leftovers.
 | E001 | error | No issue, no session | Provide issue or -c |
 | W001 | warning | No relevant git history | Proceed |
 | W002 | warning | 3 retries exhausted | INCONCLUSIVE |
+| W003 | warning | Partial archaeology agent failure (Timeline or Blame) | Proceed with available results, log failed agent |
 | W005 | warning | Pending decisions | Filter evidence phase=decision |
 | W006 | warning | No CLI tools | Skip explore |
 </error_codes>

package/.agents/skills/odyssey-improve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-improve
 description: Long-running codebase improvement cycle — multi-dimensional audit, deep diagnosis, targeted fix, verify, generalize, and engineering knowledge persistence
-argument-hint: "<target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<target> [--dimensions <list>] [--fix-threshold <severity>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - read_file
   - write_file
@@ -191,7 +191,7 @@ Commit: `"odyssey-improve({slug}): DIAGNOSE — root cause analysis"`
 `retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → ask_user | `-y` → INCONCLUSIVE → S_RECORD.
 
 ### A_FIX
-1. Exhaustive fix: ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify — new findings append to current tier.
+1. Exhaustive fix: ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify **current tier's dimension only** (not all dimensions) — new findings at same or higher severity append to current tier. Cross-dimension regression checks run once at S_VERIFY after all tiers complete.
 2. For each fix: implement → evidence phase=fix
 3. Normal: ask_user per-fix confirmation | `-y`: auto-proceed, record `deferred`
 

package/.agents/skills/odyssey-planex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-planex
 description: Requirement-driven iterative cycle — plan, execute, strict verify, fix loop until acceptance criteria met
-argument-hint: "<requirement> [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
+argument-hint: "<requirement> [--template <name>] [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
 allowed-tools:
   - read_file
   - write_file
@@ -110,7 +110,7 @@ Applies to: **S_PLAN, S_VERIFY, S_GENERALIZE**. Logic in base.
 <state_machine>
 
 <states>
-S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_GENERALIZE → S_DISCOVER → S_RECORD → END
+S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_FIX → S_GENERALIZE → S_DISCOVER → S_RECORD → END
 </states>
 
 <transitions>
@@ -124,7 +124,7 @@ S_EXECUTE → S_VERIFY
 S_VERIFY → S_GENERALIZE   : all passed AND NOT skip_generalize
 S_VERIFY → S_RECORD       : all passed AND skip_generalize
 S_VERIFY → S_FIX          : some failed AND iteration < max
-S_VERIFY → S_PLAN         : fundamental plan flaw → cross_phase_loops++ (replan)
+S_VERIFY → S_PLAN         : fundamental plan flaw → cross_phase_loops++ (replan). **Criteria preservation:** acceptance_criteria[] statuses are preserved; only plan.tasks[] are regenerated. Previously passed criteria retain `passed` status; failed criteria reset to `pending` for re-verification after new plan execution.
 S_VERIFY → S_RECORD       : some failed AND iteration >= max (escalate)
 
 S_FIX → S_VERIFY (loop)
@@ -297,7 +297,7 @@ Iron gate — every acceptance criterion checked objectively.
 |--------|--------|
 | `test` | Run relevant tests, check pass/fail |
 | `grep` | Grep for expected pattern |
-| `cli-review` | `maestro delegate --role review --mode analysis` with criterion as focus |
+| `cli-review` | `maestro delegate "PURPOSE: Verify criterion {criterion_id}: {criterion}\nTASK: Read implementation code \| Check behavior matches criterion \| Report pass/fail with file:line evidence\nMODE: analysis\nCONTEXT: @{relevant_files}\nEXPECTED: JSON {criterion_id, status: passed\|failed, evidence: [{file, line, detail}]}" --role review --mode analysis` |
 | `manual` | Normal: ask_user / `-y`: record `deferred` |
 
 Record per criterion: `{"phase":"verification","type":"criterion-check","criterion_id":"AC1","method":"","result":"passed|failed","evidence":"","iteration":N}`. Update acceptance_criteria[].status. Append to iterations[].
@@ -314,11 +314,12 @@ Commit: `"odyssey-planex({slug}): VERIFY — acceptance check"`
 2. For each failed criterion: diagnose gap → targeted code fix
 3. CLI fix review (optional):
    ```bash
-   maestro delegate "PURPOSE: Review fixes for failing criteria
-   TASK: Check fix correctness | Verify no regressions on passing criteria
+   maestro delegate "PURPOSE: Review fixes for failing criteria; success = no regressions and fixes correct
+   TASK: Check fix correctness | Verify no regressions on passing criteria | Report verdict with file:line evidence
    MODE: analysis
    CONTEXT: @{modified_files} | Passing: {passing} | Fixed: {fixed}
-   EXPECTED: JSON {verdict, regression_risk, concerns}
+   EXPECTED: JSON {verdict: passed|concerns_found, regression_risk: low|medium|high, concerns: [{criterion_id, file, line, description}]}
+   CONSTRAINTS: Read-only | Check ALL passing criteria for regressions
    " --role review --mode analysis
    ```
 4. Append evidence (fix), update understanding.md section 5 → S_VERIFY

package/.agents/skills/odyssey-review-test-fix/SKILL.md

@@ -135,6 +135,8 @@ Glob latest session → read `session.json` → jump to `current_state`.
 ### A_ARCHAEOLOGY
 2 parallel Agents: Timeline (`git log --oneline -20 -- {files}`) + Blame (top 3 files `git blame -L {region}`). Evidence phase=archaeology.
 
+**Error handling:** If any archaeology agent fails (Timeline or Blame), log W003 and proceed with available results. If delegate fails, log W003 and proceed with local agent results only.
+
 `maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
 - PURPOSE: Review recent modifications related to {target}
 - EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
@@ -172,7 +174,7 @@ for tier in [critical, high, medium, low].filter(>= threshold):
 ```
 
 Normal: ask_user per tier. `-y`: auto-fix all.
-Remaining > 0 → retry (no max_loops limit). Unchanged 2 rounds → classify each individually.
+Remaining > 0 → retry (max_fix_rounds = 5). Unchanged 2 rounds → classify each individually. After 5 rounds with remaining > 0 → escalate: Normal: ask_user (continue/accept/reclassify) | `-y`: classify remaining as `deferred`, proceed.
 Blanket "pre-existing" forbidden.
 
 Commit per tier: `"odyssey-review({slug}): FIX-{tier} — {N} items fixed"`
@@ -237,6 +239,7 @@ Every finding must have action (fix/issue/decision). Decision pending must ask_u
 | E002 | error | Target path not found | Check path |
 | W001 | warning | No git history | Proceed |
 | W002 | warning | Some dimension agents failed | Partial coverage |
+| W003 | warning | Archaeology agent or delegate failure | Proceed with available results |
 </error_codes>
 
 <success_criteria>

package/.agents/skills/odyssey-ui/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-ui
 description: Long-running UI optimization cycle — visual survey, multi-dimensional audit, divergent exploration, fix, verify, generalize, and design knowledge persistence
-argument-hint: "<target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<target> [--dimensions <list>] [--fix-threshold <severity>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - read_file
   - write_file
@@ -138,7 +138,7 @@ Glob latest session → read `session.json` → jump to `current_state`.
 ### A_SURVEY
 1. **Design system inventory**: Scan for design tokens, CSS variables, theme imports
 2. **Current state analysis**: Styling patterns, layout strategy, component hierarchy
-3. **CLI-assisted**: `maestro delegate --role analyze` — survey tokens, spacing, typography, hierarchy, consistency
+3. **CLI-assisted**: `maestro delegate --role analyze --mode analysis` — survey tokens, spacing, typography, hierarchy, consistency
 4. Append evidence phase=survey. Update section 2. Mark G1.
 
 Commit: `"odyssey-ui({slug}): SURVEY — design token inventory"`
@@ -169,7 +169,7 @@ Goes beyond defect fixing — "what would make this delightful?"
 
 Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
 
-**Step 2 — CLI-assisted**: `maestro delegate --role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
+**Step 2 — CLI-assisted**: `maestro delegate --role analyze --mode analysis` — polish opportunities, micro-interactions, visual rhythm, delight moments
 
 **Step 3 — Consolidate**: Merge audit findings + divergent ideas → prioritized list (severity x impact x effort).
 Append evidence phase=diverge. Update section 4. Mark G3.
@@ -186,7 +186,7 @@ Commit: `"odyssey-ui({slug}): FIX — implement improvements"`
 
 ### A_VERIFY
 1. Run tests (lint, unit, visual regression)
-2. `maestro delegate --role review` — visual correctness, interaction states, accessibility, responsive
+2. `maestro delegate --role review --mode analysis` — visual correctness, interaction states, accessibility, responsive
 3. `needs_rework` → S_FIX. `verified` → mark G4. Update section 5, write `confirmation`.
 
 Commit: `"odyssey-ui({slug}): VERIFY — visual verification"`

package/.agents/skills/quality-auto-test/SKILL.md

@@ -27,6 +27,8 @@ Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-i
 Phase or task: $ARGUMENTS (required — phase number)
 
 **Flags:**
+- `-c N` — Resume from iteration N of an existing session (skips setup, resumes from last checkpoint)
+- `-y` — Skip confirmation prompts for artifact registration and issue creation
 - `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
 - `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
 - `--dry-run` — Generate test plan only, do not execute
@@ -92,6 +94,14 @@ Follow '~/.maestro/workflows/auto-test.md' completely.
 - Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
 
 **Register artifact on completion:**
+
+Unless `-y` flag is set, confirm before writing:
+```
+ask_user("Register auto-test artifact TST-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to next-step routing
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -149,7 +159,7 @@ Append to state.json.artifacts[]:
 - [ ] report.json includes confidence section
 - [ ] index.json updated with auto_test section
 - [ ] If spec source: traceability matrix built, traceability.md written
-- [ ] If failures: issues auto-created in issues.jsonl
+- [ ] If failures: issues created in issues.jsonl (confirmed by user unless `-y`)
 - [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
 - [ ] Next step routed based on convergence status
 </success_criteria>

package/.agents/skills/quality-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-debug
 description: Use when bugs, test failures, or unexpected behavior need systematic root cause investigation
-argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
+argument-hint: "[issue description] [-c] [--from-uat <phase>] [--parallel]"
 allowed-tools:
   - read_file
   - write_file
@@ -75,6 +75,14 @@ Follow '~/.maestro/workflows/debug.md' completely.
 - BLOCKED if inconclusive: resume session or escalate.
 
 **Register artifact on completion (phase-scoped only):**
+
+Confirm before writing:
+```
+ask_user("Register debug artifact DBG-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to knowledge inquiry
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -94,13 +102,19 @@ Append to state.json.artifacts[]:
 
 ### Post-debug Knowledge Inquiry
 
+For each matching condition, ask the user explicitly:
+
 | Condition | Ask | Route |
 |-----------|-----|-------|
 | Recurring root cause pattern (seen in prior debug) | "Document in debug-notes.md?" | spec-add debug |
 | Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
 | Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
 
-On confirm → `invoke_skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+```
+ask_user("<ask text> (yes/no)")
+→ yes: invoke_skill("spec-add", "<category> <content> --description \"<summary>\"")
+→ no: skip this entry, proceed to next condition or completion
+```
 
 </execution>
 

package/.agents/skills/quality-retrospective/SKILL.md

@@ -32,7 +32,14 @@ Post-execution retrospective (复盘): four parallel lenses (technical/process/q
 <context>
 Arguments: $ARGUMENTS
 
-Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+**Flags:**
+- `-y` — Skip confirmation prompts for external writes (issues.jsonl, spec entries, knowhow capture)
+- `--no-route` — Skip routing stage (produce retrospective files only, no spec/issue/knowhow writes)
+- `--compare N` — Compare current phase retrospective against phase N (requires single phase argument)
+- `--all` — Run retrospective on all completed phases that lack retrospective.json
+- `--lens <name>` — Restrict to specific lens (technical|process|quality|decision); default: all four
+
+Modes (scan/single/range/all) and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
 </context>
 
 <execution>
@@ -57,6 +64,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
 - REQUIRED: `retrospective.md` written (human-readable).
 - REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
 - REQUIRED: Note tips routed via `invoke_skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
+- REQUIRED: Unless `-y` flag is set, confirm before each external write (issues.jsonl append, spec-entry append, knowhow-capture). With `-y`, skip all confirmation prompts.
 - BLOCKED if routing incomplete: finish all write operations before reporting.
 
 ### Execution Constraints

package/.agents/skills/quality-review/SKILL.md

@@ -82,6 +82,14 @@ Follow '~/.maestro/workflows/review.md' completely.
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict
 
 **Register artifact on completion:**
+
+Confirm before writing state.json and issues.jsonl:
+```
+ask_user("Register review artifact REV-{NNN} in state.json and create {N} issues in issues.jsonl? (yes/no)")
+→ yes: proceed with both writes
+→ no: skip registration and issue creation, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {

package/.agents/skills/quality-sync/SKILL.md

@@ -44,7 +44,7 @@ Follow '~/.maestro/workflows/sync.md' completely.
 
 **GATE 3: Refresh → Completion**
 - REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
-- REQUIRED: state.json updated with sync timestamp.
+- REQUIRED: If `--dry-run` is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
 - BLOCKED if missing: do not report completion without updated docs.
 </execution>
 
@@ -82,7 +82,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 </error_codes>
 
 <success_criteria>
-- [ ] state.json updated with current sync timestamp
+- [ ] state.json updated with current sync timestamp (skipped if `--dry-run`)
 - [ ] Codebase docs refreshed for all affected components
 - [ ] doc-index.json reflects current file state
 - [ ] Changes tracked and logged

package/.agents/skills/quality-test/SKILL.md

@@ -92,6 +92,14 @@ Follow '~/.maestro/workflows/test.md' completely.
 - Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
 
 **Register artifact on completion:**
+
+Confirm before writing:
+```
+ask_user("Register test artifact TST-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -165,7 +173,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 - [ ] Pressure pass completed if > 80% pass rate
 - [ ] Confidence summary appended to uat.md
 - [ ] index.json uat fields updated
-- [ ] If issues: parallel debug agents spawned per gap cluster
+- [ ] If issues: confirm with user before spawning parallel debug agents per gap cluster
 - [ ] Gaps updated with root_cause, fix_direction, affected_files
 - [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
 - [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)

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

@@ -100,10 +100,12 @@ Check for:
 
 **Phase 4: Secrets Detection** (standard + deep)
 
-```bash
-# Current codebase
-grep -rn --include="*.ts" --include="*.js" --include="*.json" --include="*.env*" \
-  -E "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}" . || true
+```
+search({
+  pattern: "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}",
+  glob: "*.{ts,js,json,env*}",
+  output_mode: "content"
+})
 ```
 
 Check `.env.example` for leaked values. Check `.gitignore` for missing `.env` patterns.
@@ -161,6 +163,14 @@ Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {l
 ```
 
 **Register artifact on completion:**
+
+Confirm before writing:
+```
+ask_user("Register security-audit artifact RVW-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {

package/.agents/skills/spec-add/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: spec-add
 description: Add spec entry by category with role tagging
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
+argument-hint: "[--scope project|global|team|personal] [-y] <category> <content>"
 allowed-tools:
   - read_file
   - write_file
   - shell
   - find_files
   - search
+  - ask_user
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
@@ -47,6 +48,8 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 
 <execution>
 Follow '~/.maestro/workflows/specs-add.md' completely.
+
+**Confirmation gate**: Unless -y flag is passed, after formatting the `<spec-entry>` block but before appending to the target file, ask_user showing the formatted entry, target file path, and scope. Proceed only on user confirm.
 </execution>
 
 <error_codes>
@@ -54,7 +57,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 |------|----------|-------------|-------|
 | E001 | fatal | Category and content are both required | parse_input |
 | E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools, ui | parse_input |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, ui | parse_input |
 | E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
 | E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
 </error_codes>

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

@@ -29,7 +29,7 @@ $ARGUMENTS -- optional flags and keyword
   - `global`: global + project merged (~/.maestro/specs/ + .workflow/specs/)
   - `team`: project + team shared (.workflow/collab/specs/)
   - `personal`: project + team + personal (requires uid)
-- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, learning, ui.
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, quality, test, review, debug, learning, ui.
 - `--keyword <word>` — Filter by keyword within entries
 
 **File → Primary Category mapping:**

package/.agents/skills/spec-remove/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id> [--cascade]"
+argument-hint: "<entry-id> [--cascade] [-y]"
 allowed-tools:
   - read_file
   - write_file

package/.agents/skills/spec-setup/SKILL.md

@@ -8,6 +8,7 @@ allowed-tools:
   - shell
   - find_files
   - search
+  - ask_user
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
@@ -29,6 +30,8 @@ $ARGUMENTS (no arguments expected)
 
 <execution>
 Follow '~/.maestro/workflows/specs-setup.md' completely.
+
+**Confirmation gate**: After scanning codebase and determining which files/directories will be created (core specs, optional specs, recipe knowhow), ask_user showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
 </execution>
 
 <error_codes>

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

@@ -3,6 +3,7 @@ name: domain-add
 description: Register a domain term into project glossary
 argument-hint: <canonical> \"<definition>\"
 allowed-tools:
+  - ask_question
   - grep_search
   - run_command
   - view_file
@@ -37,6 +38,8 @@ Domain term lifecycle: discover/manual → register → active → (optional) de
 
 <execution>
 Follow '~/.maestro/workflows/domain-add.md' completely.
+
+**Confirmation gate**: Before writing to glossary.yaml, ask_question showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
 </execution>
 
 <error_codes>

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

@@ -1,7 +1,7 @@
 ---
 name: learn-decompose
 description: Extract design patterns from code into specs and wiki
-argument-hint: <path|module> [--patterns <list>] [--save-spec] [--save-wiki]
+argument-hint: <path|module> [--patterns <list>] [--save-spec] [--save-wiki] [-y]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -26,6 +26,7 @@ $ARGUMENTS — target path/module and optional flags.
 - `--patterns <list>`: Comma-separated pattern names to look for (default: detect all)
 - `--save-spec`: `Skill("spec-add")` for each new pattern
 - `--save-wiki`: create wiki note per dimension group
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **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`
@@ -61,7 +62,8 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+  → END           GATE: unless -y, ask_question showing files to write and patterns to persist — proceed only on confirm
+                  DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>
 
@@ -88,8 +90,8 @@ For each finding, match against known pattern set:
 | Status | Condition |
 |--------|-----------|
 | documented | Already in coding-conventions.md |
-| known | In .workflow/specs/learnings.md |
-| new | Not seen before |
+| known | In .workflow/specs/learnings.md (if file exists) |
+| new | Not seen before (or learnings.md absent — treat all as new) |
 
 Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
 
@@ -102,6 +104,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 |------|-----------|----------|
 | 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 |
 | W003 | Large target (>50 files) | Consider --patterns filter |
 </error_codes>
 

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

@@ -1,7 +1,7 @@
 ---
 name: learn-follow
 description: Guided reading of code or wiki to extract patterns
-argument-hint: <path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]
+argument-hint: <path|wiki-id|topic> [--depth shallow|deep] [--save-wiki] [-y]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -31,6 +31,7 @@ $ARGUMENTS — target and optional flags.
 - `--depth shallow` (default): key patterns and structure only
 - `--depth deep`: every function, every branch, every assumption
 - `--save-wiki`: create wiki note entry with reading notes
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **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`
@@ -66,7 +67,8 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
+  → END           GATE: unless -y, ask_question showing files to write and spec-entries to append — proceed only on confirm
+                  DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>