maestro-flow 0.5.41 → 0.5.43

package/.agy/skills/team-swarm/roles/analyst/role.md

@@ -5,179 +5,175 @@ inner_loop: false
 output_tag: [analyst]
 message_types: 
 ---
-
-# Analyst Role — Phase 2-4
-
-Tag: `[analyst]` | Prefix: `ANALYST-*`
-Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
-
-## Boundaries
-
-### MUST
-- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
-- Produce `<session>/artifacts/best-solution.md` as the final deliverable
-- Explain WHY the best path won (which decisions mattered, evidence chain)
-- Compare best vs runner-ups to surface stability vs luck
-- Document convergence story (entropy curve, when stagnation hit)
-
-### MUST NOT
-- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
-- Modify best.json, trails, or pheromone state
-- Generate solutions of its own — analyst synthesizes existing ant outputs
-- Exceed ~150 lines in best-solution.md (be sharp, not verbose)
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
-| Best solution | `<session>/best.json` | Yes |
-| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
-| All trails | `<session>/trails/*.jsonl` | Yes |
-| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
-| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
-| Issues log | `<session>/wisdom/issues.md` | Optional |
-
-Workflow:
-1. Extract session path from task description
-2. Read swarm-config.json -> capture objective
-3. Read best.json -> identify best ant
-4. Read full swarm-report.json -> get top_k + convergence_curve
-5. Read the best ant's full artifact for evidence chain
-6. Read all trails/*.jsonl into a list (chronological)
-
-## Phase 3: Synthesis
-
-### 3.1 Structure the report
-
-Layout for `best-solution.md`:
-
-```markdown
-# Swarm Result — <objective_short_form>
-
-## Best Solution
-
-**Path**: node_a → node_c → node_f
-**Verified Score**: 0.82
-**Iteration**: 3 of 5
-**Ant**: ANT-3-2
-
-### Summary
-<one paragraph — what the best solution proposes and why it answers the objective>
-
-### Evidence Chain
-- `src/foo.ts:42` — <how this evidence supports the decision>
-- `tests/foo.spec.ts:18` — <...>
-
-### Candidate Artifact
-<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
-
-## Why This Path Won
-
-| Decision | Pheromone-guided? | Why it mattered |
-|----------|-------------------|-----------------|
-| start = node_a | weighted | <reason> |
-| a → c | yes (0.45 hint) | <reason> |
-| c → f | NO (deviation) | <reason> — this was the key call |
-
-## Runner-Up Solutions
-
-| Rank | Ant | Path | Score | Diff from best |
-|------|-----|------|-------|----------------|
-| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
-| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
-
-## Convergence Story
-
-Iterations: 4 of 5 max
-Trigger: stagnation (best unchanged for 2 iterations)
-
-Entropy curve:
-- iter 1: 3.21 (broad exploration)
-- iter 2: 2.45 (narrowing on node_a region)
-- iter 3: 1.85 (best emerges at ANT-3-2)
-- iter 4: 1.72 (consensus around best, no improvement)
-
-Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
-
-## Caveats
-
-- <e.g., 40% of ants in iter 2 flagged as hallucinations>
-- <e.g., evidence for node_f is single-source — recommend manual verification>
-- <e.g., search space had only N nodes — larger space may surface better solutions>
-
-## Reproducibility
-
-- Config: `swarm-config.json` (pinned)
-- Best path: `best.json`
-- Full trails: `trails/<iter>.jsonl`
-- Random seed: <if used>
-```
-
-### 3.2 Interpretation rules
-
-- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
-- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
-- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
-- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
-
-### 3.3 Constraints
-
-- Target ≤ 150 lines
-- No prose padding — every section earns its place
-- Quote evidence verbatim where possible (file:line refs)
-- Don't editorialize beyond what evidence supports
-
-## Phase 4: Verify + Publish
-
-### Behavioral Traits
-
-#### Accuracy
-- Every cited path/score MUST match best.json or trails source
-- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
-- Convergence curve numbers MUST match swarm-report.json#convergence_curve
-
-#### Feedback Contract
-| Field | Required | Content |
-|-------|----------|---------|
-| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
-| line_count | Always | int (target ≤ 150) |
-| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
-
-#### Quality Gate
-- Final report file exists and parses as markdown
-- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
-- Line count ≤ 200 (hard cap — fail if exceeded, retry with sharper edit)
-
-### Verification Steps
-
-1. Read written best-solution.md back
-2. Cross-check best.score against best.json
-3. Confirm runner-up scores against trails
-4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
-5. Count lines — if > 200, condense and rewrite
-
-### State Update
-
-```json
-{
-  "task_id": "ANALYST-1",
-  "role": "analyst",
-  "status": "completed",
-  "artifact_path": "<session>/artifacts/best-solution.md",
-  "best_score": <float>,
-  "best_ant_id": "<id>",
-  "line_count": <int>,
-  "verification": "cross_ref_pass + evidence_verified"
-}
-```
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
-| Trails empty | Same as above — no exploration data to analyze |
-| Best ant artifact missing | Use only best.json fields; note as caveat |
-| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |
-| Line count > 200 after rewrite | Hard-fail report; coordinator decides retry vs accept |
+
+# Analyst Role — Phase 2-4
+
+Tag: `[analyst]` | Prefix: `ANALYST-*`
+Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
+
+## Boundaries
+
+### MUST
+- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
+- Produce `<session>/artifacts/best-solution.md` as the final deliverable
+- Explain WHY the best path won (which decisions mattered, evidence chain)
+- Compare best vs runner-ups to surface stability vs luck
+- Document convergence story (entropy curve, when stagnation hit)
+
+### MUST NOT
+- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
+- Modify best.json, trails, or pheromone state
+- Generate solutions of its own — analyst synthesizes existing ant outputs
+- Pad best-solution.md with prose — every section must earn its place
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Best solution | `<session>/best.json` | Yes |
+| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
+| All trails | `<session>/trails/*.jsonl` | Yes |
+| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
+| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
+| Issues log | `<session>/wisdom/issues.md` | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Read swarm-config.json -> capture objective
+3. Read best.json -> identify best ant
+4. Read full swarm-report.json -> get top_k + convergence_curve
+5. Read the best ant's full artifact for evidence chain
+6. Read all trails/*.jsonl into a list (chronological)
+
+## Phase 3: Synthesis
+
+### 3.1 Structure the report
+
+Layout for `best-solution.md`:
+
+```markdown
+# Swarm Result — <objective_short_form>
+
+## Best Solution
+
+**Path**: node_a → node_c → node_f
+**Verified Score**: 0.82
+**Iteration**: 3 of 5
+**Ant**: ANT-3-2
+
+### Summary
+<one paragraph — what the best solution proposes and why it answers the objective>
+
+### Evidence Chain
+- `src/foo.ts:42` — <how this evidence supports the decision>
+- `tests/foo.spec.ts:18` — <...>
+
+### Candidate Artifact
+<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
+
+## Why This Path Won
+
+| Decision | Pheromone-guided? | Why it mattered |
+|----------|-------------------|-----------------|
+| start = node_a | weighted | <reason> |
+| a → c | yes (0.45 hint) | <reason> |
+| c → f | NO (deviation) | <reason> — this was the key call |
+
+## Runner-Up Solutions
+
+| Rank | Ant | Path | Score | Diff from best |
+|------|-----|------|-------|----------------|
+| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
+| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
+
+## Convergence Story
+
+Iterations: 4 of 5 max
+Trigger: stagnation (best unchanged for 2 iterations)
+
+Entropy curve:
+- iter 1: 3.21 (broad exploration)
+- iter 2: 2.45 (narrowing on node_a region)
+- iter 3: 1.85 (best emerges at ANT-3-2)
+- iter 4: 1.72 (consensus around best, no improvement)
+
+Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
+
+## Caveats
+
+- <e.g., 40% of ants in iter 2 flagged as hallucinations>
+- <e.g., evidence for node_f is single-source — recommend manual verification>
+- <e.g., search space had only N nodes — larger space may surface better solutions>
+
+## Reproducibility
+
+- Config: `swarm-config.json` (pinned)
+- Best path: `best.json`
+- Full trails: `trails/<iter>.jsonl`
+- Random seed: <if used>
+```
+
+### 3.2 Interpretation rules
+
+- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
+- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
+- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
+- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
+
+### 3.3 Constraints
+
+- No prose padding — every section earns its place
+- Quote evidence verbatim where possible (file:line refs)
+- Don't editorialize beyond what evidence supports
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy
+- Every cited path/score MUST match best.json or trails source
+- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
+- Convergence curve numbers MUST match swarm-report.json#convergence_curve
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
+| line_count | Always | int (informational) |
+| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
+
+#### Quality Gate
+- Final report file exists and parses as markdown
+- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
+
+### Verification Steps
+
+1. Read written best-solution.md back
+2. Cross-check best.score against best.json
+3. Confirm runner-up scores against trails
+4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
+
+### State Update
+
+```json
+{
+  "task_id": "ANALYST-1",
+  "role": "analyst",
+  "status": "completed",
+  "artifact_path": "<session>/artifacts/best-solution.md",
+  "best_score": <float>,
+  "best_ant_id": "<id>",
+  "line_count": <int>,
+  "verification": "cross_ref_pass + evidence_verified"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
+| Trails empty | Same as above — no exploration data to analyze |
+| Best ant artifact missing | Use only best.json fields; note as caveat |
+| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |

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

@@ -8,6 +8,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 <purpose>
 Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are automatically injected into agent context via hooks (domain-compact for all prompts, domain-expanded on keyword match).
@@ -38,6 +39,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, AskUserQuestion showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
 </execution>
 
 <error_codes>

package/.claude/commands/learn-decompose.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:
   - Read
   - Write
@@ -24,6 +24,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`
@@ -59,7 +60,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, AskUserQuestion 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>
 
@@ -86,8 +88,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).
 
@@ -100,6 +102,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/.claude/commands/learn-follow.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:
   - Read
   - Write
@@ -29,6 +29,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`
@@ -64,7 +65,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, AskUserQuestion 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>
 

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

@@ -1,7 +1,7 @@
 ---
 name: learn-investigate
 description: Investigate questions with hypothesis testing and evidence logging
-argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N] [-y]"
 allowed-tools:
   - Read
   - Write
@@ -22,6 +22,7 @@ $ARGUMENTS — question text and optional flags.
 **Flags**:
 - `--scope <path>`: Restrict to files under this dir (default: entire project)
 - `--max-hypotheses N`: Max hypotheses before escalation (default: 3)
+- `-y`: Skip confirmation prompts for report/spec writes
 
 **Storage write**:
 - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
@@ -57,11 +58,11 @@ S_PATTERN:
   → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
 
 S_HYPOTHESIZE:
-  → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
-  → S_TEST        WHEN: no CLI tools OR trivial hypotheses              DO: A_FORM_HYPOTHESES
+  → S_CLI_EXPLORE WHEN: CLI tools enabled (at least one tool in cli-tools.json enabled) AND hypotheses non-trivial (require cross-file tracing or data-flow analysis)    DO: A_FORM_HYPOTHESES
+  → S_TEST        WHEN: no CLI tools OR trivial hypotheses (answerable by local Grep/Read)    DO: A_FORM_HYPOTHESES
 
 S_CLI_EXPLORE:
-  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --role explore --mode analysis, run_in_background, STOP)
+  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --to <first-enabled-tool> --mode analysis, run_in_background, STOP)
 
 S_TEST:
   → S_REPORT      WHEN: hypothesis confirmed                  DO: A_TEST_HYPOTHESIS
@@ -73,7 +74,8 @@ S_ESCALATE:
   → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
 
 S_REPORT:
-  → END           DO: A_SYNTHESIZE_REPORT
+  → END           GATE: unless -y, AskUserQuestion showing report.md path and spec-entries to append — proceed only on confirm
+                  DO: A_SYNTHESIZE_REPORT
 
 </transitions>
 
@@ -108,7 +110,7 @@ Rank by plausibility (evidence strength). Write to understanding.md:
 maestro delegate "PURPOSE: Gather evidence for hypotheses
 TASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns
 EXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]
-" --role explore --mode analysis
+" --to <first-enabled-tool> --mode analysis
 ```
 Run_in_background, STOP, wait. On callback: append to evidence.ndjson.
 

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

@@ -1,7 +1,7 @@
 ---
 name: learn-second-opinion
 description: Get alternative perspectives — review, challenge, or consult
-argument-hint: "<target> [--mode review|challenge|consult]"
+argument-hint: "<target> [--mode review|challenge|consult] [-y]"
 allowed-tools:
   - Read
   - Write
@@ -27,7 +27,9 @@ $ARGUMENTS — target and optional mode flag.
 | `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
 | Phase number | Resolve via state.json.artifacts[] → plan.json |
 
-**Flags**: `--mode review|challenge|consult` (default: review)
+**Flags**:
+- `--mode review|challenge|consult` (default: review)
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
 
@@ -62,7 +64,8 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
+  → END           GATE: unless -y, AskUserQuestion showing files to write and spec-entries to append — proceed only on confirm
+                  DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
 

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-amend
 description: Generate overlays to fix workflow command deficiencies
-argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run] [-y]"
 allowed-tools:
   - Read
   - Write

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

@@ -45,7 +45,7 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 |------|--------|---------|
 | `-y` / `--yes` | Auto mode — skip interactive scoping, use recommended defaults, auto-deepen | false |
 | `-c` / `--continue` | Resume from existing session (auto-detect session folder + discussion.md) | false |
-| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only) | false |
+| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only). **Precedence**: when combined with `-c`, the resumed session preserves its original mode (full or quick); `-q` does NOT override a resumed full session to quick mode. | false |
 | `--from <source>` | Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path) | — |
 | `--gaps [ISS-ID]` | Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl | — |
 
@@ -86,51 +86,9 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
-### Evidence-Backed Decisions
-
-Every decision MUST trace to independently gathered evidence. Manual Read/Grep is preparation — NOT evidence. Valid evidence sources:
-- cli-explore-agent output (code anchors, call chains, data flows)
-- maestro delegate CLI analysis output (multi-perspective findings)
-- User-provided input (domain knowledge, constraints, corrections)
-
-Decisions without CLI/agent-sourced evidence MUST be flagged as LOW CONFIDENCE.
-
-### Boundary Grill (Step 5 → Step 6)
-
-After discussion rounds, BEFORE synthesis: run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
-Input: discussion.md decisions + exploration-codebase.json. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
-IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
-
-### Standard Mode Gates
-
-Gates 1-4 are defined in `analyze.md`. NEVER skip gates. NEVER substitute manual Read/Grep for agent/CLI exploration.
-
-### Artifact Verification
-
-Before writing the completion report (Step 9), verify ALL expected artifacts exist in OUTPUT_DIR:
-```
-FULL_MODE_REQUIRED = [
-  "discussion.md",             // Step 3+5
-  "exploration-codebase.json", // Step 4.1
-  "explorations.json" OR "perspectives.json", // Step 4.3
-  "analysis.md",               // Step 6
-  "conclusions.json",          // Step 7
-  "context.md",                // Step 8
-  "context-package.json"       // Step 8.6
-]
-```
-If any artifact is missing: DO NOT report completion. Produce the missing artifact first.
-
 ### --gaps Mode
 
 When `--gaps` is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard pipeline.
-
-**Handoff:** context.md is consumed by maestro-plan. In --gaps mode, context.md contains issue root causes for `plan --gaps`.
-
-**scope_verdict** (added to context.md in Step 6 Synthesis for macro/adhoc/standalone scopes):
-- `large` (3+ independent subsystems or hard serial dependencies) → suggest `/maestro-roadmap --from analyze:ANL-xxx`
-- `medium` (1-2 subsystems, parallelizable) → suggest `/maestro-plan --from analyze:ANL-xxx`
-- `small` (single-file or few-file change) → suggest `/maestro-plan --from analyze:ANL-xxx`
 </execution>
 
 <completion>

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

@@ -88,28 +88,6 @@ Each phase produces artifacts that are prerequisites for the next. Do NOT advanc
 **GATE P5 → P6**: `epics/` directory with `_index.md` + individual `EPIC-*.md` files. Cross-Epic dependency map present.
 **GATE P6**: Readiness score computed. Pass (≥80%) or Review (≥60%) required for handoff.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  "blueprint-config.json",        // P0
-  "product-brief.md",             // P2
-  "glossary.json",                // P2 (≥5 terms)
-  "requirements/_index.md",       // P3
-  "architecture/_index.md",       // P4
-  "epics/_index.md",              // P5
-  "readiness-report.md",          // P6
-  "blueprint-summary.md",         // P6
-  "context-package.json"          // P6
-]
-```
-If any artifact is missing: DO NOT report completion. Go back and produce it.
-
-### Evidence Requirement
-
-Architecture Decision Records (ADR-*.md) MUST cite evidence for each decision:
-- Valid: code analysis, requirement traceability (REQ-xxx), upstream context, CLI analysis output
-- INVALID: generic rationale without reference to project-specific constraints
 </execution>
 
 <completion>
@@ -181,7 +159,7 @@ Status verdicts:
 - [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
 - [ ] Artifact registered in state.json (type=blueprint)
 - [ ] context-package.json generated for downstream consumption
-- [ ] On gate Pass/Review: session sealed via finish-work (archive.json + optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
+- [ ] On gate Pass/Review: session sealed via finish-work (finish-work.md includes AskUserQuestion confirmation before state.json artifact registration and optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
 </success_criteria>
 
 <on_complete>