maestro-flow 0.5.42 → 0.5.44

package/.claude/commands/odyssey-improve.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
   - Write
@@ -189,7 +189,7 @@ Commit: `"odyssey-improve({slug}): DIAGNOSE — root cause analysis"`
 `retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → AskUserQuestion | `-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: AskUserQuestion per-fix confirmation | `-y`: auto-proceed, record `deferred`
 

package/.claude/commands/odyssey-planex.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
   - Write
@@ -108,7 +108,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>
@@ -122,7 +122,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)
@@ -295,7 +295,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: AskUserQuestion / `-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[].
@@ -312,11 +312,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/.claude/commands/odyssey-review-test-fix.md

@@ -133,6 +133,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}]
@@ -170,7 +172,7 @@ for tier in [critical, high, medium, low].filter(>= threshold):
 ```
 
 Normal: AskUserQuestion 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: AskUserQuestion (continue/accept/reclassify) | `-y`: classify remaining as `deferred`, proceed.
 Blanket "pre-existing" forbidden.
 
 Commit per tier: `"odyssey-review({slug}): FIX-{tier} — {N} items fixed"`
@@ -235,6 +237,7 @@ Every finding must have action (fix/issue/decision). Decision pending must AskUs
 | 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/.claude/commands/odyssey-ui.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
   - Write
@@ -136,7 +136,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"`
@@ -167,7 +167,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.
@@ -184,7 +184,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/.claude/commands/quality-auto-test.md

@@ -25,6 +25,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
@@ -90,6 +92,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:
+```
+AskUserQuestion("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[]:
 {
@@ -147,7 +157,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/.claude/commands/quality-debug.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
   - Write
@@ -73,6 +73,14 @@ Follow '~/.maestro/workflows/debug.md' completely.
 - BLOCKED if inconclusive: resume session or escalate.
 
 **Register artifact on completion (phase-scoped only):**
+
+Confirm before writing:
+```
+AskUserQuestion("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[]:
 {
@@ -92,13 +100,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 → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+```
+AskUserQuestion("<ask text> (yes/no)")
+→ yes: Skill("spec-add", "<category> <content> --description \"<summary>\"")
+→ no: skip this entry, proceed to next condition or completion
+```
 
 </execution>
 

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

@@ -30,7 +30,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>
@@ -55,6 +62,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 `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/.claude/commands/quality-review.md

@@ -80,6 +80,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:
+```
+AskUserQuestion("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/.claude/commands/quality-sync.md

@@ -42,7 +42,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>
 
@@ -80,7 +80,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/.claude/commands/quality-test.md

@@ -90,6 +90,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:
+```
+AskUserQuestion("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[]:
 {
@@ -163,7 +171,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/.claude/commands/security-audit.md

@@ -98,10 +98,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
+```
+Grep({
+  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.
@@ -159,6 +161,14 @@ Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {l
 ```
 
 **Register artifact on completion:**
+
+Confirm before writing:
+```
+AskUserQuestion("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/.claude/commands/spec-add.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
   - Write
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 <purpose>
 Add `<spec-entry>` to specs by category. 4 scopes: project (default), global, team, personal.
@@ -45,6 +46,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, AskUserQuestion showing the formatted entry, target file path, and scope. Proceed only on user confirm.
 </execution>
 
 <error_codes>
@@ -52,7 +55,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/.claude/commands/spec-load.md

@@ -27,7 +27,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/.claude/commands/spec-remove.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
   - Write

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

@@ -8,6 +8,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 <purpose>
 Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
@@ -27,6 +28,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), AskUserQuestion showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
 </execution>
 
 <error_codes>

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -145,22 +145,24 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 2. **Idempotent Writes**: Same-slug file exists = skip, never overwrite
 3. **Closed Tags**: All entries use `<spec-entry>` / `<knowhow-entry>` closed-tag format
 4. **Upstream Generates Manifest**: This skill only writes, never extracts knowledge
-5. **CLI First, File Fallback**: Prefer `maestro spec add` CLI; fall back to direct file append on failure
-6. **Ref Bridge**: Spec entries reference knowhow files via `ref` attribute
+5. **CLI First, File Fallback**: Prefer `maestro spec add` CLI with `--ref` param; fall back to direct file append on failure (with confirmation log)
+6. **Ref Bridge**: Spec entries reference knowhow files via `ref` attribute — both CLI path (`--ref` flag) and fallback path (`ref` attr in `<spec-entry>`) carry the ref
 </invariants>
 
 <execution>
 
 ### Step 1: Parse Package Path
 
-**Parse from `$ARGUMENTS`**:
+**Parse first positional from `$ARGUMENTS` and assign to `package_path`**:
 
 | Variable | Source | Default |
 |----------|--------|---------|
-| `package_path` | positional (required) | ERROR if missing |
+| `package_path` | first positional from $ARGUMENTS (required) | ERROR if missing |
 
 ```bash
-package_path="${PACKAGE_PATH}"
+# Parse first positional argument from $ARGUMENTS
+package_path="$(echo "$ARGUMENTS" | awk '{print $1}')"
+test -n "$package_path" || { echo "ERROR: package_path is required as first positional argument"; exit 1; }
 
 # Validate directory exists
 test -d "$package_path" || { echo "ERROR: Package path not found: $package_path"; exit 1; }
@@ -313,10 +315,12 @@ ${spec.body}
 
   // Prefer CLI, fallback to direct append
   const descFlag = spec.description ? ` --description "${spec.description}"` : '';
-  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
+  const refFlag = spec.ref ? ` --ref "${spec.ref}"` : '';
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag}${refFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
-    // Fallback: direct file append
+    // Fallback: direct file append — confirm before writing
+    REPORT(`CLI failed for "${spec.title}", falling back to direct append to ${targetFile}`);
     Edit(targetFile, { append: entryBlock });
   }
 
@@ -348,22 +352,30 @@ for file in ${knowhowPaths}; do
 done
 ```
 
-**6b: Verify spec entries**:
+**6b: Verify spec entries** (verify by actual targetFile set from manifest, not hardcoded categories):
+
+```javascript
+// Collect unique target files from manifest specs
+const verifiedFiles = new Set();
+for (const spec of manifest.specs) {
+  const targetFile = `.workflow/specs/${categoryFileMap[spec.category]}`;
+  verifiedFiles.add(targetFile);
+}
+```
 
 ```bash
 echo "=== Spec Entry Verification ==="
-grep -c "${slug}" .workflow/specs/coding-conventions.md 2>/dev/null && \
-  echo "  OK: coding-conventions.md" || echo "  MISSING: No entries in coding-conventions.md"
-
-grep -c "${slug}" .workflow/specs/architecture-constraints.md 2>/dev/null && \
-  echo "  OK: architecture-constraints.md" || echo "  MISSING: No entries in architecture-constraints.md"
+for target_file in ${verifiedFiles}; do
+  grep -c "${slug}" "${target_file}" 2>/dev/null && \
+    echo "  OK: ${target_file}" || echo "  MISSING: No entries in ${target_file}"
+done
 ```
 
-**6c: Verify ref links**:
+**6c: Verify ref links** (scan only the target files derived from the manifest):
 
 ```bash
 echo "=== Ref Link Verification ==="
-refs=$(grep -oP 'ref="knowhow/[^"]*"' .workflow/specs/coding-conventions.md .workflow/specs/architecture-constraints.md 2>/dev/null | grep "${slug}" || true)
+refs=$(grep -oP 'ref="knowhow/[^"]*"' ${verifiedFiles} 2>/dev/null | grep "${slug}" || true)
 
 if [ -n "$refs" ]; then
   echo "$refs" | while IFS= read -r ref; do

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

@@ -34,7 +34,7 @@ Extract canonical (first token, kebab-case) and definition (remainder) from argu
 
 ### Step 2: Validate Domain Directory
 
-Verify `.workflow/domain/glossary.yaml` exists (E002). If not, run `maestro domain init`.
+Verify `.workflow/domain/glossary.yaml` exists. If missing, ask user to confirm auto-initialization (`maestro domain init`). Proceed on confirmation; abort with E002 if declined. Skip confirmation when `--yes` flag is set.
 
 ### Step 3: Check Duplicates
 
@@ -42,7 +42,7 @@ Read existing glossary and check for:
 - Exact duplicate (same canonical name) → report existing entry, exit
 - Near match (Levenshtein ≤ 2 or alias overlap) → warn, ask to confirm or merge
 
-### Step 4: Extract Metadata
+### Step 4: Extract & Confirm Metadata
 
 Auto-derive from the definition and codebase context:
 - **aliases** (1-3): common abbreviations, Chinese translations, alternate forms
@@ -50,6 +50,8 @@ Auto-derive from the definition and codebase context:
 - **tier**: `core` | `extended` | `peripheral`
 - **relationships**: scan existing glossary for related terms
 
+Display a preview of all derived metadata and ask user to confirm or edit before proceeding. When `--yes` / `-y` flag is set, skip confirmation and write directly.
+
 ### Step 5: Register Term
 
 ```bash
@@ -66,7 +68,7 @@ Display: canonical name, definition, aliases, tier, relationships, and verify co
 | Code | Severity | Description |
 |------|----------|-------------|
 | E001 | fatal | Canonical name and definition are both required |
-| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first |
+| E002 | fatal | `.workflow/domain/` not initialized and user declined auto-init |
 | E003 | fatal | Term already registered with same canonical name |
 </error_codes>
 

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

@@ -77,7 +77,9 @@ Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2).
     "findings":      { "type": "string", "maxLength": 500 },
     "error":         { "type": "string" }
   },
-  "required": ["id", "result_status", "findings"]
+  "required": ["id", "result_status", "findings"],
+  "if":   { "properties": { "result_status": { "const": "completed" } } },
+  "then": { "required": ["id", "result_status", "findings", "patterns", "dimension"] }
 }
 ```
 
@@ -110,14 +112,29 @@ Each dimension agent populates `patterns` as a JSON array string of:
 
 ### Phase 3: Wave 2 — Cross-Reference + Catalog
 
-Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above.
+
+**prev_context filtering**: Only rows with `result_status=="completed"` are forwarded. For each wave 1 row that `failed`, append a `gap_note` line to the cross-ref instruction: `"[GAP] {dimension} scan failed — catalog may be incomplete for this dimension."` The cross-ref agent must not fabricate patterns for missing dimensions.
+
+Tasks:
 - Match against dedup set → mark as `documented`, `known`, or `new`
 - Merge duplicates across dimensions (same pattern found by multiple agents)
 - Flag contradictions with documented conventions
-- Build pattern catalog grouped by dimension
+- Build pattern catalog grouped by dimension; note any gap dimensions
 
 ### Phase 4: Persist
 
+**Preview gate** (unless `-y`/`--yes`):
+1. Build a summary table of all writes that will be performed:
+   - Knowhow file path + pattern count
+   - New patterns to append to `learnings.md` (list names + INS-ids)
+   - If `--save-spec`: spec entries to create
+   - If `--save-wiki`: wiki notes to create
+2. Display the summary to the user via `request_user_input` asking for confirmation (`y` to proceed, `n` to abort, `e` to edit selection).
+3. If user selects `e`, re-display with checkboxes and apply only checked items.
+4. If `-y`/`--yes` flag is set, skip the preview gate and write all items automatically.
+
+**Writes:**
 1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
 2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
 3. If `--save-spec`: invoke `spec-add` per new pattern
@@ -129,7 +146,7 @@ Single agent receives all wave 1 findings via `prev_context`. Uses same `output_
 |------|----------|-----------|----------|
 | E001 | error | Target path not found | Check path or use module name |
 | E002 | error | No source files in target | Check target has .ts/.js files |
-| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W001 | warning | Dimension agent failed — partial results | Exclude from prev_context, add gap_note, proceed |
 | W002 | warning | coding-conventions.md not found | All patterns marked "new" |
 </error_codes>
 
@@ -138,6 +155,7 @@ Single agent receives all wave 1 findings via `prev_context`. Uses same `output_
 - [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
 - [ ] Each finding has: name, dimension, confidence, anchors, description
 - [ ] Cross-reference performed (documented / known / new)
+- [ ] Preview summary shown and user confirmed (or `-y` flag bypassed)
 - [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
 - [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
 - [ ] If --save-spec / --save-wiki: entries created

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

@@ -52,10 +52,15 @@ From forcing question answers, extract: design patterns (with file:line anchors)
 
 Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
 
-### Stage 5: Persist
-1. Write `KNW-follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
-3. If `--save-wiki`: create wiki note entry
+### Stage 5: Persist (confirmation-gated)
+1. Display understanding map summary to user
+2. **Confirmation gate**: prompt user via `request_user_input` — "Save knowhow and specs? (y/n/edit)"
+   - `y` → proceed to write
+   - `n` → skip persistence, display summary only
+   - `edit` → let user modify findings before writing
+3. On confirmation: write `KNW-follow-{slug}-{date}.md` with understanding map
+4. On confirmation: append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
+5. If `--save-wiki`: create wiki note entry (also gated by step 2 confirmation)
 
 **Next steps:** `$learn-decompose <path>`, `$spec-add coding ...`, `$learn-second-opinion <file>`
 </execution>
@@ -75,6 +80,7 @@ Cross-reference against `coding-conventions.md`: documented vs undocumented patt
 - [ ] All 4 forcing questions applied per section
 - [ ] Patterns extracted with file:line anchors
 - [ ] Understanding map produced with concepts, patterns, assumptions, questions
-- [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
+- [ ] User confirmation obtained before persistence
+- [ ] `KNW-follow-{slug}-{date}.md` written (if confirmed)
+- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids (if confirmed)
 </success_criteria>